1libPARI(3) User Contributed Perl Documentation libPARI(3)
2
6 libPARI - Functions and Operations Available in PARI and GP
7 The functions and operators available in PARI and in the GP/PARI
9 calculator are numerous and everexpanding. Here is a description of the
10 ones available in version /usr/share/libpari23. It should be noted that
11 many of these functions accept quite different types as arguments, but
12 others are more restricted. The list of acceptable types will be given
13 for each function or class of functions. Except when stated otherwise,
14 it is understood that a function or operation which should make natural
15 sense is legal. In this chapter, we will describe the functions
16 according to a rough classification. The general entry looks something
17 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 * generic: all valid values for the flag are individually described
62 (``If flag is equal to "1", then...'').
63 * binary: use customary binary notation as a compact way to represent
65 many toggles with just one integer. Let "(p_0,...,p_n)" be a list of
66 switches (i.e. of properties which take either the value "0" or "1"),
67 the number "2^3 + 2^5 = 40" means that "p_3" and "p_5" are set (that
68 is, set to "1"), and none of the others are (that is, they are set to
69 "0"). This is announced as ``The binary digits of "flag" mean 1: "p_0",
70 2: "p_1", 4: "p_2"'', and so on, using the available consecutive powers
71 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 /usr/share/libpari23, this
114 pointer argument is optional for all documented functions, hence the &
115 will 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", \funs{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 \funs{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 not the Euclidean quotient (see "x" "\" "y" for that), and similarly
179 the quotient of two polynomials is a rational function in general. To
180 obtain the approximate real value of the quotient of two integers, add
181 0. to the result; to obtain the approximate "p"-adic value of the
182 quotient of two integers, add "O(p^k)" to the result; finally, to
183 obtain the Taylor series expansion of the quotient of two polynomials,
184 add "O(X^k)" to the result or use the "taylor" function (see "Label
185 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 \subsecidx{divrem}"(x,y,{v})": creates a column vector with two
236 components, the first being the Euclidean quotient ("x \y"), the second
237 the Euclidean remainder ("x - (x\y)*y"), of the division of "x" by "y".
238 This avoids the need to do two divisions if one needs both the quotient
239 and the remainder. If "v" is present, and "x", "y" are multivariate
240 polynomials, divide with respect to the variable "v".
241 Beware that "divrem(x,y)[2]" is in general not the same as "x % y";
243 there is no operator to obtain it in GP:
244 ? divrem(1/2, 3)[2]
246 %1 = 1/2
247 ? (1/2) % 3
248 %2 = 2
249 ? divrem(Mod(2,9), 3)[2]
250 *** forbidden division t_INTMOD \ t_INT.
251 ? Mod(2,9) % 6
252 %3 = Mod(2,3)
253 The library syntax is "divrem(x,y,v)",where "v" is a "long". Also
255 available as \funs{gdiventres}{x,y} when "v" is not needed.
256 ^
258 The expression "x^n" is powering. If the exponent is an integer, then
259 exact operations are performed using binary (left-shift) powering
260 techniques. In particular, in this case "x" cannot be a vector or
261 matrix unless it is a square matrix (invertible if the exponent is
262 negative). If "x" is a "p"-adic number, its precision will increase if
263 "v_p(n) > 0". Powering a binary quadratic form (types "t_QFI" and
264 "t_QFR") returns a reduced representative of the class, provided the
265 input is reduced. In particular, "x^1" is identical to "x".
266 PARI is able to rewrite the multiplication "x * x" of two identical
268 objects as "x^2", or sqr(x). Here, identical means the operands are two
269 different labels referencing the same chunk of memory; no equality test
270 is performed. This is no longer true when more than two arguments are
271 involved.
272 If the exponent is not of type integer, this is treated as a
274 transcendental function (see "Label se:trans"), and in particular has
275 the effect of componentwise powering on vector or matrices.
276 As an exception, if the exponent is a rational number "p/q" and "x" an
278 integer modulo a prime or a "p"-adic number, return a solution "y" of
279 "y^q = x^p" if it exists. Currently, "q" must not have large prime
280 factors. Beware that
281 ? Mod(7,19)^(1/2)
283 %1 = Mod(11, 19) /* is any square root */
284 ? sqrt(Mod(7,19))
285 %2 = Mod(8, 19) /* is the smallest square root */
286 ? Mod(7,19)^(3/5)
287 %3 = Mod(1, 19)
288 ? %3^(5/3)
289 %4 = Mod(1, 19) /* Mod(7,19) is just another cubic root */
290 If the exponent is a negative integer, an inverse must be computed.
292 For non-invertible "t_INTMOD", this will fail and implicitly exhibit a
293 non trivial factor of the modulus:
294 ? Mod(4,6)^(-1)
296 *** impossible inverse modulo: Mod(2, 6).
297 (Here, a factor 2 is obtained directly. In general, take the gcd of the
299 representative and the modulus.) This is most useful when performing
300 complicated operations modulo an integer "N" whose factorization is
301 unknown. Either the computation succeeds and all is well, or a factor
302 "d" is discovered and the computation may be restarted modulo "d" or
303 "N/d".
304 For non-invertible "t_POLMOD", this will fail without exhibiting a
306 factor.
307 ? Mod(x^2, x^3-x)^(-1)
309 *** non-invertible polynomial in RgXQ_inv.
310 ? a = Mod(3,4)*y^3 + Mod(1,4); b = y^6+y^5+y^4+y^3+y^2+y+1;
312 ? Mod(a, b)^(-1);
313 *** non-invertible polynomial in RgXQ_inv.
314 In fact the latter polynomial is invertible, but the algorithm used
316 (subresultant) assumes the base ring is a domain. If it is not the
317 case, as here for "Z/4Z", a result will be correct but chances are an
318 error will occur first. In this specific case, one should work with
319 2-adics. In general, one can try the following approach
320 ? inversemod(a, b) =
322 { local(m);
323 m = polsylvestermatrix(polrecip(a), polrecip(b));
324 m = matinverseimage(m, matid(#m)[,1]);
325 Polrev( vecextract(m, Str("..", poldegree(b))), variable(b) )
326 }
327 ? inversemod(a,b)
328 %2 = Mod(2,4)*y^5 + Mod(3,4)*y^3 + Mod(1,4)*y^2 + Mod(3,4)*y + Mod(2,4)
329 This is not guaranteed to work either since it must invert pivots. See
331 "Label se:linear_algebra".
332 The library syntax is "gpow(x,n,prec)" for "x^n".
334 \subsecidx{bittest}"(x,n)": outputs the "n-th" bit of "x" starting from
336 the right (i.e. the coefficient of "2^n" in the binary expansion of
337 "x"). The result is 0 or 1. To extract several bits at once as a
338 vector, pass a vector for "n".
339 See "Label se:bitand" for the behaviour at negative arguments.
341 The library syntax is "bittest(x,n)", where "n" and the result are
343 "long"s.
344 \subsecidx{shift}"(x,n)" or "x" "<< " "n" ( = "x" ">> " "(-n)"): shifts
346 "x" componentwise left by "n" bits if "n >= 0" and right by "|n|" bits
347 if "n < 0". A left shift by "n" corresponds to multiplication by
348 "2^n". A right shift of an integer "x" by "|n|" corresponds to a
349 Euclidean division of "x" by "2^{|n|}" with a remainder of the same
350 sign as "x", hence is not the same (in general) as "x \ 2^n".
351 The library syntax is "gshift(x,n)" where "n" is a "long".
353 \subsecidx{shiftmul}"(x,n)": multiplies "x" by "2^n". The difference
355 with "shift" is that when "n < 0", ordinary division takes place, hence
356 for example if "x" is an integer the result may be a fraction, while
357 for shifts Euclidean division takes place when "n < 0" hence if "x" is
358 an integer the result is still an integer.
359 The library syntax is "gmul2n(x,n)" where "n" is a "long".
361 Comparison and boolean operators
363 The six standard comparison operators "<= ", "< ", ">= ", "> ", " ==
364 ", " != " are available in GP, and in library mode under the names
365 "gle", "glt", "gge", "ggt", "geq", "gne" respectively. The library
366 syntax is "co(x,y)", where co is the comparison operator. The result is
367 1 (as a "GEN") if the comparison is true, 0 (as a "GEN") if it is
368 false. For the purpose of comparison, "t_STR" objects are strictly
369 larger than any other non-string type; two "t_STR" objects are compared
370 using the standard lexicographic order.
371 The standard boolean functions "||" (inclusive or), "&&" (and) and "!"
373 (not) are also available, and the library syntax is \funs{gor}{x,y},
374 \funs{gand}{x,y} and \funs{gnot}{x} respectively.
375 In library mode, it is in fact usually preferable to use the two basic
377 functions which are \funs{gcmp}{x,y} which gives the sign (1, 0, or -1)
378 of "x-y", where "x" and "y" must be in R, and \funs{gequal}{x,y} which
379 can be applied to any two PARI objects "x" and "y" and gives 1
380 (i.e. true) if they are equal (but not necessarily identical), 0
381 (i.e. false) otherwise. Comparisons to special constants are
382 implemented and should be used instead of "gequal": \funs{gcmp0}{x} ("x
383 == 0" ?), \funs{gcmp1}{x} ("x == 1" ?), and \funs{gcmp_1}{x} ("x == -1"
384 ?).
385 Note that gcmp0(x) tests whether "x" is equal to zero, even if "x" is
387 not an exact object. To test whether "x" is an exact object which is
388 equal to zero, one must use \funs{isexactzero}{x}.
389 Also note that the "gcmp" and "gequal" functions return a C-integer,
391 and not a "GEN" like "gle" etc.
392 GP accepts the following synonyms for some of the above functions:
394 since we thought it might easily lead to confusion, we don't use the
395 customary C operators for bitwise "and" or bitwise "or" (use "bitand"
396 or "bitor"), hence "|" and "&" are accepted as synonyms of "||" and
397 "&&" respectively. Also, "<> " is accepted as a synonym for " != ". On
398 the other hand, " = " is definitely not a synonym for " == " since it
399 is the assignment statement.
400 \subsecidx{lex}"(x,y)": gives the result of a lexicographic comparison
402 between "x" and "y" (as "-1", 0 or 1). This is to be interpreted in
403 quite a wide sense: It is admissible to compare objects of different
404 types (scalars, vectors, matrices), provided the scalars can be
405 compared, as well as vectors/matrices of different lengths. The
406 comparison is recursive.
407 In case all components are equal up to the smallest length of the
409 operands, the more complex is considered to be larger. More precisely,
410 the longest is the largest; when lengths are equal, we have matrix " >
411 " vector " > " scalar. For example:
412 ? lex([1,3], [1,2,5])
414 %1 = 1
415 ? lex([1,3], [1,3,-1])
416 %2 = -1
417 ? lex([1], [[1]])
418 %3 = -1
419 ? lex([1], [1]~)
420 %4 = 0
421 The library syntax is "lexcmp(x,y)".
423 \subsecidx{sign}"(x)": sign (0, 1 or "-1") of "x", which must be of
425 type integer, real or fraction.
426 The library syntax is "gsigne(x)". The result is a "long".
428 \subsecidx{max}"(x,y)" and \funs{min}{x,y}: creates the maximum and
430 minimum of "x" and "y" when they can be compared.
431 The library syntax is "gmax(x,y)" and \funs{gmin}{x,y}.
433 \subsecidx{vecmax}"(x)": if "x" is a vector or a matrix, returns the
435 maximum of the elements of "x", otherwise returns a copy of "x". Error
436 if "x" is empty.
437 The library syntax is "vecmax(x)".
439 \subsecidx{vecmin}"(x)": if "x" is a vector or a matrix, returns the
441 minimum of the elements of "x", otherwise returns a copy of "x". Error
442 if "x" is empty.
443 The library syntax is "vecmin(x)".
445
447 Many of the conversion functions are rounding or truncating operations.
448 In this case, if the argument is a rational function, the result is the
449 Euclidean quotient of the numerator by the denominator, and if the
450 argument is a vector or a matrix, the operation is done componentwise.
451 This will not be restated for every function.
452 \subsecidx{Col}"({x = []})": transforms the object "x" into a column
454 vector. The vector will be with one component only, except when "x" is
455 a vector or a quadratic form (in which case the resulting vector is
456 simply the initial object considered as a column vector), a matrix (the
457 column of row vectors comprising the matrix is returned), a character
458 string (a column of individual characters is returned), but more
459 importantly when "x" is a polynomial or a power series. In the case of
460 a polynomial, the coefficients of the vector start with the leading
461 coefficient of the polynomial, while for power series only the
462 significant coefficients are taken into account, but this time by
463 increasing order of degree.
464 The library syntax is "gtocol(x)".
466 \subsecidx{List}"({x = []})": transforms a (row or column) vector "x"
468 into a list. The only other way to create a "t_LIST" is to use the
469 function "listcreate".
470 This is useless in library mode.
472 \subsecidx{Mat}"({x = []})": transforms the object "x" into a matrix.
474 If "x" is already a matrix, a copy of "x" is created. If "x" is not a
475 vector or a matrix, this creates a "1 x 1" matrix. If "x" is a row
476 (resp. column) vector, this creates a 1-row (resp. 1-column) matrix,
477 unless all elements are column (resp. row) vectors of the same length,
478 in which case the vectors are concatenated sideways and the associated
479 big matrix is returned.
480 ? Mat(x + 1)
482 %1 =
483 [x + 1]
484 ? Vec( matid(3) )
485 %2 = [[1, 0, 0]~, [0, 1, 0]~, [0, 0, 1]~]
486 ? Mat(%)
487 %3 =
488 [1 0 0]
489 [0 1 0]
491 [0 0 1]
493 ? Col( [1,2; 3,4] )
494 %4 = [[1, 2], [3, 4]]~
495 ? Mat(%)
496 %5 =
497 [1 2]
498 [3 4]
500 The library syntax is "gtomat(x)".
502 \subsecidx{Mod}"(x,y,{flag = 0})": creates the PARI object "(x mod y)",
504 i.e. an intmod or a polmod. "y" must be an integer or a polynomial. If
505 "y" is an integer, "x" must be an integer, a rational number, or a
506 "p"-adic number compatible with the modulus "y". If "y" is a
507 polynomial, "x" must be a scalar (which is not a polmod), a polynomial,
508 a rational function, or a power series.
509 This function is not the same as "x" "%" "y", the result of which is an
511 integer or a polynomial.
512 "flag" is obsolete and should not be used.
514 The library syntax is "gmodulo(x,y)".
516 \subsecidx{Pol}"(x,{v = x})": transforms the object "x" into a
518 polynomial with main variable "v". If "x" is a scalar, this gives a
519 constant polynomial. If "x" is a power series, the effect is identical
520 to "truncate" (see there), i.e. it chops off the "O(X^k)". If "x" is a
521 vector, this function creates the polynomial whose coefficients are
522 given in "x", with "x[1]" being the leading coefficient (which can be
523 zero).
524 Warning:. this is not a substitution function. It will not transform an
526 object containing variables of higher priority than "v".
527 ? Pol(x + y, y)
529 *** Pol: variable must have higher priority in gtopoly.
530 The library syntax is "gtopoly(x,v)", where "v" is a variable number.
532 \subsecidx{Polrev}"(x,{v = x})": transform the object "x" into a
534 polynomial with main variable "v". If "x" is a scalar, this gives a
535 constant polynomial. If "x" is a power series, the effect is identical
536 to "truncate" (see there), i.e. it chops off the "O(X^k)". If "x" is a
537 vector, this function creates the polynomial whose coefficients are
538 given in "x", with "x[1]" being the constant term. Note that this is
539 the reverse of "Pol" if "x" is a vector, otherwise it is identical to
540 "Pol".
541 The library syntax is "gtopolyrev(x,v)", where "v" is a variable
543 number.
544 \subsecidx{Qfb}"(a,b,c,{D = 0.})": creates the binary quadratic form
546 "ax^2+bxy+cy^2". If "b^2-4ac > 0", initialize Shanks' distance function
547 to "D". Negative definite forms are not implemented, use their positive
548 definite counterpart instead.
549 The library syntax is "Qfb0(a,b,c,D,prec)". Also available are
551 \funs{qfi}{a,b,c} (when "b^2-4ac < 0"), and \funs{qfr}{a,b,c,d} (when
552 "b^2-4ac > 0").
553 \subsecidx{Ser}"(x,{v = x})": transforms the object "x" into a power
555 series with main variable "v" ("x" by default). If "x" is a scalar,
556 this gives a constant power series with precision given by the default
557 "serieslength" (corresponding to the C global variable "precdl"). If
558 "x" is a polynomial, the precision is the greatest of "precdl" and the
559 degree of the polynomial. If "x" is a vector, the precision is
560 similarly given, and the coefficients of the vector are understood to
561 be the coefficients of the power series starting from the constant term
562 (i.e. the reverse of the function "Pol").
563 The warning given for "Pol" also applies here: this is not a
565 substitution function.
566 The library syntax is "gtoser(x,v)", where "v" is a variable number
568 (i.e. a C integer).
569 \subsecidx{Set}"({x = []})": converts "x" into a set, i.e. into a row
571 vector of character strings, with strictly increasing entries with
572 respect to lexicographic ordering. The components of "x" are put in
573 canonical form (type "t_STR") so as to be easily sorted. To recover an
574 ordinary "GEN" from such an element, you can apply "eval" to it.
575 The library syntax is "gtoset(x)".
577 \subsecidx{Str}"({x}*)": converts its argument list into a single
579 character string (type "t_STR", the empty string if "x" is omitted).
580 To recover an ordinary "GEN" from a string, apply "eval" to it. The
581 arguments of "Str" are evaluated in string context, see "Label
582 se:strings".
583 ? x2 = 0; i = 2; Str(x, i)
585 %1 = "x2"
586 ? eval(%)
587 %2 = 0
588 This function is mostly useless in library mode. Use the pair
590 "strtoGEN"/"GENtostr" to convert between "GEN" and "char*". The latter
591 returns a malloced string, which should be freed after usage.
592 \subsecidx{Strchr}"(x)": converts "x" to a string, translating each
594 integer into a character.
595 ? Strchr(97)
597 %1 = "a"
598 ? Vecsmall("hello world")
599 %2 = Vecsmall([104, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100])
600 ? Strchr(%)
601 %3 = "hello world"
602 \subsecidx{Strexpand}"({x}*)": converts its argument list into a single
604 character string (type "t_STR", the empty string if "x" is omitted).
605 Then performe environment expansion, see "Label se:envir". This
606 feature can be used to read environment variable values.
607 ? Strexpand("$HOME/doc")
609 %1 = "/home/pari/doc"
610 The individual arguments are read in string context, see "Label
612 se:strings".
613 \subsecidx{Strtex}"({x}*)": translates its arguments to TeX format, and
615 concatenates the results into a single character string (type "t_STR",
616 the empty string if "x" is omitted).
617 The individual arguments are read in string context, see "Label
619 se:strings".
620 \subsecidx{Vec}"({x = []})": transforms the object "x" into a row
622 vector. The vector will be with one component only, except when "x" is
623 a vector or a quadratic form (in which case the resulting vector is
624 simply the initial object considered as a row vector), a matrix (the
625 vector of columns comprising the matrix is return), a character string
626 (a vector of individual characters is returned), but more importantly
627 when "x" is a polynomial or a power series. In the case of a
628 polynomial, the coefficients of the vector start with the leading
629 coefficient of the polynomial, while for power series only the
630 significant coefficients are taken into account, but this time by
631 increasing order of degree.
632 The library syntax is "gtovec(x)".
634 \subsecidx{Vecsmall}"({x = []})": transforms the object "x" into a row
636 vector of type "t_VECSMALL". This acts as "Vec", but only on a limited
637 set of objects (the result must be representable as a vector of small
638 integers). In particular, polynomials and power series are forbidden.
639 If "x" is a character string, a vector of individual characters in
640 ASCII encoding is returned ("Strchr" yields back the character string).
641 The library syntax is "gtovecsmall(x)".
643 \subsecidx{binary}"(x)": outputs the vector of the binary digits of
645 "|x|". Here "x" can be an integer, a real number (in which case the
646 result has two components, one for the integer part, one for the
647 fractional part) or a vector/matrix.
648 The library syntax is "binaire(x)".
650 \subsecidx{bitand}"(x,y)": bitwise "and" of two integers "x" and "y",
652 that is the integer
653 "sum_i (x_i and y_i) 2^i"
655 Negative numbers behave 2-adically, i.e. the result is the 2-adic limit
657 of "bitand""(x_n,y_n)", where "x_n" and "y_n" are non-negative integers
658 tending to "x" and "y" respectively. (The result is an ordinary
659 integer, possibly negative.)
660 ? bitand(5, 3)
662 %1 = 1
663 ? bitand(-5, 3)
664 %2 = 3
665 ? bitand(-5, -3)
666 %3 = -7
667 The library syntax is "gbitand(x,y)".
669 \subsecidx{bitneg}"(x,{n = -1})": bitwise negation of an integer "x",
671 truncated to "n" bits, that is the integer
672 "sum_{i = 0}^{n-1} not(x_i) 2^i"
674 The special case "n = -1" means no truncation: an infinite sequence of
676 leading 1 is then represented as a negative number.
677 See "Label se:bitand" for the behaviour for negative arguments.
679 The library syntax is "gbitneg(x)".
681 \subsecidx{bitnegimply}"(x,y)": bitwise negated imply of two integers
683 "x" and "y" (or "not" "(x ==> y)"), that is the integer
684 "sum (x_i and not(y_i)) 2^i"
686 See "Label se:bitand" for the behaviour for negative arguments.
688 The library syntax is "gbitnegimply(x,y)".
690 \subsecidx{bitor}"(x,y)": bitwise (inclusive) "or" of two integers "x"
692 and "y", that is the integer
693 "sum (x_i or y_i) 2^i"
695 See "Label se:bitand" for the behaviour for negative arguments.
697 The library syntax is "gbitor(x,y)".
699 \subsecidx{bittest}"(x,n)": outputs the "n-th" bit of "|x|" starting
701 from the right (i.e. the coefficient of "2^n" in the binary expansion
702 of "x"). The result is 0 or 1. To extract several bits at once as a
703 vector, pass a vector for "n".
704 The library syntax is "bittest(x,n)", where "n" and the result are
706 "long"s.
707 \subsecidx{bitxor}"(x,y)": bitwise (exclusive) "or" of two integers "x"
709 and "y", that is the integer
710 "sum (x_i xor y_i) 2^i"
712 See "Label se:bitand" for the behaviour for negative arguments.
714 The library syntax is "gbitxor(x,y)".
716 \subsecidx{ceil}"(x)": ceiling of "x". When "x" is in R, the result is
718 the smallest integer greater than or equal to "x". Applied to a
719 rational function, ceil(x) returns the euclidian quotient of the
720 numerator by the denominator.
721 The library syntax is "gceil(x)".
723 \subsecidx{centerlift}"(x,{v})": lifts an element "x = a mod n" of
725 "Z/nZ" to "a" in Z, and similarly lifts a polmod to a polynomial. This
726 is the same as "lift" except that in the particular case of elements of
727 "Z/nZ", the lift "y" is such that "-n/2 < y <= n/2". If "x" is of type
728 fraction, complex, quadratic, polynomial, power series, rational
729 function, vector or matrix, the lift is done for each coefficient.
730 Reals are forbidden.
731 The library syntax is "centerlift0(x,v)", where "v" is a "long" and an
733 omitted "v" is coded as "-1". Also available is \funs{centerlift}{x} =
734 "centerlift0(x,-1)".
735 \subsecidx{changevar}"(x,y)": creates a copy of the object "x" where
737 its variables are modified according to the permutation specified by
738 the vector "y". For example, assume that the variables have been
739 introduced in the order "x", "a", "b", "c". Then, if "y" is the vector
740 "[x,c,a,b]", the variable "a" will be replaced by "c", "b" by "a", and
741 "c" by "b", "x" being unchanged. Note that the permutation must be
742 completely specified, e.g. "[c,a,b]" would not work, since this would
743 replace "x" by "c", and leave "a" and "b" unchanged (as well as "c"
744 which is the fourth variable of the initial list). In particular, the
745 new variable names must be distinct.
746 The library syntax is "changevar(x,y)".
748 components of a PARI object
750 There are essentially three ways to extract the components from a PARI
751 object.
752 The first and most general, is the function \funs{component}{x,n} which
754 extracts the "n-th"-component of "x". This is to be understood as
755 follows: every PARI type has one or two initial code words. The
756 components are counted, starting at 1, after these code words. In
757 particular if "x" is a vector, this is indeed the "n-th"-component of
758 "x", if "x" is a matrix, the "n-th" column, if "x" is a polynomial, the
759 "n-th" coefficient (i.e. of degree "n-1"), and for power series, the
760 "n-th" significant coefficient. The use of the function "component"
761 implies the knowledge of the structure of the different PARI types,
762 which can be recalled by typing "\t" under "gp".
763 The library syntax is "compo(x,n)", where "n" is a "long".
765 The two other methods are more natural but more restricted. The
767 function \funs{polcoeff}{x,n} gives the coefficient of degree "n" of
768 the polynomial or power series "x", with respect to the main variable
769 of "x" (to check variable ordering, or to change it, use the function
770 "reorder", see "Label se:reorder"). In particular if "n" is less than
771 the valuation of "x" or in the case of a polynomial, greater than the
772 degree, the result is zero (contrary to "compo" which would send an
773 error message). If "x" is a power series and "n" is greater than the
774 largest significant degree, then an error message is issued.
775 For greater flexibility, vector or matrix types are also accepted for
777 "x", and the meaning is then identical with that of "compo".
778 Finally note that a scalar type is considered by "polcoeff" as a
780 polynomial of degree zero.
781 The library syntax is "truecoeff(x,n)".
783 The third method is specific to vectors or matrices in GP. If "x" is a
785 (row or column) vector, then "x[n]" represents the "n-th" component of
786 "x", i.e. "compo(x,n)". It is more natural and shorter to write. If "x"
787 is a matrix, "x[m,n]" represents the coefficient of row "m" and column
788 "n" of the matrix, "x[m,]" represents the "m-th" row of "x", and
789 "x[,n]" represents the "n-th" column of "x".
790 Finally note that in library mode, the macros gcoeff and gmael are
792 available as direct accessors to a "GEN component". See Chapter 4 for
793 details.
794 \subsecidx{conj}"(x)": conjugate of "x". The meaning of this is clear,
796 except that for real quadratic numbers, it means conjugation in the
797 real quadratic field. This function has no effect on integers, reals,
798 intmods, fractions or "p"-adics. The only forbidden type is polmod (see
799 "conjvec" for this).
800 The library syntax is "gconj(x)".
802 \subsecidx{conjvec}"(x)": conjugate vector representation of "x". If
804 "x" is a polmod, equal to "Mod""(a,q)", this gives a vector of length
805 degree(q) containing the complex embeddings of the polmod if "q" has
806 integral or rational coefficients, and the conjugates of the polmod if
807 "q" has some intmod coefficients. The order is the same as that of the
808 "polroots" functions. If "x" is an integer or a rational number, the
809 result is "x". If "x" is a (row or column) vector, the result is a
810 matrix whose columns are the conjugate vectors of the individual
811 elements of "x".
812 The library syntax is "conjvec(x,prec)".
814 \subsecidx{denominator}"(x)": denominator of "x". The meaning of this
816 is clear when "x" is a rational number or function. If "x" is an
817 integer or a polynomial, it is treated as a rational number of
818 function, respectively, and the result is equal to 1. For polynomials,
819 you probably want to use
820 denominator( content(x) )
822 instead. As for modular objects, "t_INTMOD" and "t_PADIC" have
824 denominator 1, and the denominator of a "t_POLMOD" is the denominator
825 of its (minimal degree) polynomial representative.
826 If "x" is a recursive structure, for instance a vector or matrix, the
828 lcm of the denominators of its components (a common denominator) is
829 computed. This also applies for "t_COMPLEX"s and "t_QUAD"s.
830 Warning:. multivariate objects are created according to variable
832 priorities, with possibly surprising side effects ("x/y" is a
833 polynomial, but "y/x" is a rational function). See "Label se:priority".
834 The library syntax is "denom(x)".
836 \subsecidx{floor}"(x)": floor of "x". When "x" is in R, the result is
838 the largest integer smaller than or equal to "x". Applied to a rational
839 function, floor(x) returns the euclidian quotient of the numerator by
840 the denominator.
841 The library syntax is "gfloor(x)".
843 \subsecidx{frac}"(x)": fractional part of "x". Identical to
845 "x-floor(x)". If "x" is real, the result is in "[0,1[".
846 The library syntax is "gfrac(x)".
848 \subsecidx{imag}"(x)": imaginary part of "x". When "x" is a quadratic
850 number, this is the coefficient of "omega" in the ``canonical''
851 integral basis "(1,omega)".
852 The library syntax is "gimag(x)". This returns a copy of the imaginary
854 part. The internal routine "imag_i" is faster, since it returns the
855 pointer and skips the copy.
856 \subsecidx{length}"(x)": number of non-code words in "x" really used
858 (i.e. the effective length minus 2 for integers and polynomials). In
859 particular, the degree of a polynomial is equal to its length minus 1.
860 If "x" has type "t_STR", output number of letters.
861 The library syntax is "glength(x)" and the result is a C long.
863 \subsecidx{lift}"(x,{v})": lifts an element "x = a mod n" of "Z/nZ" to
865 "a" in Z, and similarly lifts a polmod to a polynomial if "v" is
866 omitted. Otherwise, lifts only polmods whose modulus has main variable
867 "v" (if "v" does not occur in "x", lifts only intmods). If "x" is of
868 recursive (non modular) type, the lift is done coefficientwise. For
869 "p"-adics, this routine acts as "truncate". It is not allowed to have
870 "x" of type "t_REAL".
871 ? lift(Mod(5,3))
873 %1 = 2
874 ? lift(3 + O(3^9))
875 %2 = 3
876 ? lift(Mod(x,x^2+1))
877 %3 = x
878 ? lift(x * Mod(1,3) + Mod(2,3))
879 %4 = x + 2
880 ? lift(x * Mod(y,y^2+1) + Mod(2,3))
881 %5 = y*x + Mod(2, 3) \\ do you understand this one ?
882 ? lift(x * Mod(y,y^2+1) + Mod(2,3), x)
883 %6 = Mod(y, y^2+1) * x + Mod(2, y^2+1)
884 The library syntax is "lift0(x,v)", where "v" is a "long" and an
886 omitted "v" is coded as "-1". Also available is \funs{lift}{x} =
887 "lift0(x,-1)".
888 \subsecidx{norm}"(x)": algebraic norm of "x", i.e. the product of "x"
890 with its conjugate (no square roots are taken), or conjugates for
891 polmods. For vectors and matrices, the norm is taken componentwise and
892 hence is not the "L^2"-norm (see "norml2"). Note that the norm of an
893 element of R is its square, so as to be compatible with the complex
894 norm.
895 The library syntax is "gnorm(x)".
897 \subsecidx{norml2}"(x)": square of the "L^2"-norm of "x". More
899 precisely, if "x" is a scalar, norml2(x) is defined to be "x *
900 conj(x)". If "x" is a (row or column) vector or a matrix, norml2(x) is
901 defined recursively as "sum_i norml2(x_i)", where "(x_i)" run through
902 the components of "x". In particular, this yields the usual "sum
903 |x_i|^2" (resp. "sum |x_{i,j}|^2") if "x" is a vector (resp. matrix)
904 with complex components.
905 ? norml2( [ 1, 2, 3 ] ) \\ vector
907 %1 = 14
908 ? norml2( [ 1, 2; 3, 4] ) \\ matrix
909 %1 = 30
910 ? norml2( I + x )
911 %3 = x^2 + 1
912 ? norml2( [ [1,2], [3,4], 5, 6 ] ) \\ recursively defined
913 %4 = 91
914 The library syntax is "gnorml2(x)".
916 \subsecidx{numerator}"(x)": numerator of "x". The meaning of this is
918 clear when "x" is a rational number or function. If "x" is an integer
919 or a polynomial, it is treated as a rational number of function,
920 respectively, and the result is "x" itself. For polynomials, you
921 probably want to use
922 numerator( content(x) )
924 instead.
926 In other cases, numerator(x) is defined to be "denominator(x)*x". This
928 is the case when "x" is a vector or a matrix, but also for "t_COMPLEX"
929 or "t_QUAD". In particular since a "t_PADIC" or "t_INTMOD" has
930 denominator 1, its numerator is itself.
931 Warning:. multivariate objects are created according to variable
933 priorities, with possibly surprising side effects ("x/y" is a
934 polynomial, but "y/x" is a rational function). See "Label se:priority".
935 The library syntax is "numer(x)".
937 \subsecidx{numtoperm}"(n,k)": generates the "k"-th permutation (as a
939 row vector of length "n") of the numbers 1 to "n". The number "k" is
940 taken modulo "n!", i.e. inverse function of "permtonum".
941 The library syntax is "numtoperm(n,k)", where "n" is a "long".
943 \subsecidx{padicprec}"(x,p)": absolute "p"-adic precision of the object
945 "x". This is the minimum precision of the components of "x". The
946 result is "VERYBIGINT" ("2^{31}-1" for 32-bit machines or "2^{63}-1"
947 for 64-bit machines) if "x" is an exact object.
948 The library syntax is "padicprec(x,p)" and the result is a "long"
950 integer.
951 \subsecidx{permtonum}"(x)": given a permutation "x" on "n" elements,
953 gives the number "k" such that "x = numtoperm(n,k)", i.e. inverse
954 function of "numtoperm".
955 The library syntax is "permtonum(x)".
957 \subsecidx{precision}"(x,{n})": gives the precision in decimal digits
959 of the PARI object "x". If "x" is an exact object, the largest single
960 precision integer is returned. If "n" is not omitted, creates a new
961 object equal to "x" with a new precision "n". This is to be understood
962 as follows:
963 For exact types, no change. For "x" a vector or a matrix, the operation
965 is done componentwise.
966 For real "x", "n" is the number of desired significant decimal digits.
968 If "n" is smaller than the precision of "x", "x" is truncated,
969 otherwise "x" is extended with zeros.
970 For "x" a "p"-adic or a power series, "n" is the desired number of
972 significant "p"-adic or "X"-adic digits, where "X" is the main variable
973 of "x".
974 Note that the function "precision" never changes the type of the
976 result. In particular it is not possible to use it to obtain a
977 polynomial from a power series. For that, see "truncate".
978 The library syntax is "precision0(x,n)", where "n" is a "long". Also
980 available are \funs{ggprecision}{x} (result is a "GEN") and
981 \funs{gprec}{x,n}, where "n" is a "long".
982 \subsecidx{random}"({N = 2^{31}})": returns a random integer between 0
984 and "N-1". "N" is an integer, which can be arbitrary large. This is an
985 internal PARI function and does not depend on the system's random
986 number generator.
987 The resulting integer is obtained by means of linear congruences and
989 will not be well distributed in arithmetic progressions. The random
990 seed may be obtained via "getrand", and reset using "setrand".
991 Note that "random(2^31)" is not equivalent to "random()", although both
993 return an integer between 0 and "2^{31}-1". In fact, calling "random"
994 with an argument generates a number of random words (32bit or 64bit
995 depending on the architecture), rescaled to the desired interval. The
996 default uses directly a 31-bit generator.
997 Important technical note:. the implementation of this function is
999 incorrect unless "N" is a power of 2 (integers less than the bound are
1000 not equally likely, some may not even occur). It is kept for backward
1001 compatibility only, and has been rewritten from scratch in the 2.4.x
1002 unstable series. Use the following script for a correct version:
1003 RANDOM(N) =
1005 { local(n, L);
1006 L = 1; while (L < N, L <<= 1;);
1008 /* L/2 < N <= L, L power of 2 */
1009 until(n < N, n = random(L)); n
1010 }
1011 The library syntax is "genrand(N)". Also available are "pari_rand""()"
1013 which returns a random "unsigned long" (32bit or 64bit depending on the
1014 architecture), and "pari_rand31""()" which returns a 31bit "long"
1015 integer.
1016 \subsecidx{real}"(x)": real part of "x". In the case where "x" is a
1018 quadratic number, this is the coefficient of 1 in the ``canonical''
1019 integral basis "(1,omega)".
1020 The library syntax is "greal(x)". This returns a copy of the real part.
1022 The internal routine "real_i" is faster, since it returns the pointer
1023 and skips the copy.
1024 \subsecidx{round}"(x,{&e})": If "x" is in R, rounds "x" to the nearest
1026 integer and sets "e" to the number of error bits, that is the binary
1027 exponent of the difference between the original and the rounded value
1028 (the ``fractional part''). If the exponent of "x" is too large compared
1029 to its precision (i.e. "e > 0"), the result is undefined and an error
1030 occurs if "e" was not given.
1031 Important remark:. note that, contrary to the other truncation
1033 functions, this function operates on every coefficient at every level
1034 of a PARI object. For example
1035 "truncate((2.4*X^2-1.7)/(X)) = 2.4*X,"
1037 whereas
1039 "round((2.4*X^2-1.7)/(X)) = (2*X^2-2)/(X)."
1041 An important use of "round" is to get exact results after a long
1043 approximate computation, when theory tells you that the coefficients
1044 must be integers.
1045 The library syntax is "grndtoi(x,&e)", where "e" is a "long" integer.
1047 Also available is \funs{ground}{x}.
1048 \subsecidx{simplify}"(x)": this function simplifies "x" as much as it
1050 can. Specifically, a complex or quadratic number whose imaginary part
1051 is an exact 0 (i.e. not an approximate one as a O(3) or "0.E-28") is
1052 converted to its real part, and a polynomial of degree 0 is converted
1053 to its constant term. Simplifications occur recursively.
1054 This function is especially useful before using arithmetic functions,
1056 which expect integer arguments:
1057 ? x = 1 + y - y
1059 %1 = 1
1060 ? divisors(x)
1061 *** divisors: not an integer argument in an arithmetic function
1062 ? type(x)
1063 %2 = "t_POL"
1064 ? type(simplify(x))
1065 %3 = "t_INT"
1066 Note that GP results are simplified as above before they are stored in
1068 the history. (Unless you disable automatic simplification with "\y",
1069 that is.) In particular
1070 ? type(%1)
1072 %4 = "t_INT"
1073 The library syntax is "simplify(x)".
1075 \subsecidx{sizebyte}"(x)": outputs the total number of bytes occupied
1077 by the tree representing the PARI object "x".
1078 The library syntax is "taille2(x)" which returns a "long";
1080 \funs{taille}{x} returns the number of words instead.
1081 \subsecidx{sizedigit}"(x)": outputs a quick bound for the number of
1083 decimal digits of (the components of) "x", off by at most 1. If you
1084 want the exact value, you can use "#Str(x)", which is slower.
1085 The library syntax is "sizedigit(x)" which returns a "long".
1087 \subsecidx{truncate}"(x,{&e})": truncates "x" and sets "e" to the
1089 number of error bits. When "x" is in R, this means that the part after
1090 the decimal point is chopped away, "e" is the binary exponent of the
1091 difference between the original and the truncated value (the
1092 ``fractional part''). If the exponent of "x" is too large compared to
1093 its precision (i.e. "e > 0"), the result is undefined and an error
1094 occurs if "e" was not given. The function applies componentwise on
1095 vector / matrices; "e" is then the maximal number of error bits. If "x"
1096 is a rational function, the result is the ``integer part'' (Euclidean
1097 quotient of numerator by denominator) and "e" is not set.
1098 Note a very special use of "truncate": when applied to a power series,
1100 it transforms it into a polynomial or a rational function with
1101 denominator a power of "X", by chopping away the "O(X^k)". Similarly,
1102 when applied to a "p"-adic number, it transforms it into an integer or
1103 a rational number by chopping away the "O(p^k)".
1104 The library syntax is "gcvtoi(x,&e)", where "e" is a "long" integer.
1106 Also available is \funs{gtrunc}{x}.
1107 \subsecidx{valuation}"(x,p)": computes the highest exponent of "p"
1109 dividing "x". If "p" is of type integer, "x" must be an integer, an
1110 intmod whose modulus is divisible by "p", a fraction, a "q"-adic number
1111 with "q = p", or a polynomial or power series in which case the
1112 valuation is the minimum of the valuation of the coefficients.
1113 If "p" is of type polynomial, "x" must be of type polynomial or
1115 rational function, and also a power series if "x" is a monomial.
1116 Finally, the valuation of a vector, complex or quadratic number is the
1117 minimum of the component valuations.
1118 If "x = 0", the result is "VERYBIGINT" ("2^{31}-1" for 32-bit machines
1120 or "2^{63}-1" for 64-bit machines) if "x" is an exact object. If "x" is
1121 a "p"-adic numbers or power series, the result is the exponent of the
1122 zero. Any other type combinations gives an error.
1123 The library syntax is "ggval(x,p)", and the result is a "long".
1125 \subsecidx{variable}"(x)": gives the main variable of the object "x",
1127 and "p" if "x" is a "p"-adic number. Gives an error if "x" has no
1128 variable associated to it. Note that this function is useful only in
1129 GP, since in library mode the function "gvar" is more appropriate.
1130 The library syntax is "gpolvar(x)". However, in library mode, this
1132 function should not be used. Instead, test whether "x" is a "p"-adic
1133 (type "t_PADIC"), in which case "p" is in "x[2]", or call the function
1134 \funs{gvar}{x} which returns the variable number of "x" if it exists,
1135 "BIGINT" otherwise.
1136
1138 As a general rule, which of course in some cases may have exceptions,
1139 transcendental functions operate in the following way:
1140 * If the argument is either an integer, a real, a rational, a complex
1142 or a quadratic number, it is, if necessary, first converted to a real
1143 (or complex) number using the current precision held in the default
1144 "realprecision". Note that only exact arguments are converted, while
1145 inexact arguments such as reals are not.
1146 In GP this is transparent to the user, but when programming in library
1148 mode, care must be taken to supply a meaningful parameter prec as the
1149 last argument of the function if the first argument is an exact object.
1150 This parameter is ignored if the argument is inexact.
1151 Note that in library mode the precision argument prec is a word count
1153 including codewords, i.e. represents the length in words of a real
1154 number, while under "gp" the precision (which is changed by the
1155 metacommand "\p" or using "default(realprecision,...)") is the number
1156 of significant decimal digits.
1157 Note that some accuracies attainable on 32-bit machines cannot be
1159 attained on 64-bit machines for parity reasons. For example the default
1160 "gp" accuracy is 28 decimal digits on 32-bit machines, corresponding to
1161 prec having the value 5, but this cannot be attained on 64-bit
1162 machines.
1163 After possible conversion, the function is computed. Note that even if
1165 the argument is real, the result may be complex (e.g. "acos(2.0)" or
1166 "acosh(0.0)"). Note also that the principal branch is always chosen.
1167 * If the argument is an intmod or a "p"-adic, at present only a few
1169 functions like "sqrt" (square root), "sqr" (square), "log", "exp",
1170 powering, "teichmuller" (Teichmüller character) and "agm" (arithmetic-
1171 geometric mean) are implemented.
1172 Note that in the case of a 2-adic number, sqr(x) may not be identical
1174 to "x*x": for example if "x = 1+O(2^5)" and "y = 1+O(2^5)" then "x*y =
1175 1+O(2^5)" while "sqr(x) = 1+O(2^6)". Here, "x * x" yields the same
1176 result as sqr(x) since the two operands are known to be identical. The
1177 same statement holds true for "p"-adics raised to the power "n", where
1178 "v_p(n) > 0".
1179 Remark:. note that if we wanted to be strictly consistent with the PARI
1181 philosophy, we should have "x*y = (4 mod 8)" and "sqr(x) = (4 mod 32)"
1182 when both "x" and "y" are congruent to 2 modulo 4. However, since
1183 intmod is an exact object, PARI assumes that the modulus must not
1184 change, and the result is hence "(0 mod 4)" in both cases. On the other
1185 hand, "p"-adics are not exact objects, hence are treated differently.
1186 * If the argument is a polynomial, power series or rational function,
1188 it is, if necessary, first converted to a power series using the
1189 current precision held in the variable "precdl". Under "gp" this again
1190 is transparent to the user. When programming in library mode, however,
1191 the global variable "precdl" must be set before calling the function if
1192 the argument has an exact type (i.e. not a power series). Here "precdl"
1193 is not an argument of the function, but a global variable.
1194 Then the Taylor series expansion of the function around "X = 0" (where
1196 "X" is the main variable) is computed to a number of terms depending on
1197 the number of terms of the argument and the function being computed.
1198 * If the argument is a vector or a matrix, the result is the
1200 componentwise evaluation of the function. In particular, transcendental
1201 functions on square matrices, which are not implemented in the present
1202 version /usr/share/libpari23, will have a different name if they are
1203 implemented some day.
1204 ^
1206 If "y" is not of type integer, "x^y" has the same effect as
1207 "exp(y*log(x))". It can be applied to "p"-adic numbers as well as to
1208 the more usual types.
1209 The library syntax is "gpow(x,y,prec)".
1211 \subsecidx{Euler}: Euler's constant "gamma = 0.57721...". Note that
1213 "Euler" is one of the few special reserved names which cannot be used
1214 for variables (the others are "I" and "Pi", as well as all function
1215 names).
1216 The library syntax is "mpeuler(prec)" where "prec" must be given. Note
1218 that this creates "gamma" on the PARI stack, but a copy is also created
1219 on the heap for quicker computations next time the function is called.
1220 \subsecidx{I}: the complex number " sqrt {-1}".
1222 The library syntax is the global variable "gi" (of type "GEN").
1224 \subsecidx{Pi}: the constant "pi" (3.14159...).
1226 The library syntax is "mppi(prec)" where "prec" must be given. Note
1228 that this creates "pi" on the PARI stack, but a copy is also created on
1229 the heap for quicker computations next time the function is called.
1230 \subsecidx{abs}"(x)": absolute value of "x" (modulus if "x" is
1232 complex). Rational functions are not allowed. Contrary to most
1233 transcendental functions, an exact argument is not converted to a real
1234 number before applying "abs" and an exact result is returned if
1235 possible.
1236 ? abs(-1)
1238 %1 = 1
1239 ? abs(3/7 + 4/7*I)
1240 %2 = 5/7
1241 ? abs(1 + I)
1242 %3 = 1.414213562373095048801688724
1243 If "x" is a polynomial, returns "-x" if the leading coefficient is real
1245 and negative else returns "x". For a power series, the constant
1246 coefficient is considered instead.
1247 The library syntax is "gabs(x,prec)".
1249 \subsecidx{acos}"(x)": principal branch of "cos^{-1}(x)", i.e. such
1251 that "{Re(acos}(x))\in [0,pi]". If "x\in R" and "|x| > 1", then acos(x)
1252 is complex.
1253 The library syntax is "gacos(x,prec)".
1255 \subsecidx{acosh}"(x)": principal branch of "cosh^{-1}(x)", i.e. such
1257 that "{Im(acosh}(x))\in [0,pi]". If "x\in R" and "x < 1", then acosh(x)
1258 is complex.
1259 The library syntax is "gach(x,prec)".
1261 \subsecidx{agm}"(x,y)": arithmetic-geometric mean of "x" and "y". In
1263 the case of complex or negative numbers, the principal square root is
1264 always chosen. "p"-adic or power series arguments are also allowed.
1265 Note that a "p"-adic agm exists only if "x/y" is congruent to 1 modulo
1266 "p" (modulo 16 for "p = 2"). "x" and "y" cannot both be vectors or
1267 matrices.
1268 The library syntax is "agm(x,y,prec)".
1270 \subsecidx{arg}"(x)": argument of the complex number "x", such that
1272 "-pi < arg(x) <= pi".
1273 The library syntax is "garg(x,prec)".
1275 \subsecidx{asin}"(x)": principal branch of "sin^{-1}(x)", i.e. such
1277 that "{Re(asin}(x))\in [-pi/2,pi/2]". If "x\in R" and "|x| > 1" then
1278 asin(x) is complex.
1279 The library syntax is "gasin(x,prec)".
1281 \subsecidx{asinh}"(x)": principal branch of "sinh^{-1}(x)", i.e. such
1283 that "{Im(asinh}(x))\in [-pi/2,pi/2]".
1284 The library syntax is "gash(x,prec)".
1286 \subsecidx{atan}"(x)": principal branch of "tan^{-1}(x)", i.e. such
1288 that "{Re(atan}(x))\in ]-pi/2,pi/2[".
1289 The library syntax is "gatan(x,prec)".
1291 \subsecidx{atanh}"(x)": principal branch of "tanh^{-1}(x)", i.e. such
1293 that "{Im(atanh}(x))\in ]-pi/2,pi/2]". If "x\in R" and "|x| > 1" then
1294 atanh(x) is complex.
1295 The library syntax is "gath(x,prec)".
1297 \subsecidx{bernfrac}"(x)": Bernoulli number "B_x", where "B_0 = 1",
1299 "B_1 = -1/2", "B_2 = 1/6",..., expressed as a rational number. The
1300 argument "x" should be of type integer.
1301 The library syntax is "bernfrac(x)".
1303 \subsecidx{bernreal}"(x)": Bernoulli number "B_x", as "bernfrac", but
1305 "B_x" is returned as a real number (with the current precision).
1306 The library syntax is "bernreal(x,prec)".
1308 \subsecidx{bernvec}"(x)": creates a vector containing, as rational
1310 numbers, the Bernoulli numbers "B_0", "B_2",..., "B_{2x}". This
1311 routine is obsolete. Use "bernfrac" instead each time you need a
1312 Bernoulli number in exact form.
1313 Note:. this routine is implemented using repeated independent calls to
1315 "bernfrac", which is faster than the standard recursion in exact
1316 arithmetic. It is only kept for backward compatibility: it is not
1317 faster than individual calls to "bernfrac", its output uses a lot of
1318 memory space, and coping with the index shift is awkward.
1319 The library syntax is "bernvec(x)".
1321 \subsecidx{besselh1}"(nu,x)": "H^1"-Bessel function of index nu and
1323 argument "x".
1324 The library syntax is "hbessel1(nu,x,prec)".
1326 \subsecidx{besselh2}"(nu,x)": "H^2"-Bessel function of index nu and
1328 argument "x".
1329 The library syntax is "hbessel2(nu,x,prec)".
1331 \subsecidx{besseli}"(nu,x)": "I"-Bessel function of index nu and
1333 argument "x". If "x" converts to a power series, the initial factor
1334 "(x/2)^nu/Gamma(nu+1)" is omitted (since it cannot be represented in
1335 PARI when "nu" is not integral).
1336 The library syntax is "ibessel(nu,x,prec)".
1338 \subsecidx{besselj}"(nu,x)": "J"-Bessel function of index nu and
1340 argument "x". If "x" converts to a power series, the initial factor
1341 "(x/2)^nu/Gamma(nu+1)" is omitted (since it cannot be represented in
1342 PARI when "nu" is not integral).
1343 The library syntax is "jbessel(nu,x,prec)".
1345 \subsecidx{besseljh}"(n,x)": "J"-Bessel function of half integral
1347 index. More precisely, "besseljh(n,x)" computes "J_{n+1/2}(x)" where
1348 "n" must be of type integer, and "x" is any element of C. In the
1349 present version /usr/share/libpari23, this function is not very
1350 accurate when "x" is small.
1351 The library syntax is "jbesselh(n,x,prec)".
1353 \subsecidx{besselk}"(nu,x,{flag = 0})": "K"-Bessel function of index nu
1355 (which can be complex) and argument "x". Only real and positive
1356 arguments "x" are allowed in the present version /usr/share/libpari23.
1357 If "flag" is equal to 1, uses another implementation of this function
1358 which is faster when "x >> 1".
1359 The library syntax is "kbessel(nu,x,prec)" and
1361 \funs{kbessel2}{nu,x,prec} respectively.
1362 \subsecidx{besseln}"(nu,x)": "N"-Bessel function of index nu and
1364 argument "x".
1365 The library syntax is "nbessel(nu,x,prec)".
1367 \subsecidx{cos}"(x)": cosine of "x".
1369 The library syntax is "gcos(x,prec)".
1371 \subsecidx{cosh}"(x)": hyperbolic cosine of "x".
1373 The library syntax is "gch(x,prec)".
1375 \subsecidx{cotan}"(x)": cotangent of "x".
1377 The library syntax is "gcotan(x,prec)".
1379 \subsecidx{dilog}"(x)": principal branch of the dilogarithm of "x",
1381 i.e. analytic continuation of the power series " log _2(x) = sum_{n >=
1382 1}x^n/n^2".
1383 The library syntax is "dilog(x,prec)".
1385 \subsecidx{eint1}"(x,{n})": exponential integral "int_x^ oo
1387 (e^{-t})/(t)dt" ("x\in R")
1388 If "n" is present, outputs the "n"-dimensional vector
1390 "[eint1(x),...,eint1(nx)]" ("x >= 0"). This is faster than repeatedly
1391 calling "eint1(i * x)".
1392 The library syntax is "veceint1(x,n,prec)". Also available is
1394 \funs{eint1}{x,prec}.
1395 \subsecidx{erfc}"(x)": complementary error function "(2/ sqrt pi)int_x^
1397 oo e^{-t^2}dt" ("x\in R").
1398 The library syntax is "erfc(x,prec)".
1400 \subsecidx{eta}"(x,{flag = 0})": Dedekind's "eta" function, without the
1402 "q^{1/24}". This means the following: if "x" is a complex number with
1403 positive imaginary part, the result is "prod_{n = 1}^ oo (1-q^n)",
1404 where "q = e^{2ipi x}". If "x" is a power series (or can be converted
1405 to a power series) with positive valuation, the result is "prod_{n =
1406 1}^ oo (1-x^n)".
1407 If "flag = 1" and "x" can be converted to a complex number (i.e. is not
1409 a power series), computes the true "eta" function, including the
1410 leading "q^{1/24}".
1411 The library syntax is "eta(x,prec)".
1413 \subsecidx{exp}"(x)": exponential of "x". "p"-adic arguments with
1415 positive valuation are accepted.
1416 The library syntax is "gexp(x,prec)".
1418 \subsecidx{gammah}"(x)": gamma function evaluated at the argument
1420 "x+1/2".
1421 The library syntax is "ggamd(x,prec)".
1423 \subsecidx{gamma}"(x)": gamma function of "x".
1425 The library syntax is "ggamma(x,prec)".
1427 \subsecidx{hyperu}"(a,b,x)": "U"-confluent hypergeometric function with
1429 parameters "a" and "b". The parameters "a" and "b" can be complex but
1430 the present implementation requires "x" to be positive.
1431 The library syntax is "hyperu(a,b,x,prec)".
1433 \subsecidx{incgam}"(s,x,{y})": incomplete gamma function. The argument
1435 "x" and "s" are complex numbers ("x" must be a positive real number if
1436 "s = 0"). The result returned is "int_x^ oo e^{-t}t^{s-1}dt". When "y"
1437 is given, assume (of course without checking!) that "y = Gamma(s)". For
1438 small "x", this will speed up the computation.
1439 The library syntax is "incgam(s,x,prec)" and
1441 \funs{incgam0}{s,x,y,prec}, respectively (an omitted "y" is coded as
1442 "NULL").
1443 \subsecidx{incgamc}"(s,x)": complementary incomplete gamma function.
1445 The arguments "x" and "s" are complex numbers such that "s" is not a
1446 pole of "Gamma" and "|x|/(|s|+1)" is not much larger than 1 (otherwise
1447 the convergence is very slow). The result returned is "int_0^x
1448 e^{-t}t^{s-1}dt".
1449 The library syntax is "incgamc(s,x,prec)".
1451 \subsecidx{log}"(x)": principal branch of the natural logarithm of "x",
1453 i.e. such that "{Im(log}(x))\in ]-pi,pi]". The result is complex (with
1454 imaginary part equal to "pi") if "x\in R" and "x < 0". In general, the
1455 algorithm uses the formula
1456 " log (x) ~ (pi)/(2agm(1, 4/s)) - m log 2, "
1458 if "s = x 2^m" is large enough. (The result is exact to "B" bits
1460 provided "s > 2^{B/2}".) At low accuracies, the series expansion near 1
1461 is used.
1462 "p"-adic arguments are also accepted for "x", with the convention that
1464 " log (p) = 0". Hence in particular " exp ( log (x))/x" is not in
1465 general equal to 1 but to a "(p-1)"-th root of unity (or "+-1" if "p =
1466 2") times a power of "p".
1467 The library syntax is "glog(x,prec)".
1469 \subsecidx{lngamma}"(x)": principal branch of the logarithm of the
1471 gamma function of "x". This function is analytic on the complex plane
1472 with non-positive integers removed. Can have much larger arguments than
1473 "gamma" itself. The "p"-adic "lngamma" function is not implemented.
1474 The library syntax is "glngamma(x,prec)".
1476 \subsecidx{polylog}"(m,x,{flag = 0})": one of the different
1478 polylogarithms, depending on flag:
1479 If "flag = 0" or is omitted: "m-th" polylogarithm of "x", i.e. analytic
1481 continuation of the power series "Li_m(x) = sum_{n >= 1}x^n/n^m" ("x <
1482 1"). Uses the functional equation linking the values at "x" and "1/x"
1483 to restrict to the case "|x| <= 1", then the power series when "|x|^2
1484 <= 1/2", and the power series expansion in " log (x)" otherwise.
1485 Using "flag", computes a modified "m-th" polylogarithm of "x". We use
1487 Zagier's notations; let " Re _m" denotes " Re " or " Im " depending
1488 whether "m" is odd or even:
1489 If "flag = 1": compute "~ D_m(x)", defined for "|x| <= 1" by
1491 " Re _m(sum_{k = 0}^{m-1} ((- log |x|)^k)/(k!)Li_{m-k}(x) +((- log
1493 |x|)^{m-1})/(m!) log |1-x|)."
1494 If "flag = 2": compute D_m(x), defined for "|x| <= 1" by
1496 " Re _m(sum_{k = 0}^{m-1}((- log |x|)^k)/(k!)Li_{m-k}(x) -(1)/(2)((-
1498 log |x|)^m)/(m!))."
1499 If "flag = 3": compute P_m(x), defined for "|x| <= 1" by
1501 " Re _m(sum_{k = 0}^{m-1}(2^kB_k)/(k!)( log |x|)^kLi_{m-k}(x)
1503 -(2^{m-1}B_m)/(m!)( log |x|)^m)."
1504 These three functions satisfy the functional equation "f_m(1/x) =
1506 (-1)^{m-1}f_m(x)".
1507 The library syntax is "polylog0(m,x,flag,prec)".
1509 \subsecidx{psi}"(x)": the "psi"-function of "x", i.e. the logarithmic
1511 derivative "Gamma'(x)/Gamma(x)".
1512 The library syntax is "gpsi(x,prec)".
1514 \subsecidx{sin}"(x)": sine of "x".
1516 The library syntax is "gsin(x,prec)".
1518 \subsecidx{sinh}"(x)": hyperbolic sine of "x".
1520 The library syntax is "gsh(x,prec)".
1522 \subsecidx{sqr}"(x)": square of "x". This operation is not completely
1524 straightforward, i.e. identical to "x * x", since it can usually be
1525 computed more efficiently (roughly one-half of the elementary
1526 multiplications can be saved). Also, squaring a 2-adic number increases
1527 its precision. For example,
1528 ? (1 + O(2^4))^2
1530 %1 = 1 + O(2^5)
1531 ? (1 + O(2^4)) * (1 + O(2^4))
1532 %2 = 1 + O(2^4)
1533 Note that this function is also called whenever one multiplies two
1535 objects which are known to be identical, e.g. they are the value of the
1536 same variable, or we are computing a power.
1537 ? x = (1 + O(2^4)); x * x
1539 %3 = 1 + O(2^5)
1540 ? (1 + O(2^4))^4
1541 %4 = 1 + O(2^6)
1542 (note the difference between %2 and %3 above).
1544 The library syntax is "gsqr(x)".
1546 \subsecidx{sqrt}"(x)": principal branch of the square root of "x",
1548 i.e. such that "Arg(sqrt(x))\in ]-pi/2, pi/2]", or in other words such
1549 that " Re (sqrt(x)) > 0" or " Re (sqrt(x)) = 0" and " Im (sqrt(x)) >=
1550 0". If "x\in R" and "x < 0", then the result is complex with positive
1551 imaginary part.
1552 Intmod a prime and "p"-adics are allowed as arguments. In that case,
1554 the square root (if it exists) which is returned is the one whose first
1555 "p"-adic digit (or its unique "p"-adic digit in the case of intmods) is
1556 in the interval "[0,p/2]". When the argument is an intmod a non-prime
1557 (or a non-prime-adic), the result is undefined.
1558 The library syntax is "gsqrt(x,prec)".
1560 \subsecidx{sqrtn}"(x,n,{&z})": principal branch of the "n"th root of
1562 "x", i.e. such that "Arg(sqrt(x))\in ]-pi/n, pi/n]". Intmod a prime and
1563 "p"-adics are allowed as arguments.
1564 If "z" is present, it is set to a suitable root of unity allowing to
1566 recover all the other roots. If it was not possible, z is set to zero.
1567 In the case this argument is present and no square root exist, 0 is
1568 returned instead or raising an error.
1569 ? sqrtn(Mod(2,7), 2)
1571 %1 = Mod(4, 7)
1572 ? sqrtn(Mod(2,7), 2, &z); z
1573 %2 = Mod(6, 7)
1574 ? sqrtn(Mod(2,7), 3)
1575 *** sqrtn: nth-root does not exist in gsqrtn.
1576 ? sqrtn(Mod(2,7), 3, &z)
1577 %2 = 0
1578 ? z
1579 %3 = 0
1580 The following script computes all roots in all possible cases:
1582 sqrtnall(x,n)=
1584 {
1585 local(V,r,z,r2);
1586 r = sqrtn(x,n, &z);
1587 if (!z, error("Impossible case in sqrtn"));
1588 if (type(x) == "t_INTMOD" || type(x)=="t_PADIC" ,
1589 r2 = r*z; n = 1;
1590 while (r2!=r, r2*=z;n++));
1591 V = vector(n); V[1] = r;
1592 for(i=2, n, V[i] = V[i-1]*z);
1593 V
1594 }
1595 addhelp(sqrtnall,"sqrtnall(x,n):compute the vector of nth-roots of x");
1596 The library syntax is "gsqrtn(x,n,&z,prec)".
1598 \subsecidx{tan}"(x)": tangent of "x".
1600 The library syntax is "gtan(x,prec)".
1602 \subsecidx{tanh}"(x)": hyperbolic tangent of "x".
1604 The library syntax is "gth(x,prec)".
1606 \subsecidx{teichmuller}"(x)": Teichmüller character of the "p"-adic
1608 number "x", i.e. the unique "(p-1)"-th root of unity congruent to "x /
1609 p^{v_p(x)}" modulo "p".
1610 The library syntax is "teich(x)".
1612 \subsecidx{theta}"(q,z)": Jacobi sine theta-function.
1614 The library syntax is "theta(q,z,prec)".
1616 \subsecidx{thetanullk}"(q,k)": "k"-th derivative at "z = 0" of
1618 "theta(q,z)".
1619 The library syntax is "thetanullk(q,k,prec)", where "k" is a "long".
1621 \subsecidx{weber}"(x,{flag = 0})": one of Weber's three "f" functions.
1623 If "flag = 0", returns
1624 "f(x) = exp (-ipi/24).eta((x+1)/2)/eta(x) such that j =
1626 (f^{24}-16)^3/f^{24},"
1627 where "j" is the elliptic "j"-invariant (see the function "ellj"). If
1629 "flag = 1", returns
1630 "f_1(x) = eta(x/2)/eta(x) such that j = (f_1^{24}+16)^3/f_1^{24}."
1632 Finally, if "flag = 2", returns
1634 "f_2(x) = sqrt {2}eta(2x)/eta(x) such that j =
1636 (f_2^{24}+16)^3/f_2^{24}."
1637 Note the identities "f^8 = f_1^8+f_2^8" and "ff_1f_2 = sqrt 2".
1639 The library syntax is "weber0(x,flag,prec)". Associated to the various
1641 values of flag, the following functions are also available:
1642 \funs{werberf}{x,prec}, \funs{werberf1}{x,prec} or
1643 \funs{werberf2}{x,prec}.
1644 \subsecidx{zeta}"(s)": For "s" a complex number, Riemann's zeta
1646 function "zeta(s) = sum_{n >= 1}n^{-s}", computed using the Euler-
1647 Maclaurin summation formula, except when "s" is of type integer, in
1648 which case it is computed using Bernoulli numbers for "s <= 0" or "s >
1649 0" and even, and using modular forms for "s > 0" and odd.
1650 For "s" a "p"-adic number, Kubota-Leopoldt zeta function at "s", that
1652 is the unique continuous "p"-adic function on the "p"-adic integers
1653 that interpolates the values of "(1 - p^{-k}) zeta(k)" at negative
1654 integers "k" such that "k = 1 (mod p-1)" (resp. "k" is odd) if "p" is
1655 odd (resp. "p = 2").
1656 The library syntax is "gzeta(s,prec)".
1658
1660 These functions are by definition functions whose natural domain of
1661 definition is either Z (or "Z_{ > 0}"), or sometimes polynomials over a
1662 base ring. Functions which concern polynomials exclusively will be
1663 explained in the next section. The way these functions are used is
1664 completely different from transcendental functions: in general only the
1665 types integer and polynomial are accepted as arguments. If a vector or
1666 matrix type is given, the function will be applied on each coefficient
1667 independently.
1668 In the present version /usr/share/libpari23, all arithmetic functions
1670 in the narrow sense of the word --- Euler's totient function, the
1671 Moebius function, the sums over divisors or powers of divisors etc.---
1672 call, after trial division by small primes, the same versatile
1673 factoring machinery described under "factorint". It includes Shanks
1674 SQUFOF, Pollard Rho, ECM and MPQS stages, and has an early exit option
1675 for the functions moebius and (the integer function underlying)
1676 issquarefree. Note that it relies on a (fairly strong) probabilistic
1677 primality test, see "ispseudoprime".
1678 \subsecidx{addprimes}"({x = []})": adds the integers contained in the
1680 vector "x" (or the single integer "x") to a special table of
1681 ``user-defined primes'', and returns that table. Whenever "factor" is
1682 subsequently called, it will trial divise by the elements in this
1683 table. If "x" is empty or omitted, just returns the current list of
1684 extra primes.
1685 The entries in "x" are not checked for primality, and in fact they need
1687 only be positive integers. The algorithm makes sure that all elements
1688 in the table are pairwise coprime, so it may end up containing divisors
1689 of the input integers.
1690 It is a useful trick to add known composite numbers, which the function
1692 "factor(x,0)" was not able to factor. In case the message ``impossible
1693 inverse modulo "<"some INTMOD">"'' shows up afterwards, you have just
1694 stumbled over a non-trivial factor. Note that the arithmetic functions
1695 in the narrow sense, like eulerphi, do not use this extra table.
1696 To remove primes from the list use "removeprimes".
1698 The library syntax is "addprimes(x)".
1700 \subsecidx{bestappr}"(x,A,{B})": if "B" is omitted, finds the best
1702 rational approximation to "x\in R" (or "R[X]", or "R^n",...) with
1703 denominator at most equal to "A" using continued fractions.
1704 If "B" is present, "x" is assumed to be of type "t_INTMOD" modulo "M"
1706 (or a recursive combination of those), and the routine returns the
1707 unique fraction "a/b" in coprime integers "a <= A" and "b <= B" which
1708 is congruent to "x" modulo "M". If "M <= 2AB", uniqueness is not
1709 guaranteed and the function fails with an error message. If rational
1710 reconstruction is not possible (no such "a/b" exists for at least one
1711 component of "x"), returns "-1".
1712 The library syntax is "bestappr0(x,A,B)". Also available is
1714 \funs{bestappr}{x,A} corresponding to an omitted "B".
1715 \subsecidx{bezout}"(x,y)": finds "u" and "v" minimal in a natural sense
1717 such that "x*u+y*v = gcd (x,y)". The arguments must be both integers
1718 or both polynomials, and the result is a row vector with three
1719 components "u", "v", and " gcd (x,y)".
1720 The library syntax is "vecbezout(x,y)" to get the vector, or
1722 \funs{gbezout}{x,y, &u, &v} which gives as result the address of the
1723 created gcd, and puts the addresses of the corresponding created
1724 objects into "u" and "v".
1725 \subsecidx{bezoutres}"(x,y)": as "bezout", with the resultant of "x"
1727 and "y" replacing the gcd. The algorithm uses (subresultant) assumes
1728 the base ring is a domain.
1729 The library syntax is "vecbezoutres(x,y)" to get the vector, or
1731 \funs{subresext}{x,y, &u, &v} which gives as result the address of the
1732 created gcd, and puts the addresses of the corresponding created
1733 objects into "u" and "v".
1734 \subsecidx{bigomega}"(x)": number of prime divisors of "|x|" counted
1736 with multiplicity. "x" must be an integer.
1737 The library syntax is "bigomega(x)", the result is a "long".
1739 \subsecidx{binomial}"(x,y)": binomial coefficient "binom{x}{y}". Here
1741 "y" must be an integer, but "x" can be any PARI object.
1742 The library syntax is "binomial(x,y)", where "y" must be a "long".
1744 \subsecidx{chinese}"(x,{y})": if "x" and "y" are both intmods or both
1746 polmods, creates (with the same type) a "z" in the same residue class
1747 as "x" and in the same residue class as "y", if it is possible.
1748 This function also allows vector and matrix arguments, in which case
1750 the operation is recursively applied to each component of the vector or
1751 matrix. For polynomial arguments, it is applied to each coefficient.
1752 If "y" is omitted, and "x" is a vector, "chinese" is applied
1754 recursively to the components of "x", yielding a residue belonging to
1755 the same class as all components of "x".
1756 Finally "chinese(x,x) = x" regardless of the type of "x"; this allows
1758 vector arguments to contain other data, so long as they are identical
1759 in both vectors.
1760 The library syntax is "chinese(x,y)". Also available is
1762 "chinese1""(x)", corresponding to an ommitted "y".
1763 \subsecidx{content}"(x)": computes the gcd of all the coefficients of
1765 "x", when this gcd makes sense. This is the natural definition if "x"
1766 is a polynomial (and by extension a power series) or a vector/matrix.
1767 This is in general a weaker notion than the ideal generated by the
1768 coefficients:
1769 ? content(2*x+y)
1771 %1 = 1 \\ = gcd(2,y) over Q[y]
1772 If "x" is a scalar, this simply returns the absolute value of "x" if
1774 "x" is rational ("t_INT" or "t_FRAC"), and either 1 (inexact input) or
1775 "x" (exact input) otherwise; the result should be identical to "gcd(x,
1776 0)".
1777 The content of a rational function is the ratio of the contents of the
1779 numerator and the denominator. In recursive structures, if a matrix or
1780 vector coefficient "x" appears, the gcd is taken not with "x", but with
1781 its content:
1782 ? content([ [2], 4*matid(3) ])
1784 %1 = 2
1785 The library syntax is "content(x)".
1787 \subsecidx{contfrac}"(x,{b},{nmax})": creates the row vector whose
1789 components are the partial quotients of the continued fraction
1790 expansion of "x". That is a result "[a_0,...,a_n]" means that "x ~
1791 a_0+1/(a_1+...+1/a_n)...)". The output is normalized so that "a_n != 1"
1792 (unless we also have "n = 0").
1793 The number of partial quotients "n" is limited to "nmax". If "x" is a
1795 real number, the expansion stops at the last significant partial
1796 quotient if "nmax" is omitted. "x" can also be a rational function or a
1797 power series.
1798 If a vector "b" is supplied, the numerators will be equal to the
1800 coefficients of "b" (instead of all equal to 1 as above). The length of
1801 the result is then equal to the length of "b", unless a partial
1802 remainder is encountered which is equal to zero, in which case the
1803 expansion stops. In the case of real numbers, the stopping criterion is
1804 thus different from the one mentioned above since, if "b" is too long,
1805 some partial quotients may not be significant.
1806 If "b" is an integer, the command is understood as "contfrac(x,nmax)".
1808 The library syntax is "contfrac0(x,b,nmax)". Also available are
1810 \funs{gboundcf}{x,nmax}, \funs{gcf}{x}, or \funs{gcf2}{b,x}, where
1811 "nmax" is a C integer.
1812 \subsecidx{contfracpnqn}"(x)": when "x" is a vector or a one-row
1814 matrix, "x" is considered as the list of partial quotients
1815 "[a_0,a_1,...,a_n]" of a rational number, and the result is the 2 by 2
1816 matrix "[p_n,p_{n-1};q_n,q_{n-1}]" in the standard notation of
1817 continued fractions, so "p_n/q_n = a_0+1/(a_1+...+1/a_n)...)". If "x"
1818 is a matrix with two rows "[b_0,b_1,...,b_n]" and "[a_0,a_1,...,a_n]",
1819 this is then considered as a generalized continued fraction and we have
1820 similarly "p_n/q_n = 1/b_0(a_0+b_1/(a_1+...+b_n/a_n)...)". Note that in
1821 this case one usually has "b_0 = 1".
1822 The library syntax is "pnqn(x)".
1824 \subsecidx{core}"(n,{flag = 0})": if "n" is a non-zero integer written
1826 as "n = df^2" with "d" squarefree, returns "d". If "flag" is non-zero,
1827 returns the two-element row vector "[d,f]".
1828 The library syntax is "core0(n,flag)". Also available are
1830 \funs{core}{n} ( = \funs{core0}{n,0}) and \funs{core2}{n} ( =
1831 \funs{core0}{n,1}).
1832 \subsecidx{coredisc}"(n,{flag})": if "n" is a non-zero integer written
1834 as "n = df^2" with "d" fundamental discriminant (including 1), returns
1835 "d". If "flag" is non-zero, returns the two-element row vector "[d,f]".
1836 Note that if "n" is not congruent to 0 or 1 modulo 4, "f" will be a
1837 half integer and not an integer.
1838 The library syntax is "coredisc0(n,flag)". Also available are
1840 \funs{coredisc}{n} ( = \funs{coredisc}{n,0}) and \funs{coredisc2}{n} (
1841 = \funs{coredisc}{n,1}).
1842 \subsecidx{dirdiv}"(x,y)": "x" and "y" being vectors of perhaps
1844 different lengths but with "y[1] != 0" considered as Dirichlet series,
1845 computes the quotient of "x" by "y", again as a vector.
1846 The library syntax is "dirdiv(x,y)".
1848 \subsecidx{direuler}"(p = a,b,expr,{c})": computes the Dirichlet series
1850 associated to the Euler product of expression expr as "p" ranges
1851 through the primes from "a" to "b". expr must be a polynomial or
1852 rational function in another variable than "p" (say "X") and "expr(X)"
1853 is understood as the local factor "expr(p^{-s})".
1854 The series is output as a vector of coefficients. If "c" is present,
1856 output only the first "c" coefficients in the series. The following
1857 command computes the sigma function, associated to "zeta(s)zeta(s-1)":
1858 ? direuler(p=2, 10, 1/((1-X)*(1-p*X)))
1860 %1 = [1, 3, 4, 7, 6, 12, 8, 15, 13, 18]
1861 The library syntax is "direuler(void *E, GEN (*eval)(GEN,void*), GEN a,
1863 GEN b)"
1864 \subsecidx{dirmul}"(x,y)": "x" and "y" being vectors of perhaps
1866 different lengths considered as Dirichlet series, computes the product
1867 of "x" by "y", again as a vector.
1868 The library syntax is "dirmul(x,y)".
1870 \subsecidx{divisors}"(x)": creates a row vector whose components are
1872 the divisors of "x". The factorization of "x" (as output by "factor")
1873 can be used instead.
1874 By definition, these divisors are the products of the irreducible
1876 factors of "n", as produced by factor(n), raised to appropriate powers
1877 (no negative exponent may occur in the factorization). If "n" is an
1878 integer, they are the positive divisors, in increasing order.
1879 The library syntax is "divisors(x)".
1881 \subsecidx{eulerphi}"(x)": Euler's "phi" (totient) function of "|x|",
1883 in other words "|(Z/xZ)^*|". "x" must be of type integer.
1884 The library syntax is "phi(x)".
1886 \subsecidx{factor}"(x,{lim = -1})": general factorization function. If
1888 "x" is of type integer, rational, polynomial or rational function, the
1889 result is a two-column matrix, the first column being the irreducibles
1890 dividing "x" (prime numbers or polynomials), and the second the
1891 exponents. If "x" is a vector or a matrix, the factoring is done
1892 componentwise (hence the result is a vector or matrix of two-column
1893 matrices). By definition, 0 is factored as "0^1".
1894 If "x" is of type integer or rational, the factors are pseudoprimes
1896 (see "ispseudoprime"), and in general not rigorously proven primes. In
1897 fact, any factor which is " <= 10^{13}" is a genuine prime number. Use
1898 "isprime" to prove primality of other factors, as in
1899 fa = factor(2^2^7 +1)
1901 isprime( fa[,1] )
1902 An argument lim can be added, meaning that we look only for prime
1904 factors "p < lim", or up to "primelimit", whichever is lowest (except
1905 when "lim = 0" where the effect is identical to setting "lim =
1906 primelimit"). In this case, the remaining part may actually be a proven
1907 composite! See "factorint" for more information about the algorithms
1908 used.
1909 The polynomials or rational functions to be factored must have scalar
1911 coefficients. In particular PARI does not know how to factor
1912 multivariate polynomials. See "factormod" and "factorff" for the
1913 algorithms used over finite fields, "factornf" for the algorithms over
1914 number fields. Over Q, van Hoeij's method is used, which is able to
1915 cope with hundreds of modular factors.
1916 Note that PARI tries to guess in a sensible way over which ring you
1918 want to factor. Note also that factorization of polynomials is done up
1919 to multiplication by a constant. In particular, the factors of rational
1920 polynomials will have integer coefficients, and the content of a
1921 polynomial or rational function is discarded and not included in the
1922 factorization. If needed, you can always ask for the content
1923 explicitly:
1924 ? factor(t^2 + 5/2*t + 1)
1926 %1 =
1927 [2*t + 1 1]
1928 [t + 2 1]
1930 ? content(t^2 + 5/2*t + 1)
1932 %2 = 1/2
1933 See also "factornf" and "nffactor".
1935 The library syntax is "factor0(x,lim)", where lim is a C integer. Also
1937 available are \funs{factor}{x} ( = \funs{factor0}{x,-1}),
1938 \funs{smallfact}{x} ( = \funs{factor0}{x,0}).
1939 \subsecidx{factorback}"(f,{e},{nf})": gives back the factored object
1941 corresponding to a factorization. The integer 1 corresponds to the
1942 empty factorization. If the last argument is of number field type
1943 (e.g. created by "nfinit"), assume we are dealing with an ideal
1944 factorization in the number field. The resulting ideal product is given
1945 in HNF form.
1946 If "e" is present, "e" and "f" must be vectors of the same length ("e"
1948 being integral), and the corresponding factorization is the product of
1949 the "f[i]^{e[i]}".
1950 If not, and "f" is vector, it is understood as in the preceding case
1952 with "e" a vector of 1 (the product of the "f[i]" is returned).
1953 Finally, "f" can be a regular factorization, as produced with any
1954 "factor" command. A few examples:
1955 ? factorback([2,2; 3,1])
1957 %1 = 12
1958 ? factorback([2,2], [3,1])
1959 %2 = 12
1960 ? factorback([5,2,3])
1961 %3 = 30
1962 ? factorback([2,2], [3,1], nfinit(x^3+2))
1963 %4 =
1964 [16 0 0]
1965 [0 16 0]
1967 [0 0 16]
1969 ? nf = nfinit(x^2+1); fa = idealfactor(nf, 10)
1970 %5 =
1971 [[2, [1, 1]~, 2, 1, [1, 1]~] 2]
1972 [[5, [-2, 1]~, 1, 1, [2, 1]~] 1]
1974 [[5, [2, 1]~, 1, 1, [-2, 1]~] 1]
1976 ? factorback(fa)
1977 *** forbidden multiplication t_VEC * t_VEC.
1978 ? factorback(fa, nf)
1979 %6 =
1980 [10 0]
1981 [0 10]
1983 In the fourth example, 2 and 3 are interpreted as principal ideals in a
1985 cubic field. In the fifth one, "factorback(fa)" is meaningless since we
1986 forgot to indicate the number field, and the entries in the first
1987 column of "fa" can't be multiplied.
1988 The library syntax is "factorback0(f,e,nf)", where an omitted "nf" or
1990 "e" is entered as "NULL". Also available is "factorback""(f,nf)" (case
1991 "e = NULL") where an omitted "nf" is entered as "NULL".
1992 \subsecidx{factorcantor}"(x,p)": factors the polynomial "x" modulo the
1994 prime "p", using distinct degree plus Cantor-Zassenhaus. The
1995 coefficients of "x" must be operation-compatible with "Z/pZ". The
1996 result is a two-column matrix, the first column being the irreducible
1997 polynomials dividing "x", and the second the exponents. If you want
1998 only the degrees of the irreducible polynomials (for example for
1999 computing an "L"-function), use "factormod(x,p,1)". Note that the
2000 "factormod" algorithm is usually faster than "factorcantor".
2001 The library syntax is "factcantor(x,p)".
2003 \subsecidx{factorff}"(x,p,a)": factors the polynomial "x" in the field
2005 "F_q" defined by the irreducible polynomial "a" over "F_p". The
2006 coefficients of "x" must be operation-compatible with "Z/pZ". The
2007 result is a two-column matrix: the first column contains the
2008 irreducible factors of "x", and the second their exponents. If all the
2009 coefficients of "x" are in "F_p", a much faster algorithm is applied,
2010 using the computation of isomorphisms between finite fields.
2011 The library syntax is "factorff(x,p,a)".
2013 \subsecidx{factorial}"(x)" or "x!": factorial of "x". The expression
2015 "x!" gives a result which is an integer, while factorial(x) gives a
2016 real number.
2017 The library syntax is "mpfact(x)" for "x!" and \funs{mpfactr}{x,prec}
2019 for factorial(x). "x" must be a "long" integer and not a PARI integer.
2020 \subsecidx{factorint}"(n,{flag = 0})": factors the integer "n" into a
2022 product of pseudoprimes (see "ispseudoprime"), using a combination of
2023 the Shanks SQUFOF and Pollard Rho method (with modifications due to
2024 Brent), Lenstra's ECM (with modifications by Montgomery), and MPQS (the
2025 latter adapted from the LiDIA code with the kind permission of the
2026 LiDIA maintainers), as well as a search for pure powers with exponents"
2027 <= 10". The output is a two-column matrix as for "factor". Use
2028 "isprime" on the result if you want to guarantee primality.
2029 This gives direct access to the integer factoring engine called by most
2031 arithmetical functions. flag is optional; its binary digits mean 1:
2032 avoid MPQS, 2: skip first stage ECM (we may still fall back to it
2033 later), 4: avoid Rho and SQUFOF, 8: don't run final ECM (as a result, a
2034 huge composite may be declared to be prime). Note that a (strong)
2035 probabilistic primality test is used; thus composites might (very
2036 rarely) not be detected.
2037 You are invited to play with the flag settings and watch the internals
2039 at work by using "gp"'s "debuglevel" default parameter (level 3 shows
2040 just the outline, 4 turns on time keeping, 5 and above show an
2041 increasing amount of internal details). If you see anything funny
2042 happening, please let us know.
2043 The library syntax is "factorint(n,flag)".
2045 \subsecidx{factormod}"(x,p,{flag = 0})": factors the polynomial "x"
2047 modulo the prime integer "p", using Berlekamp. The coefficients of "x"
2048 must be operation-compatible with "Z/pZ". The result is a two-column
2049 matrix, the first column being the irreducible polynomials dividing
2050 "x", and the second the exponents. If "flag" is non-zero, outputs only
2051 the degrees of the irreducible polynomials (for example, for computing
2052 an "L"-function). A different algorithm for computing the mod "p"
2053 factorization is "factorcantor" which is sometimes faster.
2054 The library syntax is "factormod(x,p,flag)". Also available are
2056 \funs{factmod}{x,p} (which is equivalent to \funs{factormod}{x,p,0})
2057 and \funs{simplefactmod}{x,p} ( = \funs{factormod}{x,p,1}).
2058 \subsecidx{fibonacci}"(x)": "x-th" Fibonacci number.
2060 The library syntax is "fibo(x)". "x" must be a "long".
2062 \subsecidx{ffinit}"(p,n,{v = x})": computes a monic polynomial of
2064 degree "n" which is irreducible over "F_p". For instance if "P =
2065 ffinit(3,2,y)", you can represent elements in "F_{3^2}" as polmods
2066 modulo "P". This function uses a fast variant of Adleman-Lenstra's
2067 algorithm.
2068 The library syntax is "ffinit(p,n,v)", where "v" is a variable number.
2070 \subsecidx{gcd}"(x,{y})": creates the greatest common divisor of "x"
2072 and "y". "x" and "y" can be of quite general types, for instance both
2073 rational numbers. If "y" is omitted and "x" is a vector, returns the
2074 "gcd" of all components of "x", i.e. this is equivalent to content(x).
2075 When "x" and "y" are both given and one of them is a vector/matrix
2077 type, the GCD is again taken recursively on each component, but in a
2078 different way. If "y" is a vector, resp. matrix, then the result has
2079 the same type as "y", and components equal to "gcd(x, y[i])",
2080 resp. "gcd(x, y[,i])". Else if "x" is a vector/matrix the result has
2081 the same type as "x" and an analogous definition. Note that for these
2082 types, "gcd" is not commutative.
2083 The algorithm used is a naive Euclid except for the following inputs:
2085 * integers: use modified right-shift binary (``plus-minus'' variant).
2087 * univariate polynomials with coeffients in the same number field (in
2089 particular rational): use modular gcd algorithm.
2090 * general polynomials: use the subresultant algorithm if coefficient
2092 explosion is likely (exact, non modular, coefficients).
2093 The library syntax is "ggcd(x,y)". For general polynomial inputs,
2095 \funs{srgcd}{x,y} is also available. For univariate rational
2096 polynomials, one also has \funs{modulargcd}{x,y}.
2097 \subsecidx{hilbert}"(x,y,{p})": Hilbert symbol of "x" and "y" modulo
2099 "p". If "x" and "y" are of type integer or fraction, an explicit third
2100 parameter "p" must be supplied, "p = 0" meaning the place at infinity.
2101 Otherwise, "p" needs not be given, and "x" and "y" can be of compatible
2102 types integer, fraction, real, intmod a prime (result is undefined if
2103 the modulus is not prime), or "p"-adic.
2104 The library syntax is "hil(x,y,p)".
2106 \subsecidx{isfundamental}"(x)": true (1) if "x" is equal to 1 or to the
2108 discriminant of a quadratic field, false (0) otherwise.
2109 The library syntax is "gisfundamental(x)", but the simpler function
2111 \funs{isfundamental}{x} which returns a "long" should be used if "x" is
2112 known to be of type integer.
2113 \subsecidx{ispower}"(x,{k}, {&n})": if "k" is given, returns true (1)
2115 if "x" is a "k"-th power, false (0) if not. In this case, "x" may be an
2116 integer or polynomial, a rational number or function, or an intmod a
2117 prime or "p"-adic.
2118 If "k" is omitted, only integers and fractions are allowed and the
2120 function returns the maximal "k >= 2" such that "x = n^k" is a perfect
2121 power, or 0 if no such "k" exist; in particular "ispower(-1)",
2122 ispower(0), and ispower(1) all return 0.
2123 If a third argument &n is given and a "k"-th root was computed in the
2125 process, then "n" is set to that root.
2126 The library syntax is "ispower(x, k, &n)", the result is a "long".
2128 Omitted "k" or "n" are coded as "NULL".
2129 \subsecidx{isprime}"(x,{flag = 0})": true (1) if "x" is a (proven)
2131 prime number, false (0) otherwise. This can be very slow when "x" is
2132 indeed prime and has more than 1000 digits, say. Use "ispseudoprime" to
2133 quickly check for pseudo primality. See also "factor".
2134 If "flag = 0", use a combination of Baillie-PSW pseudo primality test
2136 (see "ispseudoprime"), Selfridge ``"p-1"'' test if "x-1" is smooth
2137 enough, and Adleman-Pomerance-Rumely-Cohen-Lenstra (APRCL) for general
2138 "x".
2139 If "flag = 1", use Selfridge-Pocklington-Lehmer ``"p-1"'' test and
2141 output a primality certificate as follows: return 0 if "x" is
2142 composite, 1 if "x" is small enough that passing Baillie-PSW test
2143 guarantees its primality (currently "x < 10^{13}"), 2 if "x" is a large
2144 prime whose primality could only sensibly be proven (given the
2145 algorithms implemented in PARI) using the APRCL test. Otherwise ("x" is
2146 large and "x-1" is smooth) output a three column matrix as a primality
2147 certificate. The first column contains the prime factors "p" of "x-1",
2148 the second the corresponding elements "a_p" as in Proposition 8.3.1 in
2149 GTM 138, and the third the output of isprime(p,1). The algorithm fails
2150 if one of the pseudo-prime factors is not prime, which is exceedingly
2151 unlikely (and well worth a bug report).
2152 If "flag = 2", use APRCL.
2154 The library syntax is "gisprime(x,flag)", but the simpler function
2156 \funs{isprime}{x} which returns a "long" should be used if "x" is known
2157 to be of type integer.
2158 \subsecidx{ispseudoprime}"(x,{flag})": true (1) if "x" is a strong
2160 pseudo prime (see below), false (0) otherwise. If this function returns
2161 false, "x" is not prime; if, on the other hand it returns true, it is
2162 only highly likely that "x" is a prime number. Use "isprime" (which is
2163 of course much slower) to prove that "x" is indeed prime.
2164 If "flag = 0", checks whether "x" is a Baillie-Pomerance-Selfridge-
2166 Wagstaff pseudo prime (strong Rabin-Miller pseudo prime for base 2,
2167 followed by strong Lucas test for the sequence "(P,-1)", "P" smallest
2168 positive integer such that "P^2 - 4" is not a square mod "x").
2169 There are no known composite numbers passing this test (in particular,
2171 all composites " <= 10^{13}" are correctly detected), although it is
2172 expected that infinitely many such numbers exist.
2173 If "flag > 0", checks whether "x" is a strong Miller-Rabin pseudo prime
2175 for "flag" randomly chosen bases (with end-matching to catch square
2176 roots of "-1").
2177 The library syntax is "gispseudoprime(x,flag)", but the simpler
2179 function \funs{ispseudoprime}{x} which returns a "long" should be used
2180 if "x" is known to be of type integer.
2181 \subsecidx{issquare}"(x,{&n})": true (1) if "x" is a square, false (0)
2183 if not. What ``being a square'' means depends on the type of "x": all
2184 "t_COMPLEX" are squares, as well as all non-negative "t_REAL"; for
2185 exact types such as "t_INT", "t_FRAC" and "t_INTMOD", squares are
2186 numbers of the form "s^2" with "s" in Z, Q and "Z/NZ" respectively.
2187 ? issquare(3) \\ as an integer
2189 %1 = 0
2190 ? issquare(3.) \\ as a real number
2191 %2 = 1
2192 ? issquare(Mod(7, 8)) \\ in Z/8Z
2193 %3 = 0
2194 ? issquare( 5 + O(13^4) ) \\ in Q_13
2195 %4 = 0
2196 If "n" is given and an exact square root had to be computed in the
2198 checking process, puts that square root in "n". This is the case when
2199 "x" is a "t_INT", "t_FRAC", "t_POL" or "t_RFRAC" (or a vector of such
2200 objects):
2201 ? issquare(4, &n)
2203 %1 = 1
2204 ? n
2205 %2 = 2
2206 ? issquare([4, x^2], &n)
2207 %3 = [1, 1] \\ both are squares
2208 ? n
2209 %4 = [2, x] \\ the square roots
2210 This will not work for "t_INTMOD" (use quadratic reciprocity) or
2212 "t_SER" (only check the leading coefficient).
2213 The library syntax is "gissquarerem(x,&n)". Also available is
2215 \funs{gissquare}{x}.
2216 \subsecidx{issquarefree}"(x)": true (1) if "x" is squarefree, false (0)
2218 if not. Here "x" can be an integer or a polynomial.
2219 The library syntax is "gissquarefree(x)", but the simpler function
2221 \funs{issquarefree}{x} which returns a "long" should be used if "x" is
2222 known to be of type integer. This issquarefree is just the square of
2223 the Moebius function, and is computed as a multiplicative arithmetic
2224 function much like the latter.
2225 \subsecidx{kronecker}"(x,y)": Kronecker symbol "(x|y)", where "x" and
2227 "y" must be of type integer. By definition, this is the extension of
2228 Legendre symbol to "Z x Z" by total multiplicativity in both arguments
2229 with the following special rules for "y = 0, -1" or 2:
2230 * "(x|0) = 1" if "|x |= 1" and 0 otherwise.
2232 * "(x|-1) = 1" if "x >= 0" and "-1" otherwise.
2234 * "(x|2) = 0" if "x" is even and 1 if "x = 1,-1 mod 8" and "-1" if "x =
2236 3,-3 mod 8".
2237 The library syntax is "kronecker(x,y)", the result (0 or "+- 1") is a
2239 "long".
2240 \subsecidx{lcm}"(x,{y})": least common multiple of "x" and "y",
2242 i.e. such that "lcm(x,y)* gcd (x,y) = abs(x*y)". If "y" is omitted and
2243 "x" is a vector, returns the "lcm" of all components of "x".
2244 When "x" and "y" are both given and one of them is a vector/matrix
2246 type, the LCM is again taken recursively on each component, but in a
2247 different way. If "y" is a vector, resp. matrix, then the result has
2248 the same type as "y", and components equal to "lcm(x, y[i])",
2249 resp. "lcm(x, y[,i])". Else if "x" is a vector/matrix the result has
2250 the same type as "x" and an analogous definition. Note that for these
2251 types, "lcm" is not commutative.
2252 Note that lcm(v) is quite different from
2254 l = v[1]; for (i = 1, #v, l = lcm(l, v[i]))
2256 Indeed, lcm(v) is a scalar, but "l" may not be (if one of the "v[i]" is
2258 a vector/matrix). The computation uses a divide-conquer tree and should
2259 be much more efficient, especially when using the GMP multiprecision
2260 kernel (and more subquadratic algorithms become available):
2261 ? v = vector(10^4, i, random);
2263 ? lcm(v);
2264 time = 323 ms.
2265 ? l = v[1]; for (i = 1, #v, l = lcm(l, v[i]))
2266 time = 833 ms.
2267 The library syntax is "glcm(x,y)".
2269 \subsecidx{moebius}"(x)": Moebius "mu"-function of "|x|". "x" must be
2271 of type integer.
2272 The library syntax is "mu(x)", the result (0 or "+- 1") is a "long".
2274 \subsecidx{nextprime}"(x)": finds the smallest pseudoprime (see
2276 "ispseudoprime") greater than or equal to "x". "x" can be of any real
2277 type. Note that if "x" is a pseudoprime, this function returns "x" and
2278 not the smallest pseudoprime strictly larger than "x". To rigorously
2279 prove that the result is prime, use "isprime".
2280 The library syntax is "nextprime(x)".
2282 \subsecidx{numdiv}"(x)": number of divisors of "|x|". "x" must be of
2284 type integer.
2285 The library syntax is "numbdiv(x)".
2287 \subsecidx{numbpart}"(n)": gives the number of unrestricted partitions
2289 of "n", usually called p(n) in the litterature; in other words the
2290 number of nonnegative integer solutions to "a+2b+3c+.. .= n". "n" must
2291 be of type integer and "1 <= n < 10^{15}". The algorithm uses the
2292 Hardy-Ramanujan-Rademacher formula.
2293 The library syntax is "numbpart(n)".
2295 \subsecidx{omega}"(x)": number of distinct prime divisors of "|x|". "x"
2297 must be of type integer.
2298 The library syntax is "omega(x)", the result is a "long".
2300 \subsecidx{precprime}"(x)": finds the largest pseudoprime (see
2302 "ispseudoprime") less than or equal to "x". "x" can be of any real
2303 type. Returns 0 if "x <= 1". Note that if "x" is a prime, this
2304 function returns "x" and not the largest prime strictly smaller than
2305 "x". To rigorously prove that the result is prime, use "isprime".
2306 The library syntax is "precprime(x)".
2308 \subsecidx{prime}"(x)": the "x-th" prime number, which must be among
2310 the precalculated primes.
2311 The library syntax is "prime(x)". "x" must be a "long".
2313 \subsecidx{primepi}"(x)": the prime counting function. Returns the
2315 number of primes "p", "p <= x". Uses a naive algorithm so that "x" must
2316 be less than "primelimit".
2317 The library syntax is "primepi(x)".
2319 \subsecidx{primes}"(x)": creates a row vector whose components are the
2321 first "x" prime numbers, which must be among the precalculated primes.
2322 The library syntax is "primes(x)". "x" must be a "long".
2324 \subsecidx{qfbclassno}"(D,{flag = 0})": ordinary class number of the
2326 quadratic order of discriminant "D". In the present version
2327 /usr/share/libpari23, a "O(D^{1/2})" algorithm is used for "D > 0"
2328 (using Euler product and the functional equation) so "D" should not be
2329 too large, say "D < 10^8", for the time to be reasonable. On the other
2330 hand, for "D < 0" one can reasonably compute qfbclassno(D) for "|D| <
2331 10^{25}", since the routine uses Shanks's method which is in
2332 "O(|D|^{1/4})". For larger values of "|D|", see "quadclassunit".
2333 If "flag = 1", compute the class number using Euler products and the
2335 functional equation. However, it is in "O(|D|^{1/2})".
2336 Important warning.. For "D < 0", this function may give incorrect
2338 results when the class group has a low exponent (has many cyclic
2339 factors), because implementing Shanks's method in full generality slows
2340 it down immensely. It is therefore strongly recommended to double-check
2341 results using either the version with "flag = 1" or the function
2342 "quadclassunit".
2343 Warning.. contrary to what its name implies, this routine does not
2345 compute the number of classes of binary primitive forms of discriminant
2346 "D", which is equal to the narrow class number. The two notions are the
2347 same when "D < 0" or the fundamental unit "varepsilon" has negative
2348 norm; when "D > 0" and "Nvarepsilon > 0", the number of classes of
2349 forms is twice the ordinary class number. This is a problem which we
2350 cannot fix for backward compatibility reasons. Use the following
2351 routine if you are only interested in the number of classes of forms:
2352 QFBclassno(D) =
2354 qfbclassno(D) * if (D < 0 || norm(quadunit(D)) < 0, 1, 2)
2355 Here are a few examples:
2357 %2 = 1
2359 ? qfbclassno(-400000028)
2360 time = 0 ms.
2361 %3 = 7253 \{ much faster}
2362 %2 = 1
2363 ? qfbclassno(-400000028)
2364 time = 0 ms.
2365 %3 = 7253 \{ correct, and fast enough}
2366 ? quadclassunit(-400000028).no
2367 time = 0 ms.
2368 %4 = 7253
2369 The library syntax is "qfbclassno0(D,flag)". Also available:
2371 \funs{classno}{D} ( = \funs{qfbclassno}{D}), \funs{classno2}{D} ( =
2372 \funs{qfbclassno}{D,1}), and finally we have the function
2373 \funs{hclassno}{D} which computes the class number of an imaginary
2374 quadratic field by counting reduced forms, an "O(|D|)" algorithm. See
2375 also "qfbhclassno".
2376 \subsecidx{qfbcompraw}"(x,y)" composition of the binary quadratic forms
2378 "x" and "y", without reduction of the result. This is useful e.g. to
2379 compute a generating element of an ideal.
2380 The library syntax is "compraw(x,y)".
2382 \subsecidx{qfbhclassno}"(x)": Hurwitz class number of "x", where "x" is
2384 non-negative and congruent to 0 or 3 modulo 4. For "x > 5. 10^5", we
2385 assume the GRH, and use "quadclassunit" with default parameters.
2386 The library syntax is "hclassno(x)".
2388 \subsecidx{qfbnucomp}"(x,y,l)": composition of the primitive positive
2390 definite binary quadratic forms "x" and "y" (type "t_QFI") using the
2391 NUCOMP and NUDUPL algorithms of Shanks, à la Atkin. "l" is any positive
2392 constant, but for optimal speed, one should take "l = |D|^{1/4}", where
2393 "D" is the common discriminant of "x" and "y". When "x" and "y" do not
2394 have the same discriminant, the result is undefined.
2395 The current implementation is straightforward and in general slower
2397 than the generic routine (since the latter take advantadge of
2398 asymptotically fast operations and careful optimizations).
2399 The library syntax is "nucomp(x,y,l)". The auxiliary function
2401 \funs{nudupl}{x,l} can be used when "x = y".
2402 \subsecidx{qfbnupow}"(x,n)": "n"-th power of the primitive positive
2404 definite binary quadratic form "x" using Shanks's NUCOMP and NUDUPL
2405 algorithms (see "qfbnucomp", in particular the final warning).
2406 The library syntax is "nupow(x,n)".
2408 \subsecidx{qfbpowraw}"(x,n)": "n"-th power of the binary quadratic form
2410 "x", computed without doing any reduction (i.e. using "qfbcompraw").
2411 Here "n" must be non-negative and "n < 2^{31}".
2412 The library syntax is "powraw(x,n)" where "n" must be a "long" integer.
2414 \subsecidx{qfbprimeform}"(x,p)": prime binary quadratic form of
2416 discriminant "x" whose first coefficient is the prime number "p". By
2417 abuse of notation, "p = +- 1" is a valid special case which returns the
2418 unit form. Returns an error if "x" is not a quadratic residue mod "p".
2419 In the case where "x > 0", "p < 0" is allowed, and the ``distance''
2420 component of the form is set equal to zero according to the current
2421 precision. (Note that negative definite "t_QFI" are not implemented.)
2422 The library syntax is "primeform(x,p,prec)", where the third variable
2424 "prec" is a "long", but is only taken into account when "x > 0".
2425 \subsecidx{qfbred}"(x,{flag = 0},{D},{isqrtD},{sqrtD})": reduces the
2427 binary quadratic form "x" (updating Shanks's distance function if "x"
2428 is indefinite). The binary digits of "flag" are toggles meaning
2429 1: perform a single reduction step
2431 2: don't update Shanks's distance
2433 "D", isqrtD, sqrtD, if present, supply the values of the discriminant,
2435 "floor{ sqrt {D}}", and " sqrt {D}" respectively (no checking is done
2436 of these facts). If "D < 0" these values are useless, and all
2437 references to Shanks's distance are irrelevant.
2438 The library syntax is "qfbred0(x,flag,D,isqrtD,sqrtD)". Use "NULL" to
2440 omit any of "D", isqrtD, sqrtD.
2441 Also available are
2443 \funs{redimag}{x} ( = \funs{qfbred}{x} where "x" is definite),
2445 and for indefinite forms:
2447 \funs{redreal}{x} ( = \funs{qfbred}{x}),
2449 \funs{rhoreal}{x} ( = \funs{qfbred}{x,1}),
2451 \funs{redrealnod}{x,sq} ( = \funs{qfbred}{x,2,,isqrtD}),
2453 \funs{rhorealnod}{x,sq} ( = \funs{qfbred}{x,3,,isqrtD}).
2455 \subsecidx{qfbsolve}"(Q,p)": Solve the equation "Q(x,y) = p" over the
2457 integers, where "Q" is a binary quadratic form and "p" a prime number.
2458 Return "[x,y]" as a two-components vector, or zero if there is no
2460 solution. Note that this function returns only one solution and not
2461 all the solutions.
2462 Let "D = disc Q". The algorithm used runs in probabilistic polynomial
2464 time in "p" (through the computation of a square root of "D" modulo
2465 "p"); it is polynomial time in "D" if "Q" is imaginary, but exponential
2466 time if "Q" is real (through the computation of a full cycle of reduced
2467 forms). In the latter case, note that "bnfisprincipal" provides a
2468 solution in heuristic subexponential time in "D" assuming the GRH.
2469 The library syntax is "qfbsolve(Q,n)".
2471 \subsecidx{quadclassunit}"(D,{flag = 0},{tech = []})": Buchmann-
2473 McCurley's sub-exponential algorithm for computing the class group of a
2474 quadratic order of discriminant "D".
2475 This function should be used instead of "qfbclassno" or "quadregula"
2477 when "D < -10^{25}", "D > 10^{10}", or when the structure is wanted. It
2478 is a special case of "bnfinit", which is slower, but more robust.
2479 If "flag" is non-zero and "D > 0", computes the narrow class group and
2481 regulator, instead of the ordinary (or wide) ones. In the current
2482 version /usr/share/libpari23, this does not work at all: use the
2483 general function "bnfnarrow".
2484 Optional parameter tech is a row vector of the form "[c_1, c_2]", where
2486 "c_1 <= c_2" are positive real numbers which control the execution time
2487 and the stack size. For a given "c_1", set "c_2 = c_1" to get maximum
2488 speed. To get a rigorous result under GRH, you must take "c_2 >= 6".
2489 Reasonable values for "c_1" are between 0.1 and 2. More precisely, the
2490 algorithm will assume that prime ideals of norm less than "c_2 ( log
2491 |D|)^2" generate the class group, but the bulk of the work is done with
2492 prime ideals of norm less than "c_1 ( log |D|)^2". A larger "c_1"
2493 means that relations are easier to find, but more relations are needed
2494 and the linear algebra will be harder. The default is "c_1 = c_2 =
2495 0.2", so the result is not rigorously proven.
2496 The result is a vector "v" with 3 components if "D < 0", and 4
2498 otherwise. The correspond respectively to
2499 * "v[1]": the class number
2501 * "v[2]": a vector giving the structure of the class group as a product
2503 of cyclic groups;
2504 * "v[3]": a vector giving generators of those cyclic groups (as binary
2506 quadratic forms).
2507 * "v[4]": (omitted if "D < 0") the regulator, computed to an accuracy
2509 which is the maximum of an internal accuracy determined by the program
2510 and the current default (note that once the regulator is known to a
2511 small accuracy it is trivial to compute it to very high accuracy, see
2512 the tutorial).
2513 The library syntax is "quadclassunit0(D,flag,tech)". Also available are
2515 \funs{buchimag}{D,c_1,c_2} and \funs{buchreal}{D,flag,c_1,c_2}.
2516 \subsecidx{quaddisc}"(x)": discriminant of the quadratic field "Q( sqrt
2518 {x})", where "x\in Q".
2519 The library syntax is "quaddisc(x)".
2521 \subsecidx{quadhilbert}"(D,{pq})": relative equation defining the
2523 Hilbert class field of the quadratic field of discriminant "D".
2524 If "D < 0", uses complex multiplication (Schertz's variant). The
2526 technical component "pq", if supplied, is a vector "[p,q]" where "p",
2527 "q" are the prime numbers needed for the Schertz's method. More
2528 precisely, prime ideals above "p" and "q" should be non-principal and
2529 coprime to all reduced representatives of the class group. In addition,
2530 if one of these ideals has order 2 in the class group, they should have
2531 the same class. Finally, for efficiency, " gcd (24,(p-1)(q-1))" should
2532 be as large as possible. The routine returns 0 if "[p,q]" is not
2533 suitable.
2534 If "D > 0" Stark units are used and (in rare cases) a vector of
2536 extensions may be returned whose compositum is the requested class
2537 field. See "bnrstark" for details.
2538 The library syntax is "quadhilbert(D,pq,prec)".
2540 \subsecidx{quadgen}"(D)": creates the quadratic number "omega = (a+
2542 sqrt {D})/2" where "a = 0" if "x = 0 mod 4", "a = 1" if "D = 1 mod 4",
2543 so that "(1,omega)" is an integral basis for the quadratic order of
2544 discriminant "D". "D" must be an integer congruent to 0 or 1 modulo 4,
2545 which is not a square.
2546 The library syntax is "quadgen(x)".
2548 \subsecidx{quadpoly}"(D,{v = x})": creates the ``canonical'' quadratic
2550 polynomial (in the variable "v") corresponding to the discriminant "D",
2551 i.e. the minimal polynomial of quadgen(D). "D" must be an integer
2552 congruent to 0 or 1 modulo 4, which is not a square.
2553 The library syntax is "quadpoly0(x,v)".
2555 \subsecidx{quadray}"(D,f,{lambda})": relative equation for the ray
2557 class field of conductor "f" for the quadratic field of discriminant
2558 "D" using analytic methods. A "bnf" for "x^2 - D" is also accepted in
2559 place of "D".
2560 For "D < 0", uses the "sigma" function. If supplied, lambda is is the
2562 technical element "lambda" of "bnf" necessary for Schertz's method. In
2563 that case, returns 0 if "lambda" is not suitable.
2564 For "D > 0", uses Stark's conjecture, and a vector of relative
2566 equations may be returned. See "bnrstark" for more details.
2567 The library syntax is "quadray(D,f,lambda,prec)", where an omitted
2569 "lambda" is coded as "NULL".
2570 \subsecidx{quadregulator}"(x)": regulator of the quadratic field of
2572 positive discriminant "x". Returns an error if "x" is not a
2573 discriminant (fundamental or not) or if "x" is a square. See also
2574 "quadclassunit" if "x" is large.
2575 The library syntax is "regula(x,prec)".
2577 \subsecidx{quadunit}"(D)": fundamental unit of the real quadratic field
2579 "Q( sqrt D)" where "D" is the positive discriminant of the field. If
2580 "D" is not a fundamental discriminant, this probably gives the
2581 fundamental unit of the corresponding order. "D" must be an integer
2582 congruent to 0 or 1 modulo 4, which is not a square; the result is a
2583 quadratic number (see "Label se:quadgen").
2584 The library syntax is "fundunit(x)".
2586 \subsecidx{removeprimes}"({x = []})": removes the primes listed in "x"
2588 from the prime number table. In particular "removeprimes(addprimes)"
2589 empties the extra prime table. "x" can also be a single integer. List
2590 the current extra primes if "x" is omitted.
2591 The library syntax is "removeprimes(x)".
2593 \subsecidx{sigma}"(x,{k = 1})": sum of the "k-th" powers of the
2595 positive divisors of "|x|". "x" and "k" must be of type integer.
2596 The library syntax is "sumdiv(x)" ( = \funs{sigma}{x}) or
2598 \funs{gsumdivk}{x,k} ( = \funs{sigma}{x,k}), where "k" is a C long
2599 integer.
2600 \subsecidx{sqrtint}"(x)": integer square root of "x", which must be a
2602 non-negative integer. The result is non-negative and rounded towards
2603 zero.
2604 The library syntax is "sqrti(x)". Also available is "sqrtremi""(x,&r)"
2606 which returns "s" such that "s^2 = x+r", with "0 <= r <= 2s".
2607 \subsecidx{zncoppersmith}"(P, N, X, {B = N})": finds all integers "x_0"
2609 with "|x_0| <= X" such that
2610 " gcd (N, P(x_0)) >= B."
2612 If "N" is prime or a prime power, "polrootsmod" or "polrootspadic" will
2614 be much faster. "X" must be smaller than " exp ( log ^2 B / ( deg (P)
2615 log N))".
2616 The library syntax is "zncoppersmith(P, N, X, B)", where an omitted "B"
2618 is coded as "NULL".
2619 \subsecidx{znlog}"(x,g)": "g" must be a primitive root mod a prime "p",
2621 and the result is the discrete log of "x" in the multiplicative group
2622 "(Z/pZ)^*". This function uses a simple-minded combination of Pohlig-
2623 Hellman algorithm and Shanks baby-step/giant-step which requires "O(
2624 sqrt {q})" storage, where "q" is the largest prime factor of "p-1".
2625 Hence it cannot be used when the largest prime divisor of "p-1" is
2626 greater than about "10^{13}".
2627 The library syntax is "znlog(x,g)".
2629 \subsecidx{znorder}"(x,{o})": "x" must be an integer mod "n", and the
2631 result is the order of "x" in the multiplicative group "(Z/nZ)^*".
2632 Returns an error if "x" is not invertible. If optional parameter "o" is
2633 given it is assumed to be a multiple of the order (used to limit the
2634 search space).
2635 The library syntax is "znorder(x,o)", where an omitted "o" is coded as
2637 "NULL". Also available is \funs{order}{x}.
2638 \subsecidx{znprimroot}"(n)": returns a primitive root (generator) of
2640 "(Z/nZ)^*", whenever this latter group is cyclic ("n = 4" or "n = 2p^k"
2641 or "n = p^k", where "p" is an odd prime and "k >= 0").
2642 The library syntax is "gener(x)".
2644 \subsecidx{znstar}"(n)": gives the structure of the multiplicative
2646 group "(Z/nZ)^*" as a 3-component row vector "v", where "v[1] = phi(n)"
2647 is the order of that group, "v[2]" is a "k"-component row-vector "d" of
2648 integers "d[i]" such that "d[i] > 1" and "d[i] | d[i-1]" for "i >= 2"
2649 and "(Z/nZ)^* ~ prod_{i = 1}^k(Z/d[i]Z)", and "v[3]" is a
2650 "k"-component row vector giving generators of the image of the cyclic
2651 groups "Z/d[i]Z".
2652 The library syntax is "znstar(n)".
2654
2656 We have implemented a number of functions which are useful for number
2657 theorists working on elliptic curves. We always use Tate's notations.
2658 The functions assume that the curve is given by a general Weierstrass
2659 model
2660 " y^2+a_1xy+a_3y = x^3+a_2x^2+a_4x+a_6, "
2662 where a priori the "a_i" can be of any scalar type. This curve can be
2664 considered as a five-component vector "E = [a1,a2,a3,a4,a6]". Points on
2665 "E" are represented as two-component vectors "[x,y]", except for the
2666 point at infinity, i.e. the identity element of the group law,
2667 represented by the one-component vector "[0]".
2668 It is useful to have at one's disposal more information. This is given
2670 by the function "ellinit" (see there), which initalizes and returns an
2671 ell structure by default. If a specific flag is added, a shortened
2672 sell, for small ell, is returned, which is much faster to compute but
2673 contains less information. The following member functions are available
2674 to deal with the output of "ellinit", both ell and sell:
2675 "a1"--"a6", "b2"--"b8", "c4"--"c6" : coefficients of the elliptic
2677 curve.
2678 "area" : volume of the complex lattice defining "E".
2680 "disc" : discriminant of the curve.
2682 "j" : "j"-invariant of the curve.
2684 "omega" : "[omega_1,omega_2]", periods forming a basis of the
2686 complex lattice defining "E" ("omega_1" is the
2687 real period, and "omega_2/omega_1" belongs to
2689 Poincaré's half-plane).
2690 "eta" : quasi-periods "[eta_1, eta_2]", such that
2692 "eta_1omega_2-eta_2omega_1 = ipi".
2693 "roots" : roots of the associated Weierstrass equation.
2695 "tate" : "[u^2,u,v]" in the notation of Tate.
2697 "w" : Mestre's "w" (this is technical).
2699 The member functions "area", "eta" and "omega" are only available for
2701 curves over Q. Conversely, "tate" and "w" are only available for curves
2702 defined over "Q_p". The use of member functions is best described by an
2703 example:
2704 ? E = ellinit([0,0,0,0,1]); \\ The curve y^2 = x^3 + 1
2706 ? E.a6
2707 %2 = 1
2708 ? E.c6
2709 %3 = -864
2710 ? E.disc
2711 %4 = -432
2712 Some functions, in particular those relative to height computations
2714 (see "ellheight") require also that the curve be in minimal Weierstrass
2715 form, which is duly stressed in their description below. This is
2716 achieved by the function "ellminimalmodel". Using a non-minimal model
2717 in such a routine will yield a wrong result!
2718 All functions related to elliptic curves share the prefix "ell", and
2720 the precise curve we are interested in is always the first argument, in
2721 either one of the three formats discussed above, unless otherwise
2722 specified. The requirements are given as the minimal ones: any richer
2723 structure may replace the ones requested. For instance, in functions
2724 which have no use for the extra information given by an ell structure,
2725 the curve can be given either as a five-component vector, as an sell,
2726 or as an ell; if an sell is requested, an ell may equally be given.
2727 \subsecidx{elladd}"(E,z1,z2)": sum of the points "z1" and "z2" on the
2729 elliptic curve corresponding to "E".
2730 The library syntax is "addell(E,z1,z2)".
2732 \subsecidx{ellak}"(E,n)": computes the coefficient "a_n" of the
2734 "L"-function of the elliptic curve "E", i.e. in principle coefficients
2735 of a newform of weight 2 assuming Taniyama-Weil conjecture (which is
2736 now known to hold in full generality thanks to the work of Breuil,
2737 Conrad, Diamond, Taylor and Wiles). "E" must be an sell as output by
2738 "ellinit". For this function to work for every "n" and not just those
2739 prime to the conductor, "E" must be a minimal Weierstrass equation. If
2740 this is not the case, use the function "ellminimalmodel" before using
2741 "ellak".
2742 The library syntax is "akell(E,n)".
2744 \subsecidx{ellan}"(E,n)": computes the vector of the first "n" "a_k"
2746 corresponding to the elliptic curve "E". All comments in "ellak"
2747 description remain valid.
2748 The library syntax is "anell(E,n)", where "n" is a C integer.
2750 \subsecidx{ellap}"(E,p,{flag = 0})": computes the "a_p" corresponding
2752 to the elliptic curve "E" and the prime number "p". These are defined
2753 by the equation "#E(F_p) = p+1 - a_p", where "#E(F_p)" stands for the
2754 number of points of the curve "E" over the finite field "F_p". When
2755 "flag" is 0, this uses the baby-step giant-step method and a trick due
2756 to Mestre. This runs in time "O(p^{1/4})" and requires "O(p^{1/4})"
2757 storage, hence becomes unreasonable when "p" has about 30 digits.
2758 If "flag" is 1, computes the "a_p" as a sum of Legendre symbols. This
2760 is slower than the previous method as soon as "p" is greater than 100,
2761 say.
2762 No checking is done that "p" is indeed prime. "E" must be an sell as
2764 output by "ellinit", defined over Q, "F_p" or "Q_p". "E" must be given
2765 by a Weierstrass equation minimal at "p".
2766 The library syntax is "ellap0(E,p,flag)". Also available are
2768 \funs{apell}{E,p}, corresponding to "flag = 0", and \funs{apell2}{E,p}
2769 ("flag = 1").
2770 \subsecidx{ellbil}"(E,z1,z2)": if "z1" and "z2" are points on the
2772 elliptic curve "E", assumed to be integral given by a minimal model,
2773 this function computes the value of the canonical bilinear form on
2774 "z1", "z2":
2775 " ( h(E,z1+z2) - h(E,z1) - h(E,z2) ) / 2 "
2777 where "+" denotes of course addition on "E". In addition, "z1" or "z2"
2779 (but not both) can be vectors or matrices.
2780 The library syntax is "bilhell(E,z1,z2,prec)".
2782 \subsecidx{ellchangecurve}"(E,v)": changes the data for the elliptic
2784 curve "E" by changing the coordinates using the vector "v = [u,r,s,t]",
2785 i.e. if "x'" and "y'" are the new coordinates, then "x = u^2x'+r", "y =
2786 u^3y'+su^2x'+t". "E" must be an sell as output by "ellinit".
2787 The library syntax is "coordch(E,v)".
2789 \subsecidx{ellchangepoint}"(x,v)": changes the coordinates of the point
2791 or vector of points "x" using the vector "v = [u,r,s,t]", i.e. if "x'"
2792 and "y'" are the new coordinates, then "x = u^2x'+r", "y =
2793 u^3y'+su^2x'+t" (see also "ellchangecurve").
2794 The library syntax is "pointch(x,v)".
2796 \subsecidx{ellconvertname}"(name)": converts an elliptic curve name, as
2798 found in the "elldata" database, from a string to a triplet
2799 "[conductor, isogeny class, index]". It will also convert a triplet
2800 back to a curve name. Examples:
2801 ? ellconvertname("123b1")
2803 %1 = [123, 1, 1]
2804 ? ellconvertname(%)
2805 %2 = "123b1"
2806 The library syntax is "ellconvertname(name)".
2808 \subsecidx{elleisnum}"(E,k,{flag = 0})": "E" being an elliptic curve as
2810 output by "ellinit" (or, alternatively, given by a 2-component vector
2811 "[omega_1,omega_2]" representing its periods), and "k" being an even
2812 positive integer, computes the numerical value of the Eisenstein series
2813 of weight "k" at "E", namely
2814 " (2i pi/omega_2)^k (1 + 2/zeta(1-k) sum_{n >= 0} n^{k-1}q^n /
2816 (1-q^n)), "
2817 where "q = e(omega_1/omega_2)".
2819 When flag is non-zero and "k = 4" or 6, returns the elliptic invariants
2821 "g_2" or "g_3", such that
2822 "y^2 = 4x^3 - g_2 x - g_3"
2824 is a Weierstrass equation for "E".
2826 The library syntax is "elleisnum(E,k,flag)".
2828 \subsecidx{elleta}"(om)": returns the two-component row vector
2830 "[eta_1,eta_2]" of quasi-periods associated to "om = [omega_1,
2831 omega_2]"
2832 The library syntax is "elleta(om, prec)"
2834 \subsecidx{ellgenerators}"(E)": returns a Z-basis of the free part of
2836 the Mordell-Weil group associated to "E". This function depends on the
2837 "elldata" database being installed and referencing the curve, and so is
2838 only available for curves over Z of small conductors.
2839 The library syntax is "ellgenerators(E)".
2841 \subsecidx{ellglobalred}"(E)": calculates the arithmetic conductor, the
2843 global minimal model of "E" and the global Tamagawa number "c". "E"
2844 must be an sell as output by "ellinit", and is supposed to have all its
2845 coefficients "a_i" in Q. The result is a 3 component vector "[N,v,c]".
2846 "N" is the arithmetic conductor of the curve. "v" gives the coordinate
2847 change for "E" over Q to the minimal integral model (see
2848 "ellminimalmodel"). Finally "c" is the product of the local Tamagawa
2849 numbers "c_p", a quantity which enters in the Birch and Swinnerton-Dyer
2850 conjecture.
2851 The library syntax is "ellglobalred(E)".
2853 \subsecidx{ellheight}"(E,z,{flag = 2})": global Néron-Tate height of
2855 the point "z" on the elliptic curve "E" (defined over Q), given by a
2856 standard minimal integral model. "E" must be an "ell" as output by
2857 "ellinit". flag selects the algorithm used to compute the archimedean
2858 local height. If "flag = 0", this computation is done using sigma and
2859 theta-functions and a trick due to J. Silverman. If "flag = 1", use
2860 Tate's "4^n" algorithm. If "flag = 2", use Mestre's AGM algorithm. The
2861 latter is much faster than the other two, both in theory (converges
2862 quadratically) and in practice.
2863 The library syntax is "ellheight0(E,z,flag,prec)". Also available are
2865 \funs{ghell}{E,z,prec} ("flag = 0") and \funs{ghell2}{E,z,prec} ("flag
2866 = 1").
2867 \subsecidx{ellheightmatrix}"(E,x)": "x" being a vector of points, this
2869 function outputs the Gram matrix of "x" with respect to the Néron-Tate
2870 height, in other words, the "(i,j)" component of the matrix is equal to
2871 "ellbil(E,x[i],x[j])". The rank of this matrix, at least in some
2872 approximate sense, gives the rank of the set of points, and if "x" is a
2873 basis of the Mordell-Weil group of "E", its determinant is equal to the
2874 regulator of "E". Note that this matrix should be divided by 2 to be in
2875 accordance with certain normalizations. "E" is assumed to be integral,
2876 given by a minimal model.
2877 The library syntax is "mathell(E,x,prec)".
2879 \subsecidx{ellidentify}"(E)": look up the elliptic curve "E" (over Z)
2881 in the "elldata" database and return "[[N, M, G], C]" where "N" is the
2882 name of the curve in J. E. Cremona database, "M" the minimal model,
2883 "G" a Z-basis of the free part of the Mordell-Weil group of "E" and "C"
2884 the coordinates change (see "ellchangecurve").
2885 The library syntax is "ellidentify(E)".
2887 \subsecidx{ellinit}"(E,{flag = 0})": initialize an "ell" structure,
2889 associated to the elliptic curve "E". "E" is a 5-component vector
2890 "[a_1,a_2,a_3,a_4,a_6]" defining the elliptic curve with Weierstrass
2891 equation
2892 " Y^2 + a_1 XY + a_3 Y = X^3 + a_2 X^2 + a_4 X + a_6 "
2894 or a string, in this case the coefficients of the curve with matching
2896 name are looked in the "elldata" database if available. For the time
2897 being, only curves over a prime field "F_p" and over the "p"-adic or
2898 real numbers (including rational numbers) are fully supported. Other
2899 domains are only supported for very basic operations such as point
2900 addition.
2901 The result of "ellinit" is a an ell structure by default, and a shorted
2903 sell if "flag = 1". Both contain the following information in their
2904 components:
2905 " a_1,a_2,a_3,a_4,a_6,b_2,b_4,b_6,b_8,c_4,c_6,Delta,j."
2907 All are accessible via member functions. In particular, the
2909 discriminant is "E.disc", and the "j"-invariant is "E.j".
2910 The other six components are only present if "flag" is 0 or omitted.
2912 Their content depends on whether the curve is defined over R or not:
2913 * When "E" is defined over R, "E.roots" is a vector whose three
2915 components contain the roots of the right hand side of the associated
2916 Weierstrass equation.
2917 " (y + a_1x/2 + a_3/2)^2 = g(x) "
2919 If the roots are all real, then they are ordered by decreasing value.
2921 If only one is real, it is the first component.
2922 Then "omega_1 = ""E.omega[1]" is the real period of "E" (integral of
2924 "dx/(2y+a_1x+a_3)" over the connected component of the identity element
2925 of the real points of the curve), and "omega_2 = ""E.omega[2]" is a
2926 complex period. In other words, "E.omega" forms a basis of the complex
2927 lattice defining "E", with "tau = (omega_2)/(omega_1)" having positive
2928 imaginary part.
2929 "E.eta" is a row vector containing the corresponding values "eta_1" and
2931 "eta_2" such that "eta_1omega_2-eta_2omega_1 = ipi".
2932 Finally, "E.area" is the volume of the complex lattice defining "E".
2934 * When "E" is defined over "Q_p", the "p"-adic valuation of "j" must be
2936 negative. Then "E.roots" is the vector with a single component equal to
2937 the "p"-adic root of the associated Weierstrass equation corresponding
2938 to "-1" under the Tate parametrization.
2939 "E.tate" yields the three-component vector "[u^2,u,q]", in the
2941 notations of Tate. If the "u"-component does not belong to "Q_p", it is
2942 set to zero.
2943 "E.w" is Mestre's "w" (this is technical).
2945 For all other base fields or rings, the last six components are
2947 arbitrarily set equal to zero. See also the description of member
2948 functions related to elliptic curves at the beginning of this section.
2949 The library syntax is "ellinit0(E,flag,prec)". Also available are
2951 \funs{initell}{E,prec} ("flag = 0") and \funs{smallinitell}{E,prec}
2952 ("flag = 1").
2953 \subsecidx{ellisoncurve}"(E,z)": gives 1 (i.e. true) if the point "z"
2955 is on the elliptic curve "E", 0 otherwise. If "E" or "z" have imprecise
2956 coefficients, an attempt is made to take this into account, i.e. an
2957 imprecise equality is checked, not a precise one. It is allowed for "z"
2958 to be a vector of points in which case a vector (of the same type) is
2959 returned.
2960 The library syntax is "ellisoncurve(E,z)". Also available is
2962 \funs{oncurve}{E,z} which returns a "long" but does not accept vector
2963 of points.
2964 \subsecidx{ellj}"(x)": elliptic "j"-invariant. "x" must be a complex
2966 number with positive imaginary part, or convertible into a power series
2967 or a "p"-adic number with positive valuation.
2968 The library syntax is "jell(x,prec)".
2970 \subsecidx{elllocalred}"(E,p)": calculates the Kodaira type of the
2972 local fiber of the elliptic curve "E" at the prime "p". "E" must be an
2973 sell as output by "ellinit", and is assumed to have all its
2974 coefficients "a_i" in Z. The result is a 4-component vector
2975 "[f,kod,v,c]". Here "f" is the exponent of "p" in the arithmetic
2976 conductor of "E", and "kod" is the Kodaira type which is coded as
2977 follows:
2978 1 means good reduction (type I"_0"), 2, 3 and 4 mean types II, III and
2980 IV respectively, "4+nu" with "nu > 0" means type I"_nu"; finally the
2981 opposite values "-1", "-2", etc. refer to the starred types I"_0^*",
2982 II"^*", etc. The third component "v" is itself a vector "[u,r,s,t]"
2983 giving the coordinate changes done during the local reduction.
2984 Normally, this has no use if "u" is 1, that is, if the given equation
2985 was already minimal. Finally, the last component "c" is the local
2986 Tamagawa number "c_p".
2987 The library syntax is "elllocalred(E,p)".
2989 \subsecidx{elllseries}"(E,s,{A = 1})": "E" being an sell as output by
2991 "ellinit", this computes the value of the L-series of "E" at "s". It is
2992 assumed that "E" is defined over Q, not necessarily minimal. The
2993 optional parameter "A" is a cutoff point for the integral, which must
2994 be chosen close to 1 for best speed. The result must be independent of
2995 "A", so this allows some internal checking of the function.
2996 Note that if the conductor of the curve is large, say greater than
2998 "10^{12}", this function will take an unreasonable amount of time since
2999 it uses an "O(N^{1/2})" algorithm.
3000 The library syntax is "elllseries(E,s,A,prec)" where "prec" is a "long"
3002 and an omitted "A" is coded as "NULL".
3003 \subsecidx{ellminimalmodel}"(E,{&v})": return the standard minimal
3005 integral model of the rational elliptic curve "E". If present, sets "v"
3006 to the corresponding change of variables, which is a vector "[u,r,s,t]"
3007 with rational components. The return value is identical to that of
3008 "ellchangecurve(E, v)".
3009 The resulting model has integral coefficients, is everywhere minimal,
3011 "a_1" is 0 or 1, "a_2" is 0, 1 or "-1" and "a_3" is 0 or 1. Such a
3012 model is unique, and the vector "v" is unique if we specify that "u" is
3013 positive, which we do.
3014 The library syntax is "ellminimalmodel(E,&v)", where an omitted "v" is
3016 coded as "NULL".
3017 \subsecidx{ellorder}"(E,z)": gives the order of the point "z" on the
3019 elliptic curve "E" if it is a torsion point, zero otherwise. In the
3020 present version /usr/share/libpari23, this is implemented only for
3021 elliptic curves defined over Q.
3022 The library syntax is "orderell(E,z)".
3024 \subsecidx{ellordinate}"(E,x)": gives a 0, 1 or 2-component vector
3026 containing the "y"-coordinates of the points of the curve "E" having
3027 "x" as "x"-coordinate.
3028 The library syntax is "ordell(E,x)".
3030 \subsecidx{ellpointtoz}"(E,z)": if "E" is an elliptic curve with
3032 coefficients in R, this computes a complex number "t" (modulo the
3033 lattice defining "E") corresponding to the point "z", i.e. such that,
3034 in the standard Weierstrass model, "wp(t) = z[1],wp'(t) = z[2]". In
3035 other words, this is the inverse function of "ellztopoint". More
3036 precisely, if "(w1,w2)" are the real and complex periods of "E", "t" is
3037 such that "0 <= Re (t) < w1" and "0 <= Im (t) < Im (w2)".
3038 If "E" has coefficients in "Q_p", then either Tate's "u" is in "Q_p",
3040 in which case the output is a "p"-adic number "t" corresponding to the
3041 point "z" under the Tate parametrization, or only its square is, in
3042 which case the output is "t+1/t". "E" must be an ell as output by
3043 "ellinit".
3044 The library syntax is "zell(E,z,prec)".
3046 \subsecidx{ellpow}"(E,z,n)": computes "n" times the point "z" for the
3048 group law on the elliptic curve "E". Here, "n" can be in Z, or "n" can
3049 be a complex quadratic integer if the curve "E" has complex
3050 multiplication by "n" (if not, an error message is issued).
3051 The library syntax is "powell(E,z,n)".
3053 \subsecidx{ellrootno}"(E,{p = 1})": "E" being an sell as output by
3055 "ellinit", this computes the local (if "p != 1") or global (if "p = 1")
3056 root number of the L-series of the elliptic curve "E". Note that the
3057 global root number is the sign of the functional equation and
3058 conjecturally is the parity of the rank of the Mordell-Weil group. The
3059 equation for "E" must have coefficients in Q but need not be minimal.
3060 The library syntax is "ellrootno(E,p)" and the result (equal to "+-1")
3062 is a "long".
3063 \subsecidx{ellsigma}"(E,z,{flag = 0})": value of the Weierstrass
3065 "sigma" function of the lattice associated to "E" as given by "ellinit"
3066 (alternatively, "E" can be given as a lattice "[omega_1,omega_2]").
3067 If "flag = 1", computes an (arbitrary) determination of " log
3069 (sigma(z))".
3070 If "flag = 2,3", same using the product expansion instead of theta
3072 series. The library syntax is "ellsigma(E,z,flag)"
3073 \subsecidx{ellsearch}"(N)": if "N" is an integer, it is taken as a
3075 conductor else if "N" is a string, it can be a curve name ("11a1"), a
3076 isogeny class ("11a") or a conductor "11". This function finds all
3077 curves in the "elldata" database with the given property.
3078 If "N" is a full curve name, the output format is "[N,
3080 [a_1,a_2,a_3,a_4,a_6], G]" where "[a_1,a_2,a_3,a_4,a_6]" are the
3081 coefficients of the Weierstrass equation of the curve and "G" is a
3082 Z-basis of the free part of the Mordell-Weil group associated to the
3083 curve.
3084 If "N" is not a full-curve name, the output is the list (as a vector)
3086 of all matching curves in the above format.
3087 The library syntax is "ellsearch(N)". Also available is
3089 \funs{ellsearchcurve}{N} that only accept complete curve names.
3090 \subsecidx{ellsub}"(E,z1,z2)": difference of the points "z1" and "z2"
3092 on the elliptic curve corresponding to "E".
3093 The library syntax is "subell(E,z1,z2)".
3095 \subsecidx{elltaniyama}"(E)": computes the modular parametrization of
3097 the elliptic curve "E", where "E" is an sell as output by "ellinit", in
3098 the form of a two-component vector "[u,v]" of power series, given to
3099 the current default series precision. This vector is characterized by
3100 the following two properties. First the point "(x,y) = (u,v)" satisfies
3101 the equation of the elliptic curve. Second, the differential
3102 "du/(2v+a_1u+a_3)" is equal to "f(z)dz", a differential form on
3103 "H/Gamma_0(N)" where "N" is the conductor of the curve. The variable
3104 used in the power series for "u" and "v" is "x", which is implicitly
3105 understood to be equal to " exp (2ipi z)". It is assumed that the curve
3106 is a strong Weil curve, and that the Manin constant is equal to 1. The
3107 equation of the curve "E" must be minimal (use "ellminimalmodel" to get
3108 a minimal equation).
3109 The library syntax is "elltaniyama(E, prec)", and the precision of the
3111 result is determined by "prec".
3112 \subsecidx{elltors}"(E,{flag = 0})": if "E" is an elliptic curve
3114 defined over Q, outputs the torsion subgroup of "E" as a 3-component
3115 vector "[t,v1,v2]", where "t" is the order of the torsion group, "v1"
3116 gives the structure of the torsion group as a product of cyclic groups
3117 (sorted by decreasing order), and "v2" gives generators for these
3118 cyclic groups. "E" must be an ell as output by "ellinit".
3119 ? E = ellinit([0,0,0,-1,0]);
3121 ? elltors(E)
3122 %1 = [4, [2, 2], [[0, 0], [1, 0]]]
3123 Here, the torsion subgroup is isomorphic to "Z/2Z x Z/2Z", with
3125 generators "[0,0]" and "[1,0]".
3126 If "flag = 0", use Doud's algorithm: bound torsion by computing
3128 "#E(F_p)" for small primes of good reduction, then look for torsion
3129 points using Weierstrass parametrization (and Mazur's classification).
3130 If "flag = 1", use Lutz-Nagell (much slower), "E" is allowed to be an
3132 sell.
3133 The library syntax is "elltors0(E,flag)".
3135 \subsecidx{ellwp}"(E,{z = x},{flag = 0})":
3137 Computes the value at "z" of the Weierstrass "wp" function attached to
3139 the elliptic curve "E" as given by "ellinit" (alternatively, "E" can be
3140 given as a lattice "[omega_1,omega_2]").
3141 If "z" is omitted or is a simple variable, computes the power series
3143 expansion in "z" (starting "z^{-2}+O(z^2)"). The number of terms to an
3144 even power in the expansion is the default serieslength in "gp", and
3145 the second argument (C long integer) in library mode.
3146 Optional flag is (for now) only taken into account when "z" is numeric,
3148 and means 0: compute only "wp(z)", 1: compute "[wp(z),wp'(z)]".
3149 The library syntax is "ellwp0(E,z,flag,prec,precdl)". Also available is
3151 \funs{weipell}{E,precdl} for the power series.
3152 \subsecidx{ellzeta}"(E,z)": value of the Weierstrass "zeta" function of
3154 the lattice associated to "E" as given by "ellinit" (alternatively, "E"
3155 can be given as a lattice "[omega_1,omega_2]").
3156 The library syntax is "ellzeta(E,z)".
3158 \subsecidx{ellztopoint}"(E,z)": "E" being an ell as output by
3160 "ellinit", computes the coordinates "[x,y]" on the curve "E"
3161 corresponding to the complex number "z". Hence this is the inverse
3162 function of "ellpointtoz". In other words, if the curve is put in
3163 Weierstrass form, "[x,y]" represents the Weierstrass "wp"-function and
3164 its derivative. If "z" is in the lattice defining "E" over C, the
3165 result is the point at infinity "[0]".
3166 The library syntax is "pointell(E,z,prec)".
3168
3170 In this section can be found functions which are used almost
3171 exclusively for working in general number fields. Other less specific
3172 functions can be found in the next section on polynomials. Functions
3173 related to quadratic number fields are found in section "Label
3174 se:arithmetic" (Arithmetic functions).
3175 Number field structures
3177 Let "K = Q[X] / (T)" a number field, "Z_K" its ring of integers, "T\in
3178 Z[X]" is monic. Three basic number field structures can be associated
3179 to "K" in GP:
3180 * "nf" denotes a number field, i.e. a data structure output by
3182 "nfinit". This contains the basic arithmetic data associated to the
3183 number field: signature, maximal order (given by a basis "nf.zk"),
3184 discriminant, defining polynomial "T", etc.
3185 * "bnf" denotes a ``Buchmann's number field'', i.e. a data structure
3187 output by "bnfinit". This contains "nf" and the deeper invariants of
3188 the field: units U(K), class group " Cl (K)", as well as technical data
3189 required to solve the two associated discrete logarithm problems.
3190 * "bnr" denotes a ``ray number field'', i.e. a data structure output by
3192 "bnrinit", corresponding to the ray class group structure of the field,
3193 for some modulus "f". It contains a bnf, the modulus "f", the ray class
3194 group " Cl _f(K)" and data associated to the discrete logarithm problem
3195 therein.
3196 Algebraic numbers and ideals
3198 An algebraic number belonging to "K = Q[X]/(T)" is given as
3199 * a "t_INT", "t_FRAC" or "t_POL" (implicitly modulo "T"), or
3201 * a "t_POLMOD" (modulo "T"), or
3203 * a "t_COL" "v" of dimension "N = [K:Q]", representing the element in
3205 terms of the computed integral basis, as "sum(i = 1, N, v[i] *
3206 nf.zk[i])". Note that a "t_VEC" will not be recognized.
3207 An ideal is given in any of the following ways:
3209 * an algebraic number in one of the above forms, defining a principal
3211 ideal.
3212 * a prime ideal, i.e. a 5-component vector in the format output by
3214 "idealprimedec".
3215 * a "t_MAT", square and in Hermite Normal Form (or at least upper
3217 triangular with non-negative coefficients), whose columns represent a
3218 basis of the ideal.
3219 One may use "idealhnf" to convert an ideal to the last (preferred)
3221 format.
3222 Note.. Some routines accept non-square matrices, but using this format
3224 is strongly discouraged. Nevertheless, their behaviour is as follows:
3225 If strictly less than "N = [K:Q]" generators are given, it is assumed
3226 they form a "Z_K"-basis. If "N" or more are given, a Z-basis is
3227 assumed. If exactly "N" are given, it is further assumed the matrix is
3228 in HNF. If any of these assumptions is not correct the behaviour of the
3229 routine is undefined.
3230 * an idele is a 2-component vector, the first being an ideal as above,
3232 the second being a "R_1+R_2"-component row vector giving Archimedean
3233 information, as complex numbers.
3234 Finite abelian groups
3236 A finite abelian group "G" in user-readable format is given by its
3237 Smith Normal Form as a pair "[h,d]" or triple "[h,d,g]". Here "h" is
3238 the cardinality of "G", "(d_i)" is the vector of elementary divisors,
3239 and "(g_i)" is a vector of generators. In short, "G = \oplus_{i <= n}
3240 (Z/d_iZ) g_i", with "d_n | ... | d_2 | d_1" and "prod d_i = h". This
3241 information can also be retrieved as "G.no", "G.cyc" and "G.gen".
3242 * a character on the abelian group "\oplus (Z/d_iZ) g_i" is given by a
3244 row vector "chi = [a_1,...,a_n]" such that "chi(prod g_i^{n_i}) = exp
3245 (2ipisum a_i n_i / d_i)".
3246 * given such a structure, a subgroup "H" is input as a square matrix,
3248 whose column express generators of "H" on the given generators "g_i".
3249 Note that the absolute value of the determinant of that matrix is equal
3250 to the index "(G:H)".
3251 Relative extensions
3253 When defining a relative extension, the base field "nf" must be defined
3254 by a variable having a lower priority (see "Label se:priority") than
3255 the variable defining the extension. For example, you may use the
3256 variable name "y" to define the base field, and "x" to define the
3257 relative extension.
3258 * "rnf" denotes a relative number field, i.e. a data structure output
3260 by "rnfinit".
3261 * A relative matrix is a matrix whose entries are elements of a (fixed)
3263 number field "nf", always expressed as column vectors on the integral
3264 basis "nf.zk". Hence it is a matrix of vectors.
3265 * An ideal list is a row vector of (fractional) ideals of the number
3267 field "nf".
3268 * A pseudo-matrix is a pair "(A,I)" where "A" is a relative matrix and
3270 "I" an ideal list whose length is the same as the number of columns of
3271 "A". This pair is represented by a 2-component row vector.
3272 * The projective module generated by a pseudo-matrix "(A,I)" is the sum
3274 "sum_i {a}_j A_j" where the "{a}_j" are the ideals of "I" and "A_j" is
3275 the "j"-th column of "A".
3276 * A pseudo-matrix "(A,I)" is a pseudo-basis of the module it generates
3278 if "A" is a square matrix with non-zero determinant and all the ideals
3279 of "I" are non-zero. We say that it is in Hermite Normal Form (HNF) if
3280 it is upper triangular and all the elements of the diagonal are equal
3281 to 1.
3282 * The determinant of a pseudo-basis "(A,I)" is the ideal equal to the
3284 product of the determinant of "A" by all the ideals of "I". The
3285 determinant of a pseudo-matrix is the determinant of any pseudo-basis
3286 of the module it generates.
3287 Class field theory
3289 A "modulus", in the sense of class field theory, is a divisor supported
3290 on the non-complex places of "K". In PARI terms, this means either an
3291 ordinary ideal "I" as above (no archimedean component), or a pair
3292 "[I,a]", where "a" is a vector with "r_1" "{0,1}"-components,
3293 corresponding to the infinite part of the divisor. More precisely, the
3294 "i"-th component of "a" corresponds to the real embedding associated to
3295 the "i"-th real root of "K.roots". (That ordering is not canonical, but
3296 well defined once a defining polynomial for "K" is chosen.) For
3297 instance, "[1, [1,1]]" is a modulus for a real quadratic field,
3298 allowing ramification at any of the two places at infinity.
3299 A bid or ``big ideal'' is a structure output by "idealstar" needed to
3301 compute in "(Z_K/I)^*", where "I" is a modulus in the above sense. If
3302 is a finite abelian group as described above, supplemented by technical
3303 data needed to solve discrete log problems.
3304 Finally we explain how to input ray number fields (or bnr), using class
3306 field theory. These are defined by a triple "a1", "a2", "a3", where the
3307 defining set "[a1,a2,a3]" can have any of the following forms: "[bnr]",
3308 "[bnr,subgroup]", "[bnf,module]", "[bnf,module,subgroup]".
3309 * "bnf" is as output by "bnfinit", where units are mandatory unless the
3311 modulus is trivial; bnr is as output by "bnrinit". This is the ground
3312 field "K".
3313 * module is a modulus "f", as described above.
3315 * subgroup a subgroup of the ray class group modulo "f" of "K". As
3317 described above, this is input as a square matrix expressing generators
3318 of a subgroup of the ray class group "bnr.clgp" on the given
3319 generators.
3320 The corresponding bnr is the subfield of the ray class field of "K"
3322 modulo "f", fixed by the given subgroup.
3323 General use
3325 All the functions which are specific to relative extensions, number
3326 fields, Buchmann's number fields, Buchmann's number rays, share the
3327 prefix "rnf", "nf", "bnf", "bnr" respectively. They take as first
3328 argument a number field of that precise type, respectively output by
3329 "rnfinit", "nfinit", "bnfinit", and "bnrinit".
3330 However, and even though it may not be specified in the descriptions of
3332 the functions below, it is permissible, if the function expects a "nf",
3333 to use a "bnf" instead, which contains much more information. On the
3334 other hand, if the function requires a "bnf", it will not launch
3335 "bnfinit" for you, which is a costly operation. Instead, it will give
3336 you a specific error message. In short, the types
3337 " nf <= bnf <= bnr"
3339 are ordered, each function requires a minimal type to work properly,
3341 but you may always substitute a larger type.
3342 The data types corresponding to the structures described above are
3344 rather complicated. Thus, as we already have seen it with elliptic
3345 curves, GP provides ``member functions'' to retrieve data from these
3346 structures (once they have been initialized of course). The relevant
3347 types of number fields are indicated between parentheses:
3348 "bid" (bnr, ) : bid ideal structure.
3350 "bnf" (bnr, bnf ) : Buchmann's number field.
3352 "clgp" (bnr, bnf ) : classgroup. This one admits the following
3354 three subclasses:
3355 "cyc" : cyclic decomposition (SNF).
3357 "gen" :
3359 generators.
3360 "no" : number of elements.
3362 "diff" (bnr, bnf, nf ) : the different ideal.
3364 "codiff" (bnr, bnf, nf ) : the codifferent (inverse of the
3366 different in the ideal group).
3367 "disc" (bnr, bnf, nf ) : discriminant.
3369 "fu" (bnr, bnf, nf ) : fundamental units.
3371 "index" (bnr, bnf, nf ) : index of the power order in the ring of
3373 integers.
3374 "nf" (bnr, bnf, nf ) : number field.
3376 "r1" (bnr, bnf, nf ) : the number of real embeddings.
3378 "r2" (bnr, bnf, nf ) : the number of pairs of complex embeddings.
3380 "reg" (bnr, bnf, ) : regulator.
3382 "roots" (bnr, bnf, nf ) : roots of the polynomial generating the
3384 field.
3385 "t2" (bnr, bnf, nf ) : the T2 matrix (see "nfinit").
3387 "tu" (bnr, bnf, ) : a generator for the torsion units.
3389 "tufu" (bnr, bnf, ) : "[w,u_1,...,u_r]", "(u_i)" is a vector of
3391 fundamental units, "w" generates the torsion units.
3392 "zk" (bnr, bnf, nf ) : integral basis, i.e. a Z-basis of the
3394 maximal order.
3395 For instance, assume that "bnf = bnfinit(pol)", for some polynomial.
3397 Then "bnf.clgp" retrieves the class group, and "bnf.clgp.no" the class
3398 number. If we had set "bnf = nfinit(pol)", both would have output an
3399 error message. All these functions are completely recursive, thus for
3400 instance "bnr.bnf.nf.zk" will yield the maximal order of bnr, which you
3401 could get directly with a simple "bnr.zk".
3402 Class group, units, and the GRH
3404 Some of the functions starting with "bnf" are implementations of the
3405 sub-exponential algorithms for finding class and unit groups under GRH,
3406 due to Hafner-McCurley, Buchmann and Cohen-Diaz-Olivier. The general
3407 call to the functions concerning class groups of general number fields
3408 (i.e. excluding "quadclassunit") involves a polynomial "P" and a
3409 technical vector
3410 "tech = [c, c2, nrpid ],"
3412 where the parameters are to be understood as follows:
3414 "P" is the defining polynomial for the number field, which must be in
3416 "Z[X]", irreducible and monic. In fact, if you supply a non-monic
3417 polynomial at this point, "gp" issues a warning, then transforms your
3418 polynomial so that it becomes monic. The "nfinit" routine will return a
3419 different result in this case: instead of "res", you get a vector
3420 "[res,Mod(a,Q)]", where "Mod(a,Q) = Mod(X,P)" gives the change of
3421 variables. In all other routines, the variable change is simply lost.
3422 The numbers "c <= c_2" are positive real numbers which control the
3424 execution time and the stack size. For a given "c", set "c_2 = c" to
3425 get maximum speed. To get a rigorous result under GRH you must take "c2
3426 >= 12" (or "c2 >= 6" in "P" is quadratic). Reasonable values for "c"
3427 are between 0.1 and 2. The default is "c = c_2 = 0.3".
3428 "nrpid" is the maximal number of small norm relations associated to
3430 each ideal in the factor base. Set it to 0 to disable the search for
3431 small norm relations. Otherwise, reasonable values are between 4 and
3432 20. The default is 4.
3433 Warning.. Make sure you understand the above! By default, most of the
3435 "bnf" routines depend on the correctness of a heuristic assumption
3436 which is stronger than the GRH. In particular, any of the class number,
3437 class group structure, class group generators, regulator and
3438 fundamental units may be wrong, independently of each other. Any result
3439 computed from such a "bnf" may be wrong. The only guarantee is that the
3440 units given generate a subgroup of finite index in the full unit group.
3441 In practice, very few counter-examples are known, requiring unlucky
3442 random seeds. No counter-example has been reported for "c_2 = 0.5"
3443 (which should be almost as fast as "c_2 = 0.3", and shall very probably
3444 become the default). If you use "c_2 = 12", then everything is correct
3445 assuming the GRH holds. You can use "bnfcertify" to certify the
3446 computations unconditionally.
3447 Remarks..
3449 Apart from the polynomial "P", you do not need to supply the technical
3451 parameters (under the library you still need to send at least an empty
3452 vector, coded as "NULL"). However, should you choose to set some of
3453 them, they must be given in the requested order. For example, if you
3454 want to specify a given value of nrpid, you must give some values as
3455 well for "c" and "c_2", and provide a vector "[c,c_2,nrpid]".
3456 Note also that you can use an "nf" instead of "P", which avoids
3458 recomputing the integral basis and analogous quantities.
3459 \subsecidx{bnfcertify}"(bnf)": "bnf" being as output by "bnfinit",
3461 checks whether the result is correct, i.e. whether it is possible to
3462 remove the assumption of the Generalized Riemann Hypothesis. It is
3463 correct if and only if the answer is 1. If it is incorrect, the program
3464 may output some error message, or loop indefinitely. You can check its
3465 progress by increasing the debug level.
3466 The library syntax is "certifybuchall(bnf)", and the result is a C
3468 long.
3469 \subsecidx{bnfclassunit}"(P,{flag = 0},{tech = []})": this function is
3471 DEPRECATED, use "bnfinit".
3472 Buchmann's sub-exponential algorithm for computing the class group, the
3474 regulator and a system of fundamental units of the general algebraic
3475 number field "K" defined by the irreducible polynomial "P" with integer
3476 coefficients.
3477 The result of this function is a vector "v" with many components, which
3479 for ease of presentation is in fact output as a one column matrix. It
3480 is not a "bnf", you need "bnfinit" for that. First we describe the
3481 default behaviour ("flag = 0"):
3482 "v[1]" is equal to the polynomial "P".
3484 "v[2]" is the 2-component vector "[r1,r2]", where "r1" and "r2" are as
3486 usual the number of real and half the number of complex embeddings of
3487 the number field "K".
3488 "v[3]" is the 2-component vector containing the field discriminant and
3490 the index.
3491 "v[4]" is an integral basis in Hermite normal form.
3493 "v[5]" ("v.clgp") is a 3-component vector containing the class number
3495 ("v.clgp.no"), the structure of the class group as a product of cyclic
3496 groups of order "n_i" ("v.clgp.cyc"), and the corresponding generators
3497 of the class group of respective orders "n_i" ("v.clgp.gen").
3498 "v[6]" ("v.reg") is the regulator computed to an accuracy which is the
3500 maximum of an internally determined accuracy and of the default.
3501 "v[7]" is deprecated, maintained for backward compatibility and always
3503 equal to 1.
3504 "v[8]" ("v.tu") a vector with 2 components, the first being the number
3506 "w" of roots of unity in "K" and the second a primitive "w"-th root of
3507 unity expressed as a polynomial.
3508 "v[9]" ("v.fu") is a system of fundamental units also expressed as
3510 polynomials.
3511 If "flag = 1", and the precision happens to be insufficient for
3513 obtaining the fundamental units, the internal precision is doubled and
3514 the computation redone, until the exact results are obtained. Be warned
3515 that this can take a very long time when the coefficients of the
3516 fundamental units on the integral basis are very large, for example in
3517 large real quadratic fields. For this case, there are alternate
3518 compact representations for algebraic numbers, implemented in PARI but
3519 currently not available in GP.
3520 If "flag = 2", the fundamental units and roots of unity are not
3522 computed. Hence the result has only 7 components, the first seven
3523 ones.
3524 The library syntax is "bnfclassunit0(P,flag,tech,prec)".
3526 \subsecidx{bnfclgp}"(P,{tech = []})": as "bnfinit", but only outputs
3528 "bnf.clgp", i.e. the class group.
3529 The library syntax is "classgrouponly(P,tech,prec)", where tech is as
3531 described under "bnfinit".
3532 \subsecidx{bnfdecodemodule}"(nf,m)": if "m" is a module as output in
3534 the first component of an extension given by "bnrdisclist", outputs the
3535 true module.
3536 The library syntax is "decodemodule(nf,m)".
3538 \subsecidx{bnfinit}"(P,{flag = 0},{tech = []})": initializes a bnf
3540 structure. Used in programs such as "bnfisprincipal", "bnfisunit" or
3541 "bnfnarrow". By default, the results are conditional on a heuristic
3542 strengthening of the GRH, see se:GRHbnf. The result is a 10-component
3543 vector bnf.
3544 This implements Buchmann's sub-exponential algorithm for computing the
3546 class group, the regulator and a system of fundamental units of the
3547 general algebraic number field "K" defined by the irreducible
3548 polynomial "P" with integer coefficients.
3549 If the precision becomes insufficient, "gp" outputs a warning
3551 ("fundamental units too large, not given") and does not strive to
3552 compute the units by default ("flag = 0").
3553 When "flag = 1", we insist on finding the fundamental units exactly. Be
3555 warned that this can take a very long time when the coefficients of the
3556 fundamental units on the integral basis are very large. If the
3557 fundamental units are simply too large to be represented in this form,
3558 an error message is issued. They could be obtained using the so-called
3559 compact representation of algebraic numbers as a formal product of
3560 algebraic integers. The latter is implemented internally but not
3561 publicly accessible yet.
3562 When "flag = 2", on the contrary, it is initially agreed that units are
3564 not computed. Note that the resulting bnf will not be suitable for
3565 "bnrinit", and that this flag provides negligible time savings compared
3566 to the default. In short, it is deprecated.
3567 When "flag = 3", computes a very small version of "bnfinit", a ``small
3569 Buchmann's number field'' (or sbnf for short) which contains enough
3570 information to recover the full "bnf" vector very rapidly, but which is
3571 much smaller and hence easy to store and print. It is supposed to be
3572 used in conjunction with "bnfmake".
3573 "tech" is a technical vector (empty by default, see se:GRHbnf).
3575 Careful use of this parameter may speed up your computations
3576 considerably.
3577 The components of a bnf or sbnf are technical and never used by the
3579 casual user. In fact: never access a component directly, always use a
3580 proper member function. However, for the sake of completeness and
3581 internal documentation, their description is as follows. We use the
3582 notations explained in the book by H. Cohen, A Course in Computational
3583 Algebraic Number Theory, Graduate Texts in Maths 138, Springer-Verlag,
3584 1993, Section 6.5, and subsection 6.5.5 in particular.
3585 "bnf[1]" contains the matrix "W", i.e. the matrix in Hermite normal
3587 form giving relations for the class group on prime ideal generators
3588 "(wp_i)_{1 <= i <= r}".
3589 "bnf[2]" contains the matrix "B", i.e. the matrix containing the
3591 expressions of the prime ideal factorbase in terms of the "wp_i". It is
3592 an "r x c" matrix.
3593 "bnf[3]" contains the complex logarithmic embeddings of the system of
3595 fundamental units which has been found. It is an "(r_1+r_2) x
3596 (r_1+r_2-1)" matrix.
3597 "bnf[4]" contains the matrix "M''_C" of Archimedean components of the
3599 relations of the matrix "(W|B)".
3600 "bnf[5]" contains the prime factor base, i.e. the list of prime ideals
3602 used in finding the relations.
3603 "bnf[6]" used to contain a permutation of the prime factor base, but
3605 has been obsoleted. It contains a dummy 0.
3606 "bnf[7]" or "bnf.nf" is equal to the number field data "nf" as would be
3608 given by "nfinit".
3609 "bnf[8]" is a vector containing the classgroup "bnf.clgp" as a finite
3611 abelian group, the regulator "bnf.reg", a 1 (used to contain an
3612 obsolete ``check number''), the number of roots of unity and a
3613 generator "bnf.tu", the fundamental units "bnf.fu".
3614 "bnf[9]" is a 3-element row vector used in "bnfisprincipal" only and
3616 obtained as follows. Let "D = U W V" obtained by applying the Smith
3617 normal form algorithm to the matrix "W" ( = "bnf[1]") and let "U_r" be
3618 the reduction of "U" modulo "D". The first elements of the factorbase
3619 are given (in terms of "bnf.gen") by the columns of "U_r", with
3620 Archimedean component "g_a"; let also "GD_a" be the Archimedean
3621 components of the generators of the (principal) ideals defined by the
3622 "bnf.gen[i]^bnf.cyc[i]". Then "bnf[9] = [U_r, g_a, GD_a]".
3623 "bnf[10]" is by default unused and set equal to 0. This field is used
3625 to store further information about the field as it becomes available,
3626 which is rarely needed, hence would be too expensive to compute during
3627 the initial "bnfinit" call. For instance, the generators of the
3628 principal ideals "bnf.gen[i]^bnf.cyc[i]" (during a call to
3629 "bnrisprincipal"), or those corresponding to the relations in "W" and
3630 "B" (when the "bnf" internal precision needs to be increased).
3631 An sbnf is a 12 component vector "v", as follows. Let "bnf" be the
3633 result of a full "bnfinit", complete with units. Then "v[1]" is the
3634 polynomial "P", "v[2]" is the number of real embeddings "r_1", "v[3]"
3635 is the field discriminant, "v[4]" is the integral basis, "v[5]" is the
3636 list of roots as in the sixth component of "nfinit", "v[6]" is the
3637 matrix "MD" of "nfinit" giving a Z-basis of the different, "v[7]" is
3638 the matrix "W = bnf[1]", "v[8]" is the matrix "matalpha = bnf[2]",
3639 "v[9]" is the prime ideal factor base "bnf[5]" coded in a compact way,
3640 and ordered according to the permutation "bnf[6]", "v[10]" is the
3641 2-component vector giving the number of roots of unity and a generator,
3642 expressed on the integral basis, "v[11]" is the list of fundamental
3643 units, expressed on the integral basis, "v[12]" is a vector containing
3644 the algebraic numbers alpha corresponding to the columns of the matrix
3645 "matalpha", expressed on the integral basis.
3646 Note that all the components are exact (integral or rational), except
3648 for the roots in "v[5]". Note also that member functions will not work
3649 on sbnf, you have to use "bnfmake" explicitly first.
3650 The library syntax is "bnfinit0(P,flag,tech,prec)".
3652 \subsecidx{bnfisintnorm}"(bnf,x)": computes a complete system of
3654 solutions (modulo units of positive norm) of the absolute norm equation
3655 " Norm (a) = x", where "a" is an integer in "bnf". If "bnf" has not
3656 been certified, the correctness of the result depends on the validity
3657 of GRH.
3658 See also "bnfisnorm".
3660 The library syntax is "bnfisintnorm(bnf,x)".
3662 \subsecidx{bnfisnorm}"(bnf,x,{flag = 1})": tries to tell whether the
3664 rational number "x" is the norm of some element y in "bnf". Returns a
3665 vector "[a,b]" where "x = Norm(a)*b". Looks for a solution which is an
3666 "S"-unit, with "S" a certain set of prime ideals containing (among
3667 others) all primes dividing "x". If "bnf" is known to be Galois, set
3668 "flag = 0" (in this case, "x" is a norm iff "b = 1"). If "flag" is non
3669 zero the program adds to "S" the following prime ideals, depending on
3670 the sign of "flag". If "flag > 0", the ideals of norm less than "flag".
3671 And if "flag < 0" the ideals dividing "flag".
3672 Assuming GRH, the answer is guaranteed (i.e. "x" is a norm iff "b =
3674 1"), if "S" contains all primes less than "12 log ( disc (Bnf))^2",
3675 where "Bnf" is the Galois closure of "bnf".
3676 See also "bnfisintnorm".
3678 The library syntax is "bnfisnorm(bnf,x,flag,prec)", where "flag" and
3680 "prec" are "long"s.
3681 \subsecidx{bnfissunit}"(bnf,sfu,x)": "bnf" being output by "bnfinit",
3683 sfu by "bnfsunit", gives the column vector of exponents of "x" on the
3684 fundamental "S"-units and the roots of unity. If "x" is not a unit,
3685 outputs an empty vector.
3686 The library syntax is "bnfissunit(bnf,sfu,x)".
3688 \subsecidx{bnfisprincipal}"(bnf,x,{flag = 1})": "bnf" being the number
3690 field data output by "bnfinit", and "x" being either a Z-basis of an
3691 ideal in the number field (not necessarily in HNF) or a prime ideal in
3692 the format output by the function "idealprimedec", this function tests
3693 whether the ideal is principal or not. The result is more complete than
3694 a simple true/false answer: it gives a row vector "[v_1,v_2]", where
3695 "v_1" is the vector of components "c_i" of the class of the ideal "x"
3697 in the class group, expressed on the generators "g_i" given by
3698 "bnfinit" (specifically "bnf.gen"). The "c_i" are chosen so that "0 <=
3699 c_i < n_i" where "n_i" is the order of "g_i" (the vector of "n_i" being
3700 "bnf.cyc").
3701 "v_2" gives on the integral basis the components of "alpha" such that
3703 "x = alphaprod_ig_i^{c_i}". In particular, "x" is principal if and only
3704 if "v_1" is equal to the zero vector. In the latter case, "x =
3705 alphaZ_K" where "alpha" is given by "v_2". Note that if "alpha" is too
3706 large to be given, a warning message will be printed and "v_2" will be
3707 set equal to the empty vector.
3708 If "flag = 0", outputs only "v_1", which is much easier to compute.
3710 If "flag = 2", does as if "flag" were 0, but doubles the precision
3712 until a result is obtained.
3713 If "flag = 3", as in the default behaviour ("flag = 1"), but doubles
3715 the precision until a result is obtained.
3716 The user is warned that these two last setting may induce very lengthy
3718 computations.
3719 The library syntax is "isprincipalall(bnf,x,flag)".
3721 \subsecidx{bnfisunit}"(bnf,x)": "bnf" being the number field data
3723 output by "bnfinit" and "x" being an algebraic number (type integer,
3724 rational or polmod), this outputs the decomposition of "x" on the
3725 fundamental units and the roots of unity if "x" is a unit, the empty
3726 vector otherwise. More precisely, if "u_1",...,"u_r" are the
3727 fundamental units, and "zeta" is the generator of the group of roots of
3728 unity ("bnf.tu"), the output is a vector "[x_1,...,x_r,x_{r+1}]" such
3729 that "x = u_1^{x_1}... u_r^{x_r}.zeta^{x_{r+1}}". The "x_i" are
3730 integers for "i <= r" and is an integer modulo the order of "zeta" for
3731 "i = r+1".
3732 The library syntax is "isunit(bnf,x)".
3734 \subsecidx{bnfmake}"(sbnf)": sbnf being a ``small "bnf"'' as output by
3736 "bnfinit""(x,3)", computes the complete "bnfinit" information. The
3737 result is not identical to what "bnfinit" would yield, but is
3738 functionally identical. The execution time is very small compared to a
3739 complete "bnfinit". Note that if the default precision in "gp" (or
3740 "prec" in library mode) is greater than the precision of the roots
3741 "sbnf[5]", these are recomputed so as to get a result with greater
3742 accuracy.
3743 Note that the member functions are not available for sbnf, you have to
3745 use "bnfmake" explicitly first.
3746 The library syntax is "makebigbnf(sbnf,prec)", where "prec" is a C long
3748 integer.
3749 \subsecidx{bnfnarrow}"(bnf)": "bnf" being as output by "bnfinit",
3751 computes the narrow class group of "bnf". The output is a 3-component
3752 row vector "v" analogous to the corresponding class group component
3753 "bnf.clgp" ("bnf[8][1]"): the first component is the narrow class
3754 number "v.no", the second component is a vector containing the SNF
3755 cyclic components "v.cyc" of the narrow class group, and the third is a
3756 vector giving the generators of the corresponding "v.gen" cyclic
3757 groups. Note that this function is a special case of "bnrinit".
3758 The library syntax is "buchnarrow(bnf)".
3760 \subsecidx{bnfsignunit}"(bnf)": "bnf" being as output by "bnfinit",
3762 this computes an "r_1 x (r_1+r_2-1)" matrix having "+-1" components,
3763 giving the signs of the real embeddings of the fundamental units. The
3764 following functions compute generators for the totally positive units:
3765 /* exponents of totally positive units generators on bnf.tufu */
3767 tpuexpo(bnf)=
3768 { local(S,d,K);
3769 S = bnfsignunit(bnf); d = matsize(S);
3771 S = matrix(d[1],d[2], i,j, if (S[i,j] < 0, 1,0));
3772 S = concat(vectorv(d[1],i,1), S); \\ add sign(-1)
3773 K = lift(matker(S * Mod(1,2)));
3774 if (K, mathnfmodid(K, 2), 2*matid(d[1]))
3775 }
3776 /* totally positive units */
3778 tpu(bnf)=
3779 { local(vu = bnf.tufu, ex = tpuexpo(bnf));
3780 vector(#ex-1, i, factorback(vu, ex[,i+1])) \\ ex[,1] is 1
3782 }
3783 The library syntax is "signunits(bnf)".
3785 \subsecidx{bnfreg}"(bnf)": "bnf" being as output by "bnfinit", computes
3787 its regulator.
3788 The library syntax is "regulator(bnf,tech,prec)", where tech is as in
3790 "bnfinit".
3791 \subsecidx{bnfsunit}"(bnf,S)": computes the fundamental "S"-units of
3793 the number field "bnf" (output by "bnfinit"), where "S" is a list of
3794 prime ideals (output by "idealprimedec"). The output is a vector "v"
3795 with 6 components.
3796 "v[1]" gives a minimal system of (integral) generators of the "S"-unit
3798 group modulo the unit group.
3799 "v[2]" contains technical data needed by "bnfissunit".
3801 "v[3]" is an empty vector (used to give the logarithmic embeddings of
3803 the generators in "v[1]" in version 2.0.16).
3804 "v[4]" is the "S"-regulator (this is the product of the regulator, the
3806 determinant of "v[2]" and the natural logarithms of the norms of the
3807 ideals in "S").
3808 "v[5]" gives the "S"-class group structure, in the usual format (a row
3810 vector whose three components give in order the "S"-class number, the
3811 cyclic components and the generators).
3812 "v[6]" is a copy of "S".
3814 The library syntax is "bnfsunit(bnf,S,prec)".
3816 \subsecidx{bnfunit}"(bnf)": "bnf" being as output by "bnfinit", outputs
3818 the vector of fundamental units of the number field.
3819 This function is mostly useless, since it will only succeed if bnf
3821 contains the units, in which case "bnf.fu" is recommanded instead, or
3822 bnf was produced with "bnfinit(,,2)", which is itself deprecated.
3823 The library syntax is "buchfu(bnf)".
3825 \subsecidx{bnrL1}"(bnr,{subgroup},{flag = 0})": bnr being the number
3827 field data which is output by "bnrinit(,,1)" and subgroup being a
3828 square matrix defining a congruence subgroup of the ray class group
3829 corresponding to bnr (the trivial congruence subgroup if omitted),
3830 returns for each character "chi" of the ray class group which is
3831 trivial on this subgroup, the value at "s = 1" (or "s = 0") of the
3832 abelian "L"-function associated to "chi". For the value at "s = 0", the
3833 function returns in fact for each character "chi" a vector "[r_chi ,
3834 c_chi]" where "r_chi" is the order of "L(s, chi)" at "s = 0" and
3835 "c_chi" the first non-zero term in the expansion of "L(s, chi)" at "s =
3836 0"; in other words
3837 "L(s, chi) = c_chi.s^{r_chi} + O(s^{r_chi + 1})"
3839 near 0. flag is optional, default value is 0; its binary digits mean 1:
3841 compute at "s = 1" if set to 1 or "s = 0" if set to 0, 2: compute the
3842 primitive "L"-functions associated to "chi" if set to 0 or the
3843 "L"-function with Euler factors at prime ideals dividing the modulus of
3844 bnr removed if set to 1 (this is the so-called "L_S(s, chi)" function
3845 where "S" is the set of infinite places of the number field together
3846 with the finite prime ideals dividing the modulus of bnr, see the
3847 example below), 3: returns also the character. Example:
3848 bnf = bnfinit(x^2 - 229);
3850 bnr = bnrinit(bnf,1,1);
3851 bnrL1(bnr)
3852 returns the order and the first non-zero term of the abelian
3854 "L"-functions "L(s, chi)" at "s = 0" where "chi" runs through the
3855 characters of the class group of "Q( sqrt {229})". Then
3856 bnr2 = bnrinit(bnf,2,1);
3858 bnrL1(bnr2,,2)
3859 returns the order and the first non-zero terms of the abelian
3861 "L"-functions "L_S(s, chi)" at "s = 0" where "chi" runs through the
3862 characters of the class group of "Q( sqrt {229})" and "S" is the set of
3863 infinite places of "Q( sqrt {229})" together with the finite prime 2.
3864 Note that the ray class group modulo 2 is in fact the class group, so
3865 "bnrL1(bnr2,0)" returns exactly the same answer as "bnrL1(bnr,0)".
3866 The library syntax is "bnrL1(bnr,subgroup,flag,prec)", where an omitted
3868 subgroup is coded as "NULL".
3869 \subsecidx{bnrclass}"(bnf,ideal,{flag = 0})": this function is
3871 DEPRECATED, use "bnrinit".
3872 "bnf" being as output by "bnfinit" (the units are mandatory unless the
3874 ideal is trivial), and ideal being a modulus, computes the ray class
3875 group of the number field for the modulus ideal, as a finite abelian
3876 group.
3877 The library syntax is "bnrclass0(bnf,ideal,flag)".
3879 \subsecidx{bnrclassno}"(bnf,I)": "bnf" being as output by "bnfinit"
3881 (units are mandatory unless the ideal is trivial), and "I" being a
3882 modulus, computes the ray class number of the number field for the
3883 modulus "I". This is faster than "bnrinit" and should be used if only
3884 the ray class number is desired. See "bnrclassnolist" if you need ray
3885 class numbers for all moduli less than some bound.
3886 The library syntax is "bnrclassno(bnf,I)".
3888 \subsecidx{bnrclassnolist}"(bnf,list)": "bnf" being as output by
3890 "bnfinit", and list being a list of moduli (with units) as output by
3891 "ideallist" or "ideallistarch", outputs the list of the class numbers
3892 of the corresponding ray class groups. To compute a single class
3893 number, "bnrclassno" is more efficient.
3894 ? bnf = bnfinit(x^2 - 2);
3896 ? L = ideallist(bnf, 100, 2);
3897 ? H = bnrclassnolist(bnf, L);
3898 ? H[98]
3899 %4 = [1, 3, 1]
3900 ? l = L[1][98]; ids = vector(#l, i, l[i].mod[1])
3901 %5 = [[98, 88; 0, 1], [14, 0; 0, 7], [98, 10; 0, 1]]
3902 The weird "l[i].mod[1]", is the first component of "l[i].mod", i.e.
3904 the finite part of the conductor. (This is cosmetic: since by
3905 construction the archimedean part is trivial, I do not want to see it).
3906 This tells us that the ray class groups modulo the ideals of norm 98
3907 (printed as %5) have respectively order 1, 3 and 1. Indeed, we may
3908 check directly :
3909 ? bnrclassno(bnf, ids[2])
3911 %6 = 3
3912 The library syntax is "bnrclassnolist(bnf,list)".
3914 \subsecidx{bnrconductor}"(a_1,{a_2},{a_3}, {flag = 0})": conductor "f"
3916 of the subfield of a ray class field as defined by "[a_1,a_2,a_3]" (see
3917 "bnr" at the beginning of this section).
3918 If "flag = 0", returns "f".
3920 If "flag = 1", returns "[f, Cl_f, H]", where "Cl_f" is the ray class
3922 group modulo "f", as a finite abelian group; finally "H" is the
3923 subgroup of "Cl_f" defining the extension.
3924 If "flag = 2", returns "[f, bnr(f), H]", as above except "Cl_f" is
3926 replaced by a "bnr" structure, as output by "bnrinit(,f,1)".
3927 The library syntax is "conductor(bnr, subgroup, flag)", where an
3929 omitted subgroup (trivial subgroup, i.e. ray class field) is input as
3930 "NULL", and "flag" is a C long.
3931 \subsecidx{bnrconductorofchar}"(bnr,chi)": bnr being a big ray number
3933 field as output by "bnrinit", and chi being a row vector representing a
3934 character as expressed on the generators of the ray class group, gives
3935 the conductor of this character as a modulus.
3936 The library syntax is "bnrconductorofchar(bnr,chi)".
3938 \subsecidx{bnrdisc}"(a1,{a2},{a3},{flag = 0})": "a1", "a2", "a3"
3940 defining a big ray number field "L" over a ground field "K" (see "bnr"
3941 at the beginning of this section for the meaning of "a1", "a2", "a3"),
3942 outputs a 3-component row vector "[N,R_1,D]", where "N" is the
3943 (absolute) degree of "L", "R_1" the number of real places of "L", and
3944 "D" the discriminant of "L/Q", including sign (if "flag = 0").
3945 If "flag = 1", as above but outputs relative data. "N" is now the
3947 degree of "L/K", "R_1" is the number of real places of "K" unramified
3948 in "L" (so that the number of real places of "L" is equal to "R_1"
3949 times the relative degree "N"), and "D" is the relative discriminant
3950 ideal of "L/K".
3951 If "flag = 2", as the default case, except that if the modulus is not
3953 the exact conductor corresponding to the "L", no data is computed and
3954 the result is 0.
3955 If "flag = 3", as case 2, but output relative data.
3957 The library syntax is "bnrdisc0(a1,a2,a3,flag)".
3959 \subsecidx{bnrdisclist}"(bnf,bound,{arch})": "bnf" being as output by
3961 "bnfinit" (with units), computes a list of discriminants of Abelian
3962 extensions of the number field by increasing modulus norm up to bound
3963 bound. The ramified Archimedean places are given by arch; all possible
3964 values are taken if arch is omitted.
3965 The alternative syntax "bnrdisclist(bnf,list)" is supported, where list
3967 is as output by "ideallist" or "ideallistarch" (with units), in which
3968 case arch is disregarded.
3969 The output "v" is a vector of vectors, where "v[i][j]" is understood to
3971 be in fact "V[2^{15}(i-1)+j]" of a unique big vector "V". (This akward
3972 scheme allows for larger vectors than could be otherwise represented.)
3973 "V[k]" is itself a vector "W", whose length is the number of ideals of
3975 norm "k". We consider first the case where arch was specified. Each
3976 component of "W" corresponds to an ideal "m" of norm "k", and gives
3977 invariants associated to the ray class field "L" of "bnf" of conductor
3978 "[m, arch]". Namely, each contains a vector "[m,d,r,D]" with the
3979 following meaning: "m" is the prime ideal factorization of the modulus,
3980 "d = [L:Q]" is the absolute degree of "L", "r" is the number of real
3981 places of "L", and "D" is the factorization of its absolute
3982 discriminant. We set "d = r = D = 0" if "m" is not the finite part of a
3983 conductor.
3984 If arch was omitted, all "t = 2^{r_1}" possible values are taken and a
3986 component of "W" has the form "[m, [[d_1,r_1,D_1],...,
3987 [d_t,r_t,D_t]]]", where "m" is the finite part of the conductor as
3988 above, and "[d_i,r_i,D_i]" are the invariants of the ray class field of
3989 conductor "[m,v_i]", where "v_i" is the "i"-th archimedean component,
3990 ordered by inverse lexicographic order; so "v_1 = [0,...,0]", "v_2 =
3991 [1,0...,0]", etc. Again, we set "d_i = r_i = D_i = 0" if "[m,v_i]" is
3992 not a conductor.
3993 Finally, each prime ideal "pr = [p,alpha,e,f,beta]" in the prime
3995 factorization "m" is coded as the integer "p.n^2+(f-1).n+(j-1)", where
3996 "n" is the degree of the base field and "j" is such that
3997 "pr = idealprimedec(nf,p)[j]".
3999 "m" can be decoded using "bnfdecodemodule".
4001 Note that to compute such data for a single field, either "bnrclassno"
4003 or "bnrdisc" is more efficient.
4004 The library syntax is "bnrdisclist0(bnf,bound,arch)".
4006 \subsecidx{bnrinit}"(bnf,f,{flag = 0})": "bnf" is as output by
4008 "bnfinit", "f" is a modulus, initializes data linked to the ray class
4009 group structure corresponding to this module, a so-called bnr
4010 structure. The following member functions are available on the result:
4011 ".bnf" is the underlying bnf, ".mod" the modulus, ".bid" the bid
4012 structure associated to the modulus; finally, ".clgp", ".no", ".cyc",
4013 "clgp" refer to the ray class group (as a finite abelian group), its
4014 cardinality, its elementary divisors, its generators.
4015 The last group of functions are different from the members of the
4017 underlying bnf, which refer to the class group; use "bnr.bnf.xxx" to
4018 access these, e.g. "bnr.bnf.cyc" to get the cyclic decomposition of the
4019 class group.
4020 They are also different from the members of the underlying bid, which
4022 refer to "(\O_K/f)^*"; use "bnr.bid.xxx" to access these,
4023 e.g. "bnr.bid.no" to get "phi(f)".
4024 If "flag = 0" (default), the generators of the ray class group are not
4026 computed, which saves time. Hence "bnr.gen" would produce an error.
4027 If "flag = 1", as the default, except that generators are computed.
4029 The library syntax is "bnrinit0(bnf,f,flag)".
4031 \subsecidx{bnrisconductor}"(a1,{a2},{a3})": "a1", "a2", "a3" represent
4033 an extension of the base field, given by class field theory for some
4034 modulus encoded in the parameters. Outputs 1 if this modulus is the
4035 conductor, and 0 otherwise. This is slightly faster than
4036 "bnrconductor".
4037 The library syntax is "bnrisconductor(a1,a2,a3)" and the result is a
4039 "long".
4040 \subsecidx{bnrisprincipal}"(bnr,x,{flag = 1})": bnr being the number
4042 field data which is output by "bnrinit""(,,1)" and "x" being an ideal
4043 in any form, outputs the components of "x" on the ray class group
4044 generators in a way similar to "bnfisprincipal". That is a 2-component
4045 vector "v" where "v[1]" is the vector of components of "x" on the ray
4046 class group generators, "v[2]" gives on the integral basis an element
4047 "alpha" such that "x = alphaprod_ig_i^{x_i}".
4048 If "flag = 0", outputs only "v_1". In that case, bnr need not contain
4050 the ray class group generators, i.e. it may be created with
4051 "bnrinit""(,,0)"
4052 The library syntax is "bnrisprincipal(bnr,x,flag)".
4054 \subsecidx{bnrrootnumber}"(bnr,chi,{flag = 0})": if "chi = chi" is a
4056 (not necessarily primitive) character over bnr, let "L(s,chi) =
4057 sum_{id} chi(id) N(id)^{-s}" be the associated Artin L-function.
4058 Returns the so-called Artin root number, i.e. the complex number
4059 "W(chi)" of modulus 1 such that
4060 "Lambda(1-s,chi) = W(chi) Lambda(s,\overline{chi})"
4062 where "Lambda(s,chi) = A(chi)^{s/2}gamma_chi(s) L(s,chi)" is the
4064 enlarged L-function associated to "L".
4065 The generators of the ray class group are needed, and you can set "flag
4067 = 1" if the character is known to be primitive. Example:
4068 bnf = bnfinit(x^2 - 145);
4070 bnr = bnrinit(bnf,7,1);
4071 bnrrootnumber(bnr, [5])
4072 returns the root number of the character "chi" of " Cl _7(Q( sqrt
4074 {145}))" such that "chi(g) = zeta^5", where "g" is the generator of the
4075 ray-class field and "zeta = e^{2ipi/N}" where "N" is the order of "g"
4076 ("N = 12" as "bnr.cyc" readily tells us).
4077 The library syntax is "bnrrootnumber(bnf,chi,flag)"
4079 \subsecidx{bnrstark}"{(bnr,{subgroup})}": bnr being as output by
4081 "bnrinit(,,1)", finds a relative equation for the class field
4082 corresponding to the modulus in bnr and the given congruence subgroup
4083 (as usual, omit "subgroup" if you want the whole ray class group).
4084 The routine uses Stark units and needs to find a suitable auxilliary
4086 conductor, which may not exist when the class field is not cyclic over
4087 the base. In this case "bnrstark" is allowed to return a vector of
4088 polynomials defining independent relative extensions, whose compositum
4089 is the requested class field. It was decided that it was more useful to
4090 keep the extra information thus made available, hence the user has to
4091 take the compositum herself.
4092 The main variable of bnr must not be "x", and the ground field and the
4094 class field must be totally real. When the base field is Q, the vastly
4095 simpler "galoissubcyclo" is used instead. Here is an example:
4096 bnf = bnfinit(y^2 - 3);
4098 bnr = bnrinit(bnf, 5, 1);
4099 pol = bnrstark(bnr)
4100 returns the ray class field of "Q( sqrt {3})" modulo 5. Usually, one
4102 wants to apply to the result one of
4103 rnfpolredabs(bnf, pol, 16 + 2) \\ compute a reduced relative polynomial
4105 rnfpolredabs(bnf, pol, 16 + 2) \\ compute a reduced absolute polynomial
4106 The library syntax is "bnrstark(bnr,subgroup)", where an omitted
4108 subgroup is coded by "NULL".
4109 \subsecidx{dirzetak}"(nf,b)": gives as a vector the first "b"
4111 coefficients of the Dedekind zeta function of the number field "nf"
4112 considered as a Dirichlet series.
4113 The library syntax is "dirzetak(nf,b)".
4115 \subsecidx{factornf}"(x,t)": factorization of the univariate polynomial
4117 "x" over the number field defined by the (univariate) polynomial "t".
4118 "x" may have coefficients in Q or in the number field. The algorithm
4119 reduces to factorization over Q (Trager's trick). The direct approach
4120 of "nffactor", which uses van Hoeij's method in a relative setting, is
4121 in general faster.
4122 The main variable of "t" must be of lower priority than that of "x"
4124 (see "Label se:priority"). However if non-rational number field
4125 elements occur (as polmods or polynomials) as coefficients of "x", the
4126 variable of these polmods must be the same as the main variable of "t".
4127 For example
4128 ? factornf(x^2 + Mod(y, y^2+1), y^2+1);
4130 ? factornf(x^2 + y, y^2+1); \\ these two are OK
4131 ? factornf(x^2 + Mod(z,z^2+1), y^2+1)
4132 *** factornf: inconsistent data in rnf function.
4133 ? factornf(x^2 + z, y^2+1)
4134 *** factornf: incorrect variable in rnf function.
4135 The library syntax is "polfnf(x,t)".
4137 \subsecidx{galoisexport}"(gal,{flag = 0})": gal being be a Galois field
4139 as output by "galoisinit", export the underlying permutation group as a
4140 string suitable for (no flags or "flag = 0") GAP or ("flag = 1") Magma.
4141 The following example compute the index of the underlying abstract
4142 group in the GAP library:
4143 ? G = galoisinit(x^6+108);
4145 ? s = galoisexport(G)
4146 %2 = "Group((1, 2, 3)(4, 5, 6), (1, 4)(2, 6)(3, 5))"
4147 ? extern("echo \"IdGroup("s");\" | gap -q")
4148 %3 = [6, 1]
4149 ? galoisidentify(G)
4150 %4 = [6, 1]
4151 This command also accepts subgroups returned by "galoissubgroups".
4153 The library syntax is "galoisexport(gal,flag)".
4155 \subsecidx{galoisfixedfield}"(gal,perm,{flag = 0},{v = y}))": gal being
4157 be a Galois field as output by "galoisinit" and perm an element of
4158 "gal.group" or a vector of such elements, computes the fixed field of
4159 gal by the automorphism defined by the permutations perm of the roots
4160 "gal.roots". "P" is guaranteed to be squarefree modulo "gal.p".
4161 If no flags or "flag = 0", output format is the same as for
4163 "nfsubfield", returning "[P,x]" such that "P" is a polynomial defining
4164 the fixed field, and "x" is a root of "P" expressed as a polmod in
4165 "gal.pol".
4166 If "flag = 1" return only the polynomial "P".
4168 If "flag = 2" return "[P,x,F]" where "P" and "x" are as above and "F"
4170 is the factorization of "gal.pol" over the field defined by "P", where
4171 variable "v" ("y" by default) stands for a root of "P". The priority of
4172 "v" must be less than the priority of the variable of "gal.pol" (see
4173 "Label se:priority"). Example:
4174 ? G = galoisinit(x^4+1);
4176 ? galoisfixedfield(G,G.group[2],2)
4177 %2 = [x^2 + 2, Mod(x^3 + x, x^4 + 1), [x^2 - y*x - 1, x^2 + y*x - 1]]
4178 computes the factorization "x^4+1 = (x^2- sqrt {-2}x-1)(x^2+ sqrt
4180 {-2}x-1)"
4181 The library syntax is "galoisfixedfield(gal,perm,flag,v)", where "v" is
4183 a variable number, an omitted "v" being coded by "-1".
4184 \subsecidx{galoisidentify}"(gal)": gal being be a Galois field as
4186 output by "galoisinit", output the isomorphism class of the underlying
4187 abstract group as a two-components vector "[o,i]", where "o" is the
4188 group order, and "i" is the group index in the GAP4 Small Group
4189 library, by Hans Ulrich Besche, Bettina Eick and Eamonn O'Brien.
4190 This command also accepts subgroups returned by "galoissubgroups".
4192 The current implementation is limited to degree less or equal to 127.
4194 Some larger ``easy'' orders are also supported.
4195 The output is similar to the output of the function "IdGroup" in GAP4.
4197 Note that GAP4 "IdGroup" handles all groups of order less than 2000
4198 except 1024, so you can use "galoisexport" and GAP4 to identify large
4199 Galois groups.
4200 The library syntax is "galoisidentify(gal)".
4202 \subsecidx{galoisinit}"(pol,{den})": computes the Galois group and all
4204 necessary information for computing the fixed fields of the Galois
4205 extension "K/Q" where "K" is the number field defined by "pol" (monic
4206 irreducible polynomial in "Z[X]" or a number field as output by
4207 "nfinit"). The extension "K/Q" must be Galois with Galois group
4208 ``weakly'' super-solvable (see "nfgaloisconj")
4209 This is a prerequisite for most of the "galois""xxx" routines. For
4211 instance:
4212 P = x^6 + 108;
4214 G = galoisinit(P);
4215 L = galoissubgroups(G);
4216 vector(#L, i, galoisisabelian(L[i],1))
4217 vector(#L, i, galoisidentify(L[i]))
4218 The output is an 8-component vector gal.
4220 "gal[1]" contains the polynomial pol ("gal.pol").
4222 "gal[2]" is a three-components vector "[p,e,q]" where "p" is a prime
4224 number ("gal.p") such that pol totally split modulo "p" , "e" is an
4225 integer and "q = p^e" ("gal.mod") is the modulus of the roots in
4226 "gal.roots".
4227 "gal[3]" is a vector "L" containing the "p"-adic roots of pol as
4229 integers implicitly modulo "gal.mod". ("gal.roots").
4230 "gal[4]" is the inverse of the Van der Monde matrix of the "p"-adic
4232 roots of pol, multiplied by "gal[5]".
4233 "gal[5]" is a multiple of the least common denominator of the
4235 automorphisms expressed as polynomial in a root of pol.
4236 "gal[6]" is the Galois group "G" expressed as a vector of permutations
4238 of "L" ("gal.group").
4239 "gal[7]" is a generating subset "S = [s_1,...,s_g]" of "G" expressed as
4241 a vector of permutations of "L" ("gal.gen").
4242 "gal[8]" contains the relative orders "[o_1,...,o_g]" of the generators
4244 of "S" ("gal.orders").
4245 Let "H" be the maximal normal supersolvable subgroup of "G", we have
4247 the following properties:
4248 * if "G/H ~ A_4" then "[o_1,...,o_g]" ends by "[2,2,3]".
4250 * if "G/H ~ S_4" then "[o_1,...,o_g]" ends by "[2,2,3,2]".
4252 * else "G" is super-solvable.
4254 * for "1 <= i <= g" the subgroup of "G" generated by "[s_1,...,s_g]"
4256 is normal, with the exception of "i = g-2" in the second case and of "i
4257 = g-3" in the third.
4258 * the relative order "o_i" of "s_i" is its order in the quotient
4260 group "G/<s_1,...,s_{i-1}>", with the same exceptions.
4261 * for any "x\in G" there exists a unique family "[e_1,...,e_g]" such
4263 that (no exceptions):
4264 -- for "1 <= i <= g" we have "0 <= e_i < o_i"
4266 -- "x = g_1^{e_1}g_2^{e_2}...g_n^{e_n}"
4268 If present "den" must be a suitable value for "gal[5]".
4270 The library syntax is "galoisinit(gal,den)".
4272 \subsecidx{galoisisabelian}"(gal,{fl = 0})": gal being as output by
4274 "galoisinit", return 0 if gal is not an abelian group, and the HNF
4275 matrix of gal over "gal.gen" if "fl = 0", 1 if "fl = 1".
4276 This command also accepts subgroups returned by "galoissubgroups".
4278 The library syntax is "galoisisabelian(gal,fl)" where fl is a C long
4280 integer.
4281 \subsecidx{galoispermtopol}"(gal,perm)": gal being a Galois field as
4283 output by "galoisinit" and perm a element of "gal.group", return the
4284 polynomial defining the Galois automorphism, as output by
4285 "nfgaloisconj", associated with the permutation perm of the roots
4286 "gal.roots". perm can also be a vector or matrix, in this case,
4287 "galoispermtopol" is applied to all components recursively.
4288 Note that
4290 G = galoisinit(pol);
4292 galoispermtopol(G, G[6])~
4293 is equivalent to "nfgaloisconj(pol)", if degree of pol is greater or
4295 equal to 2.
4296 The library syntax is "galoispermtopol(gal,perm)".
4298 \subsecidx{galoissubcyclo}"(N,H,{fl = 0},{v})": computes the
4300 subextension of "Q(zeta_n)" fixed by the subgroup "H \subset (Z/nZ)^*".
4301 By the Kronecker-Weber theorem, all abelian number fields can be
4302 generated in this way (uniquely if "n" is taken to be minimal).
4303 The pair "(n, H)" is deduced from the parameters "(N, H)" as follows
4305 * "N" an integer: then "n = N"; "H" is a generator, i.e. an integer or
4307 an integer modulo "n"; or a vector of generators.
4308 * "N" the output of znstar(n). "H" as in the first case above, or a
4310 matrix, taken to be a HNF left divisor of the SNF for "(Z/nZ)^*" (of
4311 type "N.cyc"), giving the generators of "H" in terms of "N.gen".
4312 * "N" the output of "bnrinit(bnfinit(y), m, 1)" where "m" is a module.
4314 "H" as in the first case, or a matrix taken to be a HNF left divisor of
4315 the SNF for the ray class group modulo "m" (of type "N.cyc"), giving
4316 the generators of "H" in terms of "N.gen".
4317 In this last case, beware that "H" is understood relatively to "N"; in
4319 particular, if the infinite place does not divide the module, e.g if
4320 "m" is an integer, then it is not a subgroup of "(Z/nZ)^*", but of its
4321 quotient by "{+- 1}".
4322 If "fl = 0", compute a polynomial (in the variable v) defining the the
4324 subfield of "Q(zeta_n)" fixed by the subgroup H of "(Z/nZ)^*".
4325 If "fl = 1", compute only the conductor of the abelian extension, as a
4327 module.
4328 If "fl = 2", output "[pol, N]", where "pol" is the polynomial as output
4330 when "fl = 0" and "N" the conductor as output when "fl = 1".
4331 The following function can be used to compute all subfields of
4333 "Q(zeta_n)" (of exact degree "d", if "d" is set):
4334 subcyclo(n, d = -1)=
4336 {
4337 local(bnr,L,IndexBound);
4338 IndexBound = if (d < 0, n, [d]);
4339 bnr = bnrinit(bnfinit(y), [n,[1]], 1);
4340 L = subgrouplist(bnr, IndexBound, 1);
4341 vector(#L,i, galoissubcyclo(bnr,L[i]));
4342 }
4343 Setting "L = subgrouplist(bnr, IndexBound)" would produce subfields of
4345 exact conductor "n oo ".
4346 The library syntax is "galoissubcyclo(N,H,fl,v)" where fl is a C long
4348 integer, and v a variable number.
4349 \subsecidx{galoissubfields}"(G,{fl = 0},{v})": Output all the subfields
4351 of the Galois group G, as a vector. This works by applying
4352 "galoisfixedfield" to all subgroups. The meaning of the flag fl is the
4353 same as for "galoisfixedfield".
4354 The library syntax is "galoissubfields(G,fl,v)", where fl is a long and
4356 v a variable number.
4357 \subsecidx{galoissubgroups}"(gal)": Output all the subgroups of the
4359 Galois group "gal". A subgroup is a vector [gen, orders], with the same
4360 meaning as for "gal.gen" and "gal.orders". Hence gen is a vector of
4361 permutations generating the subgroup, and orders is the relatives
4362 orders of the generators. The cardinal of a subgroup is the product of
4363 the relative orders. Such subgroup can be used instead of a Galois
4364 group in the following command: "galoisisabelian", "galoissubgroups",
4365 "galoisexport" and "galoisidentify".
4366 To get the subfield fixed by a subgroup sub of gal, use
4368 galoisfixedfield(gal,sub[1])
4370 The library syntax is "galoissubgroups(gal)".
4372 \subsecidx{idealadd}"(nf,x,y)": sum of the two ideals "x" and "y" in
4374 the number field "nf". When "x" and "y" are given by Z-bases, this does
4375 not depend on "nf" and can be used to compute the sum of any two
4376 Z-modules. The result is given in HNF.
4377 The library syntax is "idealadd(nf,x,y)".
4379 \subsecidx{idealaddtoone}"(nf,x,{y})": "x" and "y" being two co-prime
4381 integral ideals (given in any form), this gives a two-component row
4382 vector "[a,b]" such that "a\in x", "b\in y" and "a+b = 1".
4383 The alternative syntax "idealaddtoone(nf,v)", is supported, where "v"
4385 is a "k"-component vector of ideals (given in any form) which sum to
4386 "Z_K". This outputs a "k"-component vector "e" such that "e[i]\in x[i]"
4387 for "1 <= i <= k" and "sum_{1 <= i <= k}e[i] = 1".
4388 The library syntax is "idealaddtoone0(nf,x,y)", where an omitted "y" is
4390 coded as "NULL".
4391 \subsecidx{idealappr}"(nf,x,{flag = 0})": if "x" is a fractional ideal
4393 (given in any form), gives an element "alpha" in "nf" such that for all
4394 prime ideals "wp" such that the valuation of "x" at "wp" is non-zero,
4395 we have "v_{wp}(alpha) = v_{wp}(x)", and. "v_{wp}(alpha) >= 0" for all
4396 other "{wp}".
4397 If "flag" is non-zero, "x" must be given as a prime ideal
4399 factorization, as output by "idealfactor", but possibly with zero or
4400 negative exponents. This yields an element "alpha" such that for all
4401 prime ideals "wp" occurring in "x", "v_{wp}(alpha)" is equal to the
4402 exponent of "wp" in "x", and for all other prime ideals, "v_{wp}(alpha)
4403 >= 0". This generalizes "idealappr(nf,x,0)" since zero exponents are
4404 allowed. Note that the algorithm used is slightly different, so that
4405 "idealappr(nf,idealfactor(nf,x))" may not be the same as
4406 "idealappr(nf,x,1)".
4407 The library syntax is "idealappr0(nf,x,flag)".
4409 \subsecidx{idealchinese}"(nf,x,y)": "x" being a prime ideal
4411 factorization (i.e. a 2 by 2 matrix whose first column contain prime
4412 ideals, and the second column integral exponents), "y" a vector of
4413 elements in "nf" indexed by the ideals in "x", computes an element "b"
4414 such that
4415 "v_wp(b - y_wp) >= v_wp(x)" for all prime ideals in "x" and "v_wp(b) >=
4417 0" for all other "wp".
4418 The library syntax is "idealchinese(nf,x,y)".
4420 \subsecidx{idealcoprime}"(nf,x,y)": given two integral ideals "x" and
4422 "y" in the number field "nf", finds a "beta" in the field, expressed on
4423 the integral basis "nf[7]", such that "beta.x" is an integral ideal
4424 coprime to "y".
4425 The library syntax is "idealcoprime(nf,x,y)".
4427 \subsecidx{idealdiv}"(nf,x,y,{flag = 0})": quotient "x.y^{-1}" of the
4429 two ideals "x" and "y" in the number field "nf". The result is given in
4430 HNF.
4431 If "flag" is non-zero, the quotient "x.y^{-1}" is assumed to be an
4433 integral ideal. This can be much faster when the norm of the quotient
4434 is small even though the norms of "x" and "y" are large.
4435 The library syntax is "idealdiv0(nf,x,y,flag)". Also available are
4437 \funs{idealdiv}{nf,x,y} ("flag = 0") and \funs{idealdivexact}{nf,x,y}
4438 ("flag = 1").
4439 \subsecidx{idealfactor}"(nf,x)": factors into prime ideal powers the
4441 ideal "x" in the number field "nf". The output format is similar to the
4442 "factor" function, and the prime ideals are represented in the form
4443 output by the "idealprimedec" function, i.e. as 5-element vectors.
4444 The library syntax is "idealfactor(nf,x)".
4446 \subsecidx{idealhnf}"(nf,a,{b})": gives the Hermite normal form matrix
4448 of the ideal "a". The ideal can be given in any form whatsoever
4449 (typically by an algebraic number if it is principal, by a "Z_K"-system
4450 of generators, as a prime ideal as given by "idealprimedec", or by a
4451 Z-basis).
4452 If "b" is not omitted, assume the ideal given was "aZ_K+bZ_K", where
4454 "a" and "b" are elements of "K" given either as vectors on the integral
4455 basis "nf[7]" or as algebraic numbers.
4456 The library syntax is "idealhnf0(nf,a,b)" where an omitted "b" is coded
4458 as "NULL". Also available is \funs{idealhermite}{nf,a} ("b" omitted).
4459 \subsecidx{idealintersect}"(nf,A,B)": intersection of the two ideals
4461 "A" and "B" in the number field "nf". The result is given in HNF.
4462 ? nf = nfinit(x^2+1);
4464 ? idealintersect(nf, 2, x+1)
4465 %2 =
4466 [2 0]
4467 [0 2]
4469 This function does not apply to general Z-modules, e.g. orders, since
4471 its arguments are replaced by the ideals they generate. The following
4472 script intersects Z-modules "A" and "B" given by matrices of compatible
4473 dimensions with integer coefficients:
4474 ZM_intersect(A,B) =
4476 { local( Ker = matkerint(concat(A,B)) );
4477 mathnf(A * vecextract(Ker, Str("..", #A), ".."))
4478 }
4479 The library syntax is "idealintersect(nf,A,B)".
4481 \subsecidx{idealinv}"(nf,x)": inverse of the ideal "x" in the number
4483 field "nf". The result is the Hermite normal form of the inverse of the
4484 ideal, together with the opposite of the Archimedean information if it
4485 is given.
4486 The library syntax is "idealinv(nf,x)".
4488 \subsecidx{ideallist}"(nf,bound,{flag = 4})": computes the list of all
4490 ideals of norm less or equal to bound in the number field nf. The
4491 result is a row vector with exactly bound components. Each component
4492 is itself a row vector containing the information about ideals of a
4493 given norm, in no specific order, depending on the value of "flag":
4494 The possible values of "flag" are:
4496 0: give the bid associated to the ideals, without generators.
4498 1: as 0, but include the generators in the bid.
4500 2: in this case, nf must be a bnf with units. Each component is of
4502 the form "[bid,U]", where bid is as case 0 and "U" is a vector of
4503 discrete logarithms of the units. More precisely, it gives the
4504 "ideallog"s with respect to bid of "bnf.tufu". This structure is
4505 technical, and only meant to be used in conjunction with
4506 "bnrclassnolist" or "bnrdisclist".
4507 3: as 2, but include the generators in the bid.
4509 4: give only the HNF of the ideal.
4511 ? #L[65]
4513 %4 = 4 \\ A single ideal of norm 1
4514 ? #L[65]
4515 %4 = 4 \\ There are 4 ideals of norm 4 in B<I<Z>>[i]
4516 If one wants more information, one could do instead:
4518 ? nf = nfinit(x^2+1);
4520 ? L = ideallist(nf, 100, 0);
4521 ? l = L[25]; vector(#l, i, l[i].clgp)
4522 %3 = [[20, [20]], [16, [4, 4]], [20, [20]]]
4523 ? l[1].mod
4524 %4 = [[25, 18; 0, 1], []]
4525 ? l[2].mod
4526 %5 = [[5, 0; 0, 5], []]
4527 ? l[3].mod
4528 %6 = [[25, 7; 0, 1], []]
4529 where we ask for the structures of the "(Z[i]/I)^*" for all three
4531 ideals of norm 25. In fact, for all moduli with finite part of norm 25
4532 and trivial archimedean part, as the last 3 commands show. See
4533 "ideallistarch" to treat general moduli.
4534 The library syntax is "ideallist0(nf,bound,flag)", where bound must be
4536 a C long integer. Also available is \funs{ideallist}{nf,bound},
4537 corresponding to the case "flag = 4".
4538 \subsecidx{ideallistarch}"(nf,list,arch)": list is a vector of vectors
4540 of bid's, as output by "ideallist" with flag 0 to 3. Return a vector of
4541 vectors with the same number of components as the original list. The
4542 leaves give information about moduli whose finite part is as in
4543 original list, in the same order, and archimedean part is now arch (it
4544 was originally trivial). The information contained is of the same kind
4545 as was present in the input; see "ideallist", in particular the meaning
4546 of flag.
4547 ? L = ideallist(bnf, 100, 0);
4549 ? l = L[98]; vector(#l, i, l[i].clgp)
4550 %4 = [[42, [42]], [36, [6, 6]], [42, [42]]]
4551 ? La = ideallistarch(bnf, L, [1,1]); \\ two places at infinity
4552 ? L = ideallist(bnf, 100, 0);
4553 ? l = L[98]; vector(#l, i, l[i].clgp)
4554 %4 = [[42, [42]], [36, [6, 6]], [42, [42]]]
4555 ? La = ideallistarch(bnf, L, [1,1]); \\ add them to the modulus
4556 ? l = La[98]; vector(#l, i, l[i].clgp)
4557 %6 = [[168, [42, 2, 2]], [144, [6, 6, 2, 2]], [168, [42, 2, 2]]]
4558 Of course, the results above are obvious: adding "t" places at infinity
4560 will add "t" copies of "Z/2Z" to the ray class group. The following
4561 application is more typical:
4562 ? L = ideallist(bnf, 100, 2); \\ units are required now
4564 ? La = ideallistarch(bnf, L, [1,1]);
4565 ? H = bnrclassnolist(bnf, La);
4566 ? H[98];
4567 %6 = [2, 12, 2]
4568 The library syntax is "ideallistarch(nf,list,arch)".
4570 \subsecidx{ideallog}"(nf,x,bid)": "nf" is a number field, bid a ``big
4572 ideal'' as output by "idealstar" and "x" a non-necessarily integral
4573 element of nf which must have valuation equal to 0 at all prime ideals
4574 dividing "I = bid[1]". This function computes the ``discrete
4575 logarithm'' of "x" on the generators given in "bid[2]". In other words,
4576 if "g_i" are these generators, of orders "d_i" respectively, the result
4577 is a column vector of integers "(x_i)" such that "0 <= x_i < d_i" and
4578 "x = prod_ig_i^{x_i} (mod ^*I) ."
4580 Note that when "I" is a module, this implies also sign conditions on
4582 the embeddings.
4583 The library syntax is "zideallog(nf,x,bid)".
4585 \subsecidx{idealmin}"(nf,x,{vdir})": computes a minimum of the ideal
4587 "x" in the direction vdir in the number field nf.
4588 The library syntax is "minideal(nf,x,vdir,prec)", where an omitted vdir
4590 is coded as "NULL".
4591 \subsecidx{idealmul}"(nf,x,y,{flag = 0})": ideal multiplication of the
4593 ideals "x" and "y" in the number field nf. The result is a generating
4594 set for the ideal product with at most "n" elements, and is in Hermite
4595 normal form if either "x" or "y" is in HNF or is a prime ideal as
4596 output by "idealprimedec", and this is given together with the sum of
4597 the Archimedean information in "x" and "y" if both are given.
4598 If "flag" is non-zero, reduce the result using "idealred".
4600 The library syntax is "idealmul(nf,x,y)" ("flag = 0") or
4602 \funs{idealmulred}{nf,x,y,prec} ("flag != 0"), where as usual, "prec"
4603 is a C long integer representing the precision.
4604 \subsecidx{idealnorm}"(nf,x)": computes the norm of the ideal "x" in
4606 the number field "nf".
4607 The library syntax is "idealnorm(nf, x)".
4609 \subsecidx{idealpow}"(nf,x,k,{flag = 0})": computes the "k"-th power of
4611 the ideal "x" in the number field "nf". "k" can be positive, negative
4612 or zero. The result is NOT reduced, it is really the "k"-th ideal
4613 power, and is given in HNF.
4614 If "flag" is non-zero, reduce the result using "idealred". Note however
4616 that this is NOT the same as as "idealpow(nf,x,k)" followed by
4617 reduction, since the reduction is performed throughout the powering
4618 process.
4619 The library syntax corresponding to "flag = 0" is
4621 \funs{idealpow}{nf,x,k}. If "k" is a "long", you can use
4622 \funs{idealpows}{nf,x,k}. Corresponding to "flag = 1" is
4623 \funs{idealpowred}{nf,vp,k,prec}, where "prec" is a "long".
4624 \subsecidx{idealprimedec}"(nf,p)": computes the prime ideal
4626 decomposition of the prime number "p" in the number field "nf". "p"
4627 must be a (positive) prime number. Note that the fact that "p" is prime
4628 is not checked, so if a non-prime "p" is given the result is undefined.
4629 The result is a vector of pr structures, each representing one of the
4631 prime ideals above "p" in the number field "nf". The representation "P
4632 = [p,a,e,f,b]" of a prime ideal means the following. The prime ideal is
4633 equal to "pZ_K+alphaZ_K" where "Z_K" is the ring of integers of the
4634 field and "alpha = sum_i a_iomega_i" where the "omega_i" form the
4635 integral basis "nf.zk", "e" is the ramification index, "f" is the
4636 residual index, and "b" represents a "beta\in Z_K" such that "P^{-1} =
4637 Z_K+beta/pZ_K" which will be useful for computing valuations, but which
4638 the user can ignore. The number "alpha" is guaranteed to have a
4639 valuation equal to 1 at the prime ideal (this is automatic if "e > 1").
4640 The components of "P" should be accessed by member functions: "P.p",
4642 "P.e", "P.f", and "P.gen" (returns the vector "[p,a]").
4643 The library syntax is "primedec(nf,p)".
4645 \subsecidx{idealprincipal}"(nf,x)": creates the principal ideal
4647 generated by the algebraic number "x" (which must be of type integer,
4648 rational or polmod) in the number field "nf". The result is a one-
4649 column matrix.
4650 The library syntax is "principalideal(nf,x)".
4652 \subsecidx{idealred}"(nf,I,{vdir = 0})": LLL reduction of the ideal "I"
4654 in the number field nf, along the direction vdir. If vdir is present,
4655 it must be an "r1+r2"-component vector ("r1" and "r2" number of real
4656 and complex places of nf as usual).
4657 This function finds a ``small'' "a" in "I" (it is an LLL pseudo-minimum
4659 along direction vdir). The result is the Hermite normal form of the
4660 LLL-reduced ideal "r I/a", where "r" is a rational number such that the
4661 resulting ideal is integral and primitive. This is often, but not
4662 always, a reduced ideal in the sense of Buchmann. If "I" is an idele,
4663 the logarithmic embeddings of "a" are subtracted to the Archimedean
4664 part.
4665 More often than not, a principal ideal will yield the identity matrix.
4667 This is a quick and dirty way to check if ideals are principal without
4668 computing a full "bnf" structure, but it's not a necessary condition;
4669 hence, a non-trivial result doesn't prove the ideal is non-trivial in
4670 the class group.
4671 Note that this is not the same as the LLL reduction of the lattice "I"
4673 since ideal operations are involved.
4674 The library syntax is "ideallllred(nf,x,vdir,prec)", where an omitted
4676 vdir is coded as "NULL".
4677 \subsecidx{idealstar}"(nf,I,{flag = 1})": outputs a bid structure,
4679 necessary for computing in the finite abelian group "G = (Z_K/I)^*".
4680 Here, nf is a number field and "I" is a modulus: either an ideal in any
4681 form, or a row vector whose first component is an ideal and whose
4682 second component is a row vector of "r_1" 0 or 1.
4683 This bid is used in "ideallog" to compute discrete logarithms. It also
4685 contains useful information which can be conveniently retrieved as
4686 "bid.mod" (the modulus), "bid.clgp" ("G" as a finite abelian group),
4687 "bid.no" (the cardinality of "G"), "bid.cyc" (elementary divisors) and
4688 "bid.gen" (generators).
4689 If "flag = 1" (default), the result is a bid structure without
4691 generators.
4692 If "flag = 2", as "flag = 1", but including generators, which wastes
4694 some time.
4695 If "flag = 0", deprecated. Only outputs "(Z_K/I)^*" as an abelian
4697 group, i.e as a 3-component vector "[h,d,g]": "h" is the order, "d" is
4698 the vector of SNF cyclic components and "g" the corresponding
4699 generators. This flag is deprecated: it is in fact slightly faster to
4700 compute a true bid structure, which contains much more information.
4701 The library syntax is "idealstar0(nf,I,flag)".
4703 \subsecidx{idealtwoelt}"(nf,x,{a})": computes a two-element
4705 representation of the ideal "x" in the number field "nf", using a
4706 straightforward (exponential time) search. "x" can be an ideal in any
4707 form, (including perhaps an Archimedean part, which is ignored) and the
4708 result is a row vector "[a,alpha]" with two components such that "x =
4709 aZ_K+alphaZ_K" and "a\in Z", where "a" is the one passed as argument if
4710 any. If "x" is given by at least two generators, "a" is chosen to be
4711 the positive generator of "xcapZ".
4712 Note that when an explicit "a" is given, we use an asymptotically
4714 faster method, however in practice it is usually slower.
4715 The library syntax is "ideal_two_elt0(nf,x,a)", where an omitted "a" is
4717 entered as "NULL".
4718 \subsecidx{idealval}"(nf,x,vp)": gives the valuation of the ideal "x"
4720 at the prime ideal vp in the number field "nf", where vp must be a
4721 5-component vector as given by "idealprimedec".
4722 The library syntax is "idealval(nf,x,vp)", and the result is a "long"
4724 integer.
4725 \subsecidx{ideleprincipal}"(nf,x)": creates the principal idele
4727 generated by the algebraic number "x" (which must be of type integer,
4728 rational or polmod) in the number field "nf". The result is a two-
4729 component vector, the first being a one-column matrix representing the
4730 corresponding principal ideal, and the second being the vector with
4731 "r_1+r_2" components giving the complex logarithmic embedding of "x".
4732 The library syntax is "principalidele(nf,x)".
4734 \subsecidx{matalgtobasis}"(nf,x)": "nf" being a number field in
4736 "nfinit" format, and "x" a matrix whose coefficients are expressed as
4737 polmods in "nf", transforms this matrix into a matrix whose
4738 coefficients are expressed on the integral basis of "nf". This is the
4739 same as applying "nfalgtobasis" to each entry, but it would be
4740 dangerous to use the same name.
4741 The library syntax is "matalgtobasis(nf,x)".
4743 \subsecidx{matbasistoalg}"(nf,x)": "nf" being a number field in
4745 "nfinit" format, and "x" a matrix whose coefficients are expressed as
4746 column vectors on the integral basis of "nf", transforms this matrix
4747 into a matrix whose coefficients are algebraic numbers expressed as
4748 polmods. This is the same as applying "nfbasistoalg" to each entry, but
4749 it would be dangerous to use the same name.
4750 The library syntax is "matbasistoalg(nf,x)".
4752 \subsecidx{modreverse}"(a)": "a" being a polmod A(X) modulo T(X), finds
4754 the ``reverse polmod'' B(X) modulo Q(X), where "Q" is the minimal
4755 polynomial of "a", which must be equal to the degree of "T", and such
4756 that if "theta" is a root of "T" then "theta = B(alpha)" for a certain
4757 root "alpha" of "Q".
4758 This is very useful when one changes the generating element in
4760 algebraic extensions.
4761 The library syntax is "polmodrecip(x)".
4763 \subsecidx{newtonpoly}"(x,p)": gives the vector of the slopes of the
4765 Newton polygon of the polynomial "x" with respect to the prime number
4766 "p". The "n" components of the vector are in decreasing order, where
4767 "n" is equal to the degree of "x". Vertical slopes occur iff the
4768 constant coefficient of "x" is zero and are denoted by "VERYBIGINT",
4769 the biggest single precision integer representable on the machine
4770 ("2^{31}-1" (resp. "2^{63}-1") on 32-bit (resp. 64-bit) machines), see
4771 "Label se:valuation".
4772 The library syntax is "newtonpoly(x,p)".
4774 \subsecidx{nfalgtobasis}"(nf,x)": this is the inverse function of
4776 "nfbasistoalg". Given an object "x" whose entries are expressed as
4777 algebraic numbers in the number field "nf", transforms it so that the
4778 entries are expressed as a column vector on the integral basis "nf.zk".
4779 The library syntax is "algtobasis(nf,x)".
4781 \subsecidx{nfbasis}"(x,{flag = 0},{fa})": integral basis of the number
4783 field defined by the irreducible, preferably monic, polynomial "x",
4784 using a modified version of the round 4 algorithm by default, due to
4785 David Ford, Sebastian Pauli and Xavier Roblot. The binary digits of
4786 "flag" have the following meaning:
4787 1: assume that no square of a prime greater than the default
4789 "primelimit" divides the discriminant of "x", i.e. that the index of
4790 "x" has only small prime divisors.
4791 2: use round 2 algorithm. For small degrees and coefficient size, this
4793 is sometimes a little faster. (This program is the translation into C
4794 of a program written by David Ford in Algeb.)
4795 Thus for instance, if "flag = 3", this uses the round 2 algorithm and
4797 outputs an order which will be maximal at all the small primes.
4798 If fa is present, we assume (without checking!) that it is the two-
4800 column matrix of the factorization of the discriminant of the
4801 polynomial "x". Note that it does not have to be a complete
4802 factorization. This is especially useful if only a local integral basis
4803 for some small set of places is desired: only factors with exponents
4804 greater or equal to 2 will be considered.
4805 The library syntax is "nfbasis0(x,flag,fa)". An extended version is
4807 \funs{nfbasis}{x,&d,flag,fa}, where "d" receives the discriminant of
4808 the number field (not of the polynomial "x"), and an omitted fa is
4809 input as "NULL". Also available are \funs{base}{x,&d} ("flag = 0"),
4810 \funs{base2}{x,&d} ("flag = 2") and \funs{factoredbase}{x,fa,&d}.
4811 \subsecidx{nfbasistoalg}"(nf,x)": this is the inverse function of
4813 "nfalgtobasis". Given an object "x" whose entries are expressed on the
4814 integral basis "nf.zk", transforms it into an object whose entries are
4815 algebraic numbers (i.e. polmods).
4816 The library syntax is "basistoalg(nf,x)".
4818 \subsecidx{nfdetint}"(nf,x)": given a pseudo-matrix "x", computes a
4820 non-zero ideal contained in (i.e. multiple of) the determinant of "x".
4821 This is particularly useful in conjunction with "nfhnfmod".
4822 The library syntax is "nfdetint(nf,x)".
4824 \subsecidx{nfdisc}"(x,{flag = 0},{fa})": field discriminant of the
4826 number field defined by the integral, preferably monic, irreducible
4827 polynomial "x". "flag" and "fa" are exactly as in "nfbasis". That is,
4828 "fa" provides the matrix of a partial factorization of the discriminant
4829 of "x", and binary digits of "flag" are as follows:
4830 1: assume that no square of a prime greater than "primelimit" divides
4832 the discriminant.
4833 2: use the round 2 algorithm, instead of the default round 4. This
4835 should be slower except maybe for polynomials of small degree and
4836 coefficients.
4837 The library syntax is "nfdiscf0(x,flag,fa)" where an omitted "fa" is
4839 input as "NULL". You can also use \funs{discf}{x} ("flag = 0").
4840 \subsecidx{nfeltdiv}"(nf,x,y)": given two elements "x" and "y" in nf,
4842 computes their quotient "x/y" in the number field "nf".
4843 The library syntax is "element_div(nf,x,y)".
4845 \subsecidx{nfeltdiveuc}"(nf,x,y)": given two elements "x" and "y" in
4847 nf, computes an algebraic integer "q" in the number field "nf" such
4848 that the components of "x-qy" are reasonably small. In fact, this is
4849 functionally identical to "round(nfeltdiv(nf,x,y))".
4850 The library syntax is "nfdiveuc(nf,x,y)".
4852 \subsecidx{nfeltdivmodpr}"(nf,x,y,pr)": given two elements "x" and "y"
4854 in nf and pr a prime ideal in "modpr" format (see "nfmodprinit"),
4855 computes their quotient "x / y" modulo the prime ideal pr.
4856 The library syntax is "element_divmodpr(nf,x,y,pr)".
4858 \subsecidx{nfeltdivrem}"(nf,x,y)": given two elements "x" and "y" in
4860 nf, gives a two-element row vector "[q,r]" such that "x = qy+r", "q" is
4861 an algebraic integer in "nf", and the components of "r" are reasonably
4862 small.
4863 The library syntax is "nfdivrem(nf,x,y)".
4865 \subsecidx{nfeltmod}"(nf,x,y)": given two elements "x" and "y" in nf,
4867 computes an element "r" of "nf" of the form "r = x-qy" with "q" and
4868 algebraic integer, and such that "r" is small. This is functionally
4869 identical to
4870 "x - nfeltmul(nf,round(nfeltdiv(nf,x,y)),y)."
4872 The library syntax is "nfmod(nf,x,y)".
4874 \subsecidx{nfeltmul}"(nf,x,y)": given two elements "x" and "y" in nf,
4876 computes their product "x*y" in the number field "nf".
4877 The library syntax is "element_mul(nf,x,y)".
4879 \subsecidx{nfeltmulmodpr}"(nf,x,y,pr)": given two elements "x" and "y"
4881 in nf and pr a prime ideal in "modpr" format (see "nfmodprinit"),
4882 computes their product "x*y" modulo the prime ideal pr.
4883 The library syntax is "element_mulmodpr(nf,x,y,pr)".
4885 \subsecidx{nfeltpow}"(nf,x,k)": given an element "x" in nf, and a
4887 positive or negative integer "k", computes "x^k" in the number field
4888 "nf".
4889 The library syntax is "element_pow(nf,x,k)".
4891 \subsecidx{nfeltpowmodpr}"(nf,x,k,pr)": given an element "x" in nf, an
4893 integer "k" and a prime ideal pr in "modpr" format (see "nfmodprinit"),
4894 computes "x^k" modulo the prime ideal pr.
4895 The library syntax is "element_powmodpr(nf,x,k,pr)".
4897 \subsecidx{nfeltreduce}"(nf,x,ideal)": given an ideal in Hermite normal
4899 form and an element "x" of the number field "nf", finds an element "r"
4900 in "nf" such that "x-r" belongs to the ideal and "r" is small.
4901 The library syntax is "element_reduce(nf,x,ideal)".
4903 \subsecidx{nfeltreducemodpr}"(nf,x,pr)": given an element "x" of the
4905 number field "nf" and a prime ideal pr in "modpr" format compute a
4906 canonical representative for the class of "x" modulo pr.
4907 The library syntax is "nfreducemodpr(nf,x,pr)".
4909 \subsecidx{nfeltval}"(nf,x,pr)": given an element "x" in nf and a prime
4911 ideal pr in the format output by "idealprimedec", computes their the
4912 valuation at pr of the element "x". The same result could be obtained
4913 using "idealval(nf,x,pr)" (since "x" would then be converted to a
4914 principal ideal), but it would be less efficient.
4915 The library syntax is "element_val(nf,x,pr)", and the result is a
4917 "long".
4918 \subsecidx{nffactor}"(nf,x)": factorization of the univariate
4920 polynomial "x" over the number field "nf" given by "nfinit". "x" has
4921 coefficients in "nf" (i.e. either scalar, polmod, polynomial or column
4922 vector). The main variable of "nf" must be of lower priority than that
4923 of "x" (see "Label se:priority"). However if the polynomial defining
4924 the number field occurs explicitly in the coefficients of "x" (as
4925 modulus of a "t_POLMOD"), its main variable must be the same as the
4926 main variable of "x". For example,
4927 ? nffactor(nf, x^2 + Mod(z, z^2+1)); \\ OK
4929 ? nffactor(nf, x^2 + Mod(z, z^2+1)); \\ OK
4930 ? nffactor(nf, x^2 + Mod(z, z^2+1)); \\ WRONG
4931 The library syntax is "nffactor(nf,x)".
4933 \subsecidx{nffactormod}"(nf,x,pr)": factorization of the univariate
4935 polynomial "x" modulo the prime ideal pr in the number field "nf". "x"
4936 can have coefficients in the number field (scalar, polmod, polynomial,
4937 column vector) or modulo the prime ideal (intmod modulo the rational
4938 prime under pr, polmod or polynomial with intmod coefficients, column
4939 vector of intmod). The prime ideal pr must be in the format output by
4940 "idealprimedec". The main variable of "nf" must be of lower priority
4941 than that of "x" (see "Label se:priority"). However if the coefficients
4942 of the number field occur explicitly (as polmods) as coefficients of
4943 "x", the variable of these polmods must be the same as the main
4944 variable of "t" (see "nffactor").
4945 The library syntax is "nffactormod(nf,x,pr)".
4947 \subsecidx{nfgaloisapply}"(nf,aut,x)": "nf" being a number field as
4949 output by "nfinit", and aut being a Galois automorphism of "nf"
4950 expressed either as a polynomial or a polmod (such automorphisms being
4951 found using for example one of the variants of "nfgaloisconj"),
4952 computes the action of the automorphism aut on the object "x" in the
4953 number field. "x" can be an element (scalar, polmod, polynomial or
4954 column vector) of the number field, an ideal (either given by
4955 "Z_K"-generators or by a Z-basis), a prime ideal (given as a 5-element
4956 row vector) or an idele (given as a 2-element row vector). Because of
4957 possible confusion with elements and ideals, other vector or matrix
4958 arguments are forbidden.
4959 The library syntax is "galoisapply(nf,aut,x)".
4961 \subsecidx{nfgaloisconj}"(nf,{flag = 0},{d})": "nf" being a number
4963 field as output by "nfinit", computes the conjugates of a root "r" of
4964 the non-constant polynomial "x = nf[1]" expressed as polynomials in
4965 "r". This can be used even if the number field "nf" is not Galois since
4966 some conjugates may lie in the field.
4967 "nf" can simply be a polynomial if "flag != 1".
4969 If no flags or "flag = 0", if "nf" is a number field use a combination
4971 of flag 4 and 1 and the result is always complete, else use a
4972 combination of flag 4 and 2 and the result is subject to the
4973 restriction of "flag = 2", but a warning is issued when it is not
4974 proven complete.
4975 If "flag = 1", use "nfroots" (require a number field).
4977 If "flag = 2", use complex approximations to the roots and an integral
4979 LLL. The result is not guaranteed to be complete: some conjugates may
4980 be missing (no warning issued), especially so if the corresponding
4981 polynomial has a huge index. In that case, increasing the default
4982 precision may help.
4983 If "flag = 4", use Allombert's algorithm and permutation testing. If
4985 the field is Galois with ``weakly'' super solvable Galois group, return
4986 the complete list of automorphisms, else only the identity element. If
4987 present, "d" is assumed to be a multiple of the least common
4988 denominator of the conjugates expressed as polynomial in a root of pol.
4989 A group G is ``weakly'' super solvable (WKSS) if it contains a super
4991 solvable normal subgroup "H" such that "G = H" , or "G/H ~ A_4" , or
4992 "G/H ~ S_4". Abelian and nilpotent groups are WKSS. In practice,
4993 almost all groups of small order are WKSS, the exceptions having order
4994 36(1 exception), 48(2), 56(1), 60(1), 72(5), 75(1), 80(1), 96(10) and "
4995 >= 108".
4996 Hence "flag = 4" permits to quickly check whether a polynomial of order
4998 strictly less than 36 is Galois or not. This method is much faster than
4999 "nfroots" and can be applied to polynomials of degree larger than 50.
5000 This routine can only compute Q-automorphisms, but it may be used to
5002 get "K"-automorphism for any base field "K" as follows:
5003 rnfgaloisconj(nfK, R) = \\ K-automorphisms of L = K[X] / (R)
5005 { local(polabs, N, H);
5006 R *= Mod(1, nfK.pol); \\ convert coeffs to polmod elts of K
5007 polabs = rnfequation(nfK, R);
5008 N = nfgaloisconj(polabs) % R; \\ Q-automorphisms of L
5009 H = [];
5010 for(i=1, #N, \\ select the ones that fix K
5011 if (subst(R, variable(R), Mod(N[i],R)) == 0,
5012 H = concat(H,N[i])
5013 )
5014 ); H
5015 }
5016 K = nfinit(y^2 + 7);
5017 polL = x^4 - y*x^3 - 3*x^2 + y*x + 1;
5018 rnfgaloisconj(K, polL) \\ K-automorphisms of L
5019 The library syntax is "galoisconj0(nf,flag,d,prec)". Also available are
5021 \funs{galoisconj}{nf} for "flag = 0", \funs{galoisconj2}{nf,n,prec} for
5022 "flag = 2" where "n" is a bound on the number of conjugates, and
5023 \funs{galoisconj4}{nf,d} corresponding to "flag = 4".
5024 \subsecidx{nfhilbert}"(nf,a,b,{pr})": if pr is omitted, compute the
5026 global Hilbert symbol "(a,b)" in "nf", that is 1 if "x^2 - a y^2 - b
5027 z^2" has a non trivial solution "(x,y,z)" in "nf", and "-1" otherwise.
5028 Otherwise compute the local symbol modulo the prime ideal pr (as output
5029 by "idealprimedec").
5030 The library syntax is "nfhilbert(nf,a,b,pr)", where an omitted pr is
5032 coded as "NULL".
5033 \subsecidx{nfhnf}"(nf,x)": given a pseudo-matrix "(A,I)", finds a
5035 pseudo-basis in Hermite normal form of the module it generates.
5036 The library syntax is "nfhermite(nf,x)".
5038 \subsecidx{nfhnfmod}"(nf,x,detx)": given a pseudo-matrix "(A,I)" and an
5040 ideal detx which is contained in (read integral multiple of) the
5041 determinant of "(A,I)", finds a pseudo-basis in Hermite normal form of
5042 the module generated by "(A,I)". This avoids coefficient explosion.
5043 detx can be computed using the function "nfdetint".
5044 The library syntax is "nfhermitemod(nf,x,detx)".
5046 \subsecidx{nfinit}"(pol,{flag = 0})": pol being a non-constant,
5048 preferably monic, irreducible polynomial in "Z[X]", initializes a
5049 number field structure ("nf") associated to the field "K" defined by
5050 pol. As such, it's a technical object passed as the first argument to
5051 most "nf"xxx functions, but it contains some information which may be
5052 directly useful. Access to this information via member functions is
5053 preferred since the specific data organization specified below may
5054 change in the future. Currently, "nf" is a row vector with 9
5055 components:
5056 "nf[1]" contains the polynomial pol ("nf.pol").
5058 "nf[2]" contains "[r1,r2]" ("nf.sign", "nf.r1", "nf.r2"), the number of
5060 real and complex places of "K".
5061 "nf[3]" contains the discriminant d(K) ("nf.disc") of "K".
5063 "nf[4]" contains the index of "nf[1]" ("nf.index"), i.e. "[Z_K :
5065 Z[theta]]", where "theta" is any root of "nf[1]".
5066 "nf[5]" is a vector containing 7 matrices "M", "G", "T2", "T", "MD",
5068 "TI", "MDI" useful for certain computations in the number field "K".
5069 * "M" is the "(r1+r2) x n" matrix whose columns represent the
5071 numerical values of the conjugates of the elements of the integral
5072 basis.
5073 * "G" is such that "T2 = ^t G G", where "T2" is the quadratic form
5075 "T_2(x) = sum |sigma(x)|^2", "sigma" running over the embeddings of "K"
5076 into C.
5077 * The "T2" component is deprecated and currently unused.
5079 * "T" is the "n x n" matrix whose coefficients are
5081 "Tr(omega_iomega_j)" where the "omega_i" are the elements of the
5082 integral basis. Note also that " det (T)" is equal to the discriminant
5083 of the field "K".
5084 * The columns of "MD" ("nf.diff") express a Z-basis of the different
5086 of "K" on the integral basis.
5087 * "TI" is equal to "d(K)T^{-1}", which has integral coefficients.
5089 Note that, understood as as ideal, the matrix "T^{-1}" generates the
5090 codifferent ideal.
5091 * Finally, "MDI" is a two-element representation (for faster ideal
5093 product) of d(K) times the codifferent ideal ("nf.disc*nf.codiff",
5094 which is an integral ideal). "MDI" is only used in "idealinv".
5095 "nf[6]" is the vector containing the "r1+r2" roots ("nf.roots") of
5097 "nf[1]" corresponding to the "r1+r2" embeddings of the number field
5098 into C (the first "r1" components are real, the next "r2" have positive
5099 imaginary part).
5100 "nf[7]" is an integral basis for "Z_K" ("nf.zk") expressed on the
5102 powers of "theta". Its first element is guaranteed to be 1. This basis
5103 is LLL-reduced with respect to "T_2" (strictly speaking, it is a
5104 permutation of such a basis, due to the condition that the first
5105 element be 1).
5106 "nf[8]" is the "n x n" integral matrix expressing the power basis in
5108 terms of the integral basis, and finally
5109 "nf[9]" is the "n x n^2" matrix giving the multiplication table of the
5111 integral basis.
5112 If a non monic polynomial is input, "nfinit" will transform it into a
5114 monic one, then reduce it (see "flag = 3"). It is allowed, though not
5115 very useful given the existence of "nfnewprec", to input a "nf" or a
5116 "bnf" instead of a polynomial.
5117 ? nf = nfinit(x^3 - 12); \\ initialize number field Q[X] / (X^3 - 12)
5119 ? nf.pol \\ defining polynomial
5120 %2 = x^3 - 12
5121 ? nf.disc \\ field discriminant
5122 %3 = -972
5123 ? nf.index \\ index of power basis order in maximal order
5124 %4 = 2
5125 ? nf.zk \\ integer basis, lifted to Q[X]
5126 %5 = [1, x, 1/2*x^2]
5127 ? nf.sign \\ signature
5128 %6 = [1, 1]
5129 ? factor(abs(nf.disc )) \\ determines ramified primes
5130 %7 =
5131 [2 2]
5132 [3 5]
5134 ? idealfactor(nf, 2)
5135 %8 =
5136 [[2, [0, 0, -1]~, 3, 1, [0, 1, 0]~] 3] \\ B<P>_2^3
5137 In case pol has a huge discriminant which is difficult to factor, the
5139 special input format "[pol,B]" is also accepted where pol is a
5140 polynomial as above and "B" is the integer basis, as would be computed
5141 by "nfbasis". This is useful if the integer basis is known in advance,
5142 or was computed conditionnally.
5143 ? pol = polcompositum(x^5 - 101, polcyclo(7))[1];
5145 ? B = nfbasis(pol, 1); \\ faster than nfbasis(pol), but conditional
5146 ? nf = nfinit( [pol, B] );
5147 ? factor( abs(nf.disc) )
5148 [5 18]
5149 [7 25]
5151 [101 24]
5153 "B" is conditional when its discriminant, which is "nf.disc", can't be
5155 factored. In this example, the above factorization proves the
5156 correctness of the computation.
5157 If "flag = 2": pol is changed into another polynomial "P" defining the
5159 same number field, which is as simple as can easily be found using the
5160 "polred" algorithm, and all the subsequent computations are done using
5161 this new polynomial. In particular, the first component of the result
5162 is the modified polynomial.
5163 If "flag = 3", does a "polred" as in case 2, but outputs
5165 "[nf,Mod(a,P)]", where "nf" is as before and "Mod(a,P) = Mod(x,pol)"
5166 gives the change of variables. This is implicit when pol is not monic:
5167 first a linear change of variables is performed, to get a monic
5168 polynomial, then a "polred" reduction.
5169 If "flag = 4", as 2 but uses a partial "polred".
5171 If "flag = 5", as 3 using a partial "polred".
5173 The library syntax is "nfinit0(x,flag,prec)".
5175 \subsecidx{nfisideal}"(nf,x)": returns 1 if "x" is an ideal in the
5177 number field "nf", 0 otherwise.
5178 The library syntax is "isideal(x)".
5180 \subsecidx{nfisincl}"(x,y)": tests whether the number field "K" defined
5182 by the polynomial "x" is conjugate to a subfield of the field "L"
5183 defined by "y" (where "x" and "y" must be in "Q[X]"). If they are not,
5184 the output is the number 0. If they are, the output is a vector of
5185 polynomials, each polynomial "a" representing an embedding of "K" into
5186 "L", i.e. being such that "y | x o a".
5187 If "y" is a number field (nf), a much faster algorithm is used
5189 (factoring "x" over "y" using "nffactor"). Before version 2.0.14, this
5190 wasn't guaranteed to return all the embeddings, hence was triggered by
5191 a special flag. This is no more the case.
5192 The library syntax is "nfisincl(x,y,flag)".
5194 \subsecidx{nfisisom}"(x,y)": as "nfisincl", but tests for isomorphism.
5196 If either "x" or "y" is a number field, a much faster algorithm will be
5197 used.
5198 The library syntax is "nfisisom(x,y,flag)".
5200 \subsecidx{nfnewprec}"(nf)": transforms the number field "nf" into the
5202 corresponding data using current (usually larger) precision. This
5203 function works as expected if "nf" is in fact a "bnf" (update "bnf" to
5204 current precision) but may be quite slow (many generators of principal
5205 ideals have to be computed).
5206 The library syntax is "nfnewprec(nf,prec)".
5208 \subsecidx{nfkermodpr}"(nf,a,pr)": kernel of the matrix "a" in
5210 "Z_K/pr", where pr is in modpr format (see "nfmodprinit").
5211 The library syntax is "nfkermodpr(nf,a,pr)".
5213 \subsecidx{nfmodprinit}"(nf,pr)": transforms the prime ideal pr into
5215 "modpr" format necessary for all operations modulo pr in the number
5216 field nf.
5217 The library syntax is "nfmodprinit(nf,pr)".
5219 \subsecidx{nfsubfields}"(pol,{d = 0})": finds all subfields of degree
5221 "d" of the number field defined by the (monic, integral) polynomial pol
5222 (all subfields if "d" is null or omitted). The result is a vector of
5223 subfields, each being given by "[g,h]", where "g" is an absolute
5224 equation and "h" expresses one of the roots of "g" in terms of the root
5225 "x" of the polynomial defining "nf". This routine uses J. Klüners's
5226 algorithm in the general case, and B. Allombert's "galoissubfields"
5227 when nf is Galois (with weakly supersolvable Galois group).
5228 The library syntax is "subfields(nf,d)".
5230 \subsecidx{nfroots}"({nf},x)": roots of the polynomial "x" in the
5232 number field "nf" given by "nfinit" without multiplicity (in Q if "nf"
5233 is omitted). "x" has coefficients in the number field (scalar, polmod,
5234 polynomial, column vector). The main variable of "nf" must be of lower
5235 priority than that of "x" (see "Label se:priority"). However if the
5236 coefficients of the number field occur explicitly (as polmods) as
5237 coefficients of "x", the variable of these polmods must be the same as
5238 the main variable of "t" (see "nffactor").
5239 The library syntax is "nfroots(nf,x)".
5241 \subsecidx{nfrootsof1}"(nf)": computes the number of roots of unity "w"
5243 and a primitive "w"-th root of unity (expressed on the integral basis)
5244 belonging to the number field "nf". The result is a two-component
5245 vector "[w,z]" where "z" is a column vector expressing a primitive
5246 "w"-th root of unity on the integral basis "nf.zk".
5247 The library syntax is "rootsof1(nf)".
5249 \subsecidx{nfsnf}"(nf,x)": given a torsion module "x" as a 3-component
5251 row vector "[A,I,J]" where "A" is a square invertible "n x n" matrix,
5252 "I" and "J" are two ideal lists, outputs an ideal list "d_1,...,d_n"
5253 which is the Smith normal form of "x". In other words, "x" is
5254 isomorphic to "Z_K/d_1\oplus...\oplus Z_K/d_n" and "d_i" divides
5255 "d_{i-1}" for "i >= 2". The link between "x" and "[A,I,J]" is as
5256 follows: if "e_i" is the canonical basis of "K^n", "I = [b_1,...,b_n]"
5257 and "J = [a_1,...,a_n]", then "x" is isomorphic to
5258 " (b_1e_1\oplus...\oplus b_ne_n) / (a_1A_1\oplus...\oplus a_nA_n) , "
5260 where the "A_j" are the columns of the matrix "A". Note that every
5262 finitely generated torsion module can be given in this way, and even
5263 with "b_i = Z_K" for all "i".
5264 The library syntax is "nfsmith(nf,x)".
5266 \subsecidx{nfsolvemodpr}"(nf,a,b,pr)": solution of "a.x = b" in
5268 "Z_K/pr", where "a" is a matrix and "b" a column vector, and where pr
5269 is in modpr format (see "nfmodprinit").
5270 The library syntax is "nfsolvemodpr(nf,a,b,pr)".
5272 \subsecidx{polcompositum}"(P,Q,{flag = 0})": "P" and "Q" being
5274 squarefree polynomials in "Z[X]" in the same variable, outputs the
5275 simple factors of the étale Q-algebra "A = Q(X, Y) / (P(X), Q(Y))".
5276 The factors are given by a list of polynomials "R" in "Z[X]",
5277 associated to the number field "Q(X)/ (R)", and sorted by increasing
5278 degree (with respect to lexicographic ordering for factors of equal
5279 degrees). Returns an error if one of the polynomials is not squarefree.
5280 Note that it is more efficient to reduce to the case where "P" and "Q"
5282 are irreducible first. The routine will not perform this for you, since
5283 it may be expensive, and the inputs are irreducible in most
5284 applications anyway. Assuming "P" is irreducible (of smaller degree
5285 than "Q" for efficiency), it is in general much faster to proceed as
5286 follows
5287 nf = nfinit(P); L = nffactor(nf, Q)[,1];
5289 vector(#L, i, rnfequation(nf, L[i]))
5290 to obtain the same result. If you are only interested in the degrees of
5292 the simple factors, the "rnfequation" instruction can be replaced by a
5293 trivial "poldegree(P) * poldegree(L[i])".
5294 If "flag = 1", outputs a vector of 4-component vectors "[R,a,b,k]",
5296 where "R" ranges through the list of all possible compositums as above,
5297 and "a" (resp. "b") expresses the root of "P" (resp. "Q") as an element
5298 of "Q(X)/(R)". Finally, "k" is a small integer such that "b + ka = X"
5299 modulo "R".
5300 A compositum is quite often defined by a complicated polynomial, which
5302 it is advisable to reduce before further work. Here is a simple example
5303 involving the field "Q(zeta_5, 5^{1/5})":
5304 ? pol = z[1]
5306 %5 = x^20 + 25*x^10 + 5
5307 ? a = subst(a.pol, x, z[2]) \\ C<pol> defines the compositum
5308 ? pol = z[1]
5309 %5 = x^20 + 25*x^10 + 5
5310 ? a = subst(a.pol, x, z[2]) \\ C<a> is a fifth root of 5
5311 ? pol = z[1]
5312 %5 = x^20 + 25*x^10 + 5
5313 ? a = subst(a.pol, x, z[2]) \\ look for a simpler polynomial
5314 ? pol = z[1]
5315 %5 = x^20 + 25*x^10 + 5
5316 ? a = subst(a.pol, x, z[2]) \\ C<a> in the new coordinates
5317 %6 = Mod(-5/22*x^19 + 1/22*x^14 - 123/22*x^9 + 9/11*x^4, x^20 + 25*x^10 + 5)
5318 The library syntax is "polcompositum0(P,Q,flag)".
5320 \subsecidx{polgalois}"(x)": Galois group of the non-constant polynomial
5322 "x\in Q[X]". In the present version /usr/share/libpari23, "x" must be
5323 irreducible and the degree of "x" must be less than or equal to 7. On
5324 certain versions for which the data file of Galois resolvents has been
5325 installed (available in the Unix distribution as a separate package),
5326 degrees 8, 9, 10 and 11 are also implemented.
5327 The output is a 4-component vector "[n,s,k,name]" with the following
5329 meaning: "n" is the cardinality of the group, "s" is its signature ("s
5330 = 1" if the group is a subgroup of the alternating group "A_n", "s =
5331 -1" otherwise) and name is a character string containing name of the
5332 transitive group according to the GAP 4 transitive groups library by
5333 Alexander Hulpke.
5334 "k" is more arbitrary and the choice made up to version 2.2.3 of PARI
5336 is rather unfortunate: for "n > 7", "k" is the numbering of the group
5337 among all transitive subgroups of "S_n", as given in ``The transitive
5338 groups of degree up to eleven'', G. Butler and J. McKay, Communications
5339 in Algebra, vol. 11, 1983, pp. 863--911 (group "k" is denoted "T_k"
5340 there). And for "n <= 7", it was ad hoc, so as to ensure that a given
5341 triple would design a unique group. Specifically, for polynomials of
5342 degree " <= 7", the groups are coded as follows, using standard
5343 notations
5344 In degree 1: "S_1 = [1,1,1]".
5346 In degree 2: "S_2 = [2,-1,1]".
5348 In degree 3: "A_3 = C_3 = [3,1,1]", "S_3 = [6,-1,1]".
5350 In degree 4: "C_4 = [4,-1,1]", "V_4 = [4,1,1]", "D_4 = [8,-1,1]", "A_4
5352 = [12,1,1]", "S_4 = [24,-1,1]".
5353 In degree 5: "C_5 = [5,1,1]", "D_5 = [10,1,1]", "M_{20} = [20,-1,1]",
5355 "A_5 = [60,1,1]", "S_5 = [120,-1,1]".
5356 In degree 6: "C_6 = [6,-1,1]", "S_3 = [6,-1,2]", "D_6 = [12,-1,1]",
5358 "A_4 = [12,1,1]", "G_{18} = [18,-1,1]", "S_4^ -= [24,-1,1]", "A_4 x C_2
5359 = [24,-1,2]", "S_4^ += [24,1,1]", "G_{36}^ -= [36,-1,1]", "G_{36}^ +=
5360 [36,1,1]", "S_4 x C_2 = [48,-1,1]", "A_5 = PSL_2(5) = [60,1,1]",
5361 "G_{72} = [72,-1,1]", "S_5 = PGL_2(5) = [120,-1,1]", "A_6 = [360,1,1]",
5362 "S_6 = [720,-1,1]".
5363 In degree 7: "C_7 = [7,1,1]", "D_7 = [14,-1,1]", "M_{21} = [21,1,1]",
5365 "M_{42} = [42,-1,1]", "PSL_2(7) = PSL_3(2) = [168,1,1]", "A_7 =
5366 [2520,1,1]", "S_7 = [5040,-1,1]".
5367 This is deprecated and obsolete, but for reasons of backward
5369 compatibility, we cannot change this behaviour yet. So you can use the
5370 default "new_galois_format" to switch to a consistent naming scheme,
5371 namely "k" is always the standard numbering of the group among all
5372 transitive subgroups of "S_n". If this default is in effect, the above
5373 groups will be coded as:
5374 In degree 1: "S_1 = [1,1,1]".
5376 In degree 2: "S_2 = [2,-1,1]".
5378 In degree 3: "A_3 = C_3 = [3,1,1]", "S_3 = [6,-1,2]".
5380 In degree 4: "C_4 = [4,-1,1]", "V_4 = [4,1,2]", "D_4 = [8,-1,3]", "A_4
5382 = [12,1,4]", "S_4 = [24,-1,5]".
5383 In degree 5: "C_5 = [5,1,1]", "D_5 = [10,1,2]", "M_{20} = [20,-1,3]",
5385 "A_5 = [60,1,4]", "S_5 = [120,-1,5]".
5386 In degree 6: "C_6 = [6,-1,1]", "S_3 = [6,-1,2]", "D_6 = [12,-1,3]",
5388 "A_4 = [12,1,4]", "G_{18} = [18,-1,5]", "A_4 x C_2 = [24,-1,6]", "S_4^
5389 += [24,1,7]", "S_4^ -= [24,-1,8]", "G_{36}^ -= [36,-1,9]", "G_{36}^ +=
5390 [36,1,10]", "S_4 x C_2 = [48,-1,11]", "A_5 = PSL_2(5) = [60,1,12]",
5391 "G_{72} = [72,-1,13]", "S_5 = PGL_2(5) = [120,-1,14]", "A_6 =
5392 [360,1,15]", "S_6 = [720,-1,16]".
5393 In degree 7: "C_7 = [7,1,1]", "D_7 = [14,-1,2]", "M_{21} = [21,1,3]",
5395 "M_{42} = [42,-1,4]", "PSL_2(7) = PSL_3(2) = [168,1,5]", "A_7 =
5396 [2520,1,6]", "S_7 = [5040,-1,7]".
5397 Warning:. The method used is that of resolvent polynomials and is
5399 sensitive to the current precision. The precision is updated internally
5400 but, in very rare cases, a wrong result may be returned if the initial
5401 precision was not sufficient.
5402 The library syntax is "polgalois(x,prec)". To enable the new format in
5404 library mode, set the global variable "new_galois_format" to 1.
5405 \subsecidx{polred}"(x,{flag = 0},{fa})": finds polynomials with
5407 reasonably small coefficients defining subfields of the number field
5408 defined by "x". One of the polynomials always defines Q (hence is
5409 equal to "x-1"), and another always defines the same number field as
5410 "x" if "x" is irreducible. All "x" accepted by "nfinit" are also
5411 allowed here (e.g. non-monic polynomials, "nf", "bnf",
5412 "[x,Z_K_basis]").
5413 The following binary digits of "flag" are significant:
5415 1: possibly use a suborder of the maximal order. The primes dividing
5417 the index of the order chosen are larger than "primelimit" or divide
5418 integers stored in the "addprimes" table.
5419 2: gives also elements. The result is a two-column matrix, the first
5421 column giving the elements defining these subfields, the second giving
5422 the corresponding minimal polynomials.
5423 If "fa" is given, it is assumed that it is the two-column matrix of the
5425 factorization of the discriminant of the polynomial "x".
5426 The library syntax is "polred0(x,flag,fa)", where an omitted "fa" is
5428 coded by "NULL". Also available are \funs{polred}{x} and
5429 \funs{factoredpolred}{x,fa}, both corresponding to "flag = 0".
5430 \subsecidx{polredabs}"(x,{flag = 0})": finds one of the polynomial
5432 defining the same number field as the one defined by "x", and such that
5433 the sum of the squares of the modulus of the roots (i.e. the
5434 "T_2"-norm) is minimal. All "x" accepted by "nfinit" are also allowed
5435 here (e.g. non-monic polynomials, "nf", "bnf", "[x,Z_K_basis]").
5436 Warning:. this routine uses an exponential-time algorithm to enumerate
5438 all potential generators, and may be exceedingly slow when the number
5439 field has many subfields, hence a lot of elements of small "T_2"-norm.
5440 E.g. do not try it on the compositum of many quadratic fields, use
5441 "polred" instead.
5442 The binary digits of "flag" mean
5444 1: outputs a two-component row vector "[P,a]", where "P" is the default
5446 output and "a" is an element expressed on a root of the polynomial "P",
5447 whose minimal polynomial is equal to "x".
5448 4: gives all polynomials of minimal "T_2" norm (of the two polynomials
5450 P(x) and "P(-x)", only one is given).
5451 16: possibly use a suborder of the maximal order. The primes dividing
5453 the index of the order chosen are larger than "primelimit" or divide
5454 integers stored in the "addprimes" table. In that case it may happen
5455 that the output polynomial does not have minimal "T_2" norm.
5456 The library syntax is "polredabs0(x,flag)".
5458 \subsecidx{polredord}"(x)": finds polynomials with reasonably small
5460 coefficients and of the same degree as that of "x" defining suborders
5461 of the order defined by "x". One of the polynomials always defines Q
5462 (hence is equal to "(x-1)^n", where "n" is the degree), and another
5463 always defines the same order as "x" if "x" is irreducible.
5464 The library syntax is "ordred(x)".
5466 \subsecidx{poltschirnhaus}"(x)": applies a random Tschirnhausen
5468 transformation to the polynomial "x", which is assumed to be non-
5469 constant and separable, so as to obtain a new equation for the étale
5470 algebra defined by "x". This is for instance useful when computing
5471 resolvents, hence is used by the "polgalois" function.
5472 The library syntax is "tschirnhaus(x)".
5474 \subsecidx{rnfalgtobasis}"(rnf,x)": expresses "x" on the relative
5476 integral basis. Here, "rnf" is a relative number field extension "L/K"
5477 as output by "rnfinit", and "x" an element of "L" in absolute form,
5478 i.e. expressed as a polynomial or polmod with polmod coefficients, not
5479 on the relative integral basis.
5480 The library syntax is "rnfalgtobasis(rnf,x)".
5482 \subsecidx{rnfbasis}"(bnf, M)": let "K" the field represented by bnf,
5484 as output by "bnfinit". "M" is a projective "Z_K"-module given by a
5485 pseudo-basis, as output by "rnfhnfbasis". The routine returns either a
5486 true "Z_K"-basis of "M" if it exists, or an "n+1"-element generating
5487 set of "M" if not, where "n" is the rank of "M" over "K". (Note that
5488 "n" is the size of the pseudo-basis.)
5489 It is allowed to use a polynomial "P" with coefficients in "K" instead
5491 of "M", in which case, "M" is defined as the ring of integers of
5492 "K[X]/(P)" ("P" is assumed irreducible over "K"), viewed as a
5493 "Z_K"-module.
5494 The library syntax is "rnfbasis(bnf,x)".
5496 \subsecidx{rnfbasistoalg}"(rnf,x)": computes the representation of "x"
5498 as a polmod with polmods coefficients. Here, "rnf" is a relative number
5499 field extension "L/K" as output by "rnfinit", and "x" an element of "L"
5500 expressed on the relative integral basis.
5501 The library syntax is "rnfbasistoalg(rnf,x)".
5503 \subsecidx{rnfcharpoly}"(nf,T,a,{v = x})": characteristic polynomial of
5505 "a" over "nf", where "a" belongs to the algebra defined by "T" over
5506 "nf", i.e. "nf[X]/(T)". Returns a polynomial in variable "v" ("x" by
5507 default).
5508 The library syntax is "rnfcharpoly(nf,T,a,v)", where "v" is a variable
5510 number.
5511 \subsecidx{rnfconductor}"(bnf,pol,{flag = 0})": given "bnf" as output
5513 by "bnfinit", and pol a relative polynomial defining an Abelian
5514 extension, computes the class field theory conductor of this Abelian
5515 extension. The result is a 3-component vector
5516 "[conductor,rayclgp,subgroup]", where conductor is the conductor of the
5517 extension given as a 2-component row vector "[f_0,f_ oo ]", rayclgp is
5518 the full ray class group corresponding to the conductor given as a
5519 3-component vector [h,cyc,gen] as usual for a group, and subgroup is a
5520 matrix in HNF defining the subgroup of the ray class group on the given
5521 generators gen. If "flag" is non-zero, check that pol indeed defines an
5522 Abelian extension, return 0 if it does not.
5523 The library syntax is "rnfconductor(rnf,pol,flag)".
5525 \subsecidx{rnfdedekind}"(nf,pol,pr)": given a number field "nf" as
5527 output by "nfinit" and a polynomial pol with coefficients in "nf"
5528 defining a relative extension "L" of "nf", evaluates the relative
5529 Dedekind criterion over the order defined by a root of pol for the
5530 prime ideal pr and outputs a 3-component vector as the result. The
5531 first component is a flag equal to 1 if the enlarged order could be
5532 proven to be pr-maximal and to 0 otherwise (it may be maximal in the
5533 latter case if pr is ramified in "L"), the second component is a
5534 pseudo-basis of the enlarged order and the third component is the
5535 valuation at pr of the order discriminant.
5536 The library syntax is "rnfdedekind(nf,pol,pr)".
5538 \subsecidx{rnfdet}"(nf,M)": given a pseudo-matrix "M" over the maximal
5540 order of "nf", computes its determinant.
5541 The library syntax is "rnfdet(nf,M)".
5543 \subsecidx{rnfdisc}"(nf,pol)": given a number field "nf" as output by
5545 "nfinit" and a polynomial pol with coefficients in "nf" defining a
5546 relative extension "L" of "nf", computes the relative discriminant of
5547 "L". This is a two-element row vector "[D,d]", where "D" is the
5548 relative ideal discriminant and "d" is the relative discriminant
5549 considered as an element of "nf^*/{nf^*}^2". The main variable of "nf"
5550 must be of lower priority than that of pol, see "Label se:priority".
5551 The library syntax is "rnfdiscf(bnf,pol)".
5553 \subsecidx{rnfeltabstorel}"(rnf,x)": "rnf" being a relative number
5555 field extension "L/K" as output by "rnfinit" and "x" being an element
5556 of "L" expressed as a polynomial modulo the absolute equation
5557 "rnf.pol", computes "x" as an element of the relative extension "L/K"
5558 as a polmod with polmod coefficients.
5559 The library syntax is "rnfelementabstorel(rnf,x)".
5561 \subsecidx{rnfeltdown}"(rnf,x)": "rnf" being a relative number field
5563 extension "L/K" as output by "rnfinit" and "x" being an element of "L"
5564 expressed as a polynomial or polmod with polmod coefficients, computes
5565 "x" as an element of "K" as a polmod, assuming "x" is in "K" (otherwise
5566 an error will occur). If "x" is given on the relative integral basis,
5567 apply "rnfbasistoalg" first, otherwise PARI will believe you are
5568 dealing with a vector.
5569 The library syntax is "rnfelementdown(rnf,x)".
5571 \subsecidx{rnfeltreltoabs}"(rnf,x)": "rnf" being a relative number
5573 field extension "L/K" as output by "rnfinit" and "x" being an element
5574 of "L" expressed as a polynomial or polmod with polmod coefficients,
5575 computes "x" as an element of the absolute extension "L/Q" as a
5576 polynomial modulo the absolute equation "rnf.pol". If "x" is given on
5577 the relative integral basis, apply "rnfbasistoalg" first, otherwise
5578 PARI will believe you are dealing with a vector.
5579 The library syntax is "rnfelementreltoabs(rnf,x)".
5581 \subsecidx{rnfeltup}"(rnf,x)": "rnf" being a relative number field
5583 extension "L/K" as output by "rnfinit" and "x" being an element of "K"
5584 expressed as a polynomial or polmod, computes "x" as an element of the
5585 absolute extension "L/Q" as a polynomial modulo the absolute equation
5586 "rnf.pol". If "x" is given on the integral basis of "K", apply
5587 "nfbasistoalg" first, otherwise PARI will believe you are dealing with
5588 a vector.
5589 The library syntax is "rnfelementup(rnf,x)".
5591 \subsecidx{rnfequation}"(nf,pol,{flag = 0})": given a number field "nf"
5593 as output by "nfinit" (or simply a polynomial) and a polynomial pol
5594 with coefficients in "nf" defining a relative extension "L" of "nf",
5595 computes the absolute equation of "L" over Q.
5596 If "flag" is non-zero, outputs a 3-component row vector "[z,a,k]",
5598 where "z" is the absolute equation of "L" over Q, as in the default
5599 behaviour, "a" expresses as an element of "L" a root "alpha" of the
5600 polynomial defining the base field "nf", and "k" is a small integer
5601 such that "theta = beta+kalpha" where "theta" is a root of "z" and
5602 "beta" a root of "pol".
5603 The main variable of "nf" must be of lower priority than that of pol
5605 (see "Label se:priority"). Note that for efficiency, this does not
5606 check whether the relative equation is irreducible over "nf", but only
5607 if it is squarefree. If it is reducible but squarefree, the result will
5608 be the absolute equation of the étale algebra defined by pol. If pol is
5609 not squarefree, an error message will be issued.
5610 The library syntax is "rnfequation0(nf,pol,flag)".
5612 \subsecidx{rnfhnfbasis}"(bnf,x)": given "bnf" as output by "bnfinit",
5614 and either a polynomial "x" with coefficients in "bnf" defining a
5615 relative extension "L" of "bnf", or a pseudo-basis "x" of such an
5616 extension, gives either a true "bnf"-basis of "L" in upper triangular
5617 Hermite normal form, if it exists, and returns 0 otherwise.
5618 The library syntax is "rnfhnfbasis(nf,x)".
5620 \subsecidx{rnfidealabstorel}"(rnf,x)": let "rnf" be a relative number
5622 field extension "L/K" as output by "rnfinit", and "x" an ideal of the
5623 absolute extension "L/Q" given by a Z-basis of elements of "L".
5624 Returns the relative pseudo-matrix in HNF giving the ideal "x"
5625 considered as an ideal of the relative extension "L/K".
5626 If "x" is an ideal in HNF form, associated to an nf structure, for
5628 instance as output by "idealhnf(nf,...)", use "rnfidealabstorel(rnf,
5629 nf.zk * x)" to convert it to a relative ideal.
5630 The library syntax is "rnfidealabstorel(rnf,x)".
5632 \subsecidx{rnfidealdown}"(rnf,x)": let "rnf" be a relative number field
5634 extension "L/K" as output by "rnfinit", and "x" an ideal of "L", given
5635 either in relative form or by a Z-basis of elements of "L" (see "Label
5636 se:rnfidealabstorel"), returns the ideal of "K" below "x", i.e. the
5637 intersection of "x" with "K".
5638 The library syntax is "rnfidealdown(rnf,x)".
5640 \subsecidx{rnfidealhnf}"(rnf,x)": "rnf" being a relative number field
5642 extension "L/K" as output by "rnfinit" and "x" being a relative ideal
5643 (which can be, as in the absolute case, of many different types,
5644 including of course elements), computes the HNF pseudo-matrix
5645 associated to "x", viewed as a "Z_K"-module.
5646 The library syntax is "rnfidealhermite(rnf,x)".
5648 \subsecidx{rnfidealmul}"(rnf,x,y)": "rnf" being a relative number field
5650 extension "L/K" as output by "rnfinit" and "x" and "y" being ideals of
5651 the relative extension "L/K" given by pseudo-matrices, outputs the
5652 ideal product, again as a relative ideal.
5653 The library syntax is "rnfidealmul(rnf,x,y)".
5655 \subsecidx{rnfidealnormabs}"(rnf,x)": "rnf" being a relative number
5657 field extension "L/K" as output by "rnfinit" and "x" being a relative
5658 ideal (which can be, as in the absolute case, of many different types,
5659 including of course elements), computes the norm of the ideal "x"
5660 considered as an ideal of the absolute extension "L/Q". This is
5661 identical to "idealnorm(rnfidealnormrel(rnf,x))", but faster.
5662 The library syntax is "rnfidealnormabs(rnf,x)".
5664 \subsecidx{rnfidealnormrel}"(rnf,x)": "rnf" being a relative number
5666 field extension "L/K" as output by "rnfinit" and "x" being a relative
5667 ideal (which can be, as in the absolute case, of many different types,
5668 including of course elements), computes the relative norm of "x" as a
5669 ideal of "K" in HNF.
5670 The library syntax is "rnfidealnormrel(rnf,x)".
5672 \subsecidx{rnfidealreltoabs}"(rnf,x)": "rnf" being a relative number
5674 field extension "L/K" as output by "rnfinit" and "x" being a relative
5675 ideal, gives the ideal "xZ_L" as an absolute ideal of "L/Q", in the
5676 form of a Z-basis, given by a vector of polynomials (modulo "rnf.pol").
5677 The following routine might be useful:
5678 \\ return y = rnfidealreltoabs(rnf,...) as an ideal in HNF form
5680 \\ associated to nf = nfinit( rnf.pol );
5681 idealgentoHNF(nf, y) = mathnf( Mat( nfalgtobasis(nf, y) ) );
5682 The library syntax is "rnfidealreltoabs(rnf,x)".
5684 \subsecidx{rnfidealtwoelt}"(rnf,x)": "rnf" being a relative number
5686 field extension "L/K" as output by "rnfinit" and "x" being an ideal of
5687 the relative extension "L/K" given by a pseudo-matrix, gives a vector
5688 of two generators of "x" over "Z_L" expressed as polmods with polmod
5689 coefficients.
5690 The library syntax is "rnfidealtwoelement(rnf,x)".
5692 \subsecidx{rnfidealup}"(rnf,x)": "rnf" being a relative number field
5694 extension "L/K" as output by "rnfinit" and "x" being an ideal of "K",
5695 gives the ideal "xZ_L" as an absolute ideal of "L/Q", in the form of a
5696 Z-basis, given by a vector of polynomials (modulo "rnf.pol"). The
5697 following routine might be useful:
5698 \\ return y = rnfidealup(rnf,...) as an ideal in HNF form
5700 \\ associated to nf = nfinit( rnf.pol );
5701 idealgentoHNF(nf, y) = mathnf( Mat( nfalgtobasis(nf, y) ) );
5702 The library syntax is "rnfidealup(rnf,x)".
5704 \subsecidx{rnfinit}"(nf,pol)": "nf" being a number field in "nfinit"
5706 format considered as base field, and pol a polynomial defining a
5707 relative extension over "nf", this computes all the necessary data to
5708 work in the relative extension. The main variable of pol must be of
5709 higher priority (see "Label se:priority") than that of "nf", and the
5710 coefficients of pol must be in "nf".
5711 The result is a row vector, whose components are technical. In the
5713 following description, we let "K" be the base field defined by "nf",
5714 "m" the degree of the base field, "n" the relative degree, "L" the
5715 large field (of relative degree "n" or absolute degree "nm"), "r_1" and
5716 "r_2" the number of real and complex places of "K".
5717 "rnf[1]" contains the relative polynomial pol.
5719 "rnf[2]" is currently unused.
5721 "rnf[3]" is a two-component row vector "[d(L/K),s]" where "d(L/K)" is
5723 the relative ideal discriminant of "L/K" and "s" is the discriminant of
5724 "L/K" viewed as an element of "K^*/(K^*)^2", in other words it is the
5725 output of "rnfdisc".
5726 "rnf[4]" is the ideal index "f", i.e. such that "d(pol)Z_K =
5728 f^2d(L/K)".
5729 "rnf[5]" is currently unused.
5731 "rnf[6]" is currently unused.
5733 "rnf[7]" is a two-component row vector, where the first component is
5735 the relative integral pseudo basis expressed as polynomials (in the
5736 variable of "pol") with polmod coefficients in "nf", and the second
5737 component is the ideal list of the pseudobasis in HNF.
5738 "rnf[8]" is the inverse matrix of the integral basis matrix, with
5740 coefficients polmods in "nf".
5741 "rnf[9]" is currently unused.
5743 "rnf[10]" is "nf".
5745 "rnf[11]" is the output of "rnfequation(nf, pol, 1)". Namely, a vector
5747 vabs with 3 entries describing the absolute extension "L/Q". "vabs[1]"
5748 is an absolute equation, more conveniently obtained as "rnf.pol".
5749 "vabs[2]" expresses the generator "alpha" of the number field "nf" as a
5750 polynomial modulo the absolute equation "vabs[1]". "vabs[3]" is a small
5751 integer "k" such that, if "beta" is an abstract root of pol and "alpha"
5752 the generator of "nf", the generator whose root is vabs will be "beta +
5753 k alpha". Note that one must be very careful if "k != 0" when dealing
5754 simultaneously with absolute and relative quantities since the
5755 generator chosen for the absolute extension is not the same as for the
5756 relative one. If this happens, one can of course go on working, but we
5757 strongly advise to change the relative polynomial so that its root will
5758 be "beta + k alpha". Typically, the GP instruction would be
5759 "pol = subst(pol, x, x - k*Mod(y,nf.pol))"
5761 "rnf[12]" is by default unused and set equal to 0. This field is used
5763 to store further information about the field as it becomes available
5764 (which is rarely needed, hence would be too expensive to compute during
5765 the initial "rnfinit" call).
5766 The library syntax is "rnfinitalg(nf,pol,prec)".
5768 \subsecidx{rnfisfree}"(bnf,x)": given "bnf" as output by "bnfinit", and
5770 either a polynomial "x" with coefficients in "bnf" defining a relative
5771 extension "L" of "bnf", or a pseudo-basis "x" of such an extension,
5772 returns true (1) if "L/bnf" is free, false (0) if not.
5773 The library syntax is "rnfisfree(bnf,x)", and the result is a "long".
5775 \subsecidx{rnfisnorm}"(T,a,{flag = 0})": similar to "bnfisnorm" but in
5777 the relative case. "T" is as output by "rnfisnorminit" applied to the
5778 extension "L/K". This tries to decide whether the element "a" in "K" is
5779 the norm of some "x" in the extension "L/K".
5780 The output is a vector "[x,q]", where "a = Norm (x)*q". The algorithm
5782 looks for a solution "x" which is an "S"-integer, with "S" a list of
5783 places of "K" containing at least the ramified primes, the generators
5784 of the class group of "L", as well as those primes dividing "a". If
5785 "L/K" is Galois, then this is enough; otherwise, "flag" is used to add
5786 more primes to "S": all the places above the primes "p <= flag"
5787 (resp. "p|flag") if "flag > 0" (resp. "flag < 0").
5788 The answer is guaranteed (i.e. "a" is a norm iff "q = 1") if the field
5790 is Galois, or, under GRH, if "S" contains all primes less than "12 log
5791 ^2| disc (M)|", where "M" is the normal closure of "L/K".
5792 If "rnfisnorminit" has determined (or was told) that "L/K" is Galois,
5794 and "flag != 0", a Warning is issued (so that you can set "flag = 1" to
5795 check whether "L/K" is known to be Galois, according to "T"). Example:
5796 bnf = bnfinit(y^3 + y^2 - 2*y - 1);
5798 p = x^2 + Mod(y^2 + 2*y + 1, bnf.pol);
5799 T = rnfisnorminit(bnf, p);
5800 rnfisnorm(T, 17)
5801 checks whether 17 is a norm in the Galois extension "Q(beta) /
5803 Q(alpha)", where "alpha^3 + alpha^2 - 2alpha - 1 = 0" and "beta^2 +
5804 alpha^2 + 2alpha + 1 = 0" (it is).
5805 The library syntax is "rnfisnorm(T,x,flag)".
5807 \subsecidx{rnfisnorminit}"(pol,polrel,{flag = 2})": let "K" be defined
5809 by a root of pol, and "L/K" the extension defined by the polynomial
5810 polrel. As usual, pol can in fact be an nf, or bnf, etc; if pol has
5811 degree 1 (the base field is Q), polrel is also allowed to be an nf,
5812 etc. Computes technical data needed by "rnfisnorm" to solve norm
5813 equations "Nx = a", for "x" in "L", and "a" in "K".
5814 If "flag = 0", do not care whether "L/K" is Galois or not.
5816 If "flag = 1", "L/K" is assumed to be Galois (unchecked), which speeds
5818 up "rnfisnorm".
5819 If "flag = 2", let the routine determine whether "L/K" is Galois.
5821 The library syntax is "rnfisnorminit(pol,polrel,flag)".
5823 \subsecidx{rnfkummer}"(bnr,{subgroup},{deg = 0})": bnr being as output
5825 by "bnrinit", finds a relative equation for the class field
5826 corresponding to the module in bnr and the given congruence subgroup
5827 (the full ray class field if subgroup is omitted). If deg is positive,
5828 outputs the list of all relative equations of degree deg contained in
5829 the ray class field defined by bnr, with the same conductor as "(bnr,
5830 subgroup)".
5831 Warning:. this routine only works for subgroups of prime index. It uses
5833 Kummer theory, adjoining necessary roots of unity (it needs to compute
5834 a tough "bnfinit" here), and finds a generator via Hecke's
5835 characterization of ramification in Kummer extensions of prime degree.
5836 If your extension does not have prime degree, for the time being, you
5837 have to split it by hand as a tower / compositum of such extensions.
5838 The library syntax is "rnfkummer(bnr,subgroup,deg,prec)", where deg is
5840 a "long" and an omitted subgroup is coded as "NULL"
5841 \subsecidx{rnflllgram}"(nf,pol,order)": given a polynomial pol with
5843 coefficients in nf defining a relative extension "L" and a suborder
5844 order of "L" (of maximal rank), as output by "rnfpseudobasis""(nf,pol)"
5845 or similar, gives "[[neworder],U]", where neworder is a reduced order
5846 and "U" is the unimodular transformation matrix.
5847 The library syntax is "rnflllgram(nf,pol,order,prec)".
5849 \subsecidx{rnfnormgroup}"(bnr,pol)": bnr being a big ray class field as
5851 output by "bnrinit" and pol a relative polynomial defining an Abelian
5852 extension, computes the norm group (alias Artin or Takagi group)
5853 corresponding to the Abelian extension of "bnf = bnr[1]" defined by
5854 pol, where the module corresponding to bnr is assumed to be a multiple
5855 of the conductor (i.e. pol defines a subextension of bnr). The result
5856 is the HNF defining the norm group on the given generators of
5857 "bnr[5][3]". Note that neither the fact that pol defines an Abelian
5858 extension nor the fact that the module is a multiple of the conductor
5859 is checked. The result is undefined if the assumption is not correct.
5860 The library syntax is "rnfnormgroup(bnr,pol)".
5862 \subsecidx{rnfpolred}"(nf,pol)": relative version of "polred". Given a
5864 monic polynomial pol with coefficients in "nf", finds a list of
5865 relative polynomials defining some subfields, hopefully simpler and
5866 containing the original field. In the present version
5867 /usr/share/libpari23, this is slower and less efficient than
5868 "rnfpolredabs".
5869 The library syntax is "rnfpolred(nf,pol,prec)".
5871 \subsecidx{rnfpolredabs}"(nf,pol,{flag = 0})": relative version of
5873 "polredabs". Given a monic polynomial pol with coefficients in "nf",
5874 finds a simpler relative polynomial defining the same field. The binary
5875 digits of "flag" mean
5876 1: returns "[P,a]" where "P" is the default output and "a" is an
5878 element expressed on a root of "P" whose characteristic polynomial is
5879 pol
5880 2: returns an absolute polynomial (same as
5882 "rnfequation(nf,rnfpolredabs(nf,pol))" but faster).
5883 16: possibly use a suborder of the maximal order. This is slower than
5885 the default when the relative discriminant is smooth, and much faster
5886 otherwise. See "Label se:polredabs".
5887 Remark.. In the present implementation, this is both faster and much
5889 more efficient than "rnfpolred", the difference being more dramatic
5890 than in the absolute case. This is because the implementation of
5891 "rnfpolred" is based on (a partial implementation of) an incomplete
5892 reduction theory of lattices over number fields, the function
5893 "rnflllgram", which deserves to be improved.
5894 The library syntax is "rnfpolredabs(nf,pol,flag,prec)".
5896 \subsecidx{rnfpseudobasis}"(nf,pol)": given a number field "nf" as
5898 output by "nfinit" and a polynomial pol with coefficients in "nf"
5899 defining a relative extension "L" of "nf", computes a pseudo-basis
5900 "(A,I)" for the maximal order "Z_L" viewed as a "Z_K"-module, and the
5901 relative discriminant of "L". This is output as a four-element row
5902 vector "[A,I,D,d]", where "D" is the relative ideal discriminant and
5903 "d" is the relative discriminant considered as an element of
5904 "nf^*/{nf^*}^2".
5905 The library syntax is "rnfpseudobasis(nf,pol)".
5907 \subsecidx{rnfsteinitz}"(nf,x)": given a number field "nf" as output by
5909 "nfinit" and either a polynomial "x" with coefficients in "nf" defining
5910 a relative extension "L" of "nf", or a pseudo-basis "x" of such an
5911 extension as output for example by "rnfpseudobasis", computes another
5912 pseudo-basis "(A,I)" (not in HNF in general) such that all the ideals
5913 of "I" except perhaps the last one are equal to the ring of integers of
5914 "nf", and outputs the four-component row vector "[A,I,D,d]" as in
5915 "rnfpseudobasis". The name of this function comes from the fact that
5916 the ideal class of the last ideal of "I", which is well defined, is the
5917 Steinitz class of the "Z_K"-module "Z_L" (its image in "SK_0(Z_K)").
5918 The library syntax is "rnfsteinitz(nf,x)".
5920 \subsecidx{subgrouplist}"(bnr,{bound},{flag = 0})": bnr being as output
5922 by "bnrinit" or a list of cyclic components of a finite Abelian group
5923 "G", outputs the list of subgroups of "G". Subgroups are given as HNF
5924 left divisors of the SNF matrix corresponding to "G".
5925 Warning:. the present implementation cannot treat a group "G" where any
5927 cyclic factor has more than "2^{31}", resp. "2^{63}" elements on a
5928 32-bit, resp. 64-bit architecture. "forsubgroup" is a bit more general
5929 and can handle "G" if all "p"-Sylow subgroups of "G" satisfy the
5930 condition above.
5931 If "flag = 0" (default) and bnr is as output by "bnrinit", gives only
5933 the subgroups whose modulus is the conductor. Otherwise, the modulus is
5934 not taken into account.
5935 If bound is present, and is a positive integer, restrict the output to
5937 subgroups of index less than bound. If bound is a vector containing a
5938 single positive integer "B", then only subgroups of index exactly equal
5939 to "B" are computed. For instance
5940 %2 = [[2, 1; 0, 1], [1, 0; 0, 2], [2, 0; 0, 1], [3, 0; 0, 1], [1, 0; 0, 1]]
5942 ? subgrouplist([6,2],[3]) \\ index less than 3
5943 %2 = [[2, 1; 0, 1], [1, 0; 0, 2], [2, 0; 0, 1], [3, 0; 0, 1], [1, 0; 0, 1]]
5944 ? subgrouplist([6,2],[3]) \\ index 3
5945 %3 = [[3, 0; 0, 1]]
5946 ? bnr = bnrinit(bnfinit(x), [120,[1]], 1);
5947 ? L = subgrouplist(bnr, [8]);
5948 In the last example, "L" corresponds to the 24 subfields of
5950 "Q(zeta_{120})", of degree 8 and conductor "120 oo " (by setting flag,
5951 we see there are a total of 43 subgroups of degree 8).
5952 ? vector(#L, i, galoissubcyclo(bnr, L[i]))
5954 will produce their equations. (For a general base field, you would have
5956 to rely on "bnrstark", or "rnfkummer".)
5957 The library syntax is "subgrouplist0(bnr,bound,flag)", where "flag" is
5959 a long integer, and an omitted bound is coded by "NULL".
5960 \subsecidx{zetak}"(znf,x,{flag = 0})": znf being a number field
5962 initialized by "zetakinit" (not by "nfinit"), computes the value of the
5963 Dedekind zeta function of the number field at the complex number "x".
5964 If "flag = 1" computes Dedekind "Lambda" function instead (i.e. the
5965 product of the Dedekind zeta function by its gamma and exponential
5966 factors).
5967 CAVEAT.. This implementation is not satisfactory and must be rewritten.
5969 In particular
5970 "*" The accuracy of the result depends in an essential way on the
5972 accuracy of both the "zetakinit" program and the current accuracy. Be
5973 wary in particular that "x" of large imaginary part or, on the
5974 contrary, very close to an ordinary integer will suffer from precision
5975 loss, yielding fewer significant digits than expected. Computing with
5976 28 eight digits of relative accuracy, we have
5977 ? zeta(3)
5979 %1 = 1.202056903159594285399738161
5980 ? zeta(3-1e-20)
5981 %2 = 1.202056903159594285401719424
5982 ? zetak(zetakinit(x), 3-1e-20)
5983 %3 = 1.2020569031595952919 \\ 5 digits are wrong
5984 ? zetak(zetakinit(x), 3-1e-28)
5985 %4 = -25.33411749 \\ junk
5986 "*" As the precision increases, results become unexpectedly completely
5988 wrong:
5989 ? \p100
5991 ? zetak(zetakinit(x^2-5), -1) - 1/30
5992 %1 = 7.26691813 E-108 \\ perfect
5993 ? \p150
5994 ? zetak(zetakinit(x^2-5), -1) - 1/30
5995 %2 = -2.486113578 E-156 \\ perfect
5996 ? \p200
5997 ? zetak(zetakinit(x^2-5), -1) - 1/30
5998 %3 = 4.47... E-75 \\ more than half of the digits are wrong
5999 ? \p250
6000 ? zetak(zetakinit(x^2-5), -1) - 1/30
6001 %4 = 1.6 E43 \\ junk
6002 The library syntax is "glambdak(znf,x,prec)" or
6004 \funs{gzetak}{znf,x,prec}.
6005 \subsecidx{zetakinit}"(x)": computes a number of initialization data
6007 concerning the number field defined by the polynomial "x" so as to be
6008 able to compute the Dedekind zeta and lambda functions (respectively
6009 zetak(x) and "zetak(x,1)"). This function calls in particular the
6010 "bnfinit" program. The result is a 9-component vector "v" whose
6011 components are very technical and cannot really be used by the user
6012 except through the "zetak" function. The only component which can be
6013 used if it has not been computed already is "v[1][4]" which is the
6014 result of the "bnfinit" call.
6015 This function is very inefficient and should be rewritten. It needs to
6017 computes millions of coefficients of the corresponding Dirichlet series
6018 if the precision is big. Unless the discriminant is small it will not
6019 be able to handle more than 9 digits of relative precision. For
6020 instance, "zetakinit(x^8 - 2)" needs 440MB of memory at default
6021 precision.
6022 The library syntax is "initzeta(x)".
6024
6026 We group here all functions which are specific to polynomials or power
6027 series. Many other functions which can be applied on these objects are
6028 described in the other sections. Also, some of the functions described
6029 here can be applied to other types.
6030 \subsecidx{O}"(p^e)": if "p" is an integer greater than 2, returns a
6032 "p"-adic 0 of precision "e". In all other cases, returns a power series
6033 zero with precision given by "e v", where "v" is the "X"-adic valuation
6034 of "p" with respect to its main variable.
6035 The library syntax is "zeropadic(p,e)" for a "p"-adic and
6037 \funs{zeroser}{v,e} for a power series zero in variable "v", which is a
6038 "long". The precision "e" is a "long".
6039 \subsecidx{deriv}"(x,{v})": derivative of "x" with respect to the main
6041 variable if "v" is omitted, and with respect to "v" otherwise. The
6042 derivative of a scalar type is zero, and the derivative of a vector or
6043 matrix is done componentwise. One can use "x'" as a shortcut if the
6044 derivative is with respect to the main variable of "x".
6045 By definition, the main variable of a "t_POLMOD" is the main variable
6047 among the coefficients from its two polynomial components
6048 (representative and modulus); in other words, assuming a polmod
6049 represents an element of "R[X]/(T(X))", the variable "X" is a mute
6050 variable and the derivative is taken with respect to the main variable
6051 used in the base ring "R".
6052 The library syntax is "deriv(x,v)", where "v" is a "long", and an
6054 omitted "v" is coded as "-1". When "x" is a "t_POL", derivpol(x) is a
6055 shortcut for "deriv(x, -1)".
6056 \subsecidx{eval}"(x)": replaces in "x" the formal variables by the
6058 values that have been assigned to them after the creation of "x". This
6059 is mainly useful in GP, and not in library mode. Do not confuse this
6060 with substitution (see "subst").
6061 If "x" is a character string, eval(x) executes "x" as a GP command, as
6063 if directly input from the keyboard, and returns its output. For
6064 convenience, "x" is evaluated as if "strictmatch" was off. In
6065 particular, unused characters at the end of "x" do not prevent its
6066 evaluation:
6067 ? eval("1a")
6069 % 1 = 1
6070 The library syntax is "geval(x)". The more basic functions
6072 \funs{poleval}{q,x}, \funs{qfeval}{q,x}, and \funs{hqfeval}{q,x}
6073 evaluate "q" at "x", where "q" is respectively assumed to be a
6074 polynomial, a quadratic form (a symmetric matrix), or an Hermitian form
6075 (an Hermitian complex matrix).
6076 \subsecidx{factorpadic}"(pol,p,r,{flag = 0})": "p"-adic factorization
6078 of the polynomial pol to precision "r", the result being a two-column
6079 matrix as in "factor". The factors are normalized so that their leading
6080 coefficient is a power of "p". "r" must be strictly larger than the
6081 "p"-adic valuation of the discriminant of pol for the result to make
6082 any sense. The method used is a modified version of the round 4
6083 algorithm of Zassenhaus.
6084 If "flag = 1", use an algorithm due to Buchmann and Lenstra, which is
6086 usually less efficient.
6087 The library syntax is "factorpadic4(pol,p,r)", where "r" is a "long"
6089 integer.
6090 \subsecidx{intformal}"(x,{v})": formal integration of "x" with respect
6092 to the main variable if "v" is omitted, with respect to the variable
6093 "v" otherwise. Since PARI does not know about ``abstract'' logarithms
6094 (they are immediately evaluated, if only to a power series),
6095 logarithmic terms in the result will yield an error. "x" can be of any
6096 type. When "x" is a rational function, it is assumed that the base ring
6097 is an integral domain of characteristic zero.
6098 The library syntax is "integ(x,v)", where "v" is a "long" and an
6100 omitted "v" is coded as "-1".
6101 \subsecidx{padicappr}"(pol,a)": vector of "p"-adic roots of the
6103 polynomial "pol" congruent to the "p"-adic number "a" modulo "p", and
6104 with the same "p"-adic precision as "a". The number "a" can be an
6105 ordinary "p"-adic number (type "t_PADIC", i.e. an element of "Z_p") or
6106 can be an integral element of a finite extension of "Q_p", given as a
6107 "t_POLMOD" at least one of whose coefficients is a "t_PADIC". In this
6108 case, the result is the vector of roots belonging to the same extension
6109 of "Q_p" as "a".
6110 The library syntax is "padicappr(pol,a)".
6112 \subsecidx{polcoeff}"(x,s,{v})": coefficient of degree "s" of the
6114 polynomial "x", with respect to the main variable if "v" is omitted,
6115 with respect to "v" otherwise. Also applies to power series, scalars
6116 (polynomial of degree 0), and to rational functions provided the
6117 denominator is a monomial.
6118 The library syntax is "polcoeff0(x,s,v)", where "v" is a "long" and an
6120 omitted "v" is coded as "-1". Also available is \funs{truecoeff}{x,v}.
6121 \subsecidx{poldegree}"(x,{v})": degree of the polynomial "x" in the
6123 main variable if "v" is omitted, in the variable "v" otherwise.
6124 The degree of 0 is a fixed negative number, whose exact value should
6126 not be used. The degree of a non-zero scalar is 0. Finally, when "x" is
6127 a non-zero polynomial or rational function, returns the ordinary degree
6128 of "x". Raise an error otherwise.
6129 The library syntax is "poldegree(x,v)", where "v" and the result are
6131 "long"s (and an omitted "v" is coded as "-1"). Also available is
6132 \funs{degree}{x}, which is equivalent to "poldegree(x,-1)".
6133 \subsecidx{polcyclo}"(n,{v = x})": "n"-th cyclotomic polynomial, in
6135 variable "v" ("x" by default). The integer "n" must be positive.
6136 The library syntax is "cyclo(n,v)", where "n" and "v" are "long"
6138 integers ("v" is a variable number, usually obtained through "varn").
6139 \subsecidx{poldisc}"(pol,{v})": discriminant of the polynomial pol in
6141 the main variable is "v" is omitted, in "v" otherwise. The algorithm
6142 used is the subresultant algorithm.
6143 The library syntax is "poldisc0(x,v)". Also available is
6145 \funs{discsr}{x}, equivalent to "poldisc0(x,-1)".
6146 \subsecidx{poldiscreduced}"(f)": reduced discriminant vector of the
6148 (integral, monic) polynomial "f". This is the vector of elementary
6149 divisors of "Z[alpha]/f'(alpha)Z[alpha]", where "alpha" is a root of
6150 the polynomial "f". The components of the result are all positive, and
6151 their product is equal to the absolute value of the discriminant
6152 of "f".
6153 The library syntax is "reduceddiscsmith(x)".
6155 \subsecidx{polhensellift}"(x, y, p, e)": given a prime "p", an integral
6157 polynomial "x" whose leading coefficient is a "p"-unit, a vector "y" of
6158 integral polynomials that are pairwise relatively prime modulo "p", and
6159 whose product is congruent to "x" modulo "p", lift the elements of "y"
6160 to polynomials whose product is congruent to "x" modulo "p^e".
6161 The library syntax is "polhensellift(x,y,p,e)" where "e" must be a
6163 "long".
6164 \subsecidx{polinterpolate}"(xa,{ya},{v = x},{&e})": given the data
6166 vectors "xa" and "ya" of the same length "n" ("xa" containing the
6167 "x"-coordinates, and "ya" the corresponding "y"-coordinates), this
6168 function finds the interpolating polynomial passing through these
6169 points and evaluates it at "v". If "ya" is omitted, return the
6170 polynomial interpolating the "(i,xa[i])". If present, "e" will contain
6171 an error estimate on the returned value.
6172 The library syntax is "polint(xa,ya,v,&e)", where "e" will contain an
6174 error estimate on the returned value.
6175 \subsecidx{polisirreducible}"(pol)": pol being a polynomial (univariate
6177 in the present version /usr/share/libpari23), returns 1 if pol is non-
6178 constant and irreducible, 0 otherwise. Irreducibility is checked over
6179 the smallest base field over which pol seems to be defined.
6180 The library syntax is "gisirreducible(pol)".
6182 \subsecidx{pollead}"(x,{v})": leading coefficient of the polynomial or
6184 power series "x". This is computed with respect to the main variable of
6185 "x" if "v" is omitted, with respect to the variable "v" otherwise.
6186 The library syntax is "pollead(x,v)", where "v" is a "long" and an
6188 omitted "v" is coded as "-1". Also available is \funs{leading_term}{x}.
6189 \subsecidx{pollegendre}"(n,{v = x})": creates the "n-th" Legendre
6191 polynomial, in variable "v".
6192 The library syntax is "legendre(n)", where "x" is a "long".
6194 \subsecidx{polrecip}"(pol)": reciprocal polynomial of pol, i.e. the
6196 coefficients are in reverse order. pol must be a polynomial.
6197 The library syntax is "polrecip(x)".
6199 \subsecidx{polresultant}"(x,y,{v},{flag = 0})": resultant of the two
6201 polynomials "x" and "y" with exact entries, with respect to the main
6202 variables of "x" and "y" if "v" is omitted, with respect to the
6203 variable "v" otherwise. The algorithm assumes the base ring is a
6204 domain.
6205 If "flag = 0", uses the subresultant algorithm.
6207 If "flag = 1", uses the determinant of Sylvester's matrix instead (here
6209 "x" and "y" may have non-exact coefficients).
6210 If "flag = 2", uses Ducos's modified subresultant algorithm. It should
6212 be much faster than the default if the coefficient ring is complicated
6213 (e.g multivariate polynomials or huge coefficients), and slightly
6214 slower otherwise.
6215 The library syntax is "polresultant0(x,y,v,flag)", where "v" is a
6217 "long" and an omitted "v" is coded as "-1". Also available are
6218 \funs{subres}{x,y} ("flag = 0") and \funs{resultant2}{x,y} ("flag =
6219 1").
6220 \subsecidx{polroots}"(pol,{flag = 0})": complex roots of the polynomial
6222 pol, given as a column vector where each root is repeated according to
6223 its multiplicity. The precision is given as for transcendental
6224 functions: in GP it is kept in the variable "realprecision" and is
6225 transparent to the user, but it must be explicitly given as a second
6226 argument in library mode.
6227 The algorithm used is a modification of A. Schönhage's root-finding
6229 algorithm, due to and implemented by X. Gourdon. Barring bugs, it is
6230 guaranteed to converge and to give the roots to the required accuracy.
6231 If "flag = 1", use a variant of the Newton-Raphson method, which is not
6233 guaranteed to converge, but is rather fast. If you get the messages
6234 ``too many iterations in roots'' or ``INTERNAL ERROR: incorrect result
6235 in roots'', use the default algorithm. This used to be the default
6236 root-finding function in PARI until version 1.39.06.
6237 The library syntax is "roots(pol,prec)" or \funs{rootsold}{pol,prec}.
6239 \subsecidx{polrootsmod}"(pol,p,{flag = 0})": row vector of roots modulo
6241 "p" of the polynomial pol. The particular non-prime value "p = 4" is
6242 accepted, mainly for 2-adic computations. Multiple roots are not
6243 repeated.
6244 If "p" is very small, you may try setting "flag = 1", which uses a
6246 naive search.
6247 The library syntax is "rootmod(pol,p)" ("flag = 0") or
6249 \funs{rootmod2}{pol,p} ("flag = 1").
6250 \subsecidx{polrootspadic}"(pol,p,r)": row vector of "p"-adic roots of
6252 the polynomial pol, given to "p"-adic precision "r". Multiple roots are
6253 not repeated. "p" is assumed to be a prime, and pol to be non-zero
6254 modulo "p". Note that this is not the same as the roots in "Z/p^rZ",
6255 rather it gives approximations in "Z/p^rZ" of the true roots living in
6256 "Q_p".
6257 If pol has inexact "t_PADIC" coefficients, this is not always well-
6259 defined; in this case, the equation is first made integral, then lifted
6260 to Z. Hence the roots given are approximations of the roots of a
6261 polynomial which is "p"-adically close to the input.
6262 The library syntax is "rootpadic(pol,p,r)", where "r" is a "long".
6264 \subsecidx{polsturm}"(pol,{a},{b})": number of real roots of the real
6266 polynomial pol in the interval "]a,b]", using Sturm's algorithm. "a"
6267 (resp. "b") is taken to be "- oo " (resp. "+ oo ") if omitted.
6268 The library syntax is "sturmpart(pol,a,b)". Use "NULL" to omit an
6270 argument. \funs{sturm}{pol} is equivalent to
6271 \funs{sturmpart}{pol,"NULL","NULL"}. The result is a "long".
6272 \subsecidx{polsubcyclo}"(n,d,{v = x})": gives polynomials (in variable
6274 "v") defining the sub-Abelian extensions of degree "d" of the
6275 cyclotomic field "Q(zeta_n)", where "d | phi(n)".
6276 If there is exactly one such extension the output is a polynomial, else
6278 it is a vector of polynomials, eventually empty.
6279 To be sure to get a vector, you can use "concat([],polsubcyclo(n,d))"
6281 The function "galoissubcyclo" allows to specify more closely which sub-
6283 Abelian extension should be computed.
6284 The library syntax is "polsubcyclo(n,d,v)", where "n", "d" and "v" are
6286 "long" and "v" is a variable number. When "(Z/nZ)^*" is cyclic, you can
6287 use \funs{subcyclo}{n,d,v}, where "n", "d" and "v" are "long" and "v"
6288 is a variable number.
6289 \subsecidx{polsylvestermatrix}"(x,y)": forms the Sylvester matrix
6291 corresponding to the two polynomials "x" and "y", where the
6292 coefficients of the polynomials are put in the columns of the matrix
6293 (which is the natural direction for solving equations afterwards). The
6294 use of this matrix can be essential when dealing with polynomials with
6295 inexact entries, since polynomial Euclidean division doesn't make much
6296 sense in this case.
6297 The library syntax is "sylvestermatrix(x,y)".
6299 \subsecidx{polsym}"(x,n)": creates the vector of the symmetric powers
6301 of the roots of the polynomial "x" up to power "n", using Newton's
6302 formula.
6303 The library syntax is "polsym(x)".
6305 \subsecidx{poltchebi}"(n,{v = x})": creates the "n-th" Chebyshev
6307 polynomial "T_n" of the first kind in variable "v".
6308 The library syntax is "tchebi(n,v)", where "n" and "v" are "long"
6310 integers ("v" is a variable number).
6311 \subsecidx{polzagier}"(n,m)": creates Zagier's polynomial "P_n^{(m)}"
6313 used in the functions "sumalt" and "sumpos" (with "flag = 1"). One must
6314 have "m <= n". The exact definition can be found in ``Convergence
6315 acceleration of alternating series'', Cohen et al., Experiment. Math.,
6316 vol. 9, 2000, pp. 3--12.
6317 The library syntax is "polzagreel(n,m,prec)" if the result is only
6319 wanted as a polynomial with real coefficients to the precision "prec",
6320 or \funs{polzag}{n,m} if the result is wanted exactly, where "n" and
6321 "m" are "long"s.
6322 \subsecidx{serconvol}"(x,y)": convolution (or Hadamard product) of the
6324 two power series "x" and "y"; in other words if "x = sum a_k*X^k" and
6325 "y = sum b_k*X^k" then "serconvol(x,y) = sum a_k*b_k*X^k".
6326 The library syntax is "convol(x,y)".
6328 \subsecidx{serlaplace}"(x)": "x" must be a power series with non-
6330 negative exponents. If "x = sum (a_k/k!)*X^k" then the result is "sum
6331 a_k*X^k".
6332 The library syntax is "laplace(x)".
6334 \subsecidx{serreverse}"(x)": reverse power series (i.e. "x^{-1}", not
6336 "1/x") of "x". "x" must be a power series whose valuation is exactly
6337 equal to one.
6338 The library syntax is "recip(x)".
6340 \subsecidx{subst}"(x,y,z)": replace the simple variable "y" by the
6342 argument "z" in the ``polynomial'' expression "x". Every type is
6343 allowed for "x", but if it is not a genuine polynomial (or power
6344 series, or rational function), the substitution will be done as if the
6345 scalar components were polynomials of degree zero. In particular,
6346 beware that:
6347 ? subst(1, x, [1,2; 3,4])
6349 %1 =
6350 [1 0]
6351 [0 1]
6353 ? subst(1, x, Mat([0,1]))
6355 *** forbidden substitution by a non square matrix
6356 If "x" is a power series, "z" must be either a polynomial, a power
6358 series, or a rational function.
6359 The library syntax is "gsubst(x,y,z)", where "y" is the variable
6361 number.
6362 \subsecidx{substpol}"(x,y,z)": replace the ``variable'' "y" by the
6364 argument "z" in the ``polynomial'' expression "x". Every type is
6365 allowed for "x", but the same behaviour as "subst" above apply.
6366 The difference with "subst" is that "y" is allowed to be any polynomial
6368 here. The substitution is done as per the following script:
6369 subst_poly(pol, from, to) =
6371 { local(t = 'subst_poly_t, M = from - t);
6372 subst(lift(Mod(pol,M), variable(M)), t, to)
6374 }
6375 For instance
6377 ? substpol(x^4 + x^2 + 1, x^2, y)
6379 %1 = y^2 + y + 1
6380 ? substpol(x^4 + x^2 + 1, x^3, y)
6381 %2 = x^2 + y*x + 1
6382 ? substpol(x^4 + x^2 + 1, (x+1)^2, y)
6383 %3 = (-4*y - 6)*x + (y^2 + 3*y - 3)
6384 The library syntax is "gsubstpol(x,y,z)".
6386 \subsecidx{substvec}"(x,v,w)": "v" being a vector of monomials
6388 (variables), "w" a vector of expressions of the same length, replace in
6389 the expression "x" all occurences of "v_i" by "w_i". The substitutions
6390 are done simultaneously; more precisely, the "v_i" are first replaced
6391 by new variables in "x", then these are replaced by the "w_i":
6392 ? substvec([x,y], [x,y], [y,x])
6394 %1 = [y, x]
6395 ? substvec([x,y], [x,y], [y,x+y])
6396 %2 = [y, x + y] \\ not [y, 2*y]
6397 The library syntax is "gsubstvec(x,v,w)".
6399 \subsecidx{taylor}"(x,y)": Taylor expansion around 0 of "x" with
6401 respect to the simple variable "y". "x" can be of any reasonable type,
6402 for example a rational function. The number of terms of the expansion
6403 is transparent to the user in GP, but must be given as a second
6404 argument in library mode.
6405 The library syntax is "tayl(x,y,n)", where the "long" integer "n" is
6407 the desired number of terms in the expansion.
6408 \subsecidx{thue}"(tnf,a,{sol})": solves the equation "P(x,y) = a" in
6410 integers "x" and "y", where tnf was created with thueinit(P). sol, if
6411 present, contains the solutions of " Norm (x) = a" modulo units of
6412 positive norm in the number field defined by "P" (as computed by
6413 "bnfisintnorm"). If the result is conditional (on the GRH or some
6414 heuristic strenghtening), a Warning is printed. Otherwise, the result
6415 is unconditional, barring bugs. For instance, here's how to solve the
6416 Thue equation "x^{13} - 5y^{13} = - 4":
6417 ? tnf = thueinit(x^13 - 5);
6419 ? thue(tnf, -4)
6420 %1 = [[1, 1]]
6421 Hence, the only solution is "x = 1", "y = 1" and the result is
6423 unconditional. On the other hand:
6424 ? tnf = thueinit(x^3-2*x^2+3*x-17);
6426 ? thue(tnf, -15)
6427 *** thue: Warning: Non trivial conditional class group.
6428 *** May miss solutions of the norm equation.
6429 %2 = [[1, 1]]
6430 This time the result is conditional. All results computed using this
6432 tnf are likewise conditional, except for a right-hand side of "+- 1".
6433 The library syntax is "thue(tnf,a,sol)", where an omitted sol is coded
6435 as "NULL".
6436 \subsecidx{thueinit}"(P,{flag = 0})": initializes the tnf corresponding
6438 to "P". It is meant to be used in conjunction with "thue" to solve Thue
6439 equations "P(x,y) = a", where "a" is an integer. If "flag" is non-zero,
6440 certify the result unconditionnally. Otherwise, assume GRH, this being
6441 much faster of course.
6442 If the conditional computed class group is trivial or you are only
6444 interested in the case "a = +-1", then results are unconditional
6445 anyway. So one should only use the flag is "thue" prints a Warning (see
6446 the example there).
6447 The library syntax is "thueinit(P,flag,prec)".
6449
6451 Note that most linear algebra functions operating on subspaces defined
6452 by generating sets (such as "mathnf", "qflll", etc.) take matrices as
6453 arguments. As usual, the generating vectors are taken to be the columns
6454 of the given matrix.
6455 Since PARI does not have a strong typing system, scalars live in
6457 unspecified commutative base rings. It is very difficult to write
6458 robust linear algebra routines in such a general setting. The
6459 developpers's choice has been to assume the base ring is a domain and
6460 work over its field of fractions. If the base ring is not a domain, one
6461 gets an error as soon as a non-zero pivot turns out to be non-
6462 invertible. Some functions, e.g. "mathnf" or "mathnfmod", specifically
6463 assume the base ring is Z.
6464 \subsecidx{algdep}"(x,k,{flag = 0})":
6466 "x" being real/complex, or "p"-adic, finds a polynomial of degree at
6467 most "k" with integer coefficients having "x" as approximate root.
6468 Note that the polynomial which is obtained is not necessarily the
6469 ``correct'' one. In fact it is not even guaranteed to be irreducible.
6470 One can check the closeness either by a polynomial evaluation (use
6471 "subst"), or by computing the roots of the polynomial given by "algdep"
6472 (use "polroots").
6473 Internally, "lindep""([1,x,...,x^k], flag)" is used. If "lindep" is not
6475 able to find a relation and returns a lower bound for the sup norm of
6476 the smallest relation, "algdep" returns that bound instead. A suitable
6477 non-zero value of "flag" may improve on the default behaviour:
6478 \\\\\\\\\ LLL
6480 ? \p200
6481 ? algdep(2^(1/6)+3^(1/5), 30); \\ wrong in 3.8s
6482 ? algdep(2^(1/6)+3^(1/5), 30, 100); \\ wrong in 1s
6483 ? algdep(2^(1/6)+3^(1/5), 30, 170); \\ right in 3.3s
6484 ? algdep(2^(1/6)+3^(1/5), 30, 200); \\ wrong in 2.9s
6485 ? \p250
6486 ? algdep(2^(1/6)+3^(1/5), 30); \\ right in 2.8s
6487 ? algdep(2^(1/6)+3^(1/5), 30, 200); \\ right in 3.4s
6488 \\\\\\\\\ PSLQ
6489 ? \p200
6490 ? algdep(2^(1/6)+3^(1/5), 30, -3); \\ failure in 14s.
6491 ? \p250
6492 ? algdep(2^(1/6)+3^(1/5), 30, -3); \\ right in 18s
6493 Proceeding by increments of 5 digits of accuracy, "algdep" with default
6495 flag produces its first correct result at 205 digits, and from then on
6496 a steady stream of correct results. Interestingly enough, our PSLQ also
6497 reliably succeeds from 205 digits on (and is 5 times slower at that
6498 accuracy).
6499 The above example is the testcase studied in a 2000 paper by Borwein
6501 and Lisonek, Applications of integer relation algorithms, Discrete
6502 Math., 217, p. 65--82. The paper conludes in the superiority of the
6503 PSLQ algorithm, which either shows that PARI's implementation of PSLQ
6504 is lacking, or that its LLL is extremely good. The version of PARI
6505 tested there was 1.39, which succeeded reliably from precision 265 on,
6506 in about 60 as much time as the current version.
6507 The library syntax is "algdep0(x,k,flag,prec)", where "k" and "flag"
6509 are "long"s. Also available is \funs{algdep}{x,k,prec} ("flag = 0").
6510 \subsecidx{charpoly}"(A,{v = x},{flag = 0})": characteristic polynomial
6512 of "A" with respect to the variable "v", i.e. determinant of "v*I-A" if
6513 "A" is a square matrix. If "A" is not a square matrix, it returns the
6514 characteristic polynomial of the map ``multiplication by "A"'' if "A"
6515 is a scalar, in particular a polmod. E.g. "charpoly(I) = x^2+1".
6516 The value of "flag" is only significant for matrices.
6518 If "flag = 0", the method used is essentially the same as for computing
6520 the adjoint matrix, i.e. computing the traces of the powers of "A".
6521 If "flag = 1", uses Lagrange interpolation which is almost always
6523 slower.
6524 If "flag = 2", uses the Hessenberg form. This is faster than the
6526 default when the coefficients are intmod a prime or real numbers, but
6527 is usually slower in other base rings.
6528 The library syntax is "charpoly0(A,v,flag)", where "v" is the variable
6530 number. Also available are the functions \funs{caract}{A,v} ("flag =
6531 1"), \funs{carhess}{A,v} ("flag = 2"), and \funs{caradj}{A,v,pt} where,
6532 in this last case, pt is a "GEN*" which, if not equal to "NULL", will
6533 receive the address of the adjoint matrix of "A" (see "matadjoint"), so
6534 both can be obtained at once.
6535 \subsecidx{concat}"(x,{y})": concatenation of "x" and "y". If "x" or
6537 "y" is not a vector or matrix, it is considered as a one-dimensional
6538 vector. All types are allowed for "x" and "y", but the sizes must be
6539 compatible. Note that matrices are concatenated horizontally, i.e. the
6540 number of rows stays the same. Using transpositions, it is easy to
6541 concatenate them vertically.
6542 To concatenate vectors sideways (i.e. to obtain a two-row or two-column
6544 matrix), use "Mat" instead (see the example there). Concatenating a row
6545 vector to a matrix having the same number of columns will add the row
6546 to the matrix (top row if the vector is "x", i.e. comes first, and
6547 bottom row otherwise).
6548 The empty matrix "[;]" is considered to have a number of rows
6550 compatible with any operation, in particular concatenation. (Note that
6551 this is definitely not the case for empty vectors "[ ]" or "[ ]~".)
6552 If "y" is omitted, "x" has to be a row vector or a list, in which case
6554 its elements are concatenated, from left to right, using the above
6555 rules.
6556 ? concat([1,2], [3,4])
6558 %1 = [1, 2, 3, 4]
6559 ? a = [[1,2]~, [3,4]~]; concat(a)
6560 %2 =
6561 [1 3]
6562 [2 4]
6564 ? concat([1,2; 3,4], [5,6]~)
6566 %3 =
6567 [1 2 5]
6568 [3 4 6]
6570 ? concat([%, [7,8]~, [1,2,3,4]])
6571 %5 =
6572 [1 2 5 7]
6573 [3 4 6 8]
6575 [1 2 3 4]
6577 The library syntax is "concat(x,y)".
6579 \subsecidx{lindep}"(x,{flag = 0})":"x" being a vector with "p"-adic or
6581 real/complex coefficients, finds a small integral linear combination
6582 among these coefficients.
6583 If "x" is "p"-adic, "flag" is meaningless and the algorithm LLL-reduces
6585 a suitable (dual) lattice.
6586 Otherwise, the value of "flag" determines the algorithm used; in the
6588 current version of PARI, we suggest to use non-negative values, since
6589 it is by far the fastest and most robust implementation. See the
6590 detailed example in "Label se:algdep" ("algdep").
6591 If "flag >= 0", uses a floating point (variable precision) LLL
6593 algorithm. This is in general much faster than the other variants. If
6594 "flag = 0" the accuracy is chosen internally using a crude heuristic.
6595 If "flag > 0" the computation is done with an accuracy of "flag"
6596 decimal digits. In that case, the parameter "flag" should be between
6597 0.6 and 0.9 times the number of correct decimal digits in the input.
6598 If "flag = -1", uses a variant of the LLL algorithm due to Hastad,
6600 Lagarias and Schnorr (STACS 1986). If the precision is too low, the
6601 routine may enter an infinite loop.
6602 If "flag = -2", "x" is allowed to be (and in any case interpreted as) a
6604 matrix. Returns a non trivial element of the kernel of "x", or 0 if
6605 "x" has trivial kernel. The element is defined over the field of
6606 coefficients of "x", and is in general not integral.
6607 If "flag = -3", uses the PSLQ algorithm. This may return a real number
6609 "B", indicating that the input accuracy was exhausted and that no
6610 relation exist whose sup norm is less than "B".
6611 If "flag = -4", uses an experimental 2-level PSLQ, which does not work
6613 at all. (Should be rewritten.)
6614 The library syntax is "lindep0(x,flag,prec)". Also available is
6616 \funs{lindep}{x,prec} ("flag = 0").
6617 \subsecidx{listcreate}"(n)": creates an empty list of maximal length
6619 "n".
6620 This function is useless in library mode.
6622 \subsecidx{listinsert}"(list,x,n)": inserts the object "x" at position
6624 "n" in list (which must be of type "t_LIST"). All the remaining
6625 elements of list (from position "n+1" onwards) are shifted to the
6626 right. This and "listput" are the only commands which enable you to
6627 increase a list's effective length (as long as it remains under the
6628 maximal length specified at the time of the "listcreate").
6629 This function is useless in library mode.
6631 \subsecidx{listkill}"(list)": kill list. This deletes all elements from
6633 list and sets its effective length to 0. The maximal length is not
6634 affected.
6635 This function is useless in library mode.
6637 \subsecidx{listput}"(list,x,{n})": sets the "n"-th element of the list
6639 list (which must be of type "t_LIST") equal to "x". If "n" is omitted,
6640 or greater than the list current effective length, just appends "x".
6641 This and "listinsert" are the only commands which enable you to
6642 increase a list's effective length (as long as it remains under the
6643 maximal length specified at the time of the "listcreate").
6644 If you want to put an element into an occupied cell, i.e. if you don't
6646 want to change the effective length, you can consider the list as a
6647 vector and use the usual "list[n] = x" construct.
6648 This function is useless in library mode.
6650 \subsecidx{listsort}"(list,{flag = 0})": sorts list (which must be of
6652 type "t_LIST") in place. If "flag" is non-zero, suppresses all repeated
6653 coefficients. This is much faster than the "vecsort" command since no
6654 copy has to be made.
6655 This function is useless in library mode.
6657 \subsecidx{matadjoint}"(x)": adjoint matrix of "x", i.e. the matrix "y"
6659 of cofactors of "x", satisfying "x*y = det (x)* Id ". "x" must be a
6660 (non-necessarily invertible) square matrix.
6661 The library syntax is "adj(x)".
6663 \subsecidx{matcompanion}"(x)": the left companion matrix to the
6665 polynomial "x".
6666 The library syntax is "assmat(x)".
6668 \subsecidx{matdet}"(x,{flag = 0})": determinant of "x". "x" must be a
6670 square matrix.
6671 If "flag = 0", uses Gauss-Bareiss.
6673 If "flag = 1", uses classical Gaussian elimination, which is better
6675 when the entries of the matrix are reals or integers for example, but
6676 usually much worse for more complicated entries like multivariate
6677 polynomials.
6678 The library syntax is "det(x)" ("flag = 0") and \funs{det2}{x} ("flag =
6680 1").
6681 \subsecidx{matdetint}"(x)": "x" being an "m x n" matrix with integer
6683 coefficients, this function computes a multiple of the determinant of
6684 the lattice generated by the columns of "x" if it is of rank "m", and
6685 returns zero otherwise. This function can be useful in conjunction with
6686 the function "mathnfmod" which needs to know such a multiple. To obtain
6687 the exact determinant (assuming the rank is maximal), you can compute
6688 "matdet(mathnfmod(x, matdetint(x)))".
6689 Note that as soon as one of the dimensions gets large ("m" or "n" is
6691 larger than 20, say), it will often be much faster to use "mathnf(x,
6692 1)" or "mathnf(x, 4)" directly.
6693 The library syntax is "detint(x)".
6695 \subsecidx{matdiagonal}"(x)": "x" being a vector, creates the diagonal
6697 matrix whose diagonal entries are those of "x".
6698 The library syntax is "diagonal(x)".
6700 \subsecidx{mateigen}"(x)": gives the eigenvectors of "x" as columns of
6702 a matrix.
6703 The library syntax is "eigen(x)".
6705 \subsecidx{matfrobenius}"(M,{flag = 0},{v = x})": returns the Frobenius
6707 form of the square matrix "M". If "flag = 1", returns only the
6708 elementary divisors as a vectr of polynomials in the variable "v". If
6709 "flag = 2", returns a two-components vector [F,B] where "F" is the
6710 Frobenius form and "B" is the basis change so that "M = B^{-1}FB".
6711 The library syntax is "matfrobenius(M,flag,v)", where "v" is the
6713 variable number.
6714 \subsecidx{mathess}"(x)": Hessenberg form of the square matrix "x".
6716 The library syntax is "hess(x)".
6718 \subsecidx{mathilbert}"(x)": "x" being a "long", creates the Hilbert
6720 matrixof order "x", i.e. the matrix whose coefficient ("i","j") is "1/
6721 (i+j-1)".
6722 The library syntax is "mathilbert(x)".
6724 \subsecidx{mathnf}"(x,{flag = 0})": if "x" is a (not necessarily
6726 square) matrix with integer entries, finds the upper triangular Hermite
6727 normal form of "x". If the rank of "x" is equal to its number of rows,
6728 the result is a square matrix. In general, the columns of the result
6729 form a basis of the lattice spanned by the columns of "x".
6730 If "flag = 0", uses the naive algorithm. This should never be used if
6732 the dimension is at all large (larger than 10, say). It is recommanded
6733 to use either "mathnfmod(x, matdetint(x))" (when "x" has maximal rank)
6734 or "mathnf(x, 1)". Note that the latter is in general faster than
6735 "mathnfmod", and also provides a base change matrix.
6736 If "flag = 1", uses Batut's algorithm, which is much faster than the
6738 default. Outputs a two-component row vector "[H,U]", where "H" is the
6739 upper triangular Hermite normal form of "x" defined as above, and "U"
6740 is the unimodular transformation matrix such that "xU = [0|H]". "U" has
6741 in general huge coefficients, in particular when the kernel is large.
6742 If "flag = 3", uses Batut's algorithm, but outputs "[H,U,P]", such that
6744 "H" and "U" are as before and "P" is a permutation of the rows such
6745 that "P" applied to "xU" gives "H". The matrix "U" is smaller than with
6746 "flag = 1", but may still be large.
6747 If "flag = 4", as in case 1 above, but uses a heuristic variant of LLL
6749 reduction along the way. The matrix "U" is in general close to optimal
6750 (in terms of smallest "L_2" norm), but the reduction is slower than in
6751 case 1.
6752 The library syntax is "mathnf0(x,flag)". Also available are
6754 \funs{hnf}{x} ("flag = 0") and \funs{hnfall}{x} ("flag = 1"). To reduce
6755 huge (say "400 x 400" and more) relation matrices (sparse with small
6756 entries), you can use the pair "hnfspec" / "hnfadd". Since this is
6757 rather technical and the calling interface may change, they are not
6758 documented yet. Look at the code in "basemath/alglin1.c".
6759 \subsecidx{mathnfmod}"(x,d)": if "x" is a (not necessarily square)
6761 matrix of maximal rank with integer entries, and "d" is a multiple of
6762 the (non-zero) determinant of the lattice spanned by the columns of
6763 "x", finds the upper triangular Hermite normal form of "x".
6764 If the rank of "x" is equal to its number of rows, the result is a
6766 square matrix. In general, the columns of the result form a basis of
6767 the lattice spanned by the columns of "x". This is much faster than
6768 "mathnf" when "d" is known.
6769 The library syntax is "hnfmod(x,d)".
6771 \subsecidx{mathnfmodid}"(x,d)": outputs the (upper triangular) Hermite
6773 normal form of "x" concatenated with "d" times the identity matrix.
6774 Assumes that "x" has integer entries.
6775 The library syntax is "hnfmodid(x,d)".
6777 \subsecidx{matid}"(n)": creates the "n x n" identity matrix.
6779 The library syntax is "matid(n)" where "n" is a "long".
6781 Related functions are \funs{gscalmat}{x,n}, which creates "x" times the
6783 identity matrix ("x" being a "GEN" and "n" a "long"), and
6784 \funs{gscalsmat}{x,n} which is the same when "x" is a "long".
6785 \subsecidx{matimage}"(x,{flag = 0})": gives a basis for the image of
6787 the matrix "x" as columns of a matrix. A priori the matrix can have
6788 entries of any type. If "flag = 0", use standard Gauss pivot. If "flag
6789 = 1", use "matsupplement".
6790 The library syntax is "matimage0(x,flag)". Also available is
6792 \funs{image}{x} ("flag = 0").
6793 \subsecidx{matimagecompl}"(x)": gives the vector of the column indices
6795 which are not extracted by the function "matimage". Hence the number of
6796 components of matimagecompl(x) plus the number of columns of
6797 matimage(x) is equal to the number of columns of the matrix "x".
6798 The library syntax is "imagecompl(x)".
6800 \subsecidx{matindexrank}"(x)": "x" being a matrix of rank "r", gives
6802 two vectors "y" and "z" of length "r" giving a list of rows and columns
6803 respectively (starting from 1) such that the extracted matrix obtained
6804 from these two vectors using "vecextract(x,y,z)" is invertible.
6805 The library syntax is "indexrank(x)".
6807 \subsecidx{matintersect}"(x,y)": "x" and "y" being two matrices with
6809 the same number of rows each of whose columns are independent, finds a
6810 basis of the Q-vector space equal to the intersection of the spaces
6811 spanned by the columns of "x" and "y" respectively. See also the
6812 function "idealintersect", which does the same for free Z-modules.
6813 The library syntax is "intersect(x,y)".
6815 \subsecidx{matinverseimage}"(M,y)": gives a column vector belonging to
6817 the inverse image "z" of the column vector or matrix "y" by the matrix
6818 "M" if one exists (i.e such that "Mz = y"), the empty vector otherwise.
6819 To get the complete inverse image, it suffices to add to the result any
6820 element of the kernel of "x" obtained for example by "matker".
6821 The library syntax is "inverseimage(x,y)".
6823 \subsecidx{matisdiagonal}"(x)": returns true (1) if "x" is a diagonal
6825 matrix, false (0) if not.
6826 The library syntax is "isdiagonal(x)", and this returns a "long"
6828 integer.
6829 \subsecidx{matker}"(x,{flag = 0})": gives a basis for the kernel of the
6831 matrix "x" as columns of a matrix. A priori the matrix can have entries
6832 of any type.
6833 If "x" is known to have integral entries, set "flag = 1".
6835 Note:. The library function "FpM_ker(x, p)", where "x" has integer
6837 entries reduced mod p and "p" is prime, is equivalent to, but orders of
6838 magnitude faster than, "matker(x*Mod(1,p))" and needs much less stack
6839 space. To use it under "gp", type "install(FpM_ker, GG)" first.
6840 The library syntax is "matker0(x,flag)". Also available are
6842 \funs{ker}{x} ("flag = 0"), \funs{keri}{x} ("flag = 1").
6843 \subsecidx{matkerint}"(x,{flag = 0})": gives an LLL-reduced Z-basis for
6845 the lattice equal to the kernel of the matrix "x" as columns of the
6846 matrix "x" with integer entries (rational entries are not permitted).
6847 If "flag = 0", uses a modified integer LLL algorithm.
6849 If "flag = 1", uses "matrixqz(x,-2)". If LLL reduction of the final
6851 result is not desired, you can save time using "matrixqz(matker(x),-2)"
6852 instead.
6853 The library syntax is "matkerint0(x,flag)". Also available is
6855 \funs{kerint}{x} ("flag = 0").
6856 \subsecidx{matmuldiagonal}"(x,d)": product of the matrix "x" by the
6858 diagonal matrix whose diagonal entries are those of the vector "d".
6859 Equivalent to, but much faster than "x*matdiagonal(d)".
6860 The library syntax is "matmuldiagonal(x,d)".
6862 \subsecidx{matmultodiagonal}"(x,y)": product of the matrices "x" and
6864 "y" assuming that the result is a diagonal matrix. Much faster than
6865 "x*y" in that case. The result is undefined if "x*y" is not diagonal.
6866 The library syntax is "matmultodiagonal(x,y)".
6868 \subsecidx{matpascal}"(x,{q})": creates as a matrix the lower
6870 triangular Pascal triangle of order "x+1" (i.e. with binomial
6871 coefficients up to "x"). If "q" is given, compute the "q"-Pascal
6872 triangle (i.e. using "q"-binomial coefficients).
6873 The library syntax is "matqpascal(x,q)", where "x" is a "long" and "q =
6875 NULL" is used to omit "q". Also available is \funs{matpascal}{x}.
6876 \subsecidx{matrank}"(x)": rank of the matrix "x".
6878 The library syntax is "rank(x)", and the result is a "long".
6880 \subsecidx{matrix}"(m,n,{X},{Y},{expr = 0})": creation of the "m x n"
6882 matrix whose coefficients are given by the expression expr. There are
6883 two formal parameters in expr, the first one ("X") corresponding to the
6884 rows, the second ("Y") to the columns, and "X" goes from 1 to "m", "Y"
6885 goes from 1 to "n". If one of the last 3 parameters is omitted, fill
6886 the matrix with zeroes.
6887 The library syntax is "matrice(GEN nlig,GEN ncol,entree *e1,entree
6889 *e2,char *expr)".
6890 \subsecidx{matrixqz}"(x,p)": "x" being an "m x n" matrix with "m >= n"
6892 with rational or integer entries, this function has varying behaviour
6893 depending on the sign of "p":
6894 If "p >= 0", "x" is assumed to be of maximal rank. This function
6896 returns a matrix having only integral entries, having the same image as
6897 "x", such that the GCD of all its "n x n" subdeterminants is equal to 1
6898 when "p" is equal to 0, or not divisible by "p" otherwise. Here "p"
6899 must be a prime number (when it is non-zero). However, if the function
6900 is used when "p" has no small prime factors, it will either work or
6901 give the message ``impossible inverse modulo'' and a non-trivial
6902 divisor of "p".
6903 If "p = -1", this function returns a matrix whose columns form a basis
6905 of the lattice equal to "Z^n" intersected with the lattice generated by
6906 the columns of "x".
6907 If "p = -2", returns a matrix whose columns form a basis of the lattice
6909 equal to "Z^n" intersected with the Q-vector space generated by the
6910 columns of "x".
6911 The library syntax is "matrixqz0(x,p)".
6913 \subsecidx{matsize}"(x)": "x" being a vector or matrix, returns a row
6915 vector with two components, the first being the number of rows (1 for a
6916 row vector), the second the number of columns (1 for a column vector).
6917 The library syntax is "matsize(x)".
6919 \subsecidx{matsnf}"(X,{flag = 0})": if "X" is a (singular or non-
6921 singular) matrix outputs the vector of elementary divisors of "X"
6922 (i.e. the diagonal of the Smith normal form of "X").
6923 The binary digits of flag mean:
6925 1 (complete output): if set, outputs "[U,V,D]", where "U" and "V" are
6927 two unimodular matrices such that "UXV" is the diagonal matrix "D".
6928 Otherwise output only the diagonal of "D".
6929 2 (generic input): if set, allows polynomial entries, in which case the
6931 input matrix must be square. Otherwise, assume that "X" has integer
6932 coefficients with arbitrary shape.
6933 4 (cleanup): if set, cleans up the output. This means that elementary
6935 divisors equal to 1 will be deleted, i.e. outputs a shortened vector
6936 "D'" instead of "D". If complete output was required, returns
6937 "[U',V',D']" so that "U'XV' = D'" holds. If this flag is set, "X" is
6938 allowed to be of the form "D" or "[U,V,D]" as would normally be output
6939 with the cleanup flag unset.
6940 The library syntax is "matsnf0(X,flag)". Also available is
6942 \funs{smith}{X} ("flag = 0").
6943 \subsecidx{matsolve}"(x,y)": "x" being an invertible matrix and "y" a
6945 column vector, finds the solution "u" of "x*u = y", using Gaussian
6946 elimination. This has the same effect as, but is a bit faster, than
6947 "x^{-1}*y".
6948 The library syntax is "gauss(x,y)".
6950 \subsecidx{matsolvemod}"(m,d,y,{flag = 0})": "m" being any integral
6952 matrix, "d" a vector of positive integer moduli, and "y" an integral
6953 column vector, gives a small integer solution to the system of
6954 congruences "sum_i m_{i,j}x_j = y_i (mod d_i)" if one exists, otherwise
6955 returns zero. Shorthand notation: "y" (resp. "d") can be given as a
6956 single integer, in which case all the "y_i" (resp. "d_i") above are
6957 taken to be equal to "y" (resp. "d").
6958 ? m = [1,2;3,4];
6960 ? matsolvemod(m, [3,4], [1,2]~)
6961 %2 = [-2, 0]~
6962 ? matsolvemod(m, 3, 1) \\ m X = [1,1]~ over F_3
6963 %3 = [-1, 1]~
6964 If "flag = 1", all solutions are returned in the form of a two-
6966 component row vector "[x,u]", where "x" is a small integer solution to
6967 the system of congruences and "u" is a matrix whose columns give a
6968 basis of the homogeneous system (so that all solutions can be obtained
6969 by adding "x" to any linear combination of columns of "u"). If no
6970 solution exists, returns zero.
6971 The library syntax is "matsolvemod0(m,d,y,flag)". Also available are
6973 \funs{gaussmodulo}{m,d,y} ("flag = 0") and \funs{gaussmodulo2}{m,d,y}
6974 ("flag = 1").
6975 \subsecidx{matsupplement}"(x)": assuming that the columns of the matrix
6977 "x" are linearly independent (if they are not, an error message is
6978 issued), finds a square invertible matrix whose first columns are the
6979 columns of "x", i.e. supplement the columns of "x" to a basis of the
6980 whole space.
6981 The library syntax is "suppl(x)".
6983 \subsecidx{mattranspose}"(x)" or "x~": transpose of "x". This has an
6985 effect only on vectors and matrices.
6986 The library syntax is "gtrans(x)".
6988 \subsecidx{minpoly}"(A,{v = x},{flag = 0})": minimal polynomial of "A"
6990 with respect to the variable "v"., i.e. the monic polynomial "P" of
6991 minimal degree (in the variable "v") such that "P(A) = 0".
6992 The library syntax is "minpoly(A,v)", where "v" is the variable number.
6994 \subsecidx{qfgaussred}"(q)": decomposition into squares of the
6996 quadratic form represented by the symmetric matrix "q". The result is a
6997 matrix whose diagonal entries are the coefficients of the squares, and
6998 the non-diagonal entries represent the bilinear forms. More precisely,
6999 if "(a_{ij})" denotes the output, one has
7000 " q(x) = sum_i a_{ii} (x_i + sum_{j > i} a_{ij} x_j)^2 "
7002 The library syntax is "sqred(x)".
7004 \subsecidx{qfjacobi}"(x)": "x" being a real symmetric matrix, this
7006 gives a vector having two components: the first one is the vector of
7007 eigenvalues of "x", the second is the corresponding orthogonal matrix
7008 of eigenvectors of "x". The method used is Jacobi's method for
7009 symmetric matrices.
7010 The library syntax is "jacobi(x)".
7012 \subsecidx{qflll}"(x,{flag = 0})": LLL algorithm applied to the columns
7014 of the matrix "x". The columns of "x" must be linearly independent,
7015 unless specified otherwise below. The result is a unimodular
7016 transformation matrix "T" such that "x.T" is an LLL-reduced basis of
7017 the lattice generated by the column vectors of "x".
7018 If "flag = 0" (default), the computations are done with floating point
7020 numbers, using Householder matrices for orthogonalization. If "x" has
7021 integral entries, then computations are nonetheless approximate, with
7022 precision varying as needed (Lehmer's trick, as generalized by
7023 Schnorr).
7024 If "flag = 1", it is assumed that "x" is integral. The computation is
7026 done entirely with integers. In this case, "x" needs not be of maximal
7027 rank, but if it is not, "T" will not be square. This is slower and no
7028 more accurate than "flag = 0" above if "x" has small dimension (say 100
7029 or less).
7030 If "flag = 2", "x" should be an integer matrix whose columns are
7032 linearly independent. Returns a partially reduced basis for "x", using
7033 an unpublished algorithm by Peter Montgomery: a basis is said to be
7034 partially reduced if "|v_i +- v_j| >= |v_i|" for any two distinct basis
7035 vectors "v_i, v_j".
7036 This is significantly faster than "flag = 1", esp. when one row is huge
7038 compared to the other rows. Note that the resulting basis is not LLL-
7039 reduced in general.
7040 If "flag = 4", "x" is assumed to have integral entries, but needs not
7042 be of maximal rank. The result is a two-component vector of matrices:
7043 the columns of the first matrix represent a basis of the integer kernel
7044 of "x" (not necessarily LLL-reduced) and the second matrix is the
7045 transformation matrix "T" such that "x.T" is an LLL-reduced Z-basis of
7046 the image of the matrix "x".
7047 If "flag = 5", case as case 4, but "x" may have polynomial
7049 coefficients.
7050 If "flag = 8", same as case 0, but "x" may have polynomial
7052 coefficients.
7053 The library syntax is "qflll0(x,flag,prec)". Also available are
7055 \funs{lll}{x,prec} ("flag = 0"), \funs{lllint}{x} ("flag = 1"), and
7056 \funs{lllkerim}{x} ("flag = 4").
7057 \subsecidx{qflllgram}"(G,{flag = 0})": same as "qflll", except that the
7059 matrix "G = x~ * x" is the Gram matrix of some lattice vectors "x", and
7060 not the coordinates of the vectors themselves. In particular, "G" must
7061 now be a square symmetric real matrix, corresponding to a positive
7062 definite quadratic form. The result is a unimodular transformation
7063 matrix "T" such that "x.T" is an LLL-reduced basis of the lattice
7064 generated by the column vectors of "x".
7065 If "flag = 0" (default): the computations are done with floating point
7067 numbers, using Householder matrices for orthogonalization. If "G" has
7068 integral entries, then computations are nonetheless approximate, with
7069 precision varying as needed (Lehmer's trick, as generalized by
7070 Schnorr).
7071 If "flag = 1": "G" has integer entries, still positive but not
7073 necessarily definite (i.e "x" needs not have maximal rank). The
7074 computations are all done in integers and should be slower than the
7075 default, unless the latter triggers accuracy problems.
7076 "flag = 4": "G" has integer entries, gives the kernel and reduced image
7078 of "x".
7079 "flag = 5": same as case 4, but "G" may have polynomial coefficients.
7081 The library syntax is "qflllgram0(G,flag,prec)". Also available are
7083 \funs{lllgram}{G,prec} ("flag = 0"), \funs{lllgramint}{G} ("flag = 1"),
7084 and \funs{lllgramkerim}{G} ("flag = 4").
7085 \subsecidx{qfminim}"(x,{b},{m},{flag = 0})": "x" being a square and
7087 symmetric matrix representing a positive definite quadratic form, this
7088 function deals with the vectors of "x" whose norm is less than or equal
7089 to "b", enumerated using the Fincke-Pohst algorithm. The function
7090 searches for the minimal non-zero vectors if "b" is omitted. The
7091 precise behaviour depends on "flag".
7092 If "flag = 0" (default), seeks at most "2m" vectors. The result is a
7094 three-component vector, the first component being the number of vectors
7095 found, the second being the maximum norm found, and the last vector is
7096 a matrix whose columns are the vectors found, only one being given for
7097 each pair "+- v" (at most "m" such pairs). The vectors are returned in
7098 no particular order. In this variant, an explicit "m" must be provided.
7099 If "flag = 1", ignores "m" and returns the first vector whose norm is
7101 less than "b". In this variant, an explicit "b" must be provided.
7102 In both these cases, "x" is assumed to have integral entries. The
7104 implementation uses low precision floating point computations for
7105 maximal speed, which gives incorrect result when "x" has large entries.
7106 (The condition is checked in the code and the routine will raise an
7107 error if large rounding errors occur.) A more robust, but much slower,
7108 implementation is chosen if the following flag is used:
7109 If "flag = 2", "x" can have non integral real entries. In this case, if
7111 "b" is omitted, the ``minimal'' vectors only have approximately the
7112 same norm. If "b" is omitted, "m" is an upper bound for the number of
7113 vectors that will be stored and returned, but all minimal vectors are
7114 nevertheless enumerated. If "m" is omitted, all vectors found are
7115 stored and returned; note that this may be a huge vector!
7116 The library syntax is "qfminim0(x,b,m,flag,prec)", also available are
7118 \funs{minim}{x,b,m} ("flag = 0"), \funs{minim2}{x,b,m} ("flag = 1"). In
7119 all cases, an omitted "b" or "m" is coded as "NULL".
7120 \subsecidx{qfperfection}"(x)": "x" being a square and symmetric matrix
7122 with integer entries representing a positive definite quadratic form,
7123 outputs the perfection rank of the form. That is, gives the rank of the
7124 family of the "s" symmetric matrices "v_iv_i^t", where "s" is half the
7125 number of minimal vectors and the "v_i" ("1 <= i <= s") are the minimal
7126 vectors.
7127 As a side note to old-timers, this used to fail bluntly when "x" had
7129 more than 5000 minimal vectors. Beware that the computations can now be
7130 very lengthy when "x" has many minimal vectors.
7131 The library syntax is "perf(x)".
7133 \subsecidx{qfrep}"(q, B, {flag = 0})": "q" being a square and symmetric
7135 matrix with integer entries representing a positive definite quadratic
7136 form, outputs the vector whose "i"-th entry, "1 <= i <= B" is half the
7137 number of vectors "v" such that "q(v) = i". This routine uses a naive
7138 algorithm based on "qfminim", and will fail if any entry becomes larger
7139 than "2^{31}".
7140 The binary digits of flag mean:
7142 * 1: count vectors of even norm from 1 to "2B".
7144 * 2: return a "t_VECSMALL" instead of a "t_GEN"
7146 The library syntax is "qfrep0(q, B, flag)".
7148 \subsecidx{qfsign}"(x)": signature of the quadratic form represented by
7150 the symmetric matrix "x". The result is a two-component vector.
7151 The library syntax is "signat(x)".
7153 \subsecidx{setintersect}"(x,y)": intersection of the two sets "x" and
7155 "y".
7156 The library syntax is "setintersect(x,y)".
7158 \subsecidx{setisset}"(x)": returns true (1) if "x" is a set, false (0)
7160 if not. In PARI, a set is simply a row vector whose entries are
7161 strictly increasing. To convert any vector (and other objects) into a
7162 set, use the function "Set".
7163 The library syntax is "setisset(x)", and this returns a "long".
7165 \subsecidx{setminus}"(x,y)": difference of the two sets "x" and "y",
7167 i.e. set of elements of "x" which do not belong to "y".
7168 The library syntax is "setminus(x,y)".
7170 \subsecidx{setsearch}"(x,y,{flag = 0})": searches if "y" belongs to the
7172 set "x". If it does and "flag" is zero or omitted, returns the index
7173 "j" such that "x[j] = y", otherwise returns 0. If "flag" is non-zero
7174 returns the index "j" where "y" should be inserted, and 0 if it already
7175 belongs to "x" (this is meant to be used in conjunction with
7176 "listinsert").
7177 This function works also if "x" is a sorted list (see "listsort").
7179 The library syntax is "setsearch(x,y,flag)" which returns a "long"
7181 integer.
7182 \subsecidx{setunion}"(x,y)": union of the two sets "x" and "y".
7184 The library syntax is "setunion(x,y)".
7186 \subsecidx{trace}"(x)": this applies to quite general "x". If "x" is
7188 not a matrix, it is equal to the sum of "x" and its conjugate, except
7189 for polmods where it is the trace as an algebraic number.
7190 For "x" a square matrix, it is the ordinary trace. If "x" is a non-
7192 square matrix (but not a vector), an error occurs.
7193 The library syntax is "gtrace(x)".
7195 \subsecidx{vecextract}"(x,y,{z})": extraction of components of the
7197 vector or matrix "x" according to "y". In case "x" is a matrix, its
7198 components are as usual the columns of "x". The parameter "y" is a
7199 component specifier, which is either an integer, a string describing a
7200 range, or a vector.
7201 If "y" is an integer, it is considered as a mask: the binary bits of
7203 "y" are read from right to left, but correspond to taking the
7204 components from left to right. For example, if "y = 13 = (1101)_2" then
7205 the components 1,3 and 4 are extracted.
7206 If "y" is a vector, which must have integer entries, these entries
7208 correspond to the component numbers to be extracted, in the order
7209 specified.
7210 If "y" is a string, it can be
7212 * a single (non-zero) index giving a component number (a negative index
7214 means we start counting from the end).
7215 * a range of the form "a..b", where "a" and "b" are indexes as above.
7217 Any of "a" and "b" can be omitted; in this case, we take as default
7218 values "a = 1" and "b = -1", i.e. the first and last components
7219 respectively. We then extract all components in the interval "[a,b]",
7220 in reverse order if "b < a".
7221 In addition, if the first character in the string is "^", the
7223 complement of the given set of indices is taken.
7224 If "z" is not omitted, "x" must be a matrix. "y" is then the line
7226 specifier, and "z" the column specifier, where the component specifier
7227 is as explained above.
7228 %4 = [e, d, c]
7230 ? vecextract(v, "^2") \\ mask
7231 %4 = [e, d, c]
7232 ? vecextract(v, "^2") \\ component list
7233 %4 = [e, d, c]
7234 ? vecextract(v, "^2") \\ interval
7235 %4 = [e, d, c]
7236 ? vecextract(v, "^2") \\ interval + reverse order
7237 %4 = [e, d, c]
7238 ? vecextract(v, "^2") \\ complement
7239 %5 = [a, c, d, e]
7240 ? vecextract(matid(3), "2..", "..")
7241 %6 =
7242 [0 1 0]
7243 [0 0 1]
7245 The library syntax is "extract(x,y)" or \funs{matextract}{x,y,z}.
7247 \subsecidx{vecsort}"(x,{k},{flag = 0})": sorts the vector "x" in
7249 ascending order, using a mergesort method. "x" must be a vector, and
7250 its components integers, reals, or fractions.
7251 If "k" is present and is an integer, sorts according to the value of
7253 the "k"-th subcomponents of the components of "x". Note that mergesort
7254 is stable, hence is the initial ordering of "equal" entries (with
7255 respect to the sorting criterion) is not changed.
7256 "k" can also be a vector, in which case the sorting is done
7258 lexicographically according to the components listed in the vector "k".
7259 For example, if "k = [2,1,3]", sorting will be done with respect to the
7260 second component, and when these are equal, with respect to the first,
7261 and when these are equal, with respect to the third.
7262 The binary digits of flag mean:
7264 * 1: indirect sorting of the vector "x", i.e. if "x" is an
7266 "n"-component vector, returns a permutation of "[1,2,...,n]" which
7267 applied to the components of "x" sorts "x" in increasing order. For
7268 example, "vecextract(x, vecsort(x,,1))" is equivalent to vecsort(x).
7269 * 2: sorts "x" by ascending lexicographic order (as per the "lex"
7271 comparison function).
7272 * 4: use descending instead of ascending order.
7274 The library syntax is "vecsort0(x,k,flag)". To omit "k", use "NULL"
7276 instead. You can also use the simpler functions
7277 \funs{sort}{x} ( = \funs{vecsort0}{x,"NULL",0}).
7279 \funs{indexsort}{x} ( = \funs{vecsort0}{x,"NULL",1}).
7281 \funs{lexsort}{x} ( = \funs{vecsort0}{x,"NULL",2}).
7283 Also available are \funs{sindexsort}{x} and \funs{sindexlexsort}{x}
7285 which return a "t_VECSMALL" "v", where "v[1]...v[n]" contain the
7286 indices.
7287 \subsecidx{vector}"(n,{X},{expr = 0})": creates a row vector (type
7289 "t_VEC") with "n" components whose components are the expression expr
7290 evaluated at the integer points between 1 and "n". If one of the last
7291 two arguments is omitted, fill the vector with zeroes.
7292 Avoid modifying "X" within expr; if you do, the formal variable still
7294 runs from 1 to "n". In particular, "vector(n,i,expr)" is not equivalent
7295 to
7296 v = vector(n)
7298 for (i = 1, n, v[i] = expr)
7299 as the following example shows:
7301 n = 3
7303 v = vector(n); vector(n, i, i++) ----> [2, 3, 4]
7304 v = vector(n); for (i = 1, n, v[i] = i++) ----> [2, 0, 4]
7305 The library syntax is "vecteur(GEN nmax, entree *ep, char *expr)".
7307 \subsecidx{vectorsmall}"(n,{X},{expr = 0})": creates a row vector of
7309 small integers (type "t_VECSMALL") with "n" components whose components
7310 are the expression expr evaluated at the integer points between 1 and
7311 "n". If one of the last two arguments is omitted, fill the vector with
7312 zeroes.
7313 The library syntax is "vecteursmall(GEN nmax, entree *ep, char *expr)".
7315 \subsecidx{vectorv}"(n,X,expr)": as "vector", but returns a column
7317 vector (type "t_COL").
7318 The library syntax is "vvecteur(GEN nmax, entree *ep, char *expr)".
7320
7322 Although the "gp" calculator is programmable, it is useful to have
7323 preprogrammed a number of loops, including sums, products, and a
7324 certain number of recursions. Also, a number of functions from
7325 numerical analysis like numerical integration and summation of series
7326 will be described here.
7327 One of the parameters in these loops must be the control variable,
7329 hence a simple variable name. In the descriptions, the letter "X" will
7330 always denote any simple variable name, and represents the formal
7331 parameter used in the function. The expression to be summed,
7332 integrated, etc. is any legal PARI expression, including of course
7333 expressions using loops.
7334 Library mode.. Since it is easier to program directly the loops in
7336 library mode, these functions are mainly useful for GP programming.
7337 Using them in library mode is tricky and we will not give any details,
7338 although the reader can try and figure it out by himself by checking
7339 the example given for "sum".
7340 On the other hand, numerical routines code a function (to be
7342 integrated, summed, etc.) with two parameters named
7343 GEN (*eval)(GEN,void*)
7345 void *E;
7346 The second is meant to contain all auxilliary data needed by your
7348 function. The first is such that "eval(x, E)" returns your function
7349 evaluated at "x". For instance, one may code the family of functions
7350 "f_t: x \to (x+t)^2" via
7351 GEN f(GEN x, void *t) { return gsqr(gadd(x, (GEN)t)); }
7353 One can then integrate "f_1" between "a" and "b" with the call
7355 intnum((void*)stoi(1), &fun, a, b, NULL, prec);
7357 Since you can set "E" to a pointer to any "struct" (typecast to
7359 "void*") the above mechanism handles arbitrary functions. For simple
7360 functions without extra parameters, you may set "E = NULL" and ignore
7361 that argument in your function definition.
7362 Numerical integration.. Starting with version 2.2.9 the powerful
7364 ``double exponential'' univariate integration method is implemented in
7365 "intnum" and its variants. Romberg integration is still available under
7366 the name "intnumromb", but superseded. It is possible to compute
7367 numerically integrals to thousands of decimal places in reasonable
7368 time, as long as the integrand is regular. It is also reasonable to
7369 compute numerically integrals in several variables, although more than
7370 two becomes lengthy. The integration domain may be non-compact, and the
7371 integrand may have reasonable singularities at endpoints. To use
7372 "intnum", the user must split the integral into a sum of subintegrals
7373 where the function has (possible) singularities only at the endpoints.
7374 Polynomials in logarithms are not considered singular, and neglecting
7375 these logs, singularities are assumed to be algebraic (in other words
7376 asymptotic to "C(x-a)^{-alpha}" for some "alpha" such that "alpha > -1"
7377 when "x" is close to "a"), or to correspond to simple discontinuities
7378 of some (higher) derivative of the function. For instance, the point 0
7379 is a singularity of abs(x).
7380 See also the discrete summation methods below (sharing the prefix
7382 "sum").
7383 \subsecidx{intcirc}"(X = a,R,expr, {tab})": numerical integration of
7385 expr with respect to "X" on the circle "|X-a |= R", divided by "2ipi".
7386 In other words, when expr is a meromorphic function, sum of the
7387 residues in the corresponding disk. tab is as in "intnum", except that
7388 if computed with "intnuminit" it should be with the endpoints "[-1,
7389 1]".
7390 ? \p105
7392 ? intcirc(s=1, 0.5, zeta(s)) - 1
7393 time = 3,460 ms.
7394 %1 = -2.40... E-104 - 2.7... E-106*I
7395 The library syntax is "intcirc(void *E, GEN (*eval)(GEN,void*), GEN
7397 a,GEN R,GEN tab, long prec)".
7398 \subsecidx{intfouriercos}"(X = a,b,z,expr,{tab})": numerical
7400 integration of "expr(X) cos (2pi zX)" from "a" to "b", in other words
7401 Fourier cosine transform (from "a" to "b") of the function represented
7402 by expr. "a" and "b" are coded as in "intnum", and are not necessarily
7403 at infinity, but if they are, oscillations (i.e. "[[+-1],alpha I]") are
7404 forbidden.
7405 The library syntax is "intfouriercos(void *E, GEN (*eval)(GEN,void*),
7407 GEN a, GEN b, GEN z, GEN tab, long prec)".
7408 \subsecidx{intfourierexp}"(X = a,b,z,expr,{tab})": numerical
7410 integration of "expr(X) exp (-2pi zX)" from "a" to "b", in other words
7411 Fourier transform (from "a" to "b") of the function represented by
7412 expr. Note the minus sign. "a" and "b" are coded as in "intnum", and
7413 are not necessarily at infinity but if they are, oscillations (i.e.
7414 "[[+-1],alpha I]") are forbidden.
7415 The library syntax is "intfourierexp(void *E, GEN (*eval)(GEN,void*),
7417 GEN a, GEN b, GEN z, GEN tab, long prec)".
7418 \subsecidx{intfouriersin}"(X = a,b,z,expr,{tab})": numerical
7420 integration of "expr(X) sin (2pi zX)" from "a" to "b", in other words
7421 Fourier sine transform (from "a" to "b") of the function represented by
7422 expr. "a" and "b" are coded as in "intnum", and are not necessarily at
7423 infinity but if they are, oscillations (i.e. "[[+-1],alpha I]") are
7424 forbidden.
7425 The library syntax is "intfouriersin(void *E, GEN (*eval)(GEN,void*),
7427 GEN a, GEN b, GEN z, GEN tab, long prec)".
7428 \subsecidx{intfuncinit}"(X = a,b,expr,{flag = 0},{m = 0})": initalize
7430 tables for use with integral transforms such as "intmellininv", etc.,
7431 where "a" and "b" are coded as in "intnum", "expr" is the function s(X)
7432 to which the integral transform is to be applied (which will multiply
7433 the weights of integration) and "m" is as in "intnuminit". If "flag" is
7434 nonzero, assumes that "s(-X) = \overline{s(X)}", which makes the
7435 computation twice as fast. See "intmellininvshort" for examples of the
7436 use of this function, which is particularly useful when the function
7437 s(X) is lengthy to compute, such as a gamma product.
7438 The library syntax is "intfuncinit(void *E, GEN (*eval)(GEN,void*), GEN
7440 a,GEN b,long m, long flag, long prec)". Note that the order of "m" and
7441 "flag" are reversed compared to the "GP" syntax.
7442 \subsecidx{intlaplaceinv}"(X = sig,z,expr,{tab})": numerical
7444 integration of "expr(X)e^{Xz}" with respect to "X" on the line " Re (X)
7445 = sig", divided by "2ipi", in other words, inverse Laplace transform of
7446 the function corresponding to expr at the value "z".
7447 "sig" is coded as follows. Either it is a real number "sigma", equal to
7449 the abcissa of integration, and then the function to be integrated is
7450 assumed to be slowly decreasing when the imaginary part of the variable
7451 tends to "+- oo ". Or it is a two component vector "[sigma,alpha]",
7452 where "sigma" is as before, and either "alpha = 0" for slowly
7453 decreasing functions, or "alpha > 0" for functions decreasing like "
7454 exp (-alpha t)". Note that it is not necessary to choose the exact
7455 value of "alpha". tab is as in "intnum".
7456 It is often a good idea to use this function with a value of "m" one or
7458 two higher than the one chosen by default (which can be viewed thanks
7459 to the function "intnumstep"), or to increase the abcissa of
7460 integration "sigma". For example:
7461 ? intlaplaceinv(x=100, 1, 1/x) - 1
7463 time = 330 ms.
7464 %7 = 1.07... E-72 + 3.2... E-72*I \\ not so good
7465 ? intlaplaceinv(x=100, 1, 1/x) - 1
7466 time = 330 ms.
7467 %7 = 1.07... E-72 + 3.2... E-72*I \\ better
7468 ? intlaplaceinv(x=100, 1, 1/x) - 1
7469 time = 330 ms.
7470 %7 = 1.07... E-72 + 3.2... E-72*I \\ perfect but slow.
7471 ? intlaplaceinv(x=100, 1, 1/x) - 1
7472 time = 330 ms.
7473 %7 = 1.07... E-72 + 3.2... E-72*I \\ better than %1
7474 ? intlaplaceinv(x=100, 1, 1/x) - 1
7475 time = 330 ms.
7476 %7 = 1.07... E-72 + 3.2... E-72*I \\ perfect, fast.
7477 ? intlaplaceinv(x=100, 1, 1/x) - 1
7478 time = 330 ms.
7479 %7 = 1.07... E-72 + 3.2... E-72*I \\ perfect, fastest, but why sig = 10?
7480 ? intlaplaceinv(x=100, 1, 1/x) - 1
7481 time = 330 ms.
7482 %7 = 1.07... E-72 + 3.2... E-72*I \\ too far now...
7483 The library syntax is "intlaplaceinv(void *E, GEN (*eval)(GEN,void*),
7485 GEN sig,GEN z, GEN tab, long prec)".
7486 \subsecidx{intmellininv}"(X = sig,z,expr,{tab})": numerical integration
7488 of "expr(X)z^{-X}" with respect to "X" on the line " Re (X) = sig",
7489 divided by "2ipi", in other words, inverse Mellin transform of the
7490 function corresponding to expr at the value "z".
7491 "sig" is coded as follows. Either it is a real number "sigma", equal to
7493 the abcissa of integration, and then the function to be integrated is
7494 assumed to decrease exponentially fast, of the order of " exp (-t)"
7495 when the imaginary part of the variable tends to "+- oo ". Or it is a
7496 two component vector "[sigma,alpha]", where "sigma" is as before, and
7497 either "alpha = 0" for slowly decreasing functions, or "alpha > 0" for
7498 functions decreasing like " exp (-alpha t)", such as gamma products.
7499 Note that it is not necessary to choose the exact value of "alpha", and
7500 that "alpha = 1" (equivalent to "sig" alone) is usually sufficient. tab
7501 is as in "intnum".
7502 As all similar functions, this function is provided for the convenience
7504 of the user, who could use "intnum" directly. However it is in general
7505 better to use "intmellininvshort".
7506 ? \p 308
7508 ? intmellininv(s=2,4, gamma(s)^3);
7509 time = 51,300 ms. \\ reasonable.
7510 ? \p 308
7511 ? intmellininv(s=2,4, gamma(s)^3);
7512 time = 51,300 ms. \\ slow because of F<Gamma>(s)^3.
7513 The library syntax is "intmellininv(void *E, GEN (*eval)(GEN,void*),
7515 GEN sig, GEN z, GEN tab, long prec)".
7516 \subsecidx{intmellininvshort}"(sig,z,tab)": numerical integration of
7518 "s(X)z^{-X}" with respect to "X" on the line " Re (X) = sig", divided
7519 by "2ipi", in other words, inverse Mellin transform of s(X) at the
7520 value "z". Here s(X) is implicitly contained in tab in "intfuncinit"
7521 format, typically
7522 tab = intfuncinit(T = [-1], [1], s(sig + I*T))
7524 or similar commands. Take the example of the inverse Mellin transform
7526 of "Gamma(s)^3" given in "intmellininv":
7527 ? tab2 = intfuncinit(t=-oo, oo, gamma(2+I*t)^3, 1);
7529 ? intmellininvshort(2,4, tab2)
7530 %6 = -1.2...E-42 - 3.2...E-109*I \\ for clarity
7531 ? tab2 = intfuncinit(t=-oo, oo, gamma(2+I*t)^3, 1);
7532 ? intmellininvshort(2,4, tab2)
7533 %6 = -1.2...E-42 - 3.2...E-109*I \\ not too fast because of F<Gamma>(s)^3.
7534 ? tab2 = intfuncinit(t=-oo, oo, gamma(2+I*t)^3, 1);
7535 ? intmellininvshort(2,4, tab2)
7536 %6 = -1.2...E-42 - 3.2...E-109*I \\ function of real type, decreasing as F<exp> (-3F<pi>/2.|t|)
7537 ? tab2 = intfuncinit(t=-oo, oo, gamma(2+I*t)^3, 1);
7538 ? intmellininvshort(2,4, tab2)
7539 %6 = -1.2...E-42 - 3.2...E-109*I \\ 50 times faster than C<A> and perfect.
7540 ? tab2 = intfuncinit(t=-oo, oo, gamma(2+I*t)^3, 1);
7541 ? intmellininvshort(2,4, tab2)
7542 %6 = -1.2...E-42 - 3.2...E-109*I \\ 63 digits lost
7543 In the computation of tab, it was not essential to include the exact
7545 exponential decrease of "Gamma(2+it)^3". But as the last example shows,
7546 a rough indication must be given, otherwise slow decrease is assumed,
7547 resulting in catastrophic loss of accuracy.
7548 The library syntax is "intmellininvshort(GEN sig, GEN z, GEN tab, long
7550 prec)".
7551 \subsecidx{intnum}"(X = a,b,expr,{tab})": numerical integration of expr
7553 on "[a,b]" (possibly infinite interval) with respect to "X", where "a"
7554 and "b" are coded as explained below. The integrand may have values
7555 belonging to a vector space over the real numbers; in particular, it
7556 can be complex-valued or vector-valued.
7557 If tab is omitted, necessary integration tables are computed using
7559 "intnuminit" according to the current precision. It may be a positive
7560 integer "m", and tables are computed assuming the integration step is
7561 "1/2^m". Finally tab can be a table output by "intnuminit", in which
7562 case it is used directly. This is important if several integrations of
7563 the same type are performed (on the same kind of interval and
7564 functions, and the same accuracy), since it saves expensive
7565 precomputations.
7566 If tab is omitted the algorithm guesses a reasonable value for "m"
7568 depending on the current precision. That value may be obtained as
7569 intnumstep()
7571 However this value may be off from the optimal one, and this is
7573 important since the integration time is roughly proportional to "2^m".
7574 One may try consecutive values of "m" until they give the same value up
7575 to an accepted error.
7576 The endpoints "a" and "b" are coded as follows. If "a" is not at "+- oo
7578 ", it is either coded as a scalar (real or complex), or as a two
7579 component vector "[a,alpha]", where the function is assumed to have a
7580 singularity of the form "(x-a)^{alpha+epsilon}" at "a", where "epsilon"
7581 indicates that powers of logarithms are neglected. In particular,
7582 "[a,alpha]" with "alpha >= 0" is equivalent to "a". If a wrong
7583 singularity exponent is used, the result will lose a catastrophic
7584 number of decimals, for instance approximately half the number of
7585 digits will be correct if "alpha = -1/2" is omitted.
7586 The endpoints of integration can be "+- oo ", which is coded as "[+-
7588 1]" or as "[[+-1],alpha]". Here "alpha" codes the behaviour of the
7589 function at "+- oo " as follows.
7590 * "alpha = 0" (or no "alpha" at all, i.e. simply "[+-1]") assumes that
7592 the function to be integrated tends to zero, but not exponentially
7593 fast, and not oscillating such as " sin (x)/x".
7594 * "alpha > 0" assumes that the function tends to zero exponentially
7596 fast approximately as " exp (-alpha x)", including reasonably
7597 oscillating functions such as " exp (-x) sin (x)". The precise choice
7598 of "alpha", while useful in extreme cases, is not critical, and may be
7599 off by a factor of 10 or more from the correct value.
7600 * "alpha < -1" assumes that the function tends to 0 slowly, like
7602 "x^{alpha}". Here it is essential to give the correct "alpha", if
7603 possible, but on the other hand "alpha <= -2" is equivalent to "alpha =
7604 0", in other words to no "alpha" at all.
7605 The last two codes are reserved for oscillating functions. Let "k > 0"
7607 real, and g(x) a nonoscillating function tending to 0, then
7608 * "alpha = k I" assumes that the function behaves like " cos (kx)g(x)".
7610 * "alpha = -kI" assumes that the function behaves like " sin (kx)g(x)".
7612 Here it is critical to give the exact value of "k". If the oscillating
7614 part is not a pure sine or cosine, one must expand it into a Fourier
7615 series, use the above codings, and sum the resulting contributions.
7616 Otherwise you will get nonsense. Note that " cos (kx)" (and similarly "
7617 sin (kx)") means that very function, and not a translated version such
7618 as " cos (kx+a)".
7619 If for instance "f(x) = cos (kx)g(x)" where g(x) tends to zero
7621 exponentially fast as " exp (-alpha x)", it is up to the user to choose
7622 between "[[+-1],alpha]" and "[[+-1],kI]", but a good rule of thumb is
7623 that if the oscillations are much weaker than the exponential decrease,
7624 choose "[[+-1],alpha]", otherwise choose "[[+-1],kI]", although the
7625 latter can reasonably be used in all cases, while the former cannot. To
7626 take a specific example, in the inverse Mellin transform, the function
7627 to be integrated is almost always exponentially decreasing times
7628 oscillating. If we choose the oscillating type of integral we perhaps
7629 obtain the best results, at the expense of having to recompute our
7630 functions for a different value of the variable "z" giving the
7631 transform, preventing us to use a function such as "intmellininvshort".
7632 On the other hand using the exponential type of integral, we obtain
7633 less accurate results, but we skip expensive recomputations. See
7634 "intmellininvshort" and "intfuncinit" for more explanations.
7635 \misctitle{Note.} If you do not like the code "[+-1]" for "+- oo ", you
7637 are welcome to set, e.g "oo = [1]" or "INFINITY = [1]", then using
7638 "+oo", "-oo", "-INFINITY", etc. will have the expected behaviour.
7639 We shall now see many examples to get a feeling for what the various
7641 parameters achieve. All examples below assume precision is set to 105
7642 decimal digits. We first type
7643 ? \p 105
7645 ? oo = [1] \\ for clarity
7646 Apparent singularities.. Even if the function f(x) represented by expr
7648 has no singularities, it may be important to define the function
7649 differently near special points. For instance, if "f(x) = 1 /( exp
7650 (x)-1) - exp (-x)/x", then "int_0^ oo f(x)dx = gamma", Euler's
7651 constant "Euler". But
7652 ? f(x) = 1/(exp(x)-1) - exp(-x)/x
7654 ? intnum(x = 0, [oo,1], f(x)) - Euler
7655 %1 = 6.00... E-67
7656 thus only correct to 76 decimal digits. This is because close to 0 the
7658 function "f" is computed with an enormous loss of accuracy. A better
7659 solution is
7660 ? intnum(x = 0, [oo,1], g(x)) - Euler
7662 %2 = 0.E-106 \\ expansion around t = 0
7663 ? intnum(x = 0, [oo,1], g(x)) - Euler
7664 %2 = 0.E-106 \\ note that 6.18 > 105
7665 ? intnum(x = 0, [oo,1], g(x)) - Euler
7666 %2 = 0.E-106 \\ perfect
7667 It is up to the user to determine constants such as the "10^{-18}" and
7669 7 used above.
7670 True singularities.. With true singularities the result is much worse.
7672 For instance
7673 ? intnum(x = [0,-1/2], 1, 1/sqrt(x)) - 2
7675 %2 = 0.E-105 \\ only 59 correct decimals
7676 ? intnum(x = [0,-1/2], 1, 1/sqrt(x)) - 2
7678 %2 = 0.E-105 \\ better
7679 Oscillating functions..
7681 ? intnum(x = 0, [oo,-I], sin(x)^3/x) - Pi/4
7683 %6 = 0.0092... \\ nonsense
7684 ? intnum(x = 0, [oo,-I], sin(x)^3/x) - Pi/4
7686 %6 = 0.0092... \\ bad
7687 ? intnum(x = 0, [oo,-I], sin(x)^3/x) - Pi/4
7689 %6 = 0.0092... \\ perfect
7690 ? intnum(x = 0, [oo,-I], sin(x)^3/x) - Pi/4
7692 %6 = 0.0092... \\ oops, wrong k
7693 ? intnum(x = 0, [oo,-I], sin(x)^3/x) - Pi/4
7695 %6 = 0.0092... \\ perfect
7696 ? intnum(x = 0, [oo,-I], sin(x)^3/x) - Pi/4
7698 %6 = 0.0092... \\ bad
7699 ? sin(x)^3 - (3*sin(x)-sin(3*x))/4
7700 %7 = O(x^17)
7701 We may use the above linearization and compute two oscillating
7703 integrals with ``infinite endpoints'' "[oo, -I]" and "[oo, -3*I]"
7704 respectively, or notice the obvious change of variable, and reduce to
7705 the single integral "(1/2)int_0^ oo sin (x)/xdx". We finish with some
7706 more complicated examples:
7707 ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7709 %6 = 5.45... E-107 \\ bad
7710 ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7711 %6 = 5.45... E-107 \\ OK
7712 ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7713 %6 = 5.45... E-107 \\ OK
7714 ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7715 %6 = 5.45... E-107 \\ lost 16 decimals. Try higher m:
7716 ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7717 %6 = 5.45... E-107 \\ the value of m actually used above.
7718 ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7719 %6 = 5.45... E-107 \\ try m one higher.
7720 ? intnum(x = 0, oo, sin(x)^3*exp(-x), tab) - 0.3
7721 %6 = 5.45... E-107 \\ OK this time.
7722 Warning.. Like "sumalt", "intnum" often assigns a reasonable value to
7724 diverging integrals. Use these values at your own risk! For example:
7725 ? intnum(x = 0, [oo, -I], x^2*sin(x))
7727 %1 = -2.0000000000...
7728 Note the formula
7730 " int_0^ oo sin (x)/x^sdx = cos (pi s/2) Gamma(1-s) , "
7732 a priori valid only for "0 < Re (s) < 2", but the right hand side
7734 provides an analytic continuation which may be evaluated at "s = -2"...
7735 Multivariate integration.. Using successive univariate integration
7737 with respect to different formal parameters, it is immediate to do
7738 naive multivariate integration. But it is important to use a suitable
7739 "intnuminit" to precompute data for the internal integrations at least!
7740 For example, to compute the double integral on the unit disc "x^2+y^2
7742 <= 1" of the function "x^2+y^2", we can write
7743 ? tab = intnuminit(-1,1);
7745 ? intnum(x=-1,1, intnum(y=-sqrt(1-x^2),sqrt(1-x^2), x^2+y^2, tab), tab)
7746 The first tab is essential, the second optional. Compare:
7748 ? intnum(x=-1,1, intnum(y=-sqrt(1-x^2),sqrt(1-x^2), x^2+y^2, tab), tab);
7750 time = 7,210 ms. \\ slow
7751 ? intnum(x=-1,1, intnum(y=-sqrt(1-x^2),sqrt(1-x^2), x^2+y^2, tab), tab);
7752 time = 7,210 ms. \\ faster
7753 However, the "intnuminit" program is usually pessimistic when it comes
7755 to choosing the integration step "2^{-m}". It is often possible to
7756 improve the speed by trial and error. Continuing the above example:
7757 ? test(m - 3)
7759 time = 120 ms.
7760 %3 = -7.23... E-60 \\ what value of m did it take ?
7761 ? test(m - 3)
7762 time = 120 ms.
7763 %3 = -7.23... E-60 \\ 4 = 2^2 times faster and still OK.
7764 ? test(m - 3)
7765 time = 120 ms.
7766 %3 = -7.23... E-60 \\ 16 = 2^4 times faster and still OK.
7767 ? test(m - 3)
7768 time = 120 ms.
7769 %3 = -7.23... E-60 \\ 64 = 2^6 times faster, lost 45 decimals.
7770 The library syntax is "intnum(void *E, GEN (*eval)(GEN,void*), GEN
7772 a,GEN b,GEN tab, long prec)", where an omitted tab is coded as "NULL".
7773 \subsecidx{intnuminit}"(a,b,{m = 0})": initialize tables for
7775 integration from "a" to "b", where "a" and "b" are coded as in
7776 "intnum". Only the compactness, the possible existence of
7777 singularities, the speed of decrease or the oscillations at infinity
7778 are taken into account, and not the values. For instance
7779 "intnuminit(-1,1)" is equivalent to "intnuminit(0,Pi)", and
7780 "intnuminit([0,-1/2],[1])" is equivalent to "
7781 intnuminit([-1],[-1,-1/2])". If "m" is not given, it is computed
7782 according to the current precision. Otherwise the integration step is
7783 "1/2^m". Reasonable values of "m" are "m = 6" or "m = 7" for 100
7784 decimal digits, and "m = 9" for 1000 decimal digits.
7785 The result is technical, but in some cases it is useful to know the
7787 output. Let "x = phi(t)" be the change of variable which is used.
7788 tab[1] contains the integer "m" as above, either given by the user or
7789 computed from the default precision, and can be recomputed directly
7790 using the function "intnumstep". tab[2] and tab[3] contain
7791 respectively the abcissa and weight corresponding to "t = 0" ("phi(0)"
7792 and "phi'(0)"). tab[4] and tab[5] contain the abcissas and weights
7793 corresponding to positive "t = nh" for "1 <= n <= N" and "h = 1/2^m"
7794 ("phi(nh)" and "phi'(nh)"). Finally tab[6] and tab[7] contain either
7795 the abcissas and weights corresponding to negative "t = nh" for "-N <=
7796 n <= -1", or may be empty (but not always) if "phi(t)" is an odd
7797 function (implicitly we would have "tab[6] = -tab[4]" and "tab[7] =
7798 tab[5]").
7799 The library syntax is "intnuminit(GEN a, GEN b, long m, long prec)".
7801 \subsecidx{intnumromb}"(X = a,b,expr,{flag = 0})": numerical
7803 integration of expr (smooth in "]a,b["), with respect to "X". This
7804 function is deprecated, use "intnum" instead.
7805 Set "flag = 0" (or omit it altogether) when "a" and "b" are not too
7807 large, the function is smooth, and can be evaluated exactly everywhere
7808 on the interval "[a,b]".
7809 If "flag = 1", uses a general driver routine for doing numerical
7811 integration, making no particular assumption (slow).
7812 "flag = 2" is tailored for being used when "a" or "b" are infinite. One
7814 must have "ab > 0", and in fact if for example "b = + oo ", then it is
7815 preferable to have "a" as large as possible, at least "a >= 1".
7816 If "flag = 3", the function is allowed to be undefined (but continuous)
7818 at "a" or "b", for example the function " sin (x)/x" at "x = 0".
7819 The user should not require too much accuracy: 18 or 28 decimal digits
7821 is OK, but not much more. In addition, analytical cleanup of the
7822 integral must have been done: there must be no singularities in the
7823 interval or at the boundaries. In practice this can be accomplished
7824 with a simple change of variable. Furthermore, for improper integrals,
7825 where one or both of the limits of integration are plus or minus
7826 infinity, the function must decrease sufficiently rapidly at infinity.
7827 This can often be accomplished through integration by parts. Finally,
7828 the function to be integrated should not be very small (compared to the
7829 current precision) on the entire interval. This can of course be
7830 accomplished by just multiplying by an appropriate constant.
7831 Note that infinity can be represented with essentially no loss of
7833 accuracy by 1e1000. However beware of real underflow when dealing with
7834 rapidly decreasing functions. For example, if one wants to compute the
7835 "int_0^ oo e^{-x^2}dx" to 28 decimal digits, then one should set
7836 infinity equal to 10 for example, and certainly not to 1e1000.
7837 The library syntax is "intnumromb(void *E, GEN (*eval)(GEN,void*), GEN
7839 a, GEN b, long flag, long prec)", where "eval(x, E)" returns the value
7840 of the function at "x". You may store any additional information
7841 required by "eval" in "E", or set it to "NULL".
7842 \subsecidx{intnumstep}"()": give the value of "m" used in all the
7844 "intnum" and "sumnum" programs, hence such that the integration step is
7845 equal to "1/2^m".
7846 The library syntax is "intnumstep(long prec)".
7848 \subsecidx{prod}"(X = a,b,expr,{x = 1})": product of expression expr,
7850 initialized at "x", the formal parameter "X" going from "a" to "b". As
7851 for "sum", the main purpose of the initialization parameter "x" is to
7852 force the type of the operations being performed. For example if it is
7853 set equal to the integer 1, operations will start being done exactly.
7854 If it is set equal to the real 1., they will be done using real numbers
7855 having the default precision. If it is set equal to the power series
7856 "1+O(X^k)" for a certain "k", they will be done using power series of
7857 precision at most "k". These are the three most common
7858 initializations.
7859 As an extreme example, compare
7861 ? prod(i=1, 100, 1 - X^i); \\ this has degree 5050 !!
7863 time = 3,335 ms.
7864 ? prod(i=1, 100, 1 - X^i, 1 + O(X^101))
7865 time = 43 ms.
7866 %2 = 1 - X - X^2 + X^5 + X^7 - X^12 - X^15 + X^22 + X^26 - X^35 - X^40 + \
7867 X^51 + X^57 - X^70 - X^77 + X^92 + X^100 + O(X^101)
7868 The library syntax is "produit(entree *ep, GEN a, GEN b, char *expr,
7870 GEN x)".
7871 \subsecidx{prodeuler}"(X = a,b,expr)": product of expression expr,
7873 initialized at 1. (i.e. to a real number equal to 1 to the current
7874 "realprecision"), the formal parameter "X" ranging over the prime
7875 numbers between "a" and "b".
7876 The library syntax is "prodeuler(void *E, GEN (*eval)(GEN,void*), GEN
7878 a,GEN b, long prec)".
7879 \subsecidx{prodinf}"(X = a,expr,{flag = 0})": infinite product of
7881 expression expr, the formal parameter "X" starting at "a". The
7882 evaluation stops when the relative error of the expression minus 1 is
7883 less than the default precision. The expressions must always evaluate
7884 to an element of C.
7885 If "flag = 1", do the product of the ("1+expr") instead.
7887 The library syntax is "prodinf(void *E, GEN (*eval)(GEN, void*), GEN a,
7889 long prec)" ("flag = 0"), or prodinf1 with the same arguments ("flag =
7890 1").
7891 \subsecidx{solve}"(X = a,b,expr)": find a real root of expression expr
7893 between "a" and "b", under the condition "expr(X = a) * expr(X = b) <=
7894 0". This routine uses Brent's method and can fail miserably if expr is
7895 not defined in the whole of "[a,b]" (try "solve(x = 1, 2, tan(x)").
7896 The library syntax is "zbrent(void *E,GEN (*eval)(GEN,void*),GEN a,GEN
7898 b,long prec)".
7899 \subsecidx{sum}"(X = a,b,expr,{x = 0})": sum of expression expr,
7901 initialized at "x", the formal parameter going from "a" to "b". As for
7902 "prod", the initialization parameter "x" may be given to force the type
7903 of the operations being performed.
7904 As an extreme example, compare
7906 ? sum(i=1, 5000, 1/i); \\ rational number: denominator has 2166 digits.
7908 time = 1,241 ms.
7909 ? sum(i=1, 5000, 1/i, 0.)
7910 time = 158 ms.
7911 %2 = 9.094508852984436967261245533
7912 The library syntax is "somme(entree *ep, GEN a, GEN b, char *expr, GEN
7914 x)". This is to be used as follows: "ep" represents the dummy variable
7915 used in the expression "expr"
7916 /* compute a^2 + ... + b^2 */
7918 {
7919 /* define the dummy variable "i" */
7920 entree *ep = is_entry("i");
7921 /* sum for a <= i <= b */
7922 return somme(ep, a, b, "i^2", gen_0);
7923 }
7924 \subsecidx{sumalt}"(X = a,expr,{flag = 0})": numerical summation of the
7926 series expr, which should be an alternating series, the formal variable
7927 "X" starting at "a". Use an algorithm of F. Villegas as modified by
7928 D. Zagier (improves on Euler-Van Wijngaarden method).
7929 If "flag = 1", use a variant with slightly different polynomials.
7931 Sometimes faster.
7932 Divergent alternating series can sometimes be summed by this method, as
7934 well as series which are not exactly alternating (see for example
7935 "Label se:user_defined"). If the series already converges
7936 geometrically, "suminf" is often a better choice:
7937 ? \p28
7939 ? sumalt(i = 1, -(-1)^i / i) - log(2)
7940 time = 0 ms.
7941 %1 = -2.524354897 E-29
7942 ? suminf(i = 1, -(-1)^i / i)
7943 *** suminf: user interrupt after 10min, 20,100 ms.
7944 ? \p1000
7945 ? sumalt(i = 1, -(-1)^i / i) - log(2)
7946 time = 90 ms.
7947 %2 = 4.459597722 E-1002
7948 ? sumalt(i = 0, (-1)^i / i!) - exp(-1)
7950 time = 670 ms.
7951 %3 = -4.03698781490633483156497361352190615794353338591897830587 E-944
7952 ? suminf(i = 0, (-1)^i / i!) - exp(-1)
7953 time = 110 ms.
7954 %4 = -8.39147638 E-1000 \\ faster and more accurate
7955 The library syntax is "sumalt(void *E, GEN (*eval)(GEN,void*),GEN
7957 a,long prec)". Also available is "sumalt2" with the same arguments
7958 ("flag = 1").
7959 \subsecidx{sumdiv}"(n,X,expr)": sum of expression expr over the
7961 positive divisors of "n".
7962 Arithmetic functions like "sigma" use the multiplicativity of the
7964 underlying expression to speed up the computation. In the present
7965 version /usr/share/libpari23, there is no way to indicate that expr is
7966 multiplicative in "n", hence specialized functions should be preferred
7967 whenever possible.
7968 The library syntax is "divsum(entree *ep, GEN num, char *expr)".
7970 \subsecidx{suminf}"(X = a,expr)": infinite sum of expression expr, the
7972 formal parameter "X" starting at "a". The evaluation stops when the
7973 relative error of the expression is less than the default precision for
7974 3 consecutive evaluations. The expressions must always evaluate to a
7975 complex number.
7976 If the series converges slowly, make sure "realprecision" is low (even
7978 28 digits may be too much). In this case, if the series is alternating
7979 or the terms have a constant sign, "sumalt" and "sumpos" should be used
7980 instead.
7981 ? \p28
7983 ? suminf(i = 1, -(-1)^i / i)
7984 *** suminf: user interrupt after 10min, 20,100 ms.
7985 ? sumalt(i = 1, -(-1)^i / i) - log(2)
7986 time = 0 ms.
7987 %1 = -2.524354897 E-29
7988 The library syntax is "suminf(void *E, GEN (*eval)(GEN,void*), GEN a,
7990 long prec)".
7991 \subsecidx{sumnum}"(X = a,sig,expr,{tab}),{flag = 0}": numerical
7993 summation of expr, the variable "X" taking integer values from ceiling
7994 of "a" to "+ oo ", where expr is assumed to be a holomorphic function
7995 f(X) for " Re (X) >= sigma".
7996 The parameter "sigma\in R" is coded in the argument "sig" as follows:
7998 it is either
7999 * a real number "sigma". Then the function "f" is assumed to decrease
8001 at least as "1/X^2" at infinity, but not exponentially;
8002 * a two-component vector "[sigma,alpha]", where "sigma" is as before,
8004 "alpha < -1". The function "f" is assumed to decrease like "X^{alpha}".
8005 In particular, "alpha <= -2" is equivalent to no "alpha" at all.
8006 * a two-component vector "[sigma,alpha]", where "sigma" is as before,
8008 "alpha > 0". The function "f" is assumed to decrease like " exp (-alpha
8009 X)". In this case it is essential that "alpha" be exactly the rate of
8010 exponential decrease, and it is usually a good idea to increase the
8011 default value of "m" used for the integration step. In practice, if the
8012 function is exponentially decreasing "sumnum" is slower and less
8013 accurate than "sumpos" or "suminf", so should not be used.
8014 The function uses the "intnum" routines and integration on the line "
8016 Re (s) = sigma". The optional argument tab is as in intnum, except it
8017 must be initialized with "sumnuminit" instead of "intnuminit".
8018 When tab is not precomputed, "sumnum" can be slower than "sumpos", when
8020 the latter is applicable. It is in general faster for slowly decreasing
8021 functions.
8022 Finally, if "flag" is nonzero, we assume that the function "f" to be
8024 summed is of real type, i.e. satisfies "\overline{f(z)} =
8025 f(\overline{z})", which speeds up the computation.
8026 ? d - c
8028 time = 0 ms.
8029 %5 = 1.97... E-306 \\ slower but done once and for all.
8030 ? d - c
8031 time = 0 ms.
8032 %5 = 1.97... E-306 \\ 3 times as fast as C<sumpos>
8033 ? d - c
8034 time = 0 ms.
8035 %5 = 1.97... E-306 \\ perfect.
8036 ? d - c
8037 time = 0 ms.
8038 %5 = 1.97... E-306 \\ function of real type
8039 ? d - c
8040 time = 0 ms.
8041 %5 = 1.97... E-306 \\ twice as fast, no imaginary part.
8042 ? d - c
8043 time = 0 ms.
8044 %5 = 1.97... E-306 \\ fast
8045 ? d - c
8046 time = 0 ms.
8047 %5 = 1.97... E-306 \\ slow.
8048 ? d - c
8049 time = 0 ms.
8050 %5 = 1.97... E-306 \\ perfect.
8051 For slowly decreasing function, we must indicate singularities:
8053 time = 12,210 ms.
8055 ? b - zeta(4/3)
8056 %3 = 1.05... E-300 \\ slow because of the computation of n^{-4/3}.
8057 time = 12,210 ms.
8058 ? b - zeta(4/3)
8059 %3 = 1.05... E-300 \\ lost 200 decimals because of singularity at oo
8060 time = 12,210 ms.
8061 ? b - zeta(4/3)
8062 %3 = 1.05... E-300 \\ of real type
8063 time = 12,210 ms.
8064 ? b - zeta(4/3)
8065 %3 = 1.05... E-300 \\ better
8066 Since the complex values of the function are used, beware of
8068 determination problems. For instance:
8069 ? sumnum(n=1,[2,-3/2], 1/n^(3/2), tab,1) - zeta(3/2)
8071 time = 8,990 ms.
8072 %3 = -1.19... E-305 \\ fast and correct
8073 ? sumnum(n=1,[2,-3/2], 1/n^(3/2), tab,1) - zeta(3/2)
8074 time = 8,990 ms.
8075 %3 = -1.19... E-305 \\ nonsense. However
8076 ? sumnum(n=1,[2,-3/2], 1/n^(3/2), tab,1) - zeta(3/2)
8077 time = 8,990 ms.
8078 %3 = -1.19... E-305 \\ perfect, as 1/(n* F<sqrt> {n}) above but much slower
8079 For exponentially decreasing functions, "sumnum" is given for
8081 completeness, but one of "suminf" or "sumpos" should always be
8082 preferred. If you experiment with such functions and "sumnum" anyway,
8083 indicate the exact rate of decrease and increase "m" by 1 or 2:
8084 ? m = intnumstep()
8086 %4 = 9
8087 ? sumnum(n=1,[2,log(2)], 2^(-n), m+1, 1) - 1
8088 time = 11,770 ms.
8089 %5 = -1.9... E-305 \\ fast and perfect
8090 ? m = intnumstep()
8091 %4 = 9
8092 ? sumnum(n=1,[2,log(2)], 2^(-n), m+1, 1) - 1
8093 time = 11,770 ms.
8094 %5 = -1.9... E-305 \\ also fast and perfect
8095 ? m = intnumstep()
8096 %4 = 9
8097 ? sumnum(n=1,[2,log(2)], 2^(-n), m+1, 1) - 1
8098 time = 11,770 ms.
8099 %5 = -1.9... E-305 \\ nonsense
8100 ? m = intnumstep()
8101 %4 = 9
8102 ? sumnum(n=1,[2,log(2)], 2^(-n), m+1, 1) - 1
8103 time = 11,770 ms.
8104 %5 = -1.9... E-305 \\ of real type
8105 ? m = intnumstep()
8106 %4 = 9
8107 ? sumnum(n=1,[2,log(2)], 2^(-n), m+1, 1) - 1
8108 time = 11,770 ms.
8109 %5 = -1.9... E-305 \\ slow and lost 70 decimals
8110 ? m = intnumstep()
8111 %4 = 9
8112 ? sumnum(n=1,[2,log(2)], 2^(-n), m+1, 1) - 1
8113 time = 11,770 ms.
8114 %5 = -1.9... E-305 \\ now perfect, but slow.
8115 The library syntax is "sumnum(void *E, GEN (*eval)(GEN,void*), GEN
8117 a,GEN sig,GEN tab,long flag, long prec)".
8118 \subsecidx{sumnumalt}"(X = a,sig,expr,{tab},{flag = 0})": numerical
8120 summation of "(-1)^Xexpr(X)", the variable "X" taking integer values
8121 from ceiling of "a" to "+ oo ", where expr is assumed to be a
8122 holomorphic function for " Re (X) >= sig" (or "sig[1]").
8123 Warning.. This function uses the "intnum" routines and is orders of
8125 magnitude slower than "sumalt". It is only given for completeness and
8126 should not be used in practice.
8127 Warning2.. The expression expr must not include the "(-1)^X"
8129 coefficient. Thus "sumalt(n = a,(-1)^nf(n))" is (approximately) equal
8130 to "sumnumalt(n = a,sig,f(n))".
8131 "sig" is coded as in "sumnum". However for slowly decreasing functions
8133 (where "sig" is coded as "[sigma,alpha]" with "alpha < -1"), it is not
8134 really important to indicate "alpha". In fact, as for "sumalt", the
8135 program will often give meaningful results (usually analytic
8136 continuations) even for divergent series. On the other hand the
8137 exponential decrease must be indicated.
8138 tab is as in "intnum", but if used must be initialized with
8140 "sumnuminit". If "flag" is nonzero, assumes that the function "f" to be
8141 summed is of real type, i.e. satisfies "\overline{f(z)} =
8142 f(\overline{z})", and then twice faster when tab is precomputed.
8143 ? a - b
8145 time = 0 ms.
8146 %1 = -1.66... E-308 \\ abcissa F<sigma> = 2, alternating sums.
8147 ? a - b
8148 time = 0 ms.
8149 %1 = -1.66... E-308 \\ slow, but done once and for all.
8150 ? a - b
8151 time = 0 ms.
8152 %1 = -1.66... E-308 \\ similar speed to C<sumnum>
8153 ? a - b
8154 time = 0 ms.
8155 %1 = -1.66... E-308 \\ infinitely faster!
8156 ? a - b
8157 time = 0 ms.
8158 %1 = -1.66... E-308 \\ perfect
8159 The library syntax is "sumnumalt(void *E, GEN (*eval)(GEN,void*), GEN
8161 a, GEN sig, GEN tab, long flag, long prec)".
8162 \subsecidx{sumnuminit}"(sig,{m = 0},{sgn = 1})": initialize tables for
8164 numerical summation using "sumnum" (with "sgn = 1") or "sumnumalt"
8165 (with "sgn = -1"), "sig" is the abcissa of integration coded as in
8166 "sumnum", and "m" is as in "intnuminit".
8167 The library syntax is "sumnuminit(GEN sig, long m, long sgn, long
8169 prec)".
8170 \subsecidx{sumpos}"(X = a,expr,{flag = 0})": numerical summation of the
8172 series expr, which must be a series of terms having the same sign, the
8173 formal variable "X" starting at "a". The algorithm used is Van
8174 Wijngaarden's trick for converting such a series into an alternating
8175 one, and is quite slow. For regular functions, the function "sumnum" is
8176 in general much faster once the initializations have been made using
8177 "sumnuminit".
8178 If "flag = 1", use slightly different polynomials. Sometimes faster.
8180 The library syntax is "sumpos(void *E, GEN (*eval)(GEN,void*),GEN
8182 a,long prec)". Also available is "sumpos2" with the same arguments
8183 ("flag = 1").
8184
8186 Although plotting is not even a side purpose of PARI, a number of
8187 plotting functions are provided. Moreover, a lot of people suggested
8188 ideas or submitted patches for this section of the code. Among these,
8189 special thanks go to Klaus-Peter Nischke who suggested the recursive
8190 plotting and the forking/resizing stuff under X11, and Ilya Zakharevich
8191 who undertook a complete rewrite of the graphic code, so that most of
8192 it is now platform-independent and should be easy to port or expand.
8193 There are three types of graphic functions.
8194 High-level plotting functions
8196 (all the functions starting with "ploth") in which the user has little
8197 to do but explain what type of plot he wants, and whose syntax is
8198 similar to the one used in the preceding section.
8199 Low-level plotting functions
8201 (called rectplot functions, sharing the prefix "plot"), where every
8202 drawing primitive (point, line, box, etc.) is specified by the user.
8203 These low-level functions work as follows. You have at your disposal 16
8204 virtual windows which are filled independently, and can then be
8205 physically ORed on a single window at user-defined positions. These
8206 windows are numbered from 0 to 15, and must be initialized before being
8207 used by the function "plotinit", which specifies the height and width
8208 of the virtual window (called a rectwindow in the sequel). At all
8209 times, a virtual cursor (initialized at "[0,0]") is associated to the
8210 window, and its current value can be obtained using the function
8211 "plotcursor".
8212 A number of primitive graphic objects (called rect objects) can then be
8214 drawn in these windows, using a default color associated to that window
8215 (which can be changed under X11, using the "plotcolor" function, black
8216 otherwise) and only the part of the object which is inside the window
8217 will be drawn, with the exception of polygons and strings which are
8218 drawn entirely. The ones sharing the prefix "plotr" draw relatively to
8219 the current position of the virtual cursor, the others use absolute
8220 coordinates. Those having the prefix "plotrecth" put in the rectwindow
8221 a large batch of rect objects corresponding to the output of the
8222 related "ploth" function.
8223 Finally, the actual physical drawing is done using the function
8225 "plotdraw". The rectwindows are preserved so that further drawings
8226 using the same windows at different positions or different windows can
8227 be done without extra work. To erase a window (and free the
8228 corresponding memory), use the function "plotkill". It is not possible
8229 to partially erase a window. Erase it completely, initialize it again
8230 and then fill it with the graphic objects that you want to keep.
8231 In addition to initializing the window, you may use a scaled window to
8233 avoid unnecessary conversions. For this, use the function "plotscale"
8234 below. As long as this function is not called, the scaling is simply
8235 the number of pixels, the origin being at the upper left and the
8236 "y"-coordinates going downwards.
8237 Note that in the present version /usr/share/libpari23 all plotting
8239 functions (both low and high level) are written for the X11-window
8240 system (hence also for GUI's based on X11 such as Openwindows and
8241 Motif) only, though little code remains which is actually platform-
8242 dependent. It is also possible to compile "gp" with either of the Qt or
8243 FLTK graphical libraries. A Suntools/Sunview, Macintosh, and an
8244 Atari/Gem port were provided for previous versions, but are now
8245 obsolete.
8246 Under X11, the physical window (opened by "plotdraw" or any of the
8248 "ploth*" functions) is completely separated from "gp" (technically, a
8249 "fork" is done, and the non-graphical memory is immediately freed in
8250 the child process), which means you can go on working in the current
8251 "gp" session, without having to kill the window first. Under X11, this
8252 window can be closed, enlarged or reduced using the standard window
8253 manager functions. No zooming procedure is implemented though (yet).
8254 Functions for PostScript output:
8256 in the same way that "printtex" allows you to have a TeX output
8257 corresponding to printed results, the functions starting with "ps"
8258 allow you to have "PostScript" output of the plots. This will not be
8259 absolutely identical with the screen output, but will be sufficiently
8260 close. Note that you can use PostScript output even if you do not have
8261 the plotting routines enabled. The PostScript output is written in a
8262 file whose name is derived from the "psfile" default ("./pari.ps" if
8263 you did not tamper with it). Each time a new PostScript output is asked
8264 for, the PostScript output is appended to that file. Hence you probably
8265 want to remove this file, or change the value of "psfile", in between
8266 plots. On the other hand, in this manner, as many plots as desired can
8267 be kept in a single file.
8268 And library mode ?
8270 None of the graphic functions are available within the PARI library,
8271 you must be under "gp" to use them. The reason for that is that you
8272 really should not use PARI for heavy-duty graphical work, there are
8273 better specialized alternatives around. This whole set of routines was
8274 only meant as a convenient, but simple-minded, visual aid. If you
8275 really insist on using these in your program (we warned you), the
8276 source ("plot*.c") should be readable enough for you to achieve
8277 something.
8278 \subsecidx{plot}"(X = a,b,expr,{Ymin},{Ymax})": crude ASCII plot of the
8280 function represented by expression expr from "a" to "b", with Y ranging
8281 from Ymin to Ymax. If Ymin (resp. Ymax) is not given, the minima (resp.
8282 the maxima) of the computed values of the expression is used instead.
8283 \subsecidx{plotbox}"(w,x2,y2)": let "(x1,y1)" be the current position
8285 of the virtual cursor. Draw in the rectwindow "w" the outline of the
8286 rectangle which is such that the points "(x1,y1)" and "(x2,y2)" are
8287 opposite corners. Only the part of the rectangle which is in "w" is
8288 drawn. The virtual cursor does not move.
8289 \subsecidx{plotclip}"(w)": `clips' the content of rectwindow "w", i.e
8291 remove all parts of the drawing that would not be visible on the
8292 screen. Together with "plotcopy" this function enables you to draw on
8293 a scratchpad before commiting the part you're interested in to the
8294 final picture.
8295 \subsecidx{plotcolor}"(w,c)": set default color to "c" in rectwindow
8297 "w". In present version /usr/share/libpari23, this is only implemented
8298 for the X11 window system, and you only have the following palette to
8299 choose from:
8300 1 = black, 2 = blue, 3 = sienna, 4 = red, 5 = green, 6 = grey, 7 =
8302 gainsborough.
8303 Note that it should be fairly easy for you to hardwire some more colors
8305 by tweaking the files "rect.h" and "plotX.c". User-defined colormaps
8306 would be nice, and may be available in future versions.
8307 \subsecidx{plotcopy}"(w1,w2,dx,dy)": copy the contents of rectwindow
8309 "w1" to rectwindow "w2", with offset "(dx,dy)".
8310 \subsecidx{plotcursor}"(w)": give as a 2-component vector the current
8312 (scaled) position of the virtual cursor corresponding to the rectwindow
8313 "w".
8314 \subsecidx{plotdraw}"(list)": physically draw the rectwindows given in
8316 "list" which must be a vector whose number of components is divisible
8317 by 3. If "list = [w1,x1,y1,w2,x2,y2,...]", the windows "w1", "w2",
8318 etc. are physically placed with their upper left corner at physical
8319 position "(x1,y1)", "(x2,y2)",...respectively, and are then drawn
8320 together. Overlapping regions will thus be drawn twice, and the
8321 windows are considered transparent. Then display the whole drawing in a
8322 special window on your screen.
8323 \subsecidx{ploth}"(X = a,b,expr,{flag = 0},{n = 0})": high precision
8325 plot of the function "y = f(x)" represented by the expression expr, "x"
8326 going from "a" to "b". This opens a specific window (which is killed
8327 whenever you click on it), and returns a four-component vector giving
8328 the coordinates of the bounding box in the form
8329 "[xmin,xmax,ymin,ymax]".
8330 Important note.: Since this may involve a lot of function calls, it is
8332 advised to keep the current precision to a minimum (e.g. 9) before
8333 calling this function.
8334 "n" specifies the number of reference point on the graph (0 means use
8336 the hardwired default values, that is: 1000 for general plot, 1500 for
8337 parametric plot, and 15 for recursive plot).
8338 If no "flag" is given, expr is either a scalar expression f(X), in
8340 which case the plane curve "y = f(X)" will be drawn, or a vector
8341 "[f_1(X),...,f_k(X)]", and then all the curves "y = f_i(X)" will be
8342 drawn in the same window.
8343 The binary digits of "flag" mean:
8345 * "1 = Parametric": parametric plot. Here expr must be a vector with an
8347 even number of components. Successive pairs are then understood as the
8348 parametric coordinates of a plane curve. Each of these are then drawn.
8349 For instance:
8351 "ploth(X = 0,2*Pi,[sin(X),cos(X)],1)" will draw a circle.
8353 "ploth(X = 0,2*Pi,[sin(X),cos(X)])" will draw two entwined sinusoidal
8355 curves.
8356 "ploth(X = 0,2*Pi,[X,X,sin(X),cos(X)],1)" will draw a circle and the
8358 line "y = x".
8359 * "2 = Recursive": recursive plot. If this flag is set, only one curve
8361 can be drawn at a time, i.e. expr must be either a two-component vector
8362 (for a single parametric curve, and the parametric flag has to be set),
8363 or a scalar function. The idea is to choose pairs of successive
8364 reference points, and if their middle point is not too far away from
8365 the segment joining them, draw this as a local approximation to the
8366 curve. Otherwise, add the middle point to the reference points. This is
8367 fast, and usually more precise than usual plot. Compare the results of
8368 "ploth(X = -1,1,sin(1/X),2) and ploth(X = -1,1,sin(1/X))"
8370 for instance. But beware that if you are extremely unlucky, or choose
8372 too few reference points, you may draw some nice polygon bearing little
8373 resemblance to the original curve. For instance you should never plot
8374 recursively an odd function in a symmetric interval around 0. Try
8375 ploth(x = -20, 20, sin(x), 2)
8377 to see why. Hence, it's usually a good idea to try and plot the same
8379 curve with slightly different parameters.
8380 The other values toggle various display options:
8382 * "4 = no_Rescale": do not rescale plot according to the computed
8384 extrema. This is meant to be used when graphing multiple functions on a
8385 rectwindow (as a "plotrecth" call), in conjunction with "plotscale".
8386 * "8 = no_X_axis": do not print the "x"-axis.
8388 * "16 = no_Y_axis": do not print the "y"-axis.
8390 * "32 = no_Frame": do not print frame.
8392 * "64 = no_Lines": only plot reference points, do not join them.
8394 * "128 = Points_too": plot both lines and points.
8396 * "256 = Splines": use splines to interpolate the points.
8398 * "512 = no_X_ticks": plot no "x"-ticks.
8400 * "1024 = no_Y_ticks": plot no "y"-ticks.
8402 * "2048 = Same_ticks": plot all ticks with the same length.
8404 \subsecidx{plothraw}"(listx,listy,{flag = 0})": given listx and listy
8406 two vectors of equal length, plots (in high precision) the points whose
8407 "(x,y)"-coordinates are given in listx and listy. Automatic positioning
8408 and scaling is done, but with the same scaling factor on "x" and "y".
8409 If "flag" is 1, join points, other non-0 flags toggle display options
8410 and should be combinations of bits "2^k", "k >= 3" as in "ploth".
8411 \subsecidx{plothsizes}"()": return data corresponding to the output
8413 window in the form of a 6-component vector: window width and height,
8414 sizes for ticks in horizontal and vertical directions (this is intended
8415 for the "gnuplot" interface and is currently not significant), width
8416 and height of characters.
8417 \subsecidx{plotinit}"(w,x,y,{flag})": initialize the rectwindow "w",
8419 destroying any rect objects you may have already drawn in "w". The
8420 virtual cursor is set to "(0,0)". The rectwindow size is set to width
8421 "x" and height "y". If "flag = 0", "x" and "y" represent pixel units.
8422 Otherwise, "x" and "y" are understood as fractions of the size of the
8423 current output device (hence must be between 0 and 1) and internally
8424 converted to pixels.
8425 The plotting device imposes an upper bound for "x" and "y", for
8427 instance the number of pixels for screen output. These bounds are
8428 available through the "plothsizes" function. The following sequence
8429 initializes in a portable way (i.e independent of the output device) a
8430 window of maximal size, accessed through coordinates in the "[0,1000]
8431 x [0,1000]" range:
8432 s = plothsizes();
8434 plotinit(0, s[1]-1, s[2]-1);
8435 plotscale(0, 0,1000, 0,1000);
8436 \subsecidx{plotkill}"(w)": erase rectwindow "w" and free the
8438 corresponding memory. Note that if you want to use the rectwindow "w"
8439 again, you have to use "plotinit" first to specify the new size. So
8440 it's better in this case to use "plotinit" directly as this throws away
8441 any previous work in the given rectwindow.
8442 \subsecidx{plotlines}"(w,X,Y,{flag = 0})": draw on the rectwindow "w"
8444 the polygon such that the (x,y)-coordinates of the vertices are in the
8445 vectors of equal length "X" and "Y". For simplicity, the whole polygon
8446 is drawn, not only the part of the polygon which is inside the
8447 rectwindow. If "flag" is non-zero, close the polygon. In any case, the
8448 virtual cursor does not move.
8449 "X" and "Y" are allowed to be scalars (in this case, both have to).
8451 There, a single segment will be drawn, between the virtual cursor
8452 current position and the point "(X,Y)". And only the part thereof which
8453 actually lies within the boundary of "w". Then move the virtual cursor
8454 to "(X,Y)", even if it is outside the window. If you want to draw a
8455 line from "(x1,y1)" to "(x2,y2)" where "(x1,y1)" is not necessarily the
8456 position of the virtual cursor, use "plotmove(w,x1,y1)" before using
8457 this function.
8458 \subsecidx{plotlinetype}"(w,type)": change the type of lines
8460 subsequently plotted in rectwindow "w". type "-2" corresponds to
8461 frames, "-1" to axes, larger values may correspond to something else.
8462 "w = -1" changes highlevel plotting. This is only taken into account by
8463 the "gnuplot" interface.
8464 \subsecidx{plotmove}"(w,x,y)": move the virtual cursor of the
8466 rectwindow "w" to position "(x,y)".
8467 \subsecidx{plotpoints}"(w,X,Y)": draw on the rectwindow "w" the points
8469 whose "(x,y)"-coordinates are in the vectors of equal length "X" and
8470 "Y" and which are inside "w". The virtual cursor does not move. This is
8471 basically the same function as "plothraw", but either with no scaling
8472 factor or with a scale chosen using the function "plotscale".
8473 As was the case with the "plotlines" function, "X" and "Y" are allowed
8475 to be (simultaneously) scalar. In this case, draw the single point
8476 "(X,Y)" on the rectwindow "w" (if it is actually inside "w"), and in
8477 any case move the virtual cursor to position "(x,y)".
8478 \subsecidx{plotpointsize}"(w,size)": changes the ``size'' of following
8480 points in rectwindow "w". If "w = -1", change it in all rectwindows.
8481 This only works in the "gnuplot" interface.
8482 \subsecidx{plotpointtype}"(w,type)": change the type of points
8484 subsequently plotted in rectwindow "w". "type = -1" corresponds to a
8485 dot, larger values may correspond to something else. "w = -1" changes
8486 highlevel plotting. This is only taken into account by the "gnuplot"
8487 interface.
8488 \subsecidx{plotrbox}"(w,dx,dy)": draw in the rectwindow "w" the outline
8490 of the rectangle which is such that the points "(x1,y1)" and
8491 "(x1+dx,y1+dy)" are opposite corners, where "(x1,y1)" is the current
8492 position of the cursor. Only the part of the rectangle which is in "w"
8493 is drawn. The virtual cursor does not move.
8494 \subsecidx{plotrecth}"(w,X = a,b,expr,{flag = 0},{n = 0})": writes to
8496 rectwindow "w" the curve output of "ploth""(w,X = a,b,expr,flag,n)".
8497 \subsecidx{plotrecthraw}"(w,data,{flag = 0})": plot graph(s) for data
8499 in rectwindow "w". "flag" has the same significance here as in "ploth",
8500 though recursive plot is no more significant.
8501 data is a vector of vectors, each corresponding to a list a
8503 coordinates. If parametric plot is set, there must be an even number
8504 of vectors, each successive pair corresponding to a curve. Otherwise,
8505 the first one contains the "x" coordinates, and the other ones contain
8506 the "y"-coordinates of curves to plot.
8507 \subsecidx{plotrline}"(w,dx,dy)": draw in the rectwindow "w" the part
8509 of the segment "(x1,y1)-(x1+dx,y1+dy)" which is inside "w", where
8510 "(x1,y1)" is the current position of the virtual cursor, and move the
8511 virtual cursor to "(x1+dx,y1+dy)" (even if it is outside the window).
8512 \subsecidx{plotrmove}"(w,dx,dy)": move the virtual cursor of the
8514 rectwindow "w" to position "(x1+dx,y1+dy)", where "(x1,y1)" is the
8515 initial position of the cursor (i.e. to position "(dx,dy)" relative to
8516 the initial cursor).
8517 \subsecidx{plotrpoint}"(w,dx,dy)": draw the point "(x1+dx,y1+dy)" on
8519 the rectwindow "w" (if it is inside "w"), where "(x1,y1)" is the
8520 current position of the cursor, and in any case move the virtual cursor
8521 to position "(x1+dx,y1+dy)".
8522 \subsecidx{plotscale}"(w,x1,x2,y1,y2)": scale the local coordinates of
8524 the rectwindow "w" so that "x" goes from "x1" to "x2" and "y" goes from
8525 "y1" to "y2" ("x2 < x1" and "y2 < y1" being allowed). Initially, after
8526 the initialization of the rectwindow "w" using the function "plotinit",
8527 the default scaling is the graphic pixel count, and in particular the
8528 "y" axis is oriented downwards since the origin is at the upper left.
8529 The function "plotscale" allows to change all these defaults and should
8530 be used whenever functions are graphed.
8531 \subsecidx{plotstring}"(w,x,{flag = 0})": draw on the rectwindow "w"
8533 the String "x" (see "Label se:strings"), at the current position of the
8534 cursor.
8535 flag is used for justification: bits 1 and 2 regulate horizontal
8537 alignment: left if 0, right if 2, center if 1. Bits 4 and 8 regulate
8538 vertical alignment: bottom if 0, top if 8, v-center if 4. Can insert
8539 additional small gap between point and string: horizontal if bit 16 is
8540 set, vertical if bit 32 is set (see the tutorial for an example).
8541 \subsecidx{psdraw}"(list)": same as "plotdraw", except that the output
8543 is a PostScript program appended to the "psfile".
8544 \subsecidx{psploth}"(X = a,b,expr)": same as "ploth", except that the
8546 output is a PostScript program appended to the "psfile".
8547 \subsecidx{psplothraw}"(listx,listy)": same as "plothraw", except that
8549 the output is a PostScript program appended to the "psfile".
8550
8552 \subsecidx{Control statements}.
8553 A number of control statements are available in GP. They are simpler
8555 and have a syntax slightly different from their C counterparts, but are
8556 quite powerful enough to write any kind of program. Some of them are
8557 specific to GP, since they are made for number theorists. As usual, "X"
8558 will denote any simple variable name, and seq will always denote a
8559 sequence of expressions, including the empty sequence.
8560 Caveat:. in constructs like
8562 for (X = a,b, seq)
8564 the variable "X" is considered local to the loop, leading to possibly
8566 unexpected behaviour:
8567 n = 5;
8569 for (n = 1, 10,
8570 if (something_nice(), break);
8571 );
8572 \\ at this point C<n> is 5 !
8573 If the sequence "seq" modifies the loop index, then the loop is
8575 modified accordingly:
8576 ? for (n = 1, 10, n += 2; print(n))
8578 3
8579 6
8580 9
8581 12
8582 \subsubsecidx{break}"({n = 1})": interrupts execution of current seq,
8584 and immediately exits from the "n" innermost enclosing loops, within
8585 the current function call (or the top level loop). "n" must be bigger
8586 than 1. If "n" is greater than the number of enclosing loops, all
8587 enclosing loops are exited.
8588 \subsubsecidx{for}"(X = a,b,seq)": evaluates seq, where the formal
8590 variable "X" goes from "a" to "b". Nothing is done if "a > b". "a" and
8591 "b" must be in R.
8592 \subsubsecidx{fordiv}"(n,X,seq)": evaluates seq, where the formal
8594 variable "X" ranges through the divisors of "n" (see "divisors", which
8595 is used as a subroutine). It is assumed that "factor" can handle "n",
8596 without negative exponents. Instead of "n", it is possible to input a
8597 factorization matrix, i.e. the output of factor(n).
8598 This routine uses "divisors" as a subroutine, then loops over the
8600 divisors. In particular, if "n" is an integer, divisors are sorted by
8601 increasing size.
8602 To avoid storing all divisors, possibly using a lot of memory, the
8604 following (much slower) routine loops over the divisors using
8605 essentially constant space:
8606 FORDIV(N)=
8608 { local(P, E);
8609 P = factor(N); E = P[,2]; P = P[,1];
8611 forvec( v = vector(#E, i, [0,E[i]]),
8612 X = factorback(P, v)
8613 \\ ...
8614 );
8615 }
8616 ? for(i=1,10^5, FORDIV(i))
8617 time = 3,445 ms.
8618 ? for(i=1,10^5, fordiv(i, d, ))
8619 time = 490 ms.
8620 \subsubsecidx{forell}"(E,a,b,seq)": evaluates seq, where the formal
8622 variable "E" ranges through all elliptic curves of conductors from "a"
8623 to "b". Th "elldata" database must be installed and contain data for
8624 the specified conductors.
8625 \subsubsecidx{forprime}"(X = a,b,seq)": evaluates seq, where the formal
8627 variable "X" ranges over the prime numbers between "a" to "b"
8628 (including "a" and "b" if they are prime). More precisely, the value of
8629 "X" is incremented to the smallest prime strictly larger than "X" at
8630 the end of each iteration. Nothing is done if "a > b". Note that "a"
8631 and "b" must be in R.
8632 ? { forprime(p = 2, 12,
8634 print(p);
8635 if (p == 3, p = 6);
8636 )
8637 }
8638 2
8639 3
8640 7
8641 11
8642 \subsubsecidx{forstep}"(X = a,b,s,seq)": evaluates seq, where the
8644 formal variable "X" goes from "a" to "b", in increments of "s".
8645 Nothing is done if "s > 0" and "a > b" or if "s < 0" and "a < b". "s"
8646 must be in "R^*" or a vector of steps "[s_1,...,s_n]". In the latter
8647 case, the successive steps are used in the order they appear in "s".
8648 ? forstep(x=5, 20, [2,4], print(x))
8650 5
8651 7
8652 11
8653 13
8654 17
8655 19
8656 \subsubsecidx{forsubgroup}"(H = G,{B},seq)": evaluates seq for each
8658 subgroup "H" of the abelian group "G" (given in SNF form or as a vector
8659 of elementary divisors), whose index is bounded by "B". The subgroups
8660 are not ordered in any obvious way, unless "G" is a "p"-group in which
8661 case Birkhoff's algorithm produces them by decreasing index. A subgroup
8662 is given as a matrix whose columns give its generators on the implicit
8663 generators of "G". For example, the following prints all subgroups of
8664 index less than 2 in "G = Z/2Z g_1 x Z/2Z g_2":
8665 ? G = [2,2]; forsubgroup(H=G, 2, print(H))
8667 [1; 1]
8668 [1; 2]
8669 [2; 1]
8670 [1, 0; 1, 1]
8671 The last one, for instance is generated by "(g_1, g_1 + g_2)". This
8673 routine is intended to treat huge groups, when "subgrouplist" is not an
8674 option due to the sheer size of the output.
8675 For maximal speed the subgroups have been left as produced by the
8677 algorithm. To print them in canonical form (as left divisors of "G" in
8678 HNF form), one can for instance use
8679 ? G = matdiagonal([2,2]); forsubgroup(H=G, 2, print(mathnf(concat(G,H))))
8681 [2, 1; 0, 1]
8682 [1, 0; 0, 2]
8683 [2, 0; 0, 1]
8684 [1, 0; 0, 1]
8685 Note that in this last representation, the index "[G:H]" is given by
8687 the determinant. See "galoissubcyclo" and "galoisfixedfield" for
8688 "nfsubfields" applications to Galois theory.
8689 Warning:. the present implementation cannot treat a group "G", if one
8691 of its "p"-Sylow subgroups has a cyclic factor with more than "2^{31}",
8692 resp. "2^{63}" elements on a 32-bit, resp. 64-bit architecture.
8693 \subsubsecidx{forvec}"(X = v,seq,{flag = 0})": Let "v" be an
8695 "n"-component vector (where "n" is arbitrary) of two-component vectors
8696 "[a_i,b_i]" for "1 <= i <= n". This routine evaluates seq, where the
8697 formal variables "X[1],..., X[n]" go from "a_1" to "b_1",..., from
8698 "a_n" to "b_n", i.e. "X" goes from "[a_1,...,a_n]" to "[b_1,...,b_n]"
8699 with respect to the lexicographic ordering. (The formal variable with
8700 the highest index moves the fastest.) If "flag = 1", generate only
8701 nondecreasing vectors "X", and if "flag = 2", generate only strictly
8702 increasing vectors "X".
8703 \subsubsecidx{if}"(a,{seq1},{seq2})": evaluates the expression sequence
8705 seq1 if "a" is non-zero, otherwise the expression seq2. Of course, seq1
8706 or seq2 may be empty:
8707 "if (a,seq)" evaluates seq if "a" is not equal to zero (you don't have
8709 to write the second comma), and does nothing otherwise,
8710 "if (a,,seq)" evaluates seq if "a" is equal to zero, and does nothing
8712 otherwise. You could get the same result using the "!" ("not")
8713 operator: "if (!a,seq)".
8714 Note that the boolean operators "&&" and "||" are evaluated according
8716 to operator precedence as explained in "Label se:operators", but that,
8717 contrary to other operators, the evaluation of the arguments is stopped
8718 as soon as the final truth value has been determined. For instance
8719 if (reallydoit && longcomplicatedfunction(), ...)%
8721 is a perfectly safe statement.
8723 Recall that functions such as "break" and "next" operate on loops (such
8725 as "forxxx", "while", "until"). The "if" statement is not a loop
8726 (obviously!).
8727 \subsubsecidx{next}"({n = 1})": interrupts execution of current "seq",
8729 resume the next iteration of the innermost enclosing loop, within the
8730 current function call (or top level loop). If "n" is specified, resume
8731 at the "n"-th enclosing loop. If "n" is bigger than the number of
8732 enclosing loops, all enclosing loops are exited.
8733 \subsubsecidx{return}"({x = 0})": returns from current subroutine, with
8735 result "x". If "x" is omitted, return the "(void)" value (return no
8736 result, like "print").
8737 \subsubsecidx{until}"(a,seq)": evaluates seq until "a" is not equal to
8739 0 (i.e. until "a" is true). If "a" is initially not equal to 0, seq is
8740 evaluated once (more generally, the condition on "a" is tested after
8741 execution of the seq, not before as in "while").
8742 \subsubsecidx{while}"(a,seq)": while "a" is non-zero, evaluates the
8744 expression sequence seq. The test is made before evaluating the "seq",
8745 hence in particular if "a" is initially equal to zero the seq will not
8746 be evaluated at all.
8747 Specific functions used in GP programming
8749 In addition to the general PARI functions, it is necessary to have some
8750 functions which will be of use specifically for "gp", though a few of
8751 these can be accessed under library mode. Before we start describing
8752 these, we recall the difference between strings and keywords (see
8753 "Label se:strings"): the latter don't get expanded at all, and you can
8754 type them without any enclosing quotes. The former are dynamic objects,
8755 where everything outside quotes gets immediately expanded.
8756 \subsubsecidx{addhelp}"(S,str)": changes the help message for the
8758 symbol "S". The string str is expanded on the spot and stored as the
8759 online help for "S". If "S" is a function you have defined, its
8760 definition will still be printed before the message str. It is
8761 recommended that you document global variables and user functions in
8762 this way. Of course "gp" will not protest if you skip this.
8763 Nothing prevents you from modifying the help of built-in PARI
8765 functions. (But if you do, we would like to hear why you needed to do
8766 it!)
8767 \subsubsecidx{alias}"(newkey,key)": defines the keyword newkey as an
8769 alias for keyword key. key must correspond to an existing function
8770 name. This is different from the general user macros in that alias
8771 expansion takes place immediately upon execution, without having to
8772 look up any function code, and is thus much faster. A sample alias file
8773 "misc/gpalias" is provided with the standard distribution. Alias
8774 commands are meant to be read upon startup from the ".gprc" file, to
8775 cope with function names you are dissatisfied with, and should be
8776 useless in interactive usage.
8777 \subsubsecidx{allocatemem}"({x = 0})": this is a very special operation
8779 which allows the user to change the stack size after initialization.
8780 "x" must be a non-negative integer. If "x != 0", a new stack of size
8781 "16*ceil{x/16}" bytes is allocated, all the PARI data on the old stack
8782 is moved to the new one, and the old stack is discarded. If "x = 0",
8783 the size of the new stack is twice the size of the old one.
8784 Although it is a function, "allocatemem" cannot be used in loop-like
8786 constructs, or as part of a larger expression, e.g "2 + allocatemem()".
8787 Such an attempt will raise an error. The technical reason is that this
8788 routine usually moves the stack, so objects from the current expression
8789 may not be correct anymore, e.g. loop indexes.
8790 The library syntax is "allocatemoremem(x)", where "x" is an unsigned
8792 long, and the return type is void. "gp" uses a variant which makes sure
8793 it was not called within a loop.
8794 \subsubsecidx{default}"({key},{val})": returns the default
8796 corresponding to keyword key. If val is present, sets the default to
8797 val first (which is subject to string expansion first). Typing
8798 "default()" (or "\d") yields the complete default list as well as their
8799 current values. See "Label se:defaults" for a list of available
8800 defaults, and "Label se:meta" for some shortcut alternatives. Note that
8801 the shortcut are meant for interactive use and usually display more
8802 information than "default".
8803 The library syntax is "gp_default(key, val)", where key and val are
8805 "char *".
8806 \subsubsecidx{error}"({str}*)": outputs its argument list (each of them
8808 interpreted as a string), then interrupts the running "gp" program,
8809 returning to the input prompt. For instance
8810 error("n = ", n, " is not squarefree !")
8812 \subsubsecidxunix{extern}"(str)": the string str is the name of an
8814 external command (i.e. one you would type from your UNIX shell prompt).
8815 This command is immediately run and its input fed into "gp", just as if
8816 read from a file.
8817 The library syntax is "extern0(str)", where str is a "char *".
8819 \subsubsecidx{getheap}"()": returns a two-component row vector giving
8821 the number of objects on the heap and the amount of memory they occupy
8822 in long words. Useful mainly for debugging purposes.
8823 The library syntax is "getheap()".
8825 \subsubsecidx{getrand}"()": returns the current value of the random
8827 number seed. Useful mainly for debugging purposes.
8828 The library syntax is "getrand()", returns a C long.
8830 \subsubsecidx{getstack}"()": returns the current value of "top-avma",
8832 i.e. the number of bytes used up to now on the stack. Should be equal
8833 to 0 in between commands. Useful mainly for debugging purposes.
8834 The library syntax is "getstack()", returns a C long.
8836 \subsubsecidx{gettime}"()": returns the time (in milliseconds) elapsed
8838 since either the last call to "gettime", or to the beginning of the
8839 containing GP instruction (if inside "gp"), whichever came last.
8840 The library syntax is "gettime()", returns a C long.
8842 \subsubsecidx{global}"(list of variables)": declares the corresponding
8844 variables to be global. From now on, you will be forbidden to use them
8845 as formal parameters for function definitions or as loop indexes. This
8846 is especially useful when patching together various scripts, possibly
8847 written with different naming conventions. For instance the following
8848 situation is dangerous:
8849 p = 3 \\ fix characteristic
8851 ...
8852 forprime(p = 2, N, ...)
8853 f(p) = ...
8854 since within the loop or within the function's body (even worse: in the
8856 subroutines called in that scope), the true global value of "p" will be
8857 hidden. If the statement "global(p = 3)" appears at the beginning of
8858 the script, then both expressions will trigger syntax errors.
8859 Calling "global" without arguments prints the list of global variables
8861 in use. In particular, "eval(global)" will output the values of all
8862 global variables.
8863 \subsubsecidx{input}"()": reads a string, interpreted as a GP
8865 expression, from the input file, usually standard input (i.e. the
8866 keyboard). If a sequence of expressions is given, the result is the
8867 result of the last expression of the sequence. When using this
8868 instruction, it is useful to prompt for the string by using the
8869 "print1" function. Note that in the present version 2.19 of "pari.el",
8870 when using "gp" under GNU Emacs (see "Label se:emacs") one must prompt
8871 for the string, with a string which ends with the same prompt as any of
8872 the previous ones (a "? " will do for instance).
8873 \subsubsecidxunix{install}"(name,code,{gpname},{lib})": loads from
8875 dynamic library lib the function name. Assigns to it the name gpname in
8876 this "gp" session, with argument code code (see the Libpari Manual for
8877 an explanation of those). If lib is omitted, uses "libpari.so". If
8878 gpname is omitted, uses name.
8879 This function is useful for adding custom functions to the "gp"
8881 interpreter, or picking useful functions from unrelated libraries. For
8882 instance, it makes the function "system" obsolete:
8883 ? install(system, vs, sys, "libc.so")
8885 ? sys("ls gp*")
8886 gp.c gp.h gp_rl.c
8887 But it also gives you access to all (non static) functions defined in
8889 the PARI library. For instance, the function "GEN addii(GEN x, GEN y)"
8890 adds two PARI integers, and is not directly accessible under "gp" (it's
8891 eventually called by the "+" operator of course):
8892 ? install("addii", "GG")
8894 ? addii(1, 2)
8895 %1 = 3
8896 Re-installing a function will print a Warning, and update the prototype
8898 code if needed, but will reload a symbol from the library, even it the
8899 latter has been recompiled.
8900 Caution:. This function may not work on all systems, especially when
8902 "gp" has been compiled statically. In that case, the first use of an
8903 installed function will provoke a Segmentation Fault, i.e. a major
8904 internal blunder (this should never happen with a dynamically linked
8905 executable). Hence, if you intend to use this function, please check
8906 first on some harmless example such as the ones above that it works
8907 properly on your machine.
8908 \subsubsecidx{kill}"(s)": kills the present value of the variable,
8910 alias or user-defined function "s". The corresponding identifier can
8911 now be used to name any GP object (variable or function). This is the
8912 only way to replace a variable by a function having the same name (or
8913 the other way round), as in the following example:
8914 ? f = 1
8916 %1 = 1
8917 ? f(x) = 0
8918 *** unused characters: f(x)=0
8919 ^----
8920 ? kill(f)
8921 ? f(x) = 0
8922 ? f()
8923 %2 = 0
8924 When you kill a variable, all objects that used it become invalid. You
8926 can still display them, even though the killed variable will be printed
8927 in a funny way. For example:
8928 ? a^2 + 1
8930 %1 = a^2 + 1
8931 ? kill(a)
8932 ? %1
8933 %2 = #<1>^2 + 1
8934 If you simply want to restore a variable to its ``undefined'' value
8936 (monomial of degree one), use the quote operator: "a = 'a". Predefined
8937 symbols ("x" and GP function names) cannot be killed.
8938 \subsubsecidx{print}"({str}*)": outputs its (string) arguments in raw
8940 format, ending with a newline.
8941 \subsubsecidx{print1}"({str}*)": outputs its (string) arguments in raw
8943 format, without ending with a newline (note that you can still embed
8944 newlines within your strings, using the "\n" notation !).
8945 \subsubsecidx{printp}"({str}*)": outputs its (string) arguments in
8947 prettyprint (beautified) format, ending with a newline.
8948 \subsubsecidx{printp1}"({str}*)": outputs its (string) arguments in
8950 prettyprint (beautified) format, without ending with a newline.
8951 \subsubsecidx{printtex}"({str}*)": outputs its (string) arguments in
8953 TeX format. This output can then be used in a TeX manuscript. The
8954 printing is done on the standard output. If you want to print it to a
8955 file you should use "writetex" (see there).
8956 Another possibility is to enable the "log" default (see "Label
8958 se:defaults"). You could for instance do:
8959 default(logfile, "new.tex");
8961 default(log, 1);
8962 printtex(result);
8963 \subsubsecidx{quit}"()": exits "gp".
8965 \subsubsecidx{read}"({filename})": reads in the file filename (subject
8967 to string expansion). If filename is omitted, re-reads the last file
8968 that was fed into "gp". The return value is the result of the last
8969 expression evaluated.
8970 If a GP "binary file" is read using this command (see "Label
8972 se:writebin"), the file is loaded and the last object in the file is
8973 returned.
8974 \subsubsecidx{readvec}"({str})": reads in the file filename (subject
8976 to string expansion). If filename is omitted, re-reads the last file
8977 that was fed into "gp". The return value is a vector whose components
8978 are the evaluation of all sequences of instructions contained in the
8979 file. For instance, if file contains
8980 1
8982 2
8983 3
8984 then we will get:
8986 ? \r a
8988 %1 = 1
8989 %2 = 2
8990 %3 = 3
8991 ? read(a)
8992 %4 = 3
8993 ? readvec(a)
8994 %5 = [1, 2, 3]
8995 In general a sequence is just a single line, but as usual braces and
8997 "\\" may be used to enter multiline sequences.
8998 \subsubsecidx{reorder}"({x = []})": "x" must be a vector. If "x" is the
9000 empty vector, this gives the vector whose components are the existing
9001 variables in increasing order (i.e. in decreasing importance). Killed
9002 variables (see "kill") will be shown as 0. If "x" is non-empty, it must
9003 be a permutation of variable names, and this permutation gives a new
9004 order of importance of the variables, for output only. For example, if
9005 the existing order is "[x,y,z]", then after "reorder([z,x])" the order
9006 of importance of the variables, with respect to output, will be
9007 "[z,y,x]". The internal representation is unaffected.
9008 \subsubsecidx{setrand}"(n)": reseeds the random number generator to the
9010 value "n". The initial seed is "n = 1".
9011 The library syntax is "setrand(n)", where "n" is a "long". Returns "n".
9013 \subsubsecidxunix{system}"(str)": str is a string representing a system
9015 command. This command is executed, its output written to the standard
9016 output (this won't get into your logfile), and control returns to the
9017 PARI system. This simply calls the C "system" command.
9018 \subsubsecidx{trap}"({e}, {rec}, {seq})": tries to evaluate seq,
9020 trapping error "e", that is effectively preventing it from aborting
9021 computations in the usual way; the recovery sequence rec is executed if
9022 the error occurs and the evaluation of rec becomes the result of the
9023 command. If "e" is omitted, all exceptions are trapped. Note in
9024 particular that hitting "^C" (Control-C) raises an exception. See
9025 "Label se:errorrec" for an introduction to error recovery under "gp".
9026 ? \\ trap division by 0
9028 ? inv(x) = trap (gdiver, INFINITY, 1/x)
9029 ? inv(2)
9030 %1 = 1/2
9031 ? inv(0)
9032 %2 = INFINITY
9033 If seq is omitted, defines rec as a default action when catching
9035 exception "e", provided no other trap as above intercepts it first.
9036 The error message is printed, as well as the result of the evaluation
9037 of rec, and control is given back to the "gp" prompt. In particular,
9038 current computation is then lost.
9039 The following error handler prints the list of all user variables, then
9041 stores in a file their name and their values:
9042 ? { trap( ,
9044 print(reorder);
9045 writebin("crash")) }
9046 If no recovery code is given (rec is omitted) a break loop will be
9048 started (see "Label se:breakloop"). In particular
9049 ? trap()
9051 by itself installs a default error handler, that will start a break
9053 loop whenever an exception is raised.
9054 If rec is the empty string "" the default handler (for that error if
9056 "e" is present) is disabled.
9057 Note:. The interface is currently not adequate for trapping individual
9059 exceptions. In the current version /usr/share/libpari23, the following
9060 keywords are recognized, but the name list will be expanded and changed
9061 in the future (all library mode errors can be trapped: it's a matter of
9062 defining the keywords to "gp", and there are currently far too many
9063 useless ones):
9064 "accurer": accuracy problem
9066 "archer": not available on this architecture or operating system
9068 "errpile": the PARI stack overflows
9070 "gdiver": division by 0
9072 "invmoder": impossible inverse modulo
9074 "siginter": SIGINT received (usually from Control-C)
9076 "talker": miscellaneous error
9078 "typeer": wrong type
9080 "user": user error (from the "error" function)
9082 \subsubsecidx{type}"(x)": this is useful only under "gp". Returns the
9084 internal type name of the PARI object "x" as a string. Check out
9085 existing type names with the metacommand "\t". For example type(1)
9086 will return ""t_INT"".
9087 The library syntax is "type0(x)", though the macro "typ" is usually
9089 simpler to use since it return an integer that can easily be matched
9090 with the symbols "t_*". The name "type" was avoided due to the fact
9091 that "type" is a reserved identifier for some C(++) compilers.
9092 \subsubsecidx{version}"()": Returns the current version number as a
9094 "t_VEC" with three integer components: major version number, minor
9095 version number and patchlevel. To check against a particular version
9096 number, you can use:
9097 if (lex(version(), [2,2,0]) >= 0,
9099 \\ code to be executed if we are running 2.2.0 or more recent.
9100 ,
9101 \\ compatibility code
9102 );
9103 \subsubsecidx{whatnow}"(key)": if keyword key is the name of a function
9105 that was present in GP version 1.39.15 or lower, outputs the new
9106 function name and syntax, if it changed at all (387 out of 560 did).
9107 \subsubsecidx{write}"(filename,{str}*)": writes (appends) to filename
9109 the remaining arguments, and appends a newline (same output as
9110 "print").
9111 \subsubsecidx{write1}"(filename,{str}*)": writes (appends) to filename
9113 the remaining arguments without a trailing newline (same output as
9114 "print1").
9115 \subsubsecidx{writebin}"(filename,{x})": writes (appends) to filename
9117 the object "x" in binary format. This format is not human readable, but
9118 contains the exact internal structure of "x", and is much faster to
9119 save/load than a string expression, as would be produced by "write".
9120 The binary file format includes a magic number, so that such a file can
9121 be recognized and correctly input by the regular "read" or "\r"
9122 function. If saved objects refer to (polynomial) variables that are not
9123 defined in the new session, they will be displayed in a funny way (see
9124 "Label se:kill").
9125 If "x" is omitted, saves all user variables from the session, together
9127 with their names. Reading such a ``named object'' back in a "gp"
9128 session will set the corresponding user variable to the saved value.
9129 E.g after
9130 x = 1; writebin("log")
9132 reading "log" into a clean session will set "x" to 1. The relative
9134 variables priorities (see "Label se:priority") of new variables set in
9135 this way remain the same (preset variables retain their former
9136 priority, but are set to the new value). In particular, reading such a
9137 session log into a clean session will restore all variables exactly as
9138 they were in the original one.
9139 User functions, installed functions and history objects can not be
9141 saved via this function. Just as a regular input file, a binary file
9142 can be compressed using "gzip", provided the file name has the standard
9143 ".gz" extension.
9144 In the present implementation, the binary files are architecture
9146 dependent and compatibility with future versions of "gp" is not
9147 guaranteed. Hence binary files should not be used for long term storage
9148 (also, they are larger and harder to compress than text files).
9149 \subsubsecidx{writetex}"(filename,{str}*)": as "write", in TeX format.
9151perl v5.34.1 2022-03-30 libPARI(3)