Annotation of OpenXM_contrib/pari-2.2/doc/usersch3.tex, Revision 1.1.1.1
1.1 noro 1: % $Id: usersch3.tex,v 1.127 2001/09/29 16:36:17 karim Exp $
2: % Copyright (c) 2000 The PARI Group
3: %
4: % This file is part of the PARI/GP documentation
5: %
6: % Permission is granted to copy, distribute and/or modify this document
7: % under the terms of the GNU Free Documentation License
8: \chapter{Functions and Operations Available in PARI and GP}
9: \label{se:functions}
10:
11: The functions and operators available in PARI and in the GP/PARI calculator
12: are numerous and everexpanding. Here is a description of the ones available
13: in version \vers. It should be noted that many of these functions accept
14: quite different types as arguments, but others are more restricted. The list
15: of acceptable types will be given for each function or class of functions.
16: Except when stated otherwise, it is understood that a function or operation
17: which should make natural sense is legal. In this chapter, we will describe
18: the functions according to a rough classification. The general entry looks
19: something like:
20:
21: \key{foo}$(x,\{\fl=0\})$: short description.
22:
23: \syn{foo}{x,\fl}.
24:
25: \noindent
26: This means that the GP function \kbd{foo} has one mandatory argument $x$, and
27: an optional one, $\fl$, whose default value is 0 (the $\{\}$ should never be
28: typed, it is just a convenient notation we will use throughout to denote
29: optional arguments). That is, you can type \kbd{foo(x,2)}, or \kbd{foo(x)},
30: which is then understood to mean \kbd{foo(x,0)}. As well, a comma or closing
31: parenthesis, where an optional argument should have been, signals to GP it
32: should use the default. Thus, the syntax \kbd{foo(x,)} is also accepted as a
33: synonym for our last expression. When a function has more than one optional
34: argument, the argument list is filled with user supplied values, in order.
35: And when none are left, the defaults are used instead. Thus, assuming that
36: \kbd{foo}'s prototype had been
37: $$\hbox{%
38: \key{foo}$(\{x=1\},\{y=2\},\{z=3\})$,%
39: }$$
40: typing in \kbd{foo(6,4)} would give
41: you \kbd{foo(6,4,3)}. In the rare case when you want to set some far away
42: flag, and leave the defaults in between as they stand, you can use the
43: ``empty arg'' trick alluded to above: \kbd{foo(6,,1)} would yield
44: \kbd{foo(6,2,1)}. By the way, \kbd{foo()} by itself yields
45: \kbd{foo(1,2,3)} as was to be expected. In this rather special case of a
46: function having no mandatory argument, you can even omit the $()$: a
47: standalone \kbd{foo} would be enough (though we don't really recommend it for
48: your scripts, for the sake of clarity). In defining GP syntax, we strove
49: to put optional arguments at the end of the argument list (of course, since
50: they would not make sense otherwise), and in order of decreasing usefulness
51: so that, most of the time, you will be able to ignore them.
52:
53: \misctitle{Binary Flags}.\sidx{binary flag} For some of these optional
54: flags, we adopted the customary binary notation as a compact way to
55: represent many toggles with just one number. Letting $(p_0,\dots,p_n)$ be a
56: list of switches (i.e.~of properties which can be assumed to take either
57: the value $0$ or~$1$), the number $2^3 + 2^5=40$ means that $p_3$ and $p_5$
58: have been set (that is, set to $1$), and none of the others were (that is,
59: they were set to 0). This will usually be announced as ``The binary digits
60: of $\fl$ mean 1: $p_0$, 2: $p_1$, 4: $p_2$'', and so on, using the
61: available consecutive powers of~$2$.
62:
63: \misctitle{Pointers}.\sidx{pointer} If a parameter in the function
64: prototype is prefixed with a \& sign, as in
65:
66: \key{foo}$(x,\&e)$
67:
68: \noindent it means that, besides the normal return value, the variable named
69: $e$ may be set as a side effect. When passing the argument, the \& sign has
70: to be typed in explicitly. As of version \vers, this \tet{pointer} argument
71: is optional for all documented functions, hence the \& will always appear
72: between brackets as in \kbd{issquare}$(x,\{\&e\})$.
73:
74: \misctitle{About library programming}. To finish with our generic
75: simple-minded example, the \var{library} function \kbd{foo}, as defined
76: above, is seen to have two mandatory arguments, $x$ and \fl (no PARI
77: mathematical function has been implemented so as to accept a variable
78: number of arguments). When not mentioned otherwise, the result and
79: arguments of a function are assumed implicitly to be of type \kbd{GEN}.
80: Most other functions return an object of type \kbd{long} integer in C (see
81: Chapter~4). The variable or parameter names \var{prec} and \fl\ always
82: denote \kbd{long} integers.
83:
84: The \tet{entree} type is used by the library to implement iterators (loops,
85: sums, integrals, etc.) when a formal variable has to successively assume a
86: number of values in a given set. When programming with the library, it is
87: easier and much more efficient to code loops and the like directly. Hence
88: this type is not documented, although it does appear in a few library
89: function prototypes below. See \secref{se:sums} for more details.
90:
91: \section{Standard monadic or dyadic operators}
92:
93: \subseckbd{+$/$-}: The expressions \kbd{+}$x$ and \kbd{-}$x$ refer
94: to monadic operators (the first does nothing, the second negates $x$).
95:
96: \syn{gneg}{x} for \kbd{-}$x$.
97:
98: \subseckbd{+}, \kbd{-}: The expression $x$ \kbd{+} $y$ is the \idx{sum} and
99: $x$ \kbd{-} $y$ is the \idx{difference} of $x$ and $y$. Among the prominent
100: impossibilities are addition/subtraction between a scalar type and a vector
101: or a matrix, between vector/matrices of incompatible sizes and between an
102: integermod and a real number.
103:
104: \syn{gadd}{x,y} $x$ \kbd{+} $y$, $\teb{gsub}(x,y)$ for $x$ \kbd{-} $y$.
105:
106: \subseckbd{*}: The expression $x$ \kbd{*} $y$ is the \idx{product} of $x$
107: and $y$. Among the prominent impossibilities are multiplication between
108: vector/matrices of incompatible sizes, between an integermod and a real
109: number. Note that because of vector and matrix operations, \kbd{*} is not
110: necessarily commutative. Note also that since multiplication between two
111: column or two row vectors is not allowed, to obtain the \idx{scalar product}
112: of two vectors of the same length, you must multiply a line vector by a
113: column vector, if necessary by transposing one of the vectors (using
114: the operator \kbd{\til} or the function \kbd{mattranspose}, see
115: \secref{se:linear_algebra}).
116:
117: If $x$ and $y$ are binary quadratic forms, compose them. See also
118: \kbd{qfbnucomp} and \kbd{qfbnupow}.
119:
120: \syn{gmul}{x,y} for $x$ \kbd{*} $y$. Also available is
121: $\teb{gsqr}(x)$ for $x$ \kbd{*} $x$ (faster of course!).
122:
123: \subseckbd{/}: The expression $x$ \kbd{/} $y$ is the \idx{quotient} of $x$
124: and $y$. In addition to the impossibilities for multiplication, note that if
125: the divisor is a matrix, it must be an invertible square matrix, and in that
126: case the result is $x*y^{-1}$. Furthermore note that the result is as exact
127: as possible: in particular, division of two integers always gives a rational
128: number (which may be an integer if the quotient is exact) and \var{not} the
129: Euclidean quotient (see $x$ \kbd{\bs} $y$ for that), and similarly the
130: quotient of two polynomials is a rational function in general. To obtain the
131: approximate real value of the quotient of two integers, add \kbd{0.} to the
132: result; to obtain the approximate $p$-adic value of the quotient of two
133: integers, add \kbd{O(p\pow k)} to the result; finally, to obtain the
134: \idx{Taylor series} expansion of the quotient of two polynomials, add
135: \kbd{O(X\pow k)} to the result or use the \kbd{taylor} function
136: (see \secref{se:taylor}). \label{se:gdiv}
137:
138: \syn{gdiv}{x,y} for $x$ \kbd{/} $y$.
139:
140: \subseckbd{\bs}: The expression $x$ \kbd{\bs} $y$ is the
141: % keep "Euclidean" and "quotient" on same line for gphelp
142: \idx{Euclidean quotient} of $x$ and $y$. The types must be either both
143: integer or both polynomials. The result is the Euclidean quotient. In the
144: case of integer division, the quotient is such that the corresponding
145: remainder is non-negative.
146:
147: \syn{gdivent}{x,y} for $x$ \kbd{\bs} $y$.
148:
149: \subseckbd{\bs/}: The expression $x$ \b{/} $y$ is the Euclidean
150: quotient of $x$ and $y$. The types must be either both integer or both
151: polynomials. The result is the rounded Euclidean quotient. In the case of
152: integer division, the quotient is such that the corresponding remainder is
153: smallest in absolute value and in case of a tie the quotient closest to
154: $+\infty$ is chosen.
155:
156: \syn{gdivround}{x,y} for $x$ \b{/} $y$.
157:
158: \subseckbd{\%}: The expression $x$ \kbd{\%} $y$ is the
159: % keep "Euclidean" and "remainder" on same line for gphelp
160: \idx{Euclidean remainder} of $x$ and $y$. The modulus $y$ must be of type
161: integer or polynomial. The result is the remainder, always non-negative in
162: the case of integers. Allowed dividend types are scalar exact types when
163: the modulus is an integer, and polynomials, polmods and rational functions
164: when the modulus is a polynomial.
165:
166: \syn{gmod}{x,y} for $x$ \kbd{\%} $y$.
167:
168: \subsecidx{divrem}$(x,y)$: creates a column vector with two components,
169: the first being the Euclidean quotient, the second the Euclidean remainder,
170: of the division of $x$ by $y$. This avoids the need to do two divisions if
171: one needs both the quotient and the remainder. The arguments must be both
172: integers or both polynomials; in the case of integers, the remainder is
173: non-negative.
174:
175: \syn{gdiventres}{x,y}.
176:
177: \subseckbd{\pow}: The expression $x\hbox{\kbd{\pow}}n$ is \idx{powering}.
178: If the exponent is an integer, then exact operations are performed using
179: binary (left-shift) powering techniques. In particular, in this case $x$
180: cannot be a vector or matrix unless it is a square matrix (and moreover
181: invertible if the exponent is negative). If $x$ is a $p$-adic number, its
182: precision will increase if $v_p(n) > 0$. PARI is able to rewrite the
183: multiplication $x * x$ of two {\it identical} objects as $x^2$, or
184: $\kbd{sqr}(x)$ (here, identical means the operands are two different labels
185: referencing the same chunk of memory; no equality test is performed). This
186: is no longer true when more than two arguments are involved.
187:
188: If the exponent is not of type integer, this is treated as a transcendental
189: function (see \secref{se:trans}), and in particular has the effect of
190: componentwise powering on vector or matrices.
191:
192: As an exception, if the exponent is a rational number $p/q$ and $x$ an
193: integer modulo a prime, return a solution $y$ of $y^q=x^p$ if it
194: exists. Currently, $q$ must not have large prime factors.
195:
196: Beware that
197:
198: \bprog
199: ? Mod(7,19)^(1/2)
200: %1 = Mod(11, 19)/*is any square root*/
201: ? sqrt(Mod(7,19))
202: %2 = Mod(8, 19)/*is the smallest square root*/
203: ? Mod(7,19)^(3/5)
204: %3 = Mod(1, 19)
205: ? %3^(5/3)
206: %4 = Mod(1, 19)/*Mod(7,19) is just another cubic root*/
207: @eprog\noindent
208:
209: \syn{gpow}{x,n,\var{prec}} for $x\hbox{\kbd{\pow}}n$.
210:
211: \subsecidx{shift}$(x,n)$ or $x$ \kbd{<<} $n$ (= $x$ \kbd{>>} $(-n)$): shifts
212: $x$ componentwise left by $n$ bits if $n\ge0$ and right by $|n|$ bits if
213: $n<0$. A left shift by $n$ corresponds to multiplication by $2^n$. A right
214: shift of an integer $x$ by $|n|$ corresponds to a Euclidean division of
215: $x$ by $2^{|n|}$ with a
216: remainder of the same sign as $x$, hence is not the same (in general) as
217: $x \kbd{\bs} 2^n$.
218:
219: \syn{gshift}{x,n} where $n$ is a \kbd{long}.
220:
221: \subsecidx{shiftmul}$(x,n)$: multiplies $x$ by $2^n$. The difference with
222: \kbd{shift} is that when $n<0$, ordinary division takes place, hence for
223: example if $x$ is an integer the result may be a fraction, while for
224: \kbd{shift} Euclidean division takes place when $n<0$ hence if $x$ is an
225: integer the result is still an integer.
226:
227: \syn{gmul2n}{x,n} where $n$ is a \kbd{long}.
228:
229: \subsec{Comparison and boolean operators}.\sidx{boolean operators}
230: The six standard \idx{comparison operators} \kbd{<=}, \kbd{<}, \kbd{>=},
231: \kbd{>}, \kbd{==}, \kbd{!=} are available in GP, and in library mode under
232: the names \tet{gle}, \tet{glt}, \tet{gge}, \tet{ggt}, \tet{geq}, \tet{gne}
233: respectively. The library syntax is $\var{co}(x,y)$, where \var{co} is the
234: comparison operator. The result is 1 (as a \kbd{GEN}) if the comparison is
235: true, 0 (as a \kbd{GEN}) if it is false.
236:
237: The standard boolean functions \kbd{||} (\idx{inclusive or}), \kbd{\&\&}
238: (\idx{and})\sidx{or} and \kbd{!} (\idx{not}) are also available, and the
239: library syntax is $\teb{gor}(x,y)$, $\teb{gand}(x,y)$ and $\teb{gnot}(x)$
240: respectively.
241:
242: In library mode, it is in fact usually preferable to use the two basic
243: functions which are $\teb{gcmp}(x,y)$ which gives the sign (1, 0, or -1) of
244: $x-y$, where $x$ and $y$ must be in $\R$, and $\teb{gegal}(x,y)$ which
245: can be applied to any two PARI objects $x$ and $y$ and gives 1 (i.e.~true) if
246: they are equal (but not necessarily identical), 0 (i.e.~false) otherwise.
247: Particular cases of \teb{gegal} which should be used are $\teb{gcmp0}(x)$
248: ($x==0$ ?), $\teb{gcmp1}(x)$ ($x==1$ ?), and
249: $\teb{gcmp_1}(x)$ ($x==-1$ ?).
250:
251: Note that $\teb{gcmp0}(x)$ tests whether $x$ is equal to zero, even if $x$ is
252: not an exact object. To test whether $x$ is an exact object which is equal to
253: zero, one must use $\tet{isexactzero}$.
254:
255: Also note that the \kbd{gcmp} and \kbd{gegal} functions return a C-integer,
256: and \var{not} a \kbd{GEN} like \kbd{gle} etc.
257:
258: \smallskip
259: GP accepts the following synonyms for some of the above functions: since we
260: thought it might easily lead to confusion, we don't use the customary C
261: operators for bitwise \kbd{and} or bitwise \kbd{or} (use \tet{bitand} or
262: \tet{bitor}), hence \kbd{|} and \kbd{\&} are accepted as\sidx{bitwise
263: and}\sidx{bitwise or} synonyms of \kbd{||} and \kbd{\&\&} respectively.
264: Also, \kbd{<>} is accepted as a synonym for \kbd{!=}. On the other hand,
265: \kbd{=} is definitely \var{not} a synonym for \kbd{==} since it is the
266: assignment statement.
267:
268: \subsecidx{lex}$(x,y)$: gives the result of a lexicographic comparison
269: between $x$ and $y$. This is to be interpreted in quite a wide sense. For
270: example, the vector $[1,3]$ will be considered smaller than the longer
271: vector $[1,3,-1]$ (but of course larger than $[1,2,5]$),
272: i.e.~\kbd{lex([1,3], [1,3,-1])} will return $-1$.
273:
274: \syn{lexcmp}{x,y}.
275:
276: \subsecidx{sign}$(x)$: \idx{sign} ($0$, $1$ or $-1$) of $x$, which must be of
277: type integer, real or fraction.
278:
279: \syn{gsigne}{x}. The result is a \kbd{long}.
280:
281: \subsecidx{max}$(x,y)$ and \teb{min}$(x,y)$: creates the
282: maximum and minimum of $x$ and $y$ when they can be compared.
283:
284: \syn{gmax}{x,y} and $\teb{gmin}(x,y)$.
285:
286: \subsecidx{vecmax}$(x)$: if $x$ is a vector or a matrix, returns the maximum
287: of the elements of $x$, otherwise returns a copy of $x$. Returns $-\infty$
288: in the form of $-(2^{31}-1)$ (or $-(2^{63}-1)$ for 64-bit machines) if $x$ is
289: empty.
290:
291: \syn{vecmax}{x}.
292:
293: \subsecidx{vecmin}$(x)$: if $x$ is a vector or a matrix, returns the minimum
294: of the elements of $x$, otherwise returns a copy of $x$. Returns $+\infty$
295: in the form of $2^{31}-1$ (or $2^{63}-1$ for 64-bit machines) if $x$ is empty.
296:
297: \syn{vecmin}{x}.
298:
299: \section{Conversions and similar elementary functions or commands}
300: \label{se:conversion}
301:
302: \noindent
303: Many of the conversion functions are rounding or truncating operations. In
304: this case, if the argument is a rational function, the result is the
305: Euclidean quotient of the numerator by the denominator, and if the argument
306: is a vector or a matrix, the operation is done componentwise. This will not
307: be restated for every function.
308:
309: \subsecidx{List}$({x=[\,]})$: transforms a (row or column) vector $x$
310: into a list. The only other way to create a \typ{LIST} is to use the
311: function \kbd{listcreate}.
312:
313: This is useless in library mode.
314:
315: \subsecidx{Mat}$({x=[\,]})$: transforms the object $x$ into a matrix.
316: If $x$ is not a vector or a matrix, this creates a $1\times 1$ matrix.
317: If $x$ is a row (resp. column) vector, this creates a 1-row (resp.
318: 1-column) matrix. If $x$ is already a matrix, a copy of $x$ is created.
319:
320: This function can be useful in connection with the function \kbd{concat}
321: (see there).
322:
323: \syn{gtomat}{x}.
324:
325: \subsecidx{Mod}$(x,y,\{\fl=0\})$:\label{se:Mod} creates the PARI object
326: $(x \mod y)$, i.e.~an integermod or a polmod. $y$ must be an integer or a
327: polynomial. If $y$ is an integer, $x$ must be an integer, a rational
328: number, or a $p$-adic number compatible with the modulus $y$. If $y$ is a
329: polynomial, $x$ must be a scalar (which is not a polmod), a polynomial, a
330: rational function, or a power series.
331:
332: This function is not the same as $x$ \kbd{\%} $y$, the result of which is an
333: integer or a polynomial.
334:
335: If $\fl$ is equal to $1$, the modulus of the created result is put on the
336: heap and not on the stack, and hence becomes a permanent copy which cannot be
337: erased later by garbage collecting (see \secref{se:garbage}). Functions
338: will operate faster on such objects and memory consumption will be lower.
339: On the other hand, care should be taken to avoid creating too many such
340: objects.
341:
342: Under GP, the same effect can be obtained by assigning the object to a GP
343: variable (the value of which is a permanent object for the duration of the
344: relevant library function call, and is treated as such). This value is
345: subject to garbage collection, since it will be deleted when the value
346: changes. This is preferable and the above flag is only retained for
347: compatibility reasons (it can still be useful in library mode).
348:
349: \syn{Mod0}{x,y,\fl}. Also available are
350:
351: $\bullet$ for $\fl=1$: $\teb{gmodulo}(x,y)$.
352:
353: $\bullet$ for $\fl=0$: $\teb{gmodulcp}(x,y)$.
354:
355: \subsecidx{Pol}$(x,\{v=x\})$: transforms the object $x$ into a polynomial with
356: main variable $v$. If $x$ is a scalar, this gives a constant polynomial. If
357: $x$ is a power series, the effect is identical to \kbd{truncate} (see there),
358: i.e.~it chops off the $O(X^k)$. If $x$ is a vector, this function creates
359: the polynomial whose coefficients are given in $x$, with $x[1]$ being the
360: leading coefficient (which can be zero).
361:
362: Warning: this is \var{not} a substitution function. It is intended to be
363: quick and dirty. So if you try \kbd{Pol(a,y)} on the polynomial \kbd{a = x+y},
364: you will get \kbd{y+y}, which is not a valid PARI object.
365:
366: \syn{gtopoly}{x,v}, where $v$ is a variable number.
367:
368: \subsecidx{Polrev}$(x,\{v=x\})$: transform the object $x$ into a polynomial
369: with main variable $v$. If $x$ is a scalar, this gives a constant polynomial.
370: If $x$ is a power series, the effect is identical to \kbd{truncate} (see
371: there), i.e.~it chops off the $O(X^k)$. If $x$ is a vector, this function
372: creates the polynomial whose coefficients are given in $x$, with $x[1]$ being
373: the constant term. Note that this is the reverse of \kbd{Pol} if $x$ is a
374: vector, otherwise it is identical to \kbd{Pol}.
375:
376: \syn{gtopolyrev}{x,v}, where $v$ is a variable number.
377:
378: \subsecidx{Qfb}$(a,b,c,\{D=0.\})$: creates the binary quadratic form
379: $ax^2+bxy+cy^2$. If $b^2-4ac>0$, initialize \idx{Shanks}' distance
380: function to $D$.
381:
382: \syn{Qfb0}{a,b,c,D,\var{prec}}. Also available are
383: $\teb{qfi}(a,b,c)$ (when $b^2-4ac<0$), and
384: $\teb{qfr}(a,b,c,d)$ (when $b^2-4ac>0$).\sidx{binary quadratic form}
385:
386: \subsecidx{Ser}$(x,\{v=x\})$: transforms the object $x$ into a power series
387: with main variable $v$ ($x$ by default). If $x$ is a scalar, this gives a
388: constant power series with precision given by the default \kbd{serieslength}
389: (corresponding to the C global variable \kbd{precdl}). If $x$ is a
390: polynomial, the precision is the greatest of \kbd{precdl} and the degree of
391: the polynomial. If $x$ is a vector, the precision is similarly given, and the
392: coefficients of the vector are understood to be the coefficients of the power
393: series starting from the constant term (i.e.~the reverse of the function
394: \kbd{Pol}).
395:
396: The warning given for \kbd{Pol} applies here: this is not a substitution
397: function.
398:
399: \syn{gtoser}{x,v}, where $v$ is a variable number (i.e.~a C integer).
400:
401: \subsecidx{Set}$(\{x=[\,]\})$: converts $x$ into a set, i.e.~into a row vector
402: with strictly increasing entries. $x$ can be of any type, but is most useful
403: when $x$ is already a vector. The components of $x$ are put in canonical form
404: (type \typ{STR}) so as to be easily sorted. To recover an ordinary \kbd{GEN}
405: from such an element, you can apply \tet{eval} to it.
406:
407: \syn{gtoset}{x}.
408:
409: \subsecidx{Str}$(\{x=\hbox{\kbd{""}}\},\{\fl=0\})$: converts $x$ into a
410: character string (type \typ{STR}, the empty string if $x$ is omitted). To
411: recover an ordinary \kbd{GEN} from a string, apply \kbd{eval} to it. The
412: arguments of \kbd{Str} are evaluated in string context (see
413: \secref{se:strings}). If \fl\ is set, treat $x$ as a filename and perform
414: \idx{environment expansion} on the string. This feature can be used to read
415: \idx{environment variable} values.
416:
417: \bprog
418: ? i = 1; Str("x" i)
419: %1 = "x1"
420: ? eval(%)
421: %2 = x1;
422: ? Str("$HOME", 1)
423: %3 = "/home/pari"
424: @eprog
425:
426: \syn{strtoGENstr}{x,\fl}. This function is mostly useless in library mode. Use
427: the pair \tet{strtoGEN}/\tet{GENtostr} to convert between \kbd{char*} and
428: \kbd{GEN}.
429:
430: \subsecidx{Vec}$({x=[\,]})$: transforms the object $x$ into a row vector.
431: The vector will be with one component only, except when $x$ is a
432: vector/matrix or a quadratic form (in which case the resulting vector is
433: simply the initial object considered as a row vector), a character string
434: (a vector of individual characters is returned), but more importantly when
435: $x$ is a polynomial or a power series. In the case of a polynomial, the
436: coefficients of the vector start with the leading coefficient of the
437: polynomial, while for power series only the significant coefficients are
438: taken into account, but this time by increasing order of degree.
439:
440: \syn{gtovec}{x}.
441:
442: \subsecidx{Vecsmall}$({x=[\,]})$: transforms the object $x$ into a row
443: vector of type \typ{VECSMALL}. This acts as \kbd{Vec}, but only on a
444: limited set of objects (the result must be representable as a vector of small
445: integers). In particular, polynomials and power series are forbidden.
446:
447: \syn{gtovecsmall}{x}.
448:
449: \subsecidx{binary}$(x)$: outputs the vector of the binary digits of $|x|$.
450: Here $x$ can be an integer, a real number (in which case the result has two
451: components, one for the integer part, one for the fractional part) or a
452: vector/matrix.
453:
454: \syn{binaire}{x}.
455:
456: \subsecidx{bitand}$(x,y)$: bitwise \tet{and}\sidx{bitwise and} of two
457: integers $x$ and $y$, that is the integer
458: $$\sum (x_i~\kbd{and}~y_i) 2^i$$
459:
460: Negative numbers behave as if modulo a huge power of $2$.
461:
462: \syn{gbitand}{x,y}.
463:
464: \subsecidx{bitneg}$(x,\{n=-1\})$: \idx{bitwise negation} of an integer $x$,
465: truncated to $n$ bits, that is the integer
466: $$\sum_{i=0}^n \kbd{not}(x_i) 2^i$$
467: The special case $n=-1$ means no truncation: an infinite sequence of
468: leading $1$ is then represented as a negative number.
469:
470: Negative numbers behave as if modulo a huge power of $2$.
471:
472: \syn{gbitneg}{x}.
473:
474: \subsecidx{bitnegimply}$(x,y)$: bitwise negated imply of two integers $x$
475: and $y$ (or \kbd{not} $(x \Rightarrow y)$), that is the integer
476: $$\sum (x_i~\kbd{and not}(y_i)) 2^i$$
477:
478: Negative numbers behave as if modulo a huge power of $2$.
479:
480: \syn{gbitnegimply}{x,y}.
481:
482: \subsecidx{bitor}$(x,y)$: bitwise (inclusive) \tet{or}\sidx{bitwise
483: inclusive or} of two integers $x$ and $y$, that is the integer
484: $$\sum (x_i~\kbd{or}~y_i) 2^i$$
485:
486: Negative numbers behave as if modulo a huge power of $2$.
487:
488: \syn{gbitor}{x,y}.
489:
490: \subsecidx{bittest}$(x,n)$: outputs the $n^{\text{th}}$ bit of $|x|$ starting
491: from the right (i.e.~the coefficient of $2^n$ in the binary expansion of $x$).
492: The result is 0 or 1. To extract several bits at once as a vector, pass a
493: vector for $n$.
494:
495: \syn{bittest}{x,n}, where $n$ and the result are \kbd{long}s.
496:
497: \subsecidx{bitxor}$(x,y)$: bitwise (exclusive) \tet{or}\sidx{bitwise
498: exclusive or} of two integers $x$ and $y$, that is the integer
499: $$\sum (x_i~\kbd{xor}~y_i) 2^i$$
500: Negative numbers behave as if modulo a huge power of $2$.
501:
502: \syn{gbitxor}{x,y}.
503:
504: \subsecidx{ceil}$(x)$: ceiling of $x$. When $x$ is in $\R$,
505: the result is the smallest integer greater than or equal to $x$. Applied to a
506: rational function, $\kbd{ceil}(x)$ returns the euclidian quotient of the
507: numerator by the denominator.
508:
509: \syn{gceil}{x}.
510:
511: \subsecidx{centerlift}$(x,\{v\})$: lifts an element $x=a \bmod n$ of $\Z/n\Z$
512: to $a$ in $\Z$, and similarly lifts a polmod to a polynomial. This is the
513: same as \tet{lift} except that in the particular case of elements of
514: $\Z/n\Z$, the lift $y$ is such that $-n/2<y\le n/2$. If $x$ is of type
515: fraction, complex, quadratic, polynomial, power series, rational function,
516: vector or matrix, the lift is done for each coefficient. Reals are forbidden.
517:
518: \syn{centerlift0}{x,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded
519: as $-1$. Also available is \teb{centerlift}$(x)$ = \kbd{centerlift0($x$,-1)}.
520:
521: \subsecidx{changevar}$(x,y)$: creates a copy of the object $x$ where its
522: variables are modified according to the permutation specified by the vector
523: $y$. For example, assume that the variables have been introduced in the
524: order \kbd{x}, \kbd{a}, \kbd{b}, \kbd{c}. Then, if $y$ is the vector
525: \kbd{[x,c,a,b]}, the variable \kbd{a} will be replaced by \kbd{c}, \kbd{b} by
526: \kbd{a}, and \kbd{c} by \kbd{b}, \kbd{x} being unchanged. Note that the
527: permutation must be completely specified, e.g.~\kbd{[c,a,b]} would not work,
528: since this would replace \kbd{x} by \kbd{c}, and leave \kbd{a} and \kbd{b}
529: unchanged (as well as \kbd{c} which is the fourth variable of the initial
530: list). In particular, the new variable names must be distinct.
531:
532: \syn{changevar}{x,y}.
533:
534: \subsec{components of a PARI object}:
535:
536: There are essentially three ways to extract the \idx{components} from a PARI
537: object.
538:
539: The first and most general, is the function $\teb{component}(x,n)$ which
540: extracts the $n^{\text{th}}$-component of $x$. This is to be understood as
541: follows: every PARI type has one or two initial \idx{code words}. The
542: components are counted, starting at 1, after these code words. In particular
543: if $x$ is a vector, this is indeed the $n^{\text{th}}$-component of $x$, if
544: $x$ is a matrix, the $n^{\text{th}}$ column, if $x$ is a polynomial, the
545: $n^{\text{th}}$ coefficient (i.e.~of degree $n-1$), and for power series, the
546: $n^{\text{th}}$ significant coefficient. The use of the function
547: \kbd{component} implies the knowledge of the structure of the different PARI
548: types, which can be recalled by typing \b{t} under GP.
549:
550: \syn{compo}{x,n}, where $n$ is a \kbd{long}.
551:
552: The two other methods are more natural but more restricted. The function
553: \funs{polcoeff}{x,n} gives the coefficient of degree $n$ of the polynomial
554: or power series $x$, with respect to the main variable of $x$ (to check
555: variable ordering, or to change it, use the function \tet{reorder}, see
556: \secref{se:reorder}). In particular if $n$ is less than the valuation of
557: $x$ or in the case of a polynomial, greater than the degree, the result is
558: zero (contrary to \kbd{compo} which would send an error message). If $x$ is
559: a power series and $n$ is greater than the largest significant degree, then
560: an error message is issued.
561:
562: For greater flexibility, vector or matrix types are also accepted for $x$,
563: and the meaning is then identical with that of \kbd{compo}.
564:
565: Finally note that a scalar type is considered by \kbd{polcoeff} as a
566: polynomial of degree zero.
567:
568: \syn{truecoeff}{x,n}.
569:
570: The third method is specific to vectors or matrices under GP. If $x$ is a
571: (row or column) vector, then \tet{x[n]} represents the $n^{\text{th}}$
572: component of $x$, i.e.~\kbd{compo(x,n)}. It is more natural and shorter to
573: write. If $x$ is a matrix, \tet{x[m,n]} represents the coefficient of
574: row \kbd{m} and column \kbd{n} of the matrix, \tet{x[m,]} represents
575: the $m^{\text{th}}$ \var{row} of $x$, and \tet{x[,n]} represents
576: the $n^{\text{th}}$ \var{column} of $x$.
577:
578: Finally note that in library mode, the macros \teb{coeff} and \teb{mael}
579: are available to deal with the non-recursivity of the \kbd{GEN} type from the
580: compiler's point of view. See the discussion on typecasts in Chapter 4.
581:
582: \subsecidx{conj}$(x)$: conjugate of $x$. The meaning of this
583: is clear, except that for real quadratic numbers, it means conjugation in the
584: real quadratic field. This function has no effect on integers, reals,
585: integermods, fractions or $p$-adics. The only forbidden type is polmod
586: (see \kbd{conjvec} for this).
587:
588: \syn{gconj}{x}.
589:
590: \subsecidx{conjvec}$(x)$: conjugate vector representation of $x$. If $x$ is a
591: polmod, equal to \kbd{Mod}$(a,q)$, this gives a vector of length
592: $\text{degree}(q)$ containing the complex embeddings of the polmod if $q$ has
593: integral or rational coefficients, and the conjugates of the polmod if $q$
594: has some integermod coefficients. The order is the same as that of the
595: \kbd{polroots} functions. If $x$ is an integer or a rational number, the
596: result is~$x$. If $x$ is a (row or column) vector, the result is a matrix
597: whose columns are the conjugate vectors of the individual elements of $x$.
598:
599: \syn{conjvec}{x,\var{prec}}.
600:
601: \subsecidx{denominator}$(x)$: lowest denominator of $x$. The meaning of this
602: is clear when $x$ is a rational number or function. When $x$ is an integer
603: or a polynomial, the result is equal to $1$. When $x$ is a vector or a matrix,
604: the lowest common denominator of the components of $x$ is computed. All other
605: types are forbidden.
606:
607: \syn{denom}{x}.
608:
609: \subsecidx{floor}$(x)$: floor of $x$. When $x$ is in $\R$, the result is the
610: largest integer smaller than or equal to $x$. Applied to a rational function,
611: $\kbd{floor}(x)$ returns the euclidian quotient of the numerator by the
612: denominator.
613:
614: \syn{gfloor}{x}.
615:
616: \subsecidx{frac}$(x)$: fractional part of $x$. Identical to
617: $x-\text{floor}(x)$. If $x$ is real, the result is in $[0,1[$.
618:
619: \syn{gfrac}{x}.
620:
621: \subsecidx{imag}$(x)$: imaginary part of $x$. When
622: $x$ is a quadratic number, this is the coefficient of $\omega$ in
623: the ``canonical'' integral basis $(1,\omega)$.
624:
625: \syn{gimag}{x}.
626:
627: \subsecidx{length}$(x)$: number of non-code words in $x$ really used (i.e.~the
628: effective length minus 2 for integers and polynomials). In particular,
629: the degree of a polynomial is equal to its length minus 1. If $x$ has type
630: \typ{STR}, output number of letters.
631:
632: \syn{glength}{x} and the result is a C long.
633:
634: \subsecidx{lift}$(x,\{v\})$: lifts an element $x=a \bmod n$ of $\Z/n\Z$ to
635: $a$ in $\Z$, and similarly lifts a polmod to a polynomial if $v$ is omitted.
636: Otherwise, lifts only polmods with main variable $v$ (if $v$ does not occur
637: in $x$, lifts only intmods). If $x$ is of type fraction, complex, quadratic,
638: polynomial, power series, rational function, vector or matrix, the lift is
639: done for each coefficient. For $p$-adics, this routine acts as
640: \tet{truncate}. It is not allowed to have $x$ of type \typ{REAL}.
641:
642: \syn{lift0}{x,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded as
643: $-1$. Also available is \teb{lift}$(x)$ = \kbd{lift0($x$,-1)}.
644:
645: \subsecidx{norm}$(x)$: algebraic norm of $x$, i.e.~the product of $x$ with
646: its conjugate (no square roots are taken), or conjugates for polmods. For
647: vectors and matrices, the norm is taken componentwise and hence is not the
648: $L^2$-norm (see \kbd{norml2}). Note that the norm of an element of
649: $\R$ is its square, so as to be compatible with the complex norm.
650:
651: \syn{gnorm}{x}.
652:
653: \subsecidx{norml2}$(x)$: square of the $L^2$-norm of $x$. $x$ must
654: be a (row or column) vector.
655:
656: \syn{gnorml2}{x}.
657:
658: \subsecidx{numerator}$(x)$: numerator of $x$. When $x$ is a rational number
659: or function, the meaning is clear. When $x$ is an integer or a polynomial,
660: the result is $x$ itself. When $x$ is a vector or a matrix, then
661: \kbd{numerator(x)} is defined to be \kbd{denominator(x)*x}. All other types
662: are forbidden.
663:
664: \syn{numer}{x}.
665:
666: \subsecidx{numtoperm}$(n,k)$: generates the $k$-th permutation (as a
667: row vector of length $n$) of the numbers $1$ to $n$. The number $k$ is taken
668: modulo $n!\,$, i.e.~inverse function of \tet{permtonum}.
669:
670: \syn{numtoperm}{n,k}, where $n$ is a \kbd{long}.
671:
672: \subsecidx{padicprec}$(x,p)$: absolute $p$-adic precision of the object $x$.
673: This is the minimum precision of the components of $x$. The result is
674: \kbd{VERYBIGINT} ($2^{31}-1$ for 32-bit machines or $2^{63}-1$ for 64-bit
675: machines) if $x$ is an exact object.
676:
677: \syn{padicprec}{x,p} and the result is a \kbd{long}
678: integer.
679:
680: \subsecidx{permtonum}$(x)$: given a permutation $x$ on $n$ elements,
681: gives the number $k$ such that $x=\kbd{numtoperm(n,k)}$, i.e.~inverse
682: function of \tet{numtoperm}.
683:
684: \syn{permtonum}{x}.
685:
686: \subsecidx{precision}$(x,\{n\})$: gives the precision in decimal digits of the
687: PARI object $x$. If $x$ is an exact object, the largest single precision
688: integer is returned. If $n$ is not omitted, creates a new object equal to $x$
689: with a new precision $n$. This is to be understood as follows:
690:
691: For exact types, no change. For $x$ a vector or a matrix, the operation
692: is done componentwise.
693:
694: For real $x$, $n$ is the number of desired significant \var{decimal} digits.
695: If $n$ is smaller than the precision of $x$, $x$ is truncated, otherwise $x$
696: is extended with zeros.
697:
698: For $x$ a $p$-adic or a power series, $n$ is the desired number of
699: significant $p$-adic or $X$-adic digits, where $X$ is the main variable of
700: $x$.
701:
702: Note that the function \kbd{precision} never changes the type of the result.
703: In particular it is not possible to use it to obtain a polynomial from a
704: power series. For that, see \kbd{truncate}.
705:
706: \syn{precision0}{x,n}, where $n$ is a \kbd{long}. Also available are
707: $\teb{ggprecision}(x)$ (result is a \kbd{GEN}) and $\teb{gprec}(x,n)$, where
708: $n$ is a \kbd{long}.
709:
710: \subsecidx{random}$(\{N=2^{31}\})$: gives a random integer between 0 and
711: $N-1$. $N$ can be arbitrary large. This is an internal PARI function and does
712: not depend on the system's random number generator. Note that the resulting
713: integer is obtained by means of linear congruences and will not be well
714: distributed in arithmetic progressions.
715:
716: \syn{genrand}{N}.
717:
718: \subsecidx{real}$(x)$: real part of $x$. In the case where $x$ is a quadratic
719: number, this is the coefficient of $1$ in the ``canonical'' integral basis
720: $(1,\omega)$.
721:
722: \syn{greal}{x}.
723:
724: \subsecidx{round}$(x,\{\&e\})$: If $x$ is in $\R$, rounds $x$ to the nearest
725: integer and sets $e$ to the number of error bits, that is the binary exponent
726: of the difference between the original and the rounded value (the
727: ``fractional part''). If the exponent of $x$ is too large compared to its
728: precision (i.e.~$e>0$), the result is undefined and an error occurs if $e$
729: was not given.
730:
731: \misctitle{Important remark:} note that, contrary to the other truncation
732: functions, this function operates on every coefficient at every level of a
733: PARI object. For example
734: $$\text{truncate}\left(\dfrac{2.4*X^2-1.7}{X}\right)=2.4*X,$$ whereas
735: $$\text{round}\left(\dfrac{2.4*X^2-1.7}{X}\right)=\dfrac{2*X^2-2}{X}.$$
736: An important use of \kbd{round} is to get exact results after a long
737: approximate computation, when theory tells you that the coefficients
738: must be integers.
739:
740: \syn{grndtoi}{x,\&e}, where $e$ is a \kbd{long} integer. Also available is
741: $\teb{ground}(x)$.
742:
743: \subsecidx{simplify}$(x)$: this function tries to simplify the object $x$ as
744: much as it can. The simplifications do not concern rational functions (which
745: PARI automatically tries to simplify), but type changes. Specifically, a
746: complex or quadratic number whose imaginary part is exactly equal to 0
747: (i.e.~not a real zero) is converted to its real part, and a polynomial of
748: degree zero is converted to its constant term. For all types, this of course
749: occurs recursively. This function is useful in any case, but in particular
750: before the use of arithmetic functions which expect integer arguments, and
751: not for example a complex number of 0 imaginary part and integer real part
752: (which is however printed as an integer).
753:
754: \syn{simplify}{x}.
755:
756: \subsecidx{sizebyte}$(x)$: outputs the total number of bytes occupied by the
757: tree representing the PARI object $x$.
758:
759: \syn{taille2}{x} which returns a \kbd{long}. The
760: function \teb{taille} returns the number of \var{words} instead.
761:
762: \subsecidx{sizedigit}$(x)$: outputs a quick bound for the number of decimal
763: digits of (the components of) $x$, off by at most $1$. If you want the
764: exact value, you can use \kbd{length(Str(x))}, which is much slower.
765:
766: \syn{sizedigit}{x} which returns a \kbd{long}.
767:
768: \subsecidx{truncate}$(x,\{\&e\})$: truncates $x$ and sets $e$ to the number of
769: error bits. When $x$ is in $\R$, this means that the part after the decimal
770: point is chopped away, $e$ is the binary exponent of the difference between
771: the original and the truncated value (the ``fractional part''). If the
772: exponent of $x$ is too large compared to its precision (i.e.~$e>0$), the
773: result is undefined and an error occurs if $e$ was not given. The function
774: applies componentwise on vector / matrices; $e$ is then the maximal number of
775: error bits. If $x$ is a rational function, the result is the ``integer part''
776: (Euclidean quotient of numerator by denominator) and $e$ is not set.
777:
778: Note a very special use of \kbd{truncate}: when applied to a power series, it
779: transforms it into a polynomial or a rational function with denominator
780: a power of $X$, by chopping away the $O(X^k)$. Similarly, when applied to
781: a $p$-adic number, it transforms it into an integer or a rational number
782: by chopping away the $O(p^k)$.
783:
784: \syn{gcvtoi}{x,\&e}, where $e$ is a \kbd{long} integer. Also available is
785: \teb{gtrunc}$(x)$.
786:
787: \subsecidx{valuation}$(x,p)$:\label{se:valuation} computes the highest
788: exponent of $p$ dividing $x$. If $p$ is of type integer, $x$ must be an
789: integer, an integermod whose modulus is divisible by $p$, a fraction, a
790: $q$-adic number with $q=p$, or a polynomial or power series in which case the
791: valuation is the minimum of the valuation of the coefficients.
792:
793: If $p$ is of type polynomial, $x$ must be of type polynomial or rational
794: function, and also a power series if $x$ is a monomial. Finally, the
795: valuation of a vector, complex or quadratic number is the minimum of the
796: component valuations.
797:
798: If $x=0$, the result is \kbd{VERYBIGINT} ($2^{31}-1$ for 32-bit machines or
799: $2^{63}-1$ for 64-bit machines) if $x$ is an exact object. If $x$ is a
800: $p$-adic numbers or power series, the result is the exponent of the zero.
801: Any other type combinations gives an error.
802:
803: \syn{ggval}{x,p}, and the result is a \kbd{long}.
804:
805: \subsecidx{variable}$(x)$: gives the main variable of the object $x$, and
806: $p$ if $x$ is a $p$-adic number. Gives an error if $x$ has no variable
807: associated to it. Note that this function is useful only in GP, since in
808: library mode the function \kbd{gvar} is more appropriate.
809:
810: \syn{gpolvar}{x}. However, in library mode, this function should not be used.
811: Instead, test whether $x$ is a $p$-adic (type \typ{PADIC}), in which case $p$
812: is in $x[2]$, or call the function $\key{gvar}(x)$ which returns the variable
813: \var{number} of $x$ if it exists, \kbd{BIGINT} otherwise.
814:
815: \section{Transcendental functions}\label{se:trans}
816:
817: As a general rule, which of course in some cases may have exceptions,
818: transcendental functions operate in the following way:
819:
820: $\bullet$ If the argument is either an integer, a real, a rational, a complex
821: or a quadratic number, it is, if necessary, first converted to a real (or
822: complex) number using the current \idx{precision} held in the default
823: \kbd{realprecision}. Note that only exact arguments are converted, while
824: inexact arguments such as reals are not.
825:
826: Under GP this is transparent to the user, but when programming in library
827: mode, care must be taken to supply a meaningful parameter \var{prec} as the
828: last argument of the function if the first argument is an exact object.
829: This parameter is ignored if the argument is inexact.
830:
831: Note that in library mode the precision argument \var{prec} is a word
832: count including codewords, i.e.~represents the length in words of a real
833: number, while under GP the precision (which is changed by the metacommand
834: \b{p} or using \kbd{default(realprecision,...)}) is the number of significant
835: decimal digits.
836:
837: Note that some accuracies attainable on 32-bit machines cannot be attained
838: on 64-bit machines for parity reasons. For example the default GP accuracy
839: is 28 decimal digits on 32-bit machines, corresponding to \var{prec} having
840: the value 5, but this cannot be attained on 64-bit machines.\smallskip
841:
842: After possible conversion, the function is computed. Note that even if the
843: argument is real, the result may be complex (e.g.~$\text{acos}(2.0)$ or
844: $\text{acosh}(0.0)$). Note also that the principal branch is always chosen.
845:
846: $\bullet$ If the argument is an integermod or a $p$-adic, at present only a
847: few functions like \kbd{sqrt} (square root), \kbd{sqr} (square), \kbd{log},
848: \kbd{exp}, powering, \kbd{teichmuller} (Teichm\"uller character) and
849: \kbd{agm} (arithmetic-geometric mean) are implemented.
850:
851: Note that in the case of a $2$-adic number, $\kbd{sqr}(x)$ may not be
852: identical to $x*x$: for example if $x = 1+O(2^5)$ and $y = 1+O(2^5)$ then
853: $x*y = 1+O(2^5)$ while $\kbd{sqr}(x) = 1+O(2^6)$. Here, $x * x$ yields the
854: same result as $\kbd{sqr}(x)$ since the two operands are known to be {\it
855: identical}. The same statement holds true for $p$-adics raised to the power
856: $n$, where $v_p(n) > 0$.
857:
858: \misctitle{Remark:} note that if we wanted to be strictly consistent with
859: the PARI philosophy, we should have $x*y = (4 \mod 8)$ and $\kbd{sqr}(x) =
860: (4 \mod 32)$ when both $x$ and $y$ are congruent to $2$ modulo $4$.
861: However, since integermod is an exact object, PARI assumes that the modulus
862: must not change, and the result is hence $(0\, \mod\, 4)$ in both cases. On
863: the other hand, $p$-adics are not exact objects, hence are treated
864: differently.
865:
866: $\bullet$ If the argument is a polynomial, power series or rational function,
867: it is, if necessary, first converted to a power series using the current
868: precision held in the variable \tet{precdl}. Under GP this again is
869: transparent to the user. When programming in library mode, however, the
870: global variable \kbd{precdl} must be set before calling the function if the
871: argument has an exact type (i.e.~not a power series). Here \kbd{precdl} is
872: not an argument of the function, but a global variable.
873:
874: Then the Taylor series expansion of the function around $X=0$ (where $X$ is
875: the main variable) is computed to a number of terms depending on the number
876: of terms of the argument and the function being computed.
877:
878: $\bullet$ If the argument is a vector or a matrix, the result is the
879: componentwise evaluation of the function. In particular, transcendental
880: functions on square matrices, which are not implemented in the present
881: version \vers\ (see Appendix~B however), will have a slightly different name
882: if they are implemented some day.
883:
884: \subseckbd{\pow}: If $y$ is not of type integer, \kbd{x\pow y} has the same
885: effect as \kbd{exp(y*ln(x))}. It can be applied to $p$-adic numbers as
886: well as to the more usual types.\sidx{powering}
887:
888: \syn{gpow}{x,y,\var{prec}}.
889:
890: \subsecidx{Euler}: Euler's constant $0.57721\cdots$. Note that \kbd{Euler}
891: is one of the few special reserved names which cannot be used for variables
892: (the others are \kbd{I} and \kbd{Pi}, as well as all function names).
893: \label{se:euler}
894:
895: \syn{mpeuler}{\var{prec}} where $\var{prec}$ \var{must} be given. Note that
896: this creates $\gamma$ on the PARI stack, but a copy is also created on the
897: heap for quicker computations next time the function is called.
898:
899: \subsecidx{I}: the complex number $\sqrt{-1}$.
900:
901: The library syntax is the global variable \kbd{gi} (of type \kbd{GEN}).
902:
903: \subsecidx{Pi}: the constant $\pi$ ($3.14159\cdots$).\label{se:pi}
904:
905: \syn{mppi}{\var{prec}} where $\var{prec}$ \var{must} be given. Note that this
906: creates $\pi$ on the PARI stack, but a copy is also created on the heap for
907: quicker computations next time the function is called.
908:
909: \subsecidx{abs}$(x)$: absolute value of $x$ (modulus if $x$ is complex).
910: Power series and rational functions are not allowed. Contrary to most
911: transcendental functions, an exact argument is \var{not} converted to a real
912: number before applying \kbd{abs} and an exact result is returned if possible.
913: \bprog
914: ? abs(-1)
915: %1 = 1
916: ? abs(3/7 + 4/7*I)
917: %2 = 5/7
918: ? abs(1 + I)
919: %3 = 1.414213562373095048801688724
920: @eprog
921: \noindent If $x$ is a polynomial, returns $-x$ if the leading coefficient is
922: real and negative else returns $x$. For a power series, the constant
923: coefficient is considered instead.
924:
925: \syn{gabs}{x,\var{prec}}.
926:
927: \subsecidx{acos}$(x)$: principal branch of $\text{cos}^{-1}(x)$,
928: i.e.~such that $\text{Re(acos}(x))\in [0,\pi]$. If
929: $x\in \R$ and $|x|>1$, then $\text{acos}(x)$ is complex.
930:
931: \syn{gacos}{x,\var{prec}}.
932:
933: \subsecidx{acosh}$(x)$: principal branch of $\text{cosh}^{-1}(x)$,
934: i.e.~such that $\text{Im(acosh}(x))\in [0,\pi]$. If
935: $x\in \R$ and $x<1$, then $\text{acosh}(x)$ is complex.
936:
937: \syn{gach}{x,\var{prec}}.
938:
939: \subsecidx{agm}$(x,y)$: arithmetic-geometric mean of $x$ and $y$. In the
940: case of complex or negative numbers, the principal square root is always
941: chosen. $p$-adic or power series arguments are also allowed. Note that
942: a $p$-adic agm exists only if $x/y$ is congruent to 1 modulo $p$ (modulo
943: 16 for $p=2$). $x$ and $y$ cannot both be vectors or matrices.
944:
945: \syn{agm}{x,y,\var{prec}}.
946:
947: \subsecidx{arg}$(x)$: argument of the complex number $x$, such that
948: $-\pi<\text{arg}(x)\le\pi$.
949:
950: \syn{garg}{x,\var{prec}}.
951:
952: \subsecidx{asin}$(x)$: principal branch of $\text{sin}^{-1}(x)$, i.e.~such
953: that $\text{Re(asin}(x))\in [-\pi/2,\pi/2]$. If $x\in \R$ and $|x|>1$ then
954: $\text{asin}(x)$ is complex.
955:
956: \syn{gasin}{x,\var{prec}}.
957:
958: \subsecidx{asinh}$(x)$: principal branch of $\text{sinh}^{-1}(x)$, i.e.~such
959: that $\text{Im(asinh}(x))\in [-\pi/2,\pi/2]$.
960:
961: \syn{gash}{x,\var{prec}}.
962:
963: \subsecidx{atan}$(x)$: principal branch of $\text{tan}^{-1}(x)$, i.e.~such
964: that $\text{Re(atan}(x))\in{} ]-\pi/2,\pi/2[$.
965:
966: \syn{gatan}{x,\var{prec}}.
967:
968: \subsecidx{atanh}$(x)$: principal branch of $\text{tanh}^{-1}(x)$, i.e.~such
969: that $\text{Im(atanh}(x))\in{} ]-\pi/2,\pi/2]$. If $x\in \R$ and $|x|>1$ then
970: $\text{atanh}(x)$ is complex.
971:
972: \syn{gath}{x,\var{prec}}.
973:
974: \subsecidx{bernfrac}$(x)$: Bernoulli number\sidx{Bernoulli numbers} $B_x$,
975: where $B_0=1$, $B_1=-1/2$, $B_2=1/6$,\dots, expressed as a rational number.
976: The argument $x$ should be of type integer.
977:
978: \syn{bernfrac}{x}.
979:
980: \subsecidx{bernreal}$(x)$: Bernoulli number\sidx{Bernoulli numbers}
981: $B_x$, as \kbd{bernfrac}, but $B_x$ is returned as a real number
982: (with the current precision).
983:
984: \syn{bernreal}{x,\var{prec}}.
985:
986: \subsecidx{bernvec}$(x)$: creates a vector containing, as rational numbers,
987: the \idx{Bernoulli numbers} $B_0$, $B_2$,\dots, $B_{2x}$. These Bernoulli
988: numbers can then be used as follows. Assume that this vector has been put
989: into a variable, say \kbd{bernint}. Then you can define under GP:
990: \bprog
991: bern(x) =
992: {
993: if (x == 1, return(-1/2));
994: if (x < 0 || x % 2, return(0));
995: bernint[x/2+1]
996: }
997: @eprog
998: \noindent and then \kbd{bern(k)} gives the Bernoulli number of index $k$ as a
999: rational number, exactly as \kbd{bernreal(k)} gives it as a real number. If
1000: you need only a few values, calling \kbd{bernfrac(k)} each time will be much
1001: more efficient than computing the huge vector above.
1002:
1003: \syn{bernvec}{x}.
1004:
1005: \subsecidx{besseljh}$(n,x)$: $J$-Bessel function of half integral index.
1006: More precisely, $\kbd{besseljh}(n,x)$ computes $J_{n+1/2}(x)$ where $n$
1007: must be of type integer, and $x$ is any element of $\C$. In the
1008: present version \vers, this function is not very accurate when $x$ is
1009: small.
1010:
1011: \syn{jbesselh}{n,x,\var{prec}}.
1012:
1013: \subsecidx{besselk}$(\var{nu},x,\{\fl=0\})$: $K$-Bessel function of index
1014: \var{nu} (which can be complex) and argument $x$. Only real and positive
1015: arguments
1016: $x$ are allowed in the present version \vers. If $\fl$ is equal to 1,
1017: uses another implementation of this function which is often faster.
1018:
1019: \syn{kbessel}{\var{nu},x,\var{prec}} and
1020: $\teb{kbessel2}(\var{nu},x,\var{prec})$ respectively.
1021:
1022: \subsecidx{cos}$(x)$: cosine of $x$.
1023:
1024: \syn{gcos}{x,\var{prec}}.
1025:
1026: \subsecidx{cosh}$(x)$: hyperbolic cosine of $x$.
1027:
1028: \syn{gch}{x,\var{prec}}.
1029:
1030: \subsecidx{cotan}$(x)$: cotangent of $x$.
1031:
1032: \syn{gcotan}{x,\var{prec}}.
1033:
1034: \subsecidx{dilog}$(x)$: principal branch of the dilogarithm of $x$,
1035: i.e.~analytic continuation of the power series $\log_2(x)=\sum_{n\ge1}x^n/n^2$.
1036:
1037: \syn{dilog}{x,\var{prec}}.
1038:
1039: \subsecidx{eint1}$(x,\{n\})$: exponential integral
1040: $\int_x^\infty \dfrac{e^{-t}}{t}\,dt$ ($x\in\R$)
1041:
1042: If $n$ is present, outputs the $n$-dimensional vector
1043: $[\kbd{eint1}(x),\dots,\kbd{eint1}(nx)]$ ($x \geq 0$). This is faster than
1044: repeatedly calling \kbd{eint1($i$ * x)}.
1045:
1046: \syn{veceint1}{x,n,\var{prec}}. Also available is
1047: $\teb{eint1}(x,\var{prec})$.
1048:
1049: \subsecidx{erfc}$(x)$: complementary error function
1050: $(2/\sqrt\pi)\int_x^\infty e^{-t^2}\,dt$.
1051:
1052: \syn{erfc}{x,\var{prec}}.
1053:
1054: \subsecidx{eta}$(x,\{\fl=0\})$: \idx{Dedekind}'s $\eta$ function, without the
1055: $q^{1/24}$. This means the following: if $x$ is a complex number with positive
1056: imaginary part, the result is $\prod_{n=1}^\infty(1-q^n)$, where
1057: $q=e^{2i\pi x}$. If $x$ is a power series (or can be converted to a power
1058: series) with positive valuation, the result is $\prod_{n=1}^\infty(1-x^n)$.
1059:
1060: If $\fl=1$ and $x$ can be converted to a complex number (i.e.~is not a power
1061: series), computes the true $\eta$ function, including the leading $q^{1/24}$.
1062:
1063: \syn{eta}{x,\var{prec}}.
1064:
1065: \subsecidx{exp}$(x)$: exponential of $x$.
1066: $p$-adic arguments with positive valuation are accepted.
1067:
1068: \syn{gexp}{x,\var{prec}}.
1069:
1070: \subsecidx{gammah}$(x)$: gamma function evaluated at the argument
1071: $x+1/2$. When $x$ is an integer, this is much faster than using
1072: $\kbd{gamma}(x+1/2)$.
1073:
1074: \syn{ggamd}{x,\var{prec}}.
1075:
1076: \subsecidx{gamma}$(x)$: gamma function of $x$. In the present version
1077: \vers\ the $p$-adic gamma function is not implemented.
1078:
1079: \syn{ggamma}{x,\var{prec}}.
1080:
1081: \subsecidx{hyperu}$(a,b,x)$: $U$-confluent hypergeometric function with
1082: parameters $a$ and $b$. The parameters $a$ and $b$ can be complex but
1083: the present implementation requires $x$ to be positive.
1084:
1085: \syn{hyperu}{a,b,x,\var{prec}}.
1086:
1087: \subsecidx{incgam}$(s,x,{y})$: incomplete gamma function.
1088:
1089: $x$ must be positive and $s$ real. The result returned is $\int_x^\infty
1090: e^{-t}t^{s-1}\,dt$. When $y$ is given, assume (of course without checking!)
1091: that $y=\Gamma(s)$. For small $x$, this will tremendously speed up the
1092: computation.
1093:
1094: \syn{incgam}{s,x,\var{prec}} and $\teb{incgam4}(s,x,y,\var{prec})$,
1095: respectively. There exist also the functions \teb{incgam1} and
1096: \teb{incgam2} which are used for internal purposes.
1097:
1098: \subsecidx{incgamc}$(s,x)$: complementary incomplete gamma function.
1099:
1100: The arguments $s$ and $x$ must be positive. The result returned is
1101: $\int_0^x e^{-t}t^{s-1}\,dt$, when $x$ is not too large.
1102:
1103: \syn{incgam3}{s,x,\var{prec}}.
1104:
1105: \subsecidx{log}$(x,\{\fl=0\})$: principal branch of the natural logarithm of
1106: $x$, i.e.~such that $\text{Im(ln}(x))\in{} ]-\pi,\pi]$. The result is complex
1107: (with imaginary part equal to $\pi$) if $x\in \R$ and $x<0$.
1108:
1109: $p$-adic arguments are also accepted for $x$, with the convention that
1110: $\ln(p)=0$. Hence in particular $\exp(\ln(x))/x$ will not in general be
1111: equal to 1 but to a $(p-1)$-th root of unity (or $\pm1$ if $p=2$)
1112: times a power of $p$.
1113:
1114: If $\fl$ is equal to 1, use an agm formula suggested by Mestre, when $x$ is
1115: real, otherwise identical to \kbd{log}.
1116:
1117: \syn{glog}{x,\var{prec}} or $\teb{glogagm}(x,\var{prec})$.
1118:
1119: \subsecidx{lngamma}$(x)$: principal branch of the logarithm of the gamma
1120: function of $x$. Can have much larger arguments than \kbd{gamma} itself.
1121: In the present version \vers, the $p$-adic \kbd{lngamma} function is not
1122: implemented.
1123:
1124: \syn{glngamma}{x,\var{prec}}.
1125:
1126: \subsecidx{polylog}$(m,x,{\fl=0})$: one of the different polylogarithms,
1127: depending on \fl:
1128:
1129: If $\fl=0$ or is omitted: $m^\text{th}$ polylogarithm of $x$, i.e.~analytic
1130: continuation of the power series $\text{Li}_m(x)=\sum_{n\ge1}x^n/n^m$. The
1131: program uses the power series when $|x|^2\le1/2$, and the power series
1132: expansion in $\log(x)$ otherwise. It is valid in a large domain (at least
1133: $|x|<230$), but should not be used too far away from the unit circle since it
1134: is then better to use the functional equation linking the value at $x$ to the
1135: value at $1/x$, which takes a trivial form for the variant below. Power
1136: series, polynomial, rational and vector/matrix arguments are allowed.
1137:
1138: For the variants to follow we need a notation: let $\Re_m$
1139: denotes $\Re$ or $\Im$ depending whether $m$ is odd or even.
1140:
1141: If $\fl=1$: modified $m^\text{th}$ polylogarithm of $x$, called
1142: $\tilde D_m(x)$ in Zagier, defined for $|x|\le1$ by
1143: $$\Re_m\left(\sum_{k=0}^{m-1} \dfrac{(-\log|x|)^k}{k!}\text{Li}_{m-k}(x)
1144: +\dfrac{(-\log|x|)^{m-1}}{m!}\log|1-x|\right).$$
1145:
1146: If $\fl=2$: modified $m^\text{th}$ polylogarithm of $x$,
1147: called $D_m(x)$ in Zagier, defined for $|x|\le1$ by
1148: $$\Re_m\left(\sum_{k=0}^{m-1}\dfrac{(-\log|x|)^k}{k!}\text{Li}_{m-k}(x)
1149: -\dfrac{1}{2}\dfrac{(-\log|x|)^m}{m!}\right).$$
1150:
1151: If $\fl=3$: another modified $m^\text{th}$
1152: polylogarithm of $x$, called $P_m(x)$ in Zagier, defined for $|x|\le1$ by
1153: $$\Re_m\left(\sum_{k=0}^{m-1}\dfrac{2^kB_k}{k!}(\log|x|)^k\text{Li}_{m-k}(x)
1154: -\dfrac{2^{m-1}B_m}{m!}(\log|x|)^m\right).$$
1155:
1156: These three functions satisfy the functional equation
1157: $f_m(1/x)=(-1)^{m-1}f_m(x)$.
1158:
1159: \syn{polylog0}{m,x,\fl,\var{prec}}.
1160:
1161: \subsecidx{psi}$(x)$: the $\psi$-function of $x$, i.e.~the
1162: logarithmic derivative $\Gamma'(x)/\Gamma(x)$.
1163:
1164: \syn{gpsi}{x,\var{prec}}.
1165:
1166: \subsecidx{sin}$(x)$: sine of $x$.
1167:
1168: \syn{gsin}{x,\var{prec}}.
1169:
1170: \subsecidx{sinh}$(x)$: hyperbolic sine of $x$.
1171:
1172: \syn{gsh}{x,\var{prec}}.
1173:
1174: \subsecidx{sqr}$(x)$: square of $x$. This operation is not completely
1175: straightforward, i.e.~identical to $x * x$, since it can usually be
1176: computed more efficiently (roughly one-half of the elementary
1177: multiplications can be saved). Also, squaring a $2$-adic number increases
1178: its precision. For example,
1179: \bprog
1180: ? (1 + O(2^4))^2
1181: %1 = 1 + O(2^5)
1182: ? (1 + O(2^4)) * (1 + O(2^4))
1183: %2 = 1 + O(2^4)
1184: @eprog\noindent
1185: Note that this function is also called whenever one multiplies two objects
1186: which are known to be {\it identical}, e.g.~they are the value of the same
1187: variable, or we are computing a power.
1188: \bprog
1189: ? x = (1 + O(2^4)); x * x
1190: %3 = 1 + O(2^5)
1191: ? (1 + O(2^4))^4
1192: %4 = 1 + O(2^6)
1193: @eprog
1194: \noindent(note the difference between \kbd{\%2} and \kbd{\%3} above).
1195:
1196: \syn{gsqr}{x}.
1197:
1198: \subsecidx{sqrt}$(x)$: principal branch of the square root of $x$,
1199: i.e.~such that $\text{Arg}(\text{sqrt}(x))\in{} ]-\pi/2, \pi/2]$, or in other
1200: words such that $\Re(\text{sqrt}(x))>0$ or $\Re(\text{sqrt}(x))=0$ and
1201: $\Im(\text{sqrt}(x))\ge 0$. If $x\in \R$ and $x<0$, then the result is
1202: complex with positive imaginary part.
1203:
1204: Integermod a prime and $p$-adics are allowed as arguments. In that case,
1205: the square root (if it exists) which is returned is the one whose
1206: first $p$-adic digit (or its unique $p$-adic digit in the case of
1207: integermods) is in the interval $[0,p/2]$. When the argument is an
1208: integermod a non-prime (or a non-prime-adic), the result is undefined.
1209:
1210: \syn{gsqrt}{x,\var{prec}}.
1211:
1212: \subsecidx{sqrtn}$(x,n,\{\&z\})$: principal branch of the $n$th root of $x$,
1213: i.e.~such that $\text{Arg}(\text{sqrt}(x))\in{} ]-\pi/n, \pi/n]$.
1214:
1215: Integermod a prime and $p$-adics are allowed as arguments.
1216:
1217: If $z$ is present, it is set to a suitable root of unity allowing to
1218: recover all the other roots. If it was not possible, z is
1219: set to zero.
1220:
1221: The following script computes all roots in all possible cases:
1222:
1223: \bprog
1224: sqrtnall(x,n)=
1225: {
1226: local(V,r,z,r2);
1227: r = sqrtn(x,n, &z);
1228: if (!z, error("Impossible case in sqrtn"));
1229: if (type(x) == "t_INTMOD" || type(x)=="t_PADIC" ,
1230: r2 = r*z; n = 1;
1231: while (r2!=r, r2*=z;n++));
1232: V = vector(n); V[1] = r;
1233: for(i=2, n, V[i] = V[i-1]*z);
1234: V
1235: }
1236: addhelp(sqrtnall,"sqrtnall(x,n):compute the vector of nth-roots of x");
1237: @eprog\noindent
1238:
1239: \syn{gsqrtn}{x,n,\&z,\var{prec}}.
1240:
1241: \subsecidx{tan}$(x)$: tangent of $x$.
1242:
1243: \syn{gtan}{x,\var{prec}}.
1244:
1245: \subsecidx{tanh}$(x)$: hyperbolic tangent of $x$.
1246:
1247: \syn{gth}{x,\var{prec}}.
1248:
1249: \subsecidx{teichmuller}$(x)$: Teichm\"uller character of the $p$-adic number
1250: $x$.
1251:
1252: \syn{teich}{x}.
1253:
1254: \subsecidx{theta}$(q,z)$: Jacobi sine theta-function.
1255:
1256: \syn{theta}{q,z,\var{prec}}.
1257:
1258: \subsecidx{thetanullk}$(q,k)$: $k$-th derivative at $z=0$ of
1259: $\kbd{theta}(q,z)$.
1260:
1261: \syn{thetanullk}{q,k,\var{prec}}, where $k$ is a \kbd{long}.
1262:
1263: \subsecidx{weber}$(x,\{\fl=0\})$: one of Weber's three $f$ functions.
1264: If $\fl=0$, returns
1265: $$f(x)=\exp(-i\pi/24)\cdot\eta((x+1)/2)\,/\,\eta(x) \quad\hbox{such that}\quad
1266: j=(f^{24}-16)^3/f^{24}\,,$$
1267: where $j$ is the elliptic $j$-invariant (see the function \kbd{ellj}).
1268: If $\fl=1$, returns
1269: $$f_1(x)=\eta(x/2)\,/\,\eta(x)\quad\hbox{such that}\quad
1270: j=(f_1^{24}+16)^3/f_1^{24}\,.$$
1271: Finally, if $\fl=2$, returns
1272: $$f_2(x)=\sqrt{2}\eta(2x)\,/\,\eta(x)\quad\hbox{such that}\quad
1273: j=(f_2^{24}+16)^3/f_2^{24}.$$
1274: Note the identities $f^8=f_1^8+f_2^8$ and $ff_1f_2=\sqrt2$.
1275:
1276: \syn{weber0}{x,\fl,\var{prec}}, or
1277: $\teb{wf}(x,\var{prec})$, $\teb{wf1}(x,\var{prec})$ or
1278: $\teb{wf2}(x,\var{prec})$.
1279:
1280: \subsecidx{zeta}$(s)$: Riemann's zeta function\sidx{Riemann zeta-function}
1281: $\zeta(s)=\sum_{n\ge1}n^{-s}$, computed using the \idx{Euler-Maclaurin}
1282: summation formula, except when $s$ is of type integer, in which case it
1283: is computed using Bernoulli numbers\sidx{Bernoulli numbers} for
1284: $s\le0$ or $s>0$ and even, and using modular forms for $s>0$ and odd.
1285:
1286: \syn{gzeta}{s,\var{prec}}.
1287:
1288: \section{Arithmetic functions}\label{se:arithmetic}
1289:
1290: These functions are by definition functions whose natural domain of
1291: definition is either $\Z$ (or $\Z_{>0}$), or sometimes polynomials
1292: over a base ring. Functions which concern polynomials exclusively will be
1293: explained in the next section. The way these functions are used is
1294: completely different from transcendental functions: in general only the types
1295: integer and polynomial are accepted as arguments. If a vector or matrix type
1296: is given, the function will be applied on each coefficient independently.
1297:
1298: In the present version \vers, all arithmetic functions in the narrow sense
1299: of the word~--- Euler's totient\sidx{Euler totient function} function, the
1300: \idx{Moebius} function, the sums over divisors or powers of divisors
1301: etc.--- call, after trial division by small primes, the same versatile
1302: factoring machinery described under \kbd{factorint}. It includes
1303: \idx{Shanks SQUFOF}, \idx{Pollard Rho}, \idx{ECM} and \idx{MPQS} stages, and
1304: has an early exit option for the functions \teb{moebius} and (the integer
1305: function underlying) \teb{issquarefree}. Note that it relies on a (fairly
1306: strong) probabilistic primality test: numbers found to be strong
1307: pseudo-primes after 10 successful trials of the \idx{Rabin-Miller} test are
1308: declared primes.
1309:
1310: \bigskip
1311: \subsecidx{addprimes}$(\{x=[\,]\})$: adds the ``primes'' contained in the
1312: vector $x$ (or the single integer $x$) to the table computed upon GP
1313: initialization (by \kbd{pari\_init} in library mode), and returns a row
1314: vector entries contain all such user primes. Whenever \kbd{factor} or
1315: \kbd{smallfact} is subsequently called, first the primes in the table
1316: computed by \kbd{pari\_init} will be checked, and then the additional
1317: primes in this table. If $x$ is empty or omitted, just returns the current
1318: list of extra primes.
1319:
1320: The entries in $x$ are not checked for primality. They need only be positive
1321: integers not divisible by any of the pre-computed primes. It's in fact a nice
1322: trick to add composite numbers, which for example the function
1323: $\kbd{factor}(x,0)$ was not able to factor. In case the message
1324: ``impossible inverse modulo $\langle$\var{some INTMOD}$\rangle$'' shows up
1325: afterwards, you have just stumbled over a non-trivial factor. Note that the
1326: arithmetic functions in the narrow sense, like \teb{eulerphi}, do \var{not}
1327: use this extra table.
1328:
1329: To remove primes from the list use \kbd{removeprimes}.
1330:
1331: \syn{addprimes}{x}.
1332:
1333: \subsecidx{bestappr}$(x,A,\{B\})$: if $B$ is omitted, finds the best rational
1334: approximation to $x\in\R$ (or $\R[X]$, or $\R^n$, \dots) with denominator at
1335: most equal to $A$ using continued fractions.
1336:
1337: If $B$ is present, $x$ is assumed to be of type \typ{INTMOD} modulo $M$ (or a
1338: recursive combination of those), and the routine returns the unique fraction
1339: $a/b$ in coprime integers $a\leq A$ and $b\leq B$ which is congruent to $x$
1340: modulo $M$. If $M \leq 2AB$, uniqueness is not guaranteed and the function
1341: fails with an error message. If rational reconstruction is not possible
1342: (no such $a/b$ exists for at least one component of $x$), returns $-1$.
1343:
1344: \syn{bestappr0}{x,A,B}. Also available is $\teb{bestappr}(x,A)$ corresponding
1345: to an omitted $B$.
1346:
1347: \subsecidx{bezout}$(x,y)$: finds $u$ and $v$ minimal in a
1348: natural sense such that $x*u+y*v=\text{gcd}(x,y)$. The arguments
1349: must be both integers or both polynomials, and the result is a
1350: row vector with three components $u$, $v$, and $\text{gcd}(x,y)$.
1351:
1352: \syn{vecbezout}{x,y} to get the vector, or $\teb{gbezout}(x,y, \&u, \&v)$
1353: which gives as result the address of the created gcd, and puts
1354: the addresses of the corresponding created objects into $u$ and $v$.
1355:
1356: \subsecidx{bezoutres}$(x,y)$: as \kbd{bezout}, with the resultant of $x$ and
1357: $y$ replacing the gcd.
1358:
1359: \syn{vecbezoutres}{x,y} to get the vector, or $\teb{subresext}(x,y, \&u,
1360: \&v)$ which gives as result the address of the created gcd, and puts the
1361: addresses of the corresponding created objects into $u$ and $v$.
1362:
1363: \subsecidx{bigomega}$(x)$: number of prime divisors of $|x|$ counted with
1364: multiplicity. $x$ must be an integer.
1365:
1366: \syn{bigomega}{x}, the result is a \kbd{long}.
1367:
1368: \subsecidx{binomial}$(x,y)$: \idx{binomial coefficient} $\binom x y$.
1369: Here $y$ must be an integer, but $x$ can be any PARI object.
1370:
1371: \syn{binome}{x,y}, where $y$ must be a \kbd{long}.
1372:
1373: \subsecidx{chinese}$(x,y)$: if $x$ and $y$ are both integermods or both
1374: polmods, creates (with the same type) a $z$ in the same residue class
1375: as $x$ and in the same residue class as $y$, if it is possible.
1376:
1377: This function also allows vector and matrix arguments, in which case the
1378: operation is recursively applied to each component of the vector or matrix.
1379: For polynomial arguments, it is applied to each coefficient. Finally
1380: $\kbd{chinese}(x,x) = x$ regardless of the type of $x$; this allows vector
1381: arguments to contain other data, so long as they are identical in both
1382: vectors.
1383:
1384: \syn{chinois}{x,y}.
1385:
1386: \subsecidx{content}$(x)$: computes the gcd of all the coefficients of $x$,
1387: when this gcd makes sense. If $x$ is a scalar, this simply returns $x$. If $x$
1388: is a polynomial (and by extension a power series), it gives the usual content
1389: of $x$. If $x$ is a rational function, it gives the ratio of the contents of
1390: the numerator and the denominator. Finally, if $x$ is a vector or a matrix,
1391: it gives the gcd of all the entries.
1392:
1393: \syn{content}{x}.
1394:
1395: \subsecidx{contfrac}$(x,\{b\},\{lmax\})$: creates the row vector whose
1396: components are the partial quotients of the \idx{continued fraction}
1397: expansion of $x$, the number of partial quotients being limited to $lmax$.
1398: If $x$ is a real number, the expansion stops at the last significant partial
1399: quotient if $lmax$ is omitted. $x$ can also be a rational function or a power
1400: series.
1401:
1402: If a vector $b$ is supplied, the numerators will be equal to the coefficients
1403: of $b$. The length of the result is then equal to the length of $b$, unless a
1404: partial remainder is encountered which is equal to zero. In which case the
1405: expansion stops. In the case of real numbers, the stopping criterion is thus
1406: different from the one mentioned above since, if $b$ is too long, some partial
1407: quotients may not be significant.
1408:
1409: If $b$ is an integer, the command is understood as \kbd{contfrac($x,lmax$)}.
1410:
1411: \syn{contfrac0}{x,b,lmax}. Also available are
1412: $\teb{gboundcf}(x,lmax)$, $\teb{gcf}(x)$, or $\teb{gcf2}(b,x)$, where $lmax$
1413: is a C integer.
1414:
1415: \subsecidx{contfracpnqn}$(x)$: when $x$ is a vector or a one-row matrix, $x$
1416: is considered as the list of partial quotients $[a_0,a_1,\dots,a_n]$ of a
1417: rational number, and the result is the 2 by 2 matrix
1418: $[p_n,p_{n-1};q_n,q_{n-1}]$ in the standard notation of continued fractions,
1419: so $p_n/q_n=a_0+1/(a_1+\dots+1/a_n)\dots)$. If $x$ is a matrix with two rows
1420: $[b_0,b_1,\dots,b_n]$ and $[a_0,a_1,\dots,a_n]$, this is then considered as a
1421: generalized continued fraction and we have similarly
1422: $p_n/q_n=1/b_0(a_0+b_1/(a_1+\dots+b_n/a_n)\dots)$. Note that in this case one
1423: usually has $b_0=1$.
1424:
1425: \syn{pnqn}{x}.
1426:
1427: \subsecidx{core}$(n,\{\fl=0\})$: if $n$ is a non-zero integer written as
1428: $n=df^2$ with $d$ squarefree, returns $d$. If $\fl$ is non-zero,
1429: returns the two-element row vector $[d,f]$.
1430:
1431: \syn{core0}{n,\fl}.
1432: Also available are
1433: $\teb{core}(n)$ (= \teb{core}$(n,0)$) and
1434: $\teb{core2}(n)$ (= \teb{core}$(n,1)$).
1435:
1436: \subsecidx{coredisc}$(n,\{\fl\})$: if $n$ is a non-zero integer written as
1437: $n=df^2$ with $d$ fundamental discriminant (including 1), returns $d$. If
1438: $\fl$ is non-zero, returns the two-element row vector $[d,f]$. Note that if
1439: $n$ is not congruent to 0 or 1 modulo 4, $f$ will be a half integer and not
1440: an integer.
1441:
1442: \syn{coredisc0}{n,\fl}.
1443: Also available are
1444: $\teb{coredisc}(n)$ (= \teb{coredisc}$(n,0)$) and
1445: $\teb{coredisc2}(n)$ (= \teb{coredisc}$(n,1)$).
1446:
1447: \subsecidx{dirdiv}$(x,y)$: $x$ and $y$ being vectors of perhaps different
1448: lengths but with $y[1]\neq 0$ considered as \idx{Dirichlet series}, computes
1449: the quotient of $x$ by $y$, again as a vector.
1450:
1451: \syn{dirdiv}{x,y}.
1452:
1453: \subsecidx{direuler}$(p=a,b,\var{expr},\{c\})$: computes the
1454: \idx{Dirichlet series} to $b$ terms of the \idx{Euler product} of
1455: expression \var{expr} as $p$ ranges through the primes from $a$ to $b$.
1456: \var{expr} must be a polynomial or rational function in another variable
1457: than $p$ (say $X$) and $\var{expr}(X)$ is understood as the Dirichlet
1458: series (or more precisely the local factor) $\var{expr}(p^{-s})$. If $c$ is
1459: present, output only the first $c$ coefficients in the series.
1460:
1461: \synt{direuler}{entree *ep, GEN a, GEN b, char *expr}
1462:
1463: \subsecidx{dirmul}$(x,y)$: $x$ and $y$ being vectors of perhaps different
1464: lengths considered as \idx{Dirichlet series}, computes the product of
1465: $x$ by $y$, again as a vector.
1466:
1467: \syn{dirmul}{x,y}.
1468:
1469: \subsecidx{divisors}$(x)$: creates a row vector whose components are the
1470: positive divisors of the integer $x$ in increasing order. The factorization
1471: of $x$ (as output by \tet{factor}) can be used instead.
1472:
1473: \syn{divisors}{x}.
1474:
1475: \subsecidx{eulerphi}$(x)$: Euler's $\phi$
1476: (totient)\sidx{Euler totient function} function of $|x|$, in other words
1477: $|(\Z/x\Z)^*|$. $x$ must be of type integer.
1478:
1479: \syn{phi}{x}.
1480:
1481: \subsecidx{factor}$(x,\{\var{lim}=-1\})$: general factorization function.
1482: If $x$ is of type integer, rational, polynomial or rational function, the
1483: result is a two-column matrix, the first column being the irreducibles
1484: dividing $x$ (prime numbers or polynomials), and the second the exponents.
1485: If $x$ is a vector or a matrix, the factoring is done componentwise (hence
1486: the result is a vector or matrix of two-column matrices). By definition,
1487: $0$ is factored as $0^1$.
1488:
1489: If $x$ is of type integer or rational, an argument \var{lim} can be
1490: added, meaning that we look only for factors up to \var{lim}, or to
1491: \kbd{primelimit}, whichever is lowest (except when $\var{lim}=0$ where the
1492: effect is identical to setting $\var{lim}=\kbd{primelimit}$). Hence in this
1493: case, the remaining part is not necessarily prime. See \tet{factorint} for
1494: more information about the algorithms used.
1495:
1496: The polynomials or rational functions to be factored must have scalar
1497: coefficients. In particular PARI does \var{not} know how to factor
1498: multivariate polynomials.
1499:
1500: Note that PARI tries to guess in a sensible way over which ring you want
1501: to factor. Note also that factorization of polynomials is done up to
1502: multiplication by a constant. In particular, the factors of rational
1503: polynomials will have integer coefficients, and the content of a polynomial
1504: or rational function is discarded and not included in the factorization. If
1505: you need it, you can always ask for the content explicitly:
1506:
1507: \bprog
1508: ? factor(t^2 + 5/2*t + 1)
1509: %1 =
1510: [2*t + 1 1]
1511:
1512: [t + 2 1]
1513:
1514: ? content(t^2 + 5/2*t + 1)
1515: %2 = 1/2
1516: @eprog
1517:
1518: \noindent See also \tet{factornf}.
1519:
1520: \syn{factor0}{x,\var{lim}}, where \var{lim} is a C integer.
1521: Also available are
1522: $\teb{factor}(x)$ (= $\teb{factor0}(x,-1)$),
1523: $\teb{smallfact}(x)$ (= $\teb{factor0}(x,0)$).
1524:
1525: \subsecidx{factorback}$(f,\{nf\})$: $f$ being any factorization, gives back
1526: the factored object. If a second argument $\var{nf}$ is supplied, $f$ is
1527: assumed to be a prime ideal factorization in the number field $\var{nf}$.
1528: The resulting ideal is given in HNF\sidx{Hermite normal form} form.
1529:
1530: \syn{factorback}{f,\var{nf}}, where an omitted
1531: $\var{nf}$ is entered as \kbd{NULL}.
1532:
1533: \subsecidx{factorcantor}$(x,p)$: factors the polynomial $x$ modulo the
1534: prime $p$, using distinct degree plus
1535: \idx{Cantor-Zassenhaus}\sidx{Zassenhaus}. The coefficients of $x$ must be
1536: operation-compatible with $\Z/p\Z$. The result is a two-column matrix, the
1537: first column being the irreducible polynomials dividing $x$, and the second
1538: the exponents. If you want only the \var{degrees} of the irreducible
1539: polynomials (for example for computing an $L$-function), use
1540: $\kbd{factormod}(x,p,1)$. Note that the \kbd{factormod} algorithm is
1541: usually faster than \kbd{factorcantor}.
1542:
1543: \syn{factcantor}{x,p}.
1544:
1545: \subsecidx{factorff}$(x,p,a)$: factors the polynomial $x$ in the field
1546: $\F_q$ defined by the irreducible polynomial $a$ over $\F_p$. The
1547: coefficients of $x$ must be operation-compatible with $\Z/p\Z$. The result
1548: is a two-column matrix, the first column being the irreducible polynomials
1549: dividing $x$, and the second the exponents. It is recommended to use for
1550: the variable of $a$ (which will be used as variable of a polmod) a name
1551: distinct from the other variables used, so that a \kbd{lift()} of the
1552: result will be legible. If all the coefficients of $x$ are in $\F_p$, a much faster algorithm is applied, using the computation of isomorphisms between finite fields.
1553:
1554: \syn{factmod9}{x,p,a}.
1555:
1556: \subsecidx{factorial}$(x)$ or $x!$: factorial of $x$. The expression $x!$
1557: gives a result which is an integer, while $\kbd{factorial}(x)$ gives a real
1558: number.
1559:
1560: \syn{mpfact}{x} for $x!$ and
1561: $\teb{mpfactr}(x,\var{prec})$ for $\kbd{factorial}(x)$. $x$ must be a \kbd{long}
1562: integer and not a PARI integer.
1563:
1564: \subsecidx{factorint}$(n,\{\fl=0\})$: factors the integer n using a
1565: combination of the \idx{Shanks SQUFOF} and \idx{Pollard Rho} method (with
1566: modifications due to Brent), \idx{Lenstra}'s \idx{ECM} (with modifications by
1567: Montgomery), and \idx{MPQS} (the latter adapted from the \idx{LiDIA} code
1568: with the kind permission of the LiDIA maintainers), as well as a search for
1569: pure powers with exponents$\le 10$. The output is a two-column matrix as for
1570: \kbd{factor}.
1571:
1572: This gives direct access to the integer factoring engine called by most
1573: arithmetical functions. \fl\ is optional; its binary digits mean 1: avoid
1574: MPQS, 2: skip first stage ECM (we may still fall back to it later), 4: avoid
1575: Rho and SQUFOF, 8: don't run final ECM (as a result, a huge composite may be
1576: declared to be prime). Note that a (strong) probabilistic primality test is
1577: used; thus composites might (very rarely) not be detected.
1578:
1579: The machinery underlying this function is still in a somewhat experimental
1580: state, but should be much faster on average than pure ECM as used by all
1581: PARI versions up to 2.0.8, at the expense of heavier memory use. You are
1582: invited to play with the flag settings and watch the internals at work by
1583: using GP's \tet{debuglevel} default parameter (level 3 shows just the
1584: outline, 4 turns on time keeping, 5 and above show an increasing amount
1585: of internal details). If you see anything funny happening, please let
1586: us know.
1587:
1588: \syn{factorint}{n,\fl}.
1589:
1590: \subsecidx{factormod}$(x,p,\{\fl=0\})$: factors the polynomial $x$ modulo
1591: the prime integer $p$, using \idx{Berlekamp}. The coefficients of $x$ must be
1592: operation-compatible with $\Z/p\Z$. The result is a two-column matrix, the
1593: first column being the irreducible polynomials dividing $x$, and the second
1594: the exponents. If $\fl$ is non-zero, outputs only the \var{degrees} of the
1595: irreducible polynomials (for example, for computing an $L$-function). A
1596: different algorithm for computing the mod $p$ factorization is
1597: \kbd{factorcantor} which is sometimes faster.
1598:
1599: \syn{factormod}{x,p,\fl}. Also available are
1600: $\teb{factmod}(x,p)$ (which is equivalent to $\teb{factormod}(x,p,0)$) and
1601: $\teb{simplefactmod}(x,p)$ (= $\teb{factormod}(x,p,1)$).
1602:
1603: \subsecidx{fibonacci}$(x)$: $x^{\text{th}}$ Fibonacci number.
1604:
1605: \syn{fibo}{x}. $x$ must be a \kbd{long}.
1606:
1607: \subsecidx{ffinit}$(p,n,\{v=x\})$: computes a monic polynomial of degree
1608: $n$ which is irreducible over $\F_p$. For instance if
1609: \kbd{P = ffinit(3,2,y)}, you can represent elements in $\F_{3^2}$ as polmods
1610: modulo \kbd{P}.
1611:
1612: \syn{ffinit}{p,n,v}, where $v$ is a variable number.
1613:
1614: \subsecidx{gcd}$(x,y,\{\fl=0\})$: creates the greatest common divisor of $x$
1615: and $y$. $x$ and $y$ can be of quite general types, for instance both
1616: rational numbers. Vector/matrix types are also accepted, in which case
1617: the GCD is taken recursively on each component. Note that for these
1618: types, \kbd{gcd} is not commutative.
1619:
1620: If $\fl=0$, use \idx{Euclid}'s algorithm.
1621:
1622: If $\fl=1$, use the modular gcd algorithm ($x$ and $y$ have to be
1623: polynomials, with integer coefficients).
1624:
1625: If $\fl=2$, use the \idx{subresultant algorithm}.
1626:
1627: \syn{gcd0}{x,y,\fl}. Also available are
1628: $\teb{ggcd}(x,y)$, $\teb{modulargcd}(x,y)$, and $\teb{srgcd}(x,y)$
1629: corresponding to $\fl=0$, $1$ and $2$ respectively.
1630:
1631: \subsecidx{hilbert}$(x,y,\{p\})$: \idx{Hilbert symbol} of $x$ and $y$ modulo
1632: $p$. If $x$ and $y$ are of type integer or fraction, an explicit third
1633: parameter $p$ must be supplied, $p=0$ meaning the place at infinity.
1634: Otherwise, $p$ needs not be given, and $x$ and $y$ can be of compatible types
1635: integer, fraction, real, integermod or $p$-adic.
1636:
1637: \syn{hil}{x,y,p}.
1638:
1639: \subsecidx{isfundamental}$(x)$: true (1) if $x$ is equal to 1 or to the
1640: discriminant of a quadratic field, false (0) otherwise.
1641:
1642: \syn{gisfundamental}{x}, but the
1643: simpler function $\teb{isfundamental}(x)$ which returns a \kbd{long}
1644: should be used if $x$ is known to be of type integer.
1645:
1646: \subsecidx{isprime}$(x,\{\fl=0\})$: if $\fl=0$ (default), true (1) if $x$ is a strong pseudo-prime
1647: for 10 randomly chosen bases, false (0) otherwise.
1648:
1649: If $\fl=1$, use Pocklington-Lehmer ``P-1'' test. true (1) if $x$ is
1650: prime, false (0) otherwise.
1651:
1652: If $\fl=2$, use Pocklington-Lehmer ``P-1'' test and output a primality
1653: certificate as follows: return 0 if $x$ is composite, 1 if $x$ is a
1654: small prime (currently strictly less than $341 550 071 728 321$), and
1655: a matrix if $x$ is a large prime. The matrix has three columns. The
1656: first contains the prime factors $p$, the second the corresponding
1657: elements $a_p$ as in Proposition~8.3.1 in GTM~138, and the third the
1658: output of isprime(p,2).
1659:
1660: In the two last cases, the algorithm fails if one of the (strong
1661: pseudo-)prime factors is not prime, but it should be exceedingly rare.
1662:
1663:
1664: \syn{gisprime}{x,\fl}, but the simpler function $\teb{isprime}(x)$
1665: which returns a \kbd{long} should be used if $x$ is known to be of
1666: type integer. Also available is $\teb{plisprime}(N,\fl)$,
1667: corresponding to $\teb{gisprime}(x,\fl+1)$ if $x$ is known to be of
1668: type integer.
1669:
1670:
1671: \subsecidx{ispseudoprime}$(x)$: true (1) if $x$ is a strong
1672: pseudo-prime for a randomly chosen base, false (0) otherwise.
1673:
1674: \syn{gispsp}{x}, but the
1675: simpler function $\teb{ispsp}(x)$ which returns a \kbd{long}
1676: should be used if $x$ is known to be of type integer.
1677:
1678: \subsecidx{issquare}$(x,\{\&n\})$: true (1) if $x$ is square, false (0) if
1679: not. $x$ can be of any type. If $n$ is given and an exact square root had to
1680: be computed in the checking process, puts that square root in $n$. This is in
1681: particular the case when $x$ is an integer or a polynomial. This is \var{not}
1682: the case for intmods (use quadratic reciprocity) or series (only check the
1683: leading coefficient).
1684:
1685: \syn{gcarrecomplet}{x,\&n}. Also available is $\teb{gcarreparfait}(x)$.
1686:
1687: \subsecidx{issquarefree}$(x)$: true (1) if $x$ is squarefree, false (0) if not.
1688: Here $x$ can be an integer or a polynomial.
1689:
1690: \syn{gissquarefree}{x}, but the simpler function $\teb{issquarefree}(x)$
1691: which returns a \kbd{long} should be used if $x$ is known to be of type
1692: integer. This \teb{issquarefree} is just the square of the
1693: \idx{Moebius} function, and is computed as a multiplicative
1694: arithmetic function much like the latter.
1695:
1696: \subsecidx{kronecker}$(x,y)$:
1697: Kronecker\sidx{Kronecker symbol}\sidx{Legendre symbol}
1698: (i.e.~generalized Legendre) symbol $\left(\dfrac{x}{y}\right)$. $x$ and $y$
1699: must be of type integer.
1700:
1701: \syn{kronecker}{x,y}, the result ($0$ or $\pm 1$) is a \kbd{long}.
1702:
1703: \subsecidx{lcm}$(x,y)$: least common multiple of $x$ and $y$, i.e.~such
1704: that $\text{lcm}(x,y)*\text{gcd}(x,y)=\text{abs}(x*y)$.
1705:
1706: \syn{glcm}{x,y}.
1707:
1708: \subsecidx{moebius}$(x)$: \idx{Moebius} $\mu$-function of $|x|$. $x$ must
1709: be of type integer.
1710:
1711: \syn{mu}{x}, the result ($0$ or $\pm 1$) is a \kbd{long}.
1712:
1713: \subsecidx{nextprime}$(x)$: finds the smallest prime greater than or
1714: equal to $x$. $x$ can be of any real type. Note that if $x$ is a prime,
1715: this function returns $x$ and not the smallest prime strictly larger than $x$.
1716:
1717: \syn{nextprime}{x}.
1718:
1719: \subsecidx{numdiv}$(x)$: number of divisors of $|x|$. $x$ must be of type
1720: integer, and the result is a \kbd{long}.
1721:
1722: \syn{numbdiv}{x}.
1723:
1724: \subsecidx{omega}$(x)$: number of distinct prime divisors of $|x|$. $x$
1725: must be of type integer.
1726:
1727: \syn{omega}{x}, the result is a \kbd{long}.
1728:
1729: \subsecidx{precprime}$(x)$: finds the largest prime less than or equal to
1730: $x$. $x$ can be of any real type. Returns 0 if $x\le1$.
1731: Note that if $x$ is a prime, this function returns $x$ and not the largest
1732: prime strictly smaller than $x$.
1733:
1734: \syn{precprime}{x}.
1735:
1736: \subsecidx{prime}$(x)$: the $x^{\text{th}}$ prime number, which must be among
1737: the precalculated primes.
1738:
1739: \syn{prime}{x}. $x$ must be a \kbd{long}.
1740:
1741: \subsecidx{primes}$(x)$: creates a row vector whose components
1742: are the first $x$ prime numbers, which must be among the precalculated primes.
1743:
1744: \syn{primes}{x}. $x$ must be a \kbd{long}.
1745:
1746: \subsecidx{qfbclassno}$(x,\{\fl=0\})$: class number of the quadratic field
1747: of discriminant $x$. In the present version \vers, a simple algorithm is used
1748: for $x>0$, so $x$ should not be too large (say $x<10^7$) for the time to be
1749: reasonable. On the other hand, for $x<0$ one can reasonably compute
1750: classno($x$) for $|x|<10^{25}$, since the method used is \idx{Shanks}' method
1751: which is in $O(|x|^{1/4})$. For larger values of $|D|$, see
1752: \kbd{quadclassunit}.
1753:
1754: If $\fl=1$, compute the class number using \idx{Euler product}s and the
1755: functional equation. However, it is in $O(|x|^{1/2})$.
1756:
1757: \misctitle{Important warning.} For $D<0$, this function often gives
1758: incorrect results when the class group is non-cyclic, because the authors
1759: were too lazy to implement \idx{Shanks}' method completely. It is therefore
1760: strongly recommended to use either the version with $\fl=1$, the function
1761: $\kbd{qfhclassno}(-x)$ if $x$ is known to be a fundamental discriminant, or
1762: the function \kbd{quadclassunit}.
1763:
1764: \syn{qfbclassno0}{x,\fl}. Also available are
1765: $\teb{classno}(x)$ (= $\teb{qfbclassno}(x)$),
1766: $\teb{classno2}(x)$ (= $\teb{qfbclassno}(x,1)$), and finally
1767: there exists the function $\teb{hclassno}(x)$ which computes the class
1768: number of an imaginary quadratic field by counting reduced forms, an $O(|x|)$
1769: algorithm. See also \kbd{qfbhclassno}.
1770:
1771: \subsecidx{qfbcompraw}$(x,y)$ \idx{composition} of the binary quadratic forms
1772: $x$ and $y$, without \idx{reduction} of the result. This is useful e.g.~to
1773: compute a generating element of an ideal.
1774:
1775: \syn{compraw}{x,y}.
1776:
1777: \subsecidx{qfbhclassno}$(x)$: \idx{Hurwitz class number} of $x$, where $x$ is
1778: non-negative and congruent to 0 or 3 modulo 4. See also \kbd{qfbclassno}.
1779:
1780: \syn{hclassno}{x}.
1781:
1782: \subsecidx{qfbnucomp}$(x,y,l)$: \idx{composition} of the primitive positive
1783: definite binary quadratic forms $x$ and $y$ using the NUCOMP and NUDUPL
1784: algorithms of \idx{Shanks} (\`a la Atkin). $l$ is any positive constant,
1785: but for optimal speed, one should take $l=|D|^{1/4}$, where $D$ is the common
1786: discriminant of $x$ and $y$.
1787:
1788: \syn{nucomp}{x,y,l}. The auxiliary function
1789: $\teb{nudupl}(x,l)$ should be used instead for speed when $x=y$.
1790:
1791: \subsecidx{qfbnupow}$(x,n)$: $n$-th power of the primitive positive definite
1792: binary quadratic form $x$ using the NUCOMP and NUDUPL algorithms (see
1793: \kbd{qfbnucomp}).
1794:
1795: \syn{nupow}{x,n}.
1796:
1797: \subsecidx{qfbpowraw}$(x,n)$: $n$-th power of the binary quadratic form
1798: $x$, computed without doing any \idx{reduction} (i.e.~using \kbd{qfbcompraw}).
1799: Here $n$ must be non-negative and $n<2^{31}$.
1800:
1801: \syn{powraw}{x,n} where $n$ must be a \kbd{long}
1802: integer.
1803:
1804: \subsecidx{qfbprimeform}$(x,p)$: prime binary quadratic form of discriminant
1805: $x$ whose first coefficient is the prime number $p$. By abuse of notation,
1806: $p = 1$ is a valid special case which returns the unit form. Returns an
1807: error if $x$ is not a quadratic residue mod $p$. In the case where $x>0$,
1808: the ``distance'' component of the form is set equal to zero according to
1809: the current precision.
1810:
1811: \syn{primeform}{x,p,\var{prec}}, where the third variable $\var{prec}$ is a
1812: \kbd{long}, but is only taken into account when $x>0$.
1813:
1814: \subsecidx{qfbred}$(x,\{\fl=0\},\{D\},\{\var{isqrtD}\},\{\var{sqrtD}\})$:
1815: reduces the binary quadratic form $x$ (updating Shanks's distance function
1816: if $x$ is indefinite). The binary digits of $\fl$ are toggles meaning
1817:
1818: \quad 1: perform a single \idx{reduction} step
1819:
1820: \quad 2: don't update \idx{Shanks}'s distance
1821:
1822: $D$, \var{isqrtD}, \var{sqrtD}, if present, supply the values of the
1823: discriminant, $\lfloor \sqrt{D}\rfloor$, and $\sqrt{D}$ respectively
1824: (no checking is done of these facts). If $D<0$ these values are useless,
1825: and all references to Shanks's distance are irrelevant.
1826:
1827: \syn{qfbred0}{x,\fl,D,\var{isqrtD},\var{sqrtD}}. Use \kbd{NULL}
1828: to omit any of $D$, \var{isqrtD}, \var{sqrtD}.
1829:
1830: \noindent Also available are
1831:
1832: $\teb{redimag}(x)$ (= $\teb{qfbred}(x)$ where $x$ is definite),
1833:
1834: \noindent and for indefinite forms:
1835:
1836: $\teb{redreal}(x)$ (= $\teb{qfbred}(x)$),
1837:
1838: $\teb{rhoreal}(x)$ (= $\teb{qfbred}(x,1)$),
1839:
1840: $\teb{redrealnod}(x,sq)$ (= $\teb{qfbred}(x,2,,isqrtD)$),
1841:
1842: $\teb{rhorealnod}(x,sq)$ (= $\teb{qfbred}(x,3,,isqrtD)$).
1843:
1844: \subsecidx{quadclassunit}$(D,\{\fl=0\},\{\var{tech}=[]\})$:
1845: \idx{Buchmann-McCurley}'s sub-exponential algorithm for computing the class
1846: group of a quadratic field of discriminant $D$. If $D$ is not fundamental,
1847: the function may or may not be defined, but usually is, and often gives the
1848: right answer (a warning is issued). The more general function \tet{bnrinit}
1849: should be used to compute the class group of an order.
1850:
1851: This function should be used instead of \kbd{qfbclassno} or \kbd{quadregula}
1852: when $D<-10^{25}$, $D>10^{10}$, or when the \var{structure} is wanted.
1853:
1854: If $\fl$ is non-zero \var{and} $D>0$, computes the narrow class group and
1855: regulator, instead of the ordinary (or wide) ones. In the current version
1856: \vers, this doesn't work at all~: use the general function \tet{bnfnarrow}.
1857:
1858: Optional parameter \var{tech} is a row vector of the form
1859: $[c_1,c_2]$, where $c_1$ and $c_2$ are positive real numbers which
1860: control the execution time and the stack size. To get maximum speed,
1861: set $c_2=c$. To get a rigorous result (under \idx{GRH}) you must take
1862: $c_2=6$. Reasonable values for $c$ are between $0.1$ and $2$.
1863:
1864: The result of this function is a vector $v$ with 4 components if $D<0$, and
1865: $5$ otherwise. The correspond respectively to
1866:
1867: $\bullet$ $v[1]$~: the class number
1868:
1869: $\bullet$ $v[2]$~: a vector giving the structure of the class group as a
1870: product of cyclic groups;
1871:
1872: $\bullet$ $v[3]$~: a vector giving generators of those cyclic groups (as
1873: binary quadratic forms).
1874:
1875: $\bullet$ $v[4]$~: (omitted if $D < 0$) the regulator, computed to an
1876: accuracy which is the maximum of an internal accuracy determined by the
1877: program and the current default (note that once the regulator is known to a
1878: small accuracy it is trivial to compute it to very high accuracy, see the
1879: tutorial).
1880:
1881: $\bullet$ $v[5]$~: a measure of the correctness of the result. If it is
1882: close to 1, the result is correct (under \idx{GRH}). If it is close to a
1883: larger integer, this shows that the class number is off by a factor equal
1884: to this integer, and you must start again with a larger value for $c_1$ or
1885: a different random seed. In this case, a warning message is printed.
1886:
1887: \syn{quadclassunit0}{D,\fl,tech}. Also available are
1888: $\teb{buchimag}(D,c_1,c_2)$ and $\teb{buchreal}(D,\fl,c_1,c_2)$.
1889:
1890: \subsecidx{quaddisc}$(x)$: discriminant of the quadratic field
1891: $\Q(\sqrt{x})$, where $x\in\Q$.
1892:
1893: \syn{quaddisc}{x}.
1894:
1895: \subsecidx{quadhilbert}$(D,\{\fl=0\})$: relative equation defining the
1896: \idx{Hilbert class field} of the quadratic field of discriminant $D$.
1897: If $\fl$ is non-zero
1898: and $D<0$, outputs $[\var{form},\var{root}(\var{form})]$ (to be used for
1899: constructing subfields). If $\fl$ is non-zero and $D>0$, try hard to
1900: get the best modulus.
1901: Uses complex multiplication in the imaginary case and \idx{Stark units}
1902: in the real case.
1903:
1904: \syn{quadhilbert}{D,\fl,\var{prec}}.
1905:
1906: \subsecidx{quadgen}$(x)$: creates the quadratic number\sidx{omega}
1907: $\omega=(a+\sqrt{x})/2$ where $a=0$ if $x\equiv0\mod4$,
1908: $a=1$ if $x\equiv1\mod4$, so that $(1,\omega)$ is an integral basis for
1909: the quadratic order of discriminant $x$. $x$ must be an integer congruent to
1910: 0 or 1 modulo 4.
1911:
1912: \syn{quadgen}{x}.
1913:
1914: \subsecidx{quadpoly}$(D,\{v=x\})$: creates the ``canonical'' quadratic
1915: polynomial (in the variable $v$) corresponding to the discriminant $D$,
1916: i.e.~the minimal polynomial of $\kbd{quadgen}(x)$. $D$ must be an integer
1917: congruent to 0 or 1 modulo 4.
1918:
1919: \syn{quadpoly0}{x,v}.
1920:
1921: \subsecidx{quadray}$(D,f,\{\fl=0\})$: relative equation for the ray class
1922: field of conductor $f$ for the quadratic field of discriminant $D$ (which
1923: can also be a \kbd{bnf}), using analytic methods.
1924:
1925: For $D<0$, uses the $\sigma$ function. $\fl$ has the following meaning: if
1926: it's an odd integer, outputs instead the vector of $[\var{ideal},
1927: \var{corresponding root}]$. It can also be a two-component vector
1928: $[\lambda,\fl]$, where \fl\ is as above and $\lambda$ is the technical
1929: element of \kbd{bnf} necessary for Schertz's method. In that case, returns
1930: 0 if $\lambda$ is not suitable.
1931:
1932: For $D>0$, uses Stark's conjecture. If $\fl$ is non-zero, try hard to
1933: get the best modulus. The function may fail with the following message
1934: \bprog
1935: "Cannot find a suitable modulus in FindModulus"
1936: @eprog
1937: See \tet{bnrstark} for more details about the real case.
1938:
1939: \syn{quadray}{D,f,\fl}.
1940:
1941: \subsecidx{quadregulator}$(x)$: regulator of the quadratic field of
1942: positive discriminant $x$. Returns an error if $x$ is not a discriminant
1943: (fundamental or not) or if $x$ is a square. See also \kbd{quadclassunit} if
1944: $x$ is large.
1945:
1946: \syn{regula}{x,\var{prec}}.
1947:
1948: \subsecidx{quadunit}$(x)$: fundamental unit\sidx{fundamental units} of the
1949: real quadratic field $\Q(\sqrt x)$ where $x$ is the positive discriminant
1950: of the field. If $x$ is not a fundamental discriminant, this probably gives
1951: the fundamental unit of the corresponding order. $x$ must be of type
1952: integer, and the result is a quadratic number.
1953:
1954: \syn{fundunit}{x}.
1955:
1956: \subsecidx{removeprimes}$(\{x=[\,]\})$: removes the primes listed in $x$ from
1957: the prime number table. In particular \kbd{removeprimes(addprimes)} empties
1958: the extra prime table. $x$ can also be a single integer. List the current
1959: extra primes if $x$ is omitted.
1960:
1961: \syn{removeprimes}{x}.
1962:
1963: \subsecidx{sigma}$(x,\{k=1\})$: sum of the $k^{\text{th}}$ powers of the
1964: positive divisors of $|x|$. $x$ must be of type integer.
1965:
1966: \syn{sumdiv}{x} (= $\teb{sigma}(x)$) or $\teb{gsumdivk}(x,k)$ (=
1967: $\teb{sigma}(x,k)$), where $k$ is a C long integer.
1968:
1969: \subsecidx{sqrtint}$(x)$: integer square root of $x$, which must be of PARI
1970: type integer. The result is non-negative and rounded towards zero. A
1971: negative $x$ is allowed, and the result in that case is \kbd{I*sqrtint(-x)}.
1972:
1973: \syn{racine}{x}.
1974:
1975: \subsecidx{znlog}$(x,g)$: $g$ must be a primitive root mod a prime $p$, and
1976: the result is the discrete log of $x$ in the multiplicative group
1977: $(\Z/p\Z)^*$. This function uses a simple-minded combination of
1978: Pohlig-Hellman algorithm and Shanks baby-step/giant-step which requires
1979: $O(\sqrt{q})$ storage, where $q$ is the largest prime factor of $p-1$. Hence
1980: it cannot be used when the largest prime divisor of $p-1$ is greater than
1981: about $10^{13}$.
1982:
1983: \syn{znlog}{x,g}.
1984:
1985: \subsecidx{znorder}$(x)$: $x$ must be an integer mod $n$, and the result is the
1986: order of $x$ in the multiplicative group $(\Z/n\Z)^*$. Returns an error if $x$
1987: is not invertible.
1988:
1989: \syn{order}{x}.
1990:
1991: \subsecidx{znprimroot}$(n)$: returns a primitive root (generator) of
1992: $(\Z/n\Z)^*$, whenever this latter group is cyclic ($n = 4$ or $n = 2p^k$ or
1993: $n = p^k$, where $p$ is an odd prime and $k \geq 0$).
1994:
1995: \syn{gener}{x}.
1996:
1997: \subsecidx{znstar}$(n)$: gives the structure of the multiplicative group
1998: $(\Z/n\Z)^*$ as a 3-component row vector $v$, where $v[1]=\phi(n)$ is the
1999: order of that group, $v[2]$ is a $k$-component row-vector $d$ of integers
2000: $d[i]$ such that $d[i]>1$ and $d[i]\mid d[i-1]$ for $i \ge 2$ and
2001: $(\Z/n\Z)^* \simeq \prod_{i=1}^k(\Z/d[i]\Z)$, and $v[3]$ is a $k$-component row
2002: vector giving generators of the image of the cyclic groups $\Z/d[i]\Z$.
2003:
2004: \syn{znstar}{n}.
2005:
2006: \section{Functions related to elliptic curves}
2007:
2008: We have implemented a number of functions which are useful for number
2009: theorists working on elliptic curves. We always use \idx{Tate}'s notations.
2010: The functions assume that the curve is given by a general Weierstrass
2011: model\sidx{Weierstrass equation}
2012: $$
2013: y^2+a_1xy+a_3y=x^3+a_2x^2+a_4x+a_6,
2014: $$
2015: where a priori the $a_i$ can be of any scalar type. This curve can be
2016: considered as a five-component vector \kbd{E=[a1,a2,a3,a4,a6]}. Points on
2017: \kbd{E} are represented as two-component vectors \kbd{[x,y]}, except for the
2018: point at infinity, i.e.~the identity element of the group law, represented by
2019: the one-component vector \kbd{[0]}.
2020:
2021: It is useful to have at one's disposal more information. This is given by
2022: the function \tet{ellinit} (see there), which usually gives a 19 component
2023: vector (which we will call a long vector in this section). If a specific flag
2024: is added, a vector with only 13 component will be output (which we will call
2025: a medium vector). A medium vector just gives the first 13 components of the
2026: long vector corresponding to the same curve, but is of course faster to
2027: compute. The following \idx{member functions} are available to deal with the
2028: output of \kbd{ellinit}:
2029: \settabs\+xxxxxxxxxxxxxxxxxx&: &\cr
2030:
2031: \+ \kbd{a1}--\kbd{a6}, \kbd{b2}--\kbd{b8}, \kbd{c4}--\kbd{c6} &: &
2032: coefficients of the elliptic curve.\cr
2033:
2034: \+ \tet{area} &: & volume of the complex lattice defining $E$.\cr
2035:
2036: \+ \tet{disc} &: & discriminant of the curve.\cr
2037:
2038: \+ \tet{j} &: & $j$-invariant of the curve.\cr
2039:
2040: \+ \tet{omega}&: & $[\omega_1,\omega_2]$, periods forming a basis of
2041: the complex lattice defining $E$ ($\omega_1$ is the\cr
2042:
2043: \+ & & real period, and $\omega_2/\omega_1$ belongs to
2044: Poincar\'e's half-plane).\cr
2045:
2046: \+ \tet{eta} &: & quasi-periods $[\eta_1, \eta_2]$, such that
2047: $\eta_1\omega_2-\eta_2\omega_1=i\pi$.\cr
2048:
2049: \+ \tet{roots}&: & roots of the associated Weierstrass equation.\cr
2050:
2051: \+ \tet{tate} &: & $[u^2,u,v]$ in the notation of Tate.\cr
2052:
2053: \+ \tet{w} &: & Mestre's $w$ (this is technical).\cr
2054:
2055: Their use is best described by an example: assume that $E$ was output by
2056: \kbd{ellinit}, then typing \kbd{$E$.disc} will retrieve the curve's
2057: discriminant. The member functions \kbd{area}, \kbd{eta} and \kbd{omega} are
2058: only available for curves over $\Q$. Conversely, \kbd{tate} and \kbd{w} are
2059: only available for curves defined over $\Q_p$.\smallskip
2060:
2061: Some functions, in particular those relative to height computations (see
2062: \kbd{ellheight}) require also that the curve be in minimal Weierstrass
2063: form. This is achieved by the function \kbd{ellglobalred}.
2064:
2065: All functions related to elliptic curves share the prefix \kbd{ell}, and the
2066: precise curve we are interested in is always the first argument, in either
2067: one of the three formats discussed above, unless otherwise specified. For
2068: instance, in functions which do not use the extra information given by long
2069: vectors, the curve can be given either as a five-component vector, or by one
2070: of the longer vectors computed by \kbd{ellinit}.
2071:
2072: \subsecidx{elladd}$(E,z1,z2)$: sum of the points $z1$ and $z2$ on the
2073: elliptic curve corresponding to the vector $E$.
2074:
2075: \syn{addell}{E,z1,z2}.
2076:
2077: \subsecidx{ellak}$(E,n)$: computes the coefficient $a_n$ of the
2078: $L$-function of the elliptic curve $E$, i.e.~in principle coefficients of a
2079: newform of weight 2 assuming \idx{Taniyama-Weil conjecture} (which is now
2080: known to hold in full generality thanks to the work of \idx{Breuil},
2081: \idx{Conrad}, \idx{Diamond}, \idx{Taylor} and \idx{Wiles}). $E$ must be a
2082: medium or long vector of the type given by \kbd{ellinit}. For this function
2083: to work for every $n$ and not just those prime to the conductor, $E$ must
2084: be a minimal Weierstrass equation. If this is not the case, use the
2085: function \kbd{ellglobalred} first before using \kbd{ellak}.
2086:
2087: \syn{akell}{E,n}.
2088:
2089: \subsecidx{ellan}$(E,n)$: computes the vector of the first $n$ $a_k$
2090: corresponding to the elliptic curve $E$. All comments in \kbd{ellak}
2091: description remain valid.
2092:
2093: \syn{anell}{E,n}, where $n$ is a C integer.
2094:
2095: \subsecidx{ellap}$(E,p,\{\fl=0\})$: computes the $a_p$ corresponding to the
2096: elliptic curve $E$ and the prime number $p$. These are defined by the
2097: equation $\#E(\F_p) = p+1 - a_p$, where $\#E(\F_p)$ stands for the number
2098: of points of the curve $E$ over the finite field $\F_p$. When $\fl$ is $0$,
2099: this uses the baby-step giant-step method and a trick due to Mestre. This
2100: runs in time $O(p^{1/4})$ and requires $O(p^{1/4})$ storage, hence becomes
2101: unreasonable when $p$ has about 30 digits.
2102:
2103: If $\fl$ is $1$, computes the $a_p$ as a sum of Legendre symbols. This is
2104: slower than the previous method as soon as $p$ is greater than 100, say.
2105:
2106: No checking is done that $p$ is indeed prime. $E$ must be a medium or long
2107: vector of the type given by \kbd{ellinit}, defined over $\Q$, $\F_p$ or
2108: $\Q_p$. $E$ must be given by a Weierstrass equation minimal at $p$.
2109:
2110: \syn{ellap0}{E,p,\fl}. Also available are $\teb{apell}(E,p)$, corresponding
2111: to $\fl=0$, and $\teb{apell2}(E,p)$ ($\fl=1$).
2112:
2113: \subsecidx{ellbil}$(E,z1,z2)$: if $z1$ and $z2$ are points on the elliptic
2114: curve $E$, this function computes the value of the canonical bilinear form on
2115: $z1$, $z2$:
2116: $$
2117: \kbd{ellheight}(E,z1\kbd{+}z2) - \kbd{ellheight}(E,z1) - \kbd{ellheight}(E,z2)
2118: $$
2119: where \kbd{+} denotes of course addition on $E$. In addition, $z1$ or $z2$
2120: (but not both) can be vectors or matrices. Note that this is equal to twice
2121: some normalizations. $E$ is assumed to be integral, given by a minimal model.
2122:
2123: \syn{bilhell}{E,z1,z2,\var{prec}}.
2124:
2125: \subsecidx{ellchangecurve}$(E,v)$: changes the data for the elliptic curve $E$
2126: by changing the coordinates using the vector \kbd{v=[u,r,s,t]}, i.e.~if $x'$
2127: and $y'$ are the new coordinates, then $x=u^2x'+r$, $y=u^3y'+su^2x'+t$.
2128: The vector $E$ must be a medium or long vector of the type given by
2129: \kbd{ellinit}.
2130:
2131: \syn{coordch}{E,v}.
2132:
2133: \subsecidx{ellchangepoint}$(x,v)$: changes the coordinates of the point or
2134: vector of points $x$ using the vector \kbd{v=[u,r,s,t]}, i.e.~if $x'$ and
2135: $y'$ are the new coordinates, then $x=u^2x'+r$, $y=u^3y'+su^2x'+t$ (see also
2136: \kbd{ellchangecurve}).
2137:
2138: \syn{pointch}{x,v}.
2139:
2140: \subsecidx{elleisnum}$(E,k,\{\fl=0\})$: $E$ being an elliptic curve as
2141: output by \kbd{ellinit} (or, alternatively, given by a 2-component vector
2142: $[\omega_1,\omega_2]$), and $k$ being an even positive integer, computes
2143: the numerical value of the Eisenstein series of weight $k$ at $E$. When
2144: \fl\ is non-zero and $k=4$ or 6, returns $g_2$ or $g_3$ with the correct
2145: normalization.
2146:
2147: \syn{elleisnum}{E,k,\fl}.
2148:
2149: \subsecidx{elleta}$(om)$: returns the two-component row vector
2150: $[\eta_1,\eta_2]$ of quasi-periods associated to $\kbd{om} = [\omega_1,
2151: \omega_2]$
2152:
2153: \syn{elleta}{om, \var{prec}}
2154:
2155: \subsecidx{ellglobalred}$(E)$: calculates the arithmetic conductor, the global
2156: minimal model of $E$ and the global \idx{Tamagawa number} $c$. Here $E$ is an
2157: elliptic curve given by a medium or long vector of the type given by
2158: \kbd{ellinit}, {\it and is supposed to have all its coefficients $a_i$ in}
2159: $\Q$. The result is a 3 component vector $[N,v,c]$. $N$ is the arithmetic
2160: conductor of the curve, $v$ is itself a vector $[u,r,s,t]$ with rational
2161: components. It gives a coordinate change for $E$ over $\Q$ such that the
2162: resulting model has integral coefficients, is everywhere minimal, $a_1$ is 0
2163: or 1, $a_2$ is 0, 1 or $-1$ and $a_3$ is 0 or 1. Such a model is unique, and
2164: the vector $v$ is unique if we specify that $u$ is positive. To get the new
2165: model, simply type \kbd{ellchangecurve(E,v)}. Finally $c$ is the product of
2166: the local Tamagawa numbers $c_p$, a quantity which enters in the
2167: \idx{Birch and Swinnerton-Dyer conjecture}.
2168:
2169: \syn{globalreduction}{E}.
2170:
2171: \subsecidx{ellheight}$(E,z,\{\fl=0\})$: global \idx{N\'eron-Tate height} of
2172: the point $z$ on the elliptic curve $E$. The vector $E$ must be a long vector
2173: of the type given by \kbd{ellinit}, with $\fl=1$. If $\fl=0$, this
2174: computation is done using sigma and theta-functions and a trick due to J.
2175: Silverman. If $\fl=1$, use Tate's $4^n$ algorithm, which is much slower.
2176: $E$ is assumed to be integral, given by a minimal model.
2177:
2178: \syn{ellheight0}{E,z,\fl,\var{prec}}. The Archimedean
2179: contribution alone is given by the library function
2180: $\teb{hell}(E,z,\var{prec})$.
2181: Also available are $\teb{ghell}(E,z,\var{prec})$ ($\fl=0$) and
2182: $\teb{ghell2}(E,z,\var{prec})$ ($\fl=1$).
2183:
2184: \subsecidx{ellheightmatrix}$(E,x)$: $x$ being a vector of points, this
2185: function outputs the Gram matrix of $x$ with respect to the N\'eron-Tate
2186: height, in other words, the $(i,j)$ component of the matrix is equal to
2187: \kbd{ellbil($E$,x[$i$],x[$j$])}. The rank of this matrix, at least in some
2188: approximate sense, gives the rank of the set of points, and if $x$ is a
2189: basis of the \idx{Mordell-Weil group} of $E$, its determinant is equal to
2190: the regulator of $E$. Note that this matrix should be divided by 2 to be in
2191: accordance with certain normalizations. $E$ is assumed to be integral,
2192: given by a minimal model.
2193:
2194: \syn{mathell}{E,x,\var{prec}}.
2195:
2196: \subsecidx{ellinit}$(E,\{\fl=0\})$: computes some fixed data concerning the
2197: elliptic curve given by the five-component vector $E$, which will be
2198: essential for most further computations on the curve. The result is a
2199: 19-component vector E (called a long vector in this section), shortened
2200: to 13 components (medium vector) if $\fl=1$. Both contain the
2201: following information in the first 13 components:
2202: %
2203: $$ a_1,a_2,a_3,a_4,a_6,b_2,b_4,b_6,b_8,c_4,c_6,\Delta,j.$$
2204: %
2205: In particular, the discriminant is $E[12]$ (or \kbd{$E$.disc}), and the
2206: $j$-invariant is $E[13]$ (or \kbd{$E$.j}).
2207:
2208: The other six components are only present if $\fl$ is $0$ (or omitted!).
2209: Their content depends on whether the curve is defined over $\R$ or not:
2210: \smallskip
2211: $\bullet$ When $E$ is defined over $\R$, $E[14]$ (\kbd{$E$.roots}) is a
2212: vector whose three components contain the roots of the associated Weierstrass
2213: equation. If the roots are all real, then they are ordered by decreasing
2214: value. If only one is real, it is the first component of $E[14]$.
2215:
2216: $E[15]$ (\kbd{$E$.omega[1]}) is the real period of $E$ (integral of
2217: $dx/(2y+a_1x+a_3)$ over the connected component of the identity element of
2218: the real points of the curve), and $E[16]$ (\kbd{$E$.omega[2]}) is a complex
2219: period. In other words, $\omega_1=E[15]$ and $\omega_2=E[16]$ form a basis of
2220: the complex lattice defining $E$ (\kbd{$E$.omega}), with
2221: $\tau=\dfrac{\omega_2}{\omega_1}$ having positive imaginary part.
2222:
2223: $E[17]$ and $E[18]$ are the corresponding values $\eta_1$ and $\eta_2$ such
2224: that $\eta_1\omega_2-\eta_2\omega_1=i\pi$, and both can be retrieved by
2225: typing \kbd{$E$.eta} (as a row vector whose components are the $\eta_i$).
2226:
2227: Finally, $E[19]$ (\kbd{$E$.area}) is the volume of the complex lattice defining
2228: $E$.\smallskip
2229:
2230: $\bullet$ When $E$ is defined over $\Q_p$, the $p$-adic valuation of $j$
2231: must be negative. Then $E[14]$ (\kbd{$E$.roots}) is the vector with a single
2232: component equal to the $p$-adic root of the associated Weierstrass equation
2233: corresponding to $-1$ under the Tate parametrization.
2234:
2235: $E[15]$ is equal to the square of the $u$-value, in the notation of Tate.
2236:
2237: $E[16]$ is the $u$-value itself, if it belongs to $\Q_p$, otherwise zero.
2238:
2239: $E[17]$ is the value of Tate's $q$ for the curve $E$.
2240:
2241: \kbd{$E$.tate} will yield the three-component vector $[u^2,u,q]$.
2242:
2243: $E[18]$ (\kbd{$E$.w}) is the value of Mestre's $w$ (this is technical), and
2244: $E[19]$ is arbitrarily set equal to zero.
2245: \smallskip
2246: For all other base fields or rings, the last six components are arbitrarily
2247: set equal to zero (see also the description of member functions related to
2248: elliptic curves at the beginning of this section).
2249:
2250: \syn{ellinit0}{E,\fl,\var{prec}}. Also available are
2251: $\teb{initell}(E,\var{prec})$ ($\fl=0$) and
2252: $\teb{smallinitell}(E,\var{prec})$ ($\fl=1$).
2253:
2254: \subsecidx{ellisoncurve}$(E,z)$: gives 1 (i.e.~true) if the point $z$ is on
2255: the elliptic curve $E$, 0 otherwise. If $E$ or $z$ have imprecise coefficients,
2256: an attempt is made to take this into account, i.e.~an imprecise equality is
2257: checked, not a precise one.
2258:
2259: \syn{oncurve}{E,z}, and the result is a \kbd{long}.
2260:
2261: \subsecidx{ellj}$(x)$: elliptic $j$-invariant. $x$ must be a complex number
2262: with positive imaginary part, or convertible into a power series or a
2263: $p$-adic number with positive valuation.
2264:
2265: \syn{jell}{x,\var{prec}}.
2266:
2267: \subsecidx{elllocalred}$(E,p)$: calculates the \idx{Kodaira} type of the
2268: local fiber of the elliptic curve $E$ at the prime $p$.
2269: $E$ must be given by a medium or
2270: long vector of the type given by \kbd{ellinit}, and is assumed to have all
2271: its coefficients $a_i$ in $\Z$. The result is a 4-component vector
2272: $[f,kod,v,c]$. Here $f$ is the exponent of $p$ in the arithmetic conductor of
2273: $E$, and $kod$ is the Kodaira type which is coded as follows:
2274:
2275: 1 means good reduction (type I$_0$), 2, 3 and 4 mean types II, III and IV
2276: respectively, $4+\nu$ with $\nu>0$ means type I$_\nu$;
2277: finally the opposite values $-1$, $-2$, etc.~refer to the starred types
2278: I$_0^*$, II$^*$, etc. The third component $v$ is itself a vector $[u,r,s,t]$
2279: giving the coordinate changes done during the local reduction. Normally, this
2280: has no use if $u$ is 1, that is, if the given equation was already minimal.
2281: Finally, the last component $c$ is the local \idx{Tamagawa number} $c_p$.
2282:
2283: \syn{localreduction}{E,p}.
2284:
2285: \subsecidx{elllseries}$(E,s,\{A=1\})$: $E$ being a medium or long vector
2286: given by \kbd{ellinit}, this computes the value of the L-series of $E$ at
2287: $s$. It is assumed that $E$ is a minimal model over $\Z$ and that the curve
2288: is a modular elliptic curve. The optional parameter $A$ is a cutoff point for
2289: the integral, which must be chosen close to 1 for best speed. The result
2290: must be independent of $A$, so this allows some internal checking of the
2291: function.
2292:
2293: Note that if the conductor of the curve is large, say greater than $10^{12}$,
2294: this function will take an unreasonable amount of time since it uses an
2295: $O(N^{1/2})$ algorithm.
2296:
2297: \syn{lseriesell}{E,s,A,\var{prec}} where $\var{prec}$ is a \kbd{long} and an
2298: omitted $A$ is coded as \kbd{NULL}.
2299:
2300: \subsecidx{ellorder}$(E,z)$: gives the order of the point $z$ on the elliptic
2301: curve $E$ if it is a torsion point, zero otherwise. In the present version
2302: \vers, this is implemented only for elliptic curves defined over $\Q$.
2303:
2304: \syn{orderell}{E,z}.
2305:
2306: \subsecidx{ellordinate}$(E,x)$: gives a 0, 1 or 2-component vector containing
2307: the $y$-coordinates of the points of the curve $E$ having $x$ as
2308: $x$-coordinate.
2309:
2310: \syn{ordell}{E,x}.
2311:
2312: \subsecidx{ellpointtoz}$(E,z)$: if $E$ is an elliptic curve with coefficients
2313: in $\R$, this computes a complex number $t$ (modulo the lattice defining
2314: $E$) corresponding to the point $z$, i.e.~such that, in the standard
2315: Weierstrass model, $\wp(t)=z[1],\wp'(t)=z[2]$. In other words, this is the
2316: inverse function of \kbd{ellztopoint}.
2317:
2318: If $E$ has coefficients in $\Q_p$, then either Tate's $u$ is in $\Q_p$, in
2319: which case the output is a $p$-adic number $t$ corresponding to the point $z$
2320: under the Tate parametrization, or only its square is, in which case the
2321: output is $t+1/t$. $E$ must be a long vector output by \kbd{ellinit}.
2322:
2323: \syn{zell}{E,z,\var{prec}}.
2324:
2325: \subsecidx{ellpow}$(E,z,n)$: computes $n$ times the point $z$ for the
2326: group law on the elliptic curve $E$. Here, $n$ can be in $\Z$, or $n$
2327: can be a complex quadratic integer if the curve $E$ has complex multiplication
2328: by $n$ (if not, an error message is issued).
2329:
2330: \syn{powell}{E,z,n}.
2331:
2332: \subsecidx{ellrootno}$(E,\{p=1\})$: $E$ being a medium or long vector given
2333: by \kbd{ellinit}, this computes the local (if $p\neq 1$) or global (if $p=1$)
2334: root number of the L-series of the elliptic curve $E$. Note that the global
2335: root number is the sign of the functional equation and conjecturally is the
2336: parity of the rank of the \idx{Mordell-Weil group}.
2337: The equation for $E$ must have
2338: coefficients in $\Q$ but need \var{not} be minimal.
2339:
2340: \syn{ellrootno}{E,p} and the result (equal to $\pm1$) is a \kbd{long}.
2341:
2342: \subsecidx{ellsigma}$(E,z,\{\fl=0\})$: value of the Weierstrass $\sigma$
2343: function of the lattice associated to $E$ as given by \kbd{ellinit}
2344: (alternatively, $E$ can be given as a lattice $[\omega_1,\omega_2]$).
2345:
2346: If $\fl=1$, computes an (arbitrary) determination of $\log(\sigma(z))$.
2347:
2348: If $\fl=2,3$, same using the product expansion instead of theta series.
2349: \syn{ellsigma}{E,z,\fl}
2350:
2351: \subsecidx{ellsub}$(E,z1,z2)$: difference of the points $z1$ and $z2$ on the
2352: elliptic curve corresponding to the vector $E$.
2353:
2354: \syn{subell}{E,z1,z2}.
2355:
2356: \subsecidx{elltaniyama}$(E)$: computes the modular parametrization of the
2357: elliptic curve $E$, where $E$ is given in the (long or medium) format output
2358: by \kbd{ellinit}, in the form of a two-component vector $[u,v]$ of power
2359: series, given to the current default series precision. This vector is
2360: characterized by the following two properties. First the point $(x,y)=(u,v)$
2361: satisfies the equation of the elliptic curve. Second, the differential
2362: $du/(2v+a_1u+a_3)$ is equal to $f(z)dz$, a differential form on
2363: $H/\Gamma_0(N)$ where $N$ is the conductor of the curve. The variable used in
2364: the power series for $u$ and $v$ is $x$, which is implicitly understood to be
2365: equal to $\exp(2i\pi z)$. It is assumed that the curve is a \var{strong}
2366: \idx{Weil curve}, and the Manin constant is equal to 1. The equation of
2367: the curve $E$ must be minimal (use \kbd{ellglobalred} to get a minimal
2368: equation).
2369:
2370: \syn{taniyama}{E}, and the precision of the result is determined by the
2371: global variable \kbd{precdl}.
2372:
2373: \subsecidx{elltors}$(E,\{\fl=0\})$: if $E$ is an elliptic curve {\it defined
2374: over $\Q$}, outputs the torsion subgroup of $E$ as a 3-component vector
2375: \kbd{[t,v1,v2]}, where \kbd{t} is the order of the torsion group, \kbd{v1}
2376: gives the structure of the torsion group as a product of cyclic groups
2377: (sorted by decreasing order), and \kbd{v2} gives generators for these cyclic
2378: groups. $E$ must be a long vector as output by \kbd{ellinit}.
2379:
2380: \bprog
2381: ? E = ellinit([0,0,0,-1,0]);
2382: ? elltors(E)
2383: %1 = [4, [2, 2], [[0, 0], [1, 0]]]
2384: @eprog
2385: Here, the torsion subgroup is isomorphic to $\Z/2\Z \times \Z/2\Z$, with
2386: generators $[0,0]$ and $[1,0]$.
2387:
2388: If $\fl = 0$, use Doud's algorithm~: bound torsion by computing $\#E(\F_p)$
2389: for small primes of good reduction, then look for torsion points using
2390: Weierstrass parametrization (and Mazur's classification).
2391:
2392: If $\fl = 1$, use Lutz--Nagell (\var{much} slower), $E$ is allowed to be a
2393: medium vector.
2394:
2395: \syn{elltors0}{E,flag}.
2396:
2397: \subsecidx{ellwp}$(E,\{z=x\},\{\fl=0\})$:
2398:
2399: Computes the value at $z$ of the Weierstrass $\wp$ function attached to the
2400: elliptic curve $E$ as given by \kbd{ellinit} (alternatively, $E$ can be
2401: given as a lattice $[\omega_1,\omega_2]$).
2402:
2403: If $z$ is omitted or is a simple variable, computes the \var{power series}
2404: expansion in $z$ (starting $z^{-2}+O(z^2)$). The number of terms to an
2405: \var{even} power in the expansion is the default serieslength in GP, and the
2406: second argument (C long integer) in library mode.
2407:
2408: Optional \fl\ is (for now) only taken into account when $z$ is numeric, and
2409: means 0: compute only $\wp(z)$, 1: compute $[\wp(z),\wp'(z)]$.
2410:
2411: \syn{ellwp0}{E,z,\fl,\var{prec},\var{precdl}}. Also available is
2412: \teb{weipell}$(E,\var{precdl})$ for the power series (in
2413: $x=\kbd{polx[0]}$).
2414:
2415: \subsecidx{ellzeta}$(E,z)$: value of the Weierstrass $\zeta$ function of the
2416: lattice associated to $E$ as given by \kbd{ellinit} (alternatively, $E$ can
2417: be given as a lattice $[\omega_1,\omega_2]$).
2418:
2419: \syn{ellzeta}{E,z}.
2420:
2421: \subsecidx{ellztopoint}$(E,z)$: $E$ being a long vector, computes the
2422: coordinates $[x,y]$ on the curve $E$ corresponding to the complex number $z$.
2423: Hence this is the inverse function of \kbd{ellpointtoz}. In other words, if
2424: the curve is put in Weierstrass form, $[x,y]$ represents the
2425: \idx{Weierstrass $\wp$-function} and its derivative.
2426: If $z$ is in the lattice defining $E$ over
2427: $\C$, the result is the point at infinity $[0]$.
2428:
2429: \syn{pointell}{E,z,\var{prec}}.
2430:
2431: \section{Functions related to general number fields}
2432:
2433: In this section can be found functions which are used almost exclusively for
2434: working in general number fields. Other less specific functions can be found
2435: in the next section on polynomials. Functions related to quadratic number
2436: fields can be found in the section \secref{se:arithmetic} (Arithmetic
2437: functions).
2438:
2439: \noindent We shall use the following conventions:
2440:
2441: $\bullet$ $\tev{nf}$ denotes a number field, i.e.~a 9-component vector
2442: in the format output by \tet{nfinit}. This contains the basic arithmetic data
2443: associated to the number field: signature, maximal order, discriminant, etc.
2444:
2445: $\bullet$ $\tev{bnf}$ denotes a big number field, i.e.~a 10-component
2446: vector in the format output by \tet{bnfinit}. This contains $\var{nf}$ and
2447: the deeper invariants of the field: units, class groups, as well as a lot of
2448: technical data necessary for some complex fonctions like \kbd{bnfisprincipal}.
2449:
2450: $\bullet$ $\tev{bnr}$ denotes a big ``ray number field'', i.e.~some data
2451: structure output by \kbd{bnrinit}, even more complicated than $\var{bnf}$,
2452: corresponding to the ray class group structure of the field, for some
2453: modulus.
2454:
2455: $\bullet$ $\tev{rnf}$ denotes a relative number field (see below).
2456: \smallskip
2457:
2458: $\bullet$ $\tev{ideal}$ can mean any of the following:
2459:
2460: \quad -- a $\Z$-basis, in \idx{Hermite normal form}
2461: (HNF) or not. In this case $x$ is a square matrix.
2462:
2463: \quad -- an \tev{idele}, i.e.~a 2-component vector, the first being an
2464: ideal given as a $\Z$--basis, the second being a $r_1+r_2$-component row
2465: vector giving the complex logarithmic Archimedean information.
2466:
2467: \quad -- a $\Z_K$-generating system for an ideal.
2468:
2469: \quad -- a \var{column} vector $x$ expressing an element of the number field
2470: on the integral basis, in which case the ideal is treated as being the
2471: principal idele (or ideal) generated by $x$.
2472:
2473: \quad -- a prime ideal, i.e.~a 5-component vector in the format output by
2474: \kbd{idealprimedec}.
2475:
2476: \quad -- a polmod $x$, i.e.~an algebraic integer, in which case the ideal
2477: is treated as being the principal idele generated by $x$.
2478:
2479: \quad -- an integer or a rational number, also treated as a principal idele.
2480:
2481: $\bullet$ a \var{{character}} on the Abelian group
2482: $\bigoplus (\Z/N_i\Z) g_i$
2483: is given by a row vector $\chi = [a_1,\ldots,a_n]$ such that
2484: $\chi(\prod g_i^{n_i}) = exp(2i\pi\sum a_i n_i / N_i)$.
2485:
2486:
2487: \misctitle{Warnings:}
2488:
2489: 1) An element in $\var{nf}$ can be expressed either as a polmod or as a
2490: vector of components on the integral basis \kbd{\var{nf}.zk}. It is absolutely
2491: essential that all such vectors be \var{column} vectors.
2492:
2493: 2) When giving an ideal by a $\Z_K$ generating system to a function expecting
2494: an ideal, it must be ensured that the function understands that it is a
2495: $\Z_K$-generating system and not a $\Z$-generating system. When the number of
2496: generators is strictly less than the degree of the field, there is no
2497: ambiguity and the program assumes that one is giving a $\Z_K$-generating set.
2498: When the number of generators is greater than or equal to the degree of the
2499: field, however, the program assumes on the contrary that you are giving a
2500: $\Z$-generating set. If this is not the case, you \var{must} absolutely
2501: change it into a $\Z$-generating set, the simplest manner being to use
2502: \kbd{idealhnf(\var{nf},$x$)}.
2503:
2504: Concerning relative extensions, some additional definitions are necessary.
2505:
2506: $\bullet$ A \var{{relative matrix}} will be a matrix whose entries are
2507: elements of a (given) number field $\var{nf}$, always expressed as column
2508: vectors on the integral basis \kbd{\var{nf}.zk}. Hence it is a matrix of
2509: vectors.
2510:
2511: $\bullet$ An \tev{ideal list} will be a row vector of (fractional)
2512: ideals of the number field $\var{nf}$.
2513:
2514: $\bullet$ A \tev{pseudo-matrix} will be a pair $(A,I)$ where $A$ is a
2515: relative matrix and $I$ an ideal list whose length is the same as the number
2516: of columns of $A$. This pair will be represented by a 2-component row vector.
2517:
2518: $\bullet$ The \tev{module} generated by a pseudo-matrix $(A,I)$ is
2519: the sum $\sum_i{\Bbb a}_jA_j$ where the ${\Bbb a}_j$ are the ideals of $I$
2520: and $A_j$ is the $j$-th column of $A$.
2521:
2522: $\bullet$ A pseudo-matrix $(A,I)$ is a \tev{pseudo-basis} of the module
2523: it generates if $A$ is a square matrix with non-zero determinant and all the
2524: ideals of $I$ are non-zero. We say that it is in Hermite Normal
2525: Form\sidx{Hermite normal form} (HNF) if it is upper triangular and all the
2526: elements of the diagonal are equal to 1.
2527:
2528: $\bullet$ The \var{determinant} of a pseudo-basis $(A,I)$ is the ideal
2529: equal to the product of the determinant of $A$ by all the ideals of $I$. The
2530: determinant of a pseudo-matrix is the determinant of any pseudo-basis of the
2531: module it generates.
2532:
2533: Finally, when defining a relative extension, the base field should be
2534: defined by a variable having a lower priority (i.e.~a higher number)
2535: than the variable defining the extension. For example, under GP you can
2536: use the variable name $y$ (or $t$) to define the base field, and the
2537: variable name $x$ to define the relative extension.
2538:
2539: Now a last set of definitions concerning the way big ray number fields
2540: (or \var{bnr}) are input, using class field theory.
2541: These are defined by a triple
2542: $a1$, $a2$, $a3$, where the defining set $[a1,a2,a3]$ can have any of the
2543: following forms: $[\var{bnr}]$, $[\var{bnr},\var{subgroup}]$,
2544: $[\var{bnf},\var{module}]$, $[\var{bnf},\var{module},\var{subgroup}]$, where:
2545:
2546: $\bullet$ $\var{bnf}$ is as output by \kbd{bnfclassunit} or \kbd{bnfinit},
2547: where units are mandatory unless the ideal is trivial; \var{bnr} by
2548: \kbd{bnrclass} (with $\fl>0$) or \kbd{bnrinit}. This is the ground field.
2549:
2550: $\bullet$ \var{module} is either an ideal in any form (see above) or a
2551: two-component row vector containing an ideal and an $r_1$-component row
2552: vector of flags indicating which real Archimedean embeddings to take in the
2553: module.
2554:
2555: $\bullet$ \var{subgroup} is the HNF matrix of a subgroup of the ray class group
2556: of the ground field for the modulus \var{module}. This is input as a square
2557: matrix expressing generators of a subgroup of the ray class group
2558: \kbd{\var{bnr}.clgp} on the given generators.
2559:
2560: The corresponding \var{bnr} is then the subfield of the ray class field of the
2561: ground field for the given modulus, associated to the given subgroup.
2562:
2563: All the functions which are specific to relative extensions, number fields,
2564: big number fields, big number rays, share the prefix \kbd{rnf}, \kbd{nf},
2565: \kbd{bnf}, \kbd{bnr} respectively. They are meant to take as first argument a
2566: number field of that precise type, respectively output by \kbd{rnfinit},
2567: \kbd{nfinit}, \kbd{bnfinit}, and \kbd{bnrinit}.
2568:
2569: However, and even though it may not be specified in the descriptions of the
2570: functions below, it is permissible, if the function expects a $\var{nf}$, to
2571: use a $\var{bnf}$ instead (which contains much more information). The program
2572: will make the effort of converting to what it needs. On the other hand, if
2573: the program requires a big number field, the program will \var{not} launch
2574: \kbd{bnfinit} for you, which can be a costly operation. Instead, it will give
2575: you a specific error message.
2576:
2577: The data types corresponding to the structures described above are rather
2578: complicated. Thus, as we already have seen it with elliptic curves, GP
2579: provides you with some ``member functions'' to retrieve the data you need
2580: from these structures (once they have been initialized of course). The
2581: relevant types of number fields are indicated between parentheses:
2582: \smallskip
2583:
2584: \sidx{member functions}
2585: \settabs\+xxxxxxx&(\var{bnr},x&\var{bnf},x&nf\hskip2pt&)x&: &\cr
2586:
2587: \+\tet{bnf} &(\var{bnr},& \var{bnf}&&)&: & big number field.\cr
2588:
2589: \+\tet{clgp} &(\var{bnr},& \var{bnf}&&)&: & classgroup. This one admits the
2590: following three subclasses:\cr
2591:
2592: \+ \quad \tet{cyc} &&&&&: & \quad cyclic decomposition
2593: (SNF)\sidx{Smith normal form}.\cr
2594:
2595: \+ \quad \kbd{gen}\sidx{gen (member function)} &&&&&: &
2596: \quad generators.\cr
2597:
2598: \+ \quad \tet{no} &&&&&: & \quad number of elements.\cr
2599:
2600: \+\tet{diff} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & the different ideal.\cr
2601:
2602: \+\tet{codiff}&(\var{bnr},& \var{bnf},& \var{nf}&)&: & the codifferent
2603: (inverse of the different in the ideal group).\cr
2604:
2605: \+\tet{disc} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & discriminant.\cr
2606:
2607: \+\tet{fu} &(\var{bnr},& \var{bnf},& \var{nf}&)&: &
2608: \idx{fundamental units}.\cr
2609:
2610: \+\tet{futu} &(\var{bnr},& \var{bnf}&&)&: & $[u,w]$, $u$ is a vector of
2611: fundamental units, $w$ generates the torsion.\cr
2612:
2613: \+\tet{nf} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & number field.\cr
2614:
2615: \+\tet{reg} &(\var{bnr},& \var{bnf},&&)&: & regulator.\cr
2616:
2617: \+\tet{roots}&(\var{bnr},& \var{bnf},& \var{nf}&)&: & roots of the
2618: polnomial generating the field.\cr
2619:
2620: \+\tet{sign} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & $[r_1,r_2]$ the
2621: signature of the field. This means that the field has $r_1$ real \cr
2622: \+ &&&&&& embeddings, $2r_2$ complex ones.\cr
2623:
2624: \+\tet{t2} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & the T2 matrix (see
2625: \kbd{nfinit}).\cr
2626:
2627: \+\tet{tu} &(\var{bnr},& \var{bnf},&&)&: & a generator for the torsion
2628: units.\cr
2629:
2630: \+\tet{tufu} &(\var{bnr},& \var{bnf},&&)&: & as \kbd{futu}, but outputs
2631: $[w,u]$.\cr
2632:
2633: \+\tet{zk} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & integral basis, i.e.~a
2634: $\Z$-basis of the maximal order.\cr
2635:
2636: \+\tet{zkst} &(\var{bnr}& & &)&: & structure of $(\Z_K/m)^*$ (can be
2637: extracted also from an \var{idealstar}).\cr
2638:
2639: For instance, assume that $\var{bnf} = \kbd{bnfinit}(\var{pol})$, for some
2640: polynomial. Then \kbd{\var{bnf}.clgp} retrieves the class group, and
2641: \kbd{\var{bnf}.clgp.no} the class number. If we had set $\var{bnf} =
2642: \kbd{nfinit}(\var{pol})$, both would have output an error message. All these
2643: functions are completely recursive, thus for instance
2644: \kbd{\var{bnr}.bnf.nf.zk} will yield the maximal order of \var{bnr} (which
2645: you could get directly with a simple \kbd{\var{bnr}.zk} of course).
2646:
2647: \medskip
2648: The following functions, starting with \kbd{buch} in library mode, and with
2649: \kbd{bnf} under GP, are implementations of the sub-exponential algorithms for
2650: finding class and unit groups under \idx{GRH}, due to Hafner-McCurley,
2651: \idx{Buchmann} and Cohen-Diaz-Olivier.
2652:
2653: The general call to the functions concerning class groups of general number
2654: fields (i.e.~excluding \kbd{quadclassunit}) involves a polynomial $P$ and a
2655: technical vector
2656: $$\var{tech} = [c,c2,\var{nrel},\var{borne},\var{nrpid},\var{minsfb}],$$
2657: where the parameters are to be understood as follows:
2658:
2659: $P$ is the defining polynomial for the number field, which must be in
2660: $\Z[X]$, irreducible and, preferably, monic. In fact, if you supply a
2661: non-monic polynomial at this point, GP will issue a warning, then
2662: \var{transform your polynomial} so that it becomes monic. Instead of the
2663: normal result, say \kbd{res}, you then get a vector \kbd{[res,Mod(a,Q)]},
2664: where \kbd{Mod(a,Q)=Mod(X,P)} gives the change of variables.
2665:
2666: The numbers $c$ and $c2$ are positive real numbers which control the
2667: execution time and the stack size. To get maximum speed, set $c2=c$. To get a
2668: rigorous result (under \idx{GRH}) you must take $c2=12$ (or $c2=6$ in the
2669: quadratic case, but then you should use the much faster function
2670: \kbd{quadclassunit}). Reasonable values for $c$ are between $0.1$ and
2671: $2$. (The defaults are $c=c2=0.3$).
2672:
2673: $\var{nrel}$ is the number of initial extra relations requested in
2674: computing the
2675: relation matrix. Reasonable values are between 5 and 20. (The default is 5).
2676:
2677: $\var{borne}$ is a multiplicative coefficient of the Minkowski bound which
2678: controls
2679: the search for small norm relations. If this parameter is set equal to 0, the
2680: program does not search for small norm relations. Otherwise reasonable values
2681: are between $0.5$ and $2.0$. (The default is $1.0$).
2682:
2683: $\var{nrpid}$ is the maximal number of small norm relations associated to each
2684: ideal in the factor base. Irrelevant when $\var{borne}=0$. Otherwise,
2685: reasonable values are between 4 and 20. (The default is 4).
2686:
2687: $\var{minsfb}$ is the minimal number of elements in the ``sub-factorbase''.
2688: If the
2689: program does not seem to succeed in finding a full rank matrix (which you can
2690: see in GP by typing \kbd{\bs g 2}), increase this number. Reasonable values
2691: are between 2 and 5. (The default is 3).
2692:
2693: \misctitle{Remarks.}
2694:
2695: Apart from the polynomial $P$, you don't need to supply any of the technical
2696: parameters (under the library you still need to send at least an empty
2697: vector, \kbd{cgetg(1,t\_VEC)}). However, should you choose to set some of
2698: them, they \var{must} be given in the requested order. For example, if you
2699: want to specify a given value of $nrel$, you must give some values as well
2700: for $c$ and $c2$, and provide a vector $[c,c2,nrel]$.
2701:
2702: Note also that you can use an $\var{nf}$ instead of $P$, which avoids
2703: recomputing the integral basis and analogous quantities.
2704:
2705: \smallskip
2706: \subsecidx{bnfcertify}$(\var{bnf})$: $\var{bnf}$ being a big number field
2707: as output by \kbd{bnfinit} or \kbd{bnfclassunit}, checks whether the result
2708: is correct, i.e.~whether it is possible to remove the assumption of the
2709: Generalized Riemann Hypothesis\sidx{GRH}. If it is correct, the answer is 1.
2710: If not, the program may output some error message, but more probably will loop
2711: indefinitely. In \var{no} occasion can the program give a wrong answer
2712: (barring bugs of course): if the program answers 1, the answer is certified.
2713:
2714: \syn{certifybuchall}{\var{bnf}}, and the result is a C long.
2715:
2716: \subsecidx{bnfclassunit}$(P,\{\fl=0\},\{\var{tech}=[\,]\})$: \idx{Buchmann}'s
2717: sub-exponential algorithm for computing the class group, the regulator and a
2718: system of \idx{fundamental units} of the general algebraic number field $K$
2719: defined by the irreducible polynomial $P$ with integer coefficients.
2720:
2721: The result of this function is a vector $v$ with 10 components (it is
2722: \var{not} a $\var{bnf}$, you need \kbd{bnfinit} for that), which for ease of
2723: presentation is in fact output as a one column matrix. First we describe the
2724: default behaviour ($\fl=0$):
2725:
2726: $v[1]$ is equal to the polynomial $P$. Note that for optimum performance,
2727: $P$ should have gone through \kbd{polred} or $\kbd{nfinit}(x,2)$.
2728:
2729: $v[2]$ is the 2-component vector $[r1,r2]$, where $r1$ and $r2$ are as usual
2730: the number of real and half the number of complex embeddings of the number
2731: field $K$.
2732:
2733: $v[3]$ is the 2-component vector containing the field discriminant and the
2734: index.
2735:
2736: $v[4]$ is an integral basis in Hermite normal form.
2737:
2738: $v[5]$ (\kbd{$v$.clgp}) is a 3-component vector containing the class number
2739: (\kbd{$v$.clgp.no}), the structure of the class group as a product of cyclic
2740: groups of order $n_i$ (\kbd{$v$.clgp.cyc}), and the corresponding generators
2741: of the class group of respective orders $n_i$ (\kbd{$v$.clgp.gen}).
2742:
2743: $v[6]$ (\kbd{$v$.reg}) is the regulator computed to an accuracy which is the
2744: maximum of an internally determined accuracy and of the default.
2745:
2746: $v[7]$ is a measure of the correctness of the result. If it is close to 1,
2747: the results are correct (under \idx{GRH}). If it is close to a larger integer,
2748: this shows that the product of the class number by the regulator is off by a
2749: factor equal to this integer, and you must start again with a larger value
2750: for $c$ or a different random seed, i.e.~use the function \kbd{setrand}.
2751: (Since the computation involves a random process, starting again with exactly
2752: the same parameters may give the correct result.) In this case a warning
2753: message is printed.
2754:
2755: $v[8]$ (\kbd{$v$.tu}) a vector with 2 components, the first being the number
2756: $w$ of roots of unity in $K$ and the second a primitive $w$-th root of unity
2757: expressed as a polynomial.
2758:
2759: $v[9]$ (\kbd{$v$.fu}) is a system of fundamental units also expressed as
2760: polynomials.
2761:
2762: $v[10]$ gives a measure of the correctness of the computations of the
2763: fundamental units (not of the regulator), expressed as a number of bits. If
2764: this number is greater than $20$, say, everything is OK. If $v[10]\le0$,
2765: then we have lost all accuracy in computing the units (usually an error
2766: message will be printed and the units not given). In the intermediate cases,
2767: one must proceed with caution (for example by increasing the current
2768: precision).
2769:
2770: If $\fl=1$, and the precision happens to be insufficient for obtaining the
2771: fundamental units exactly, the internal precision is doubled and the
2772: computation redone, until the exact results are obtained. The user should be
2773: warned that this can take a very long time when the coefficients of the
2774: fundamental units on the integral basis are very large, for example in the
2775: case of large real quadratic fields. In that case, there are alternate
2776: methods for representing algebraic numbers which are not implemented in PARI.
2777:
2778: If $\fl=2$, the fundamental units and roots of unity are not computed.
2779: Hence the result has only 7 components, the first seven ones.
2780:
2781: $\var{tech}$ is a technical vector (empty by default) containing $c$, $c2$,
2782: \var{nrel}, \var{borne}, \var{nbpid}, \var{minsfb}, in this order (see
2783: the beginning of the section or the keyword \kbd{bnf}).
2784: You can supply any number of these {\it provided you give an actual value to
2785: each of them} (the ``empty arg'' trick won't work here). Careful use of these
2786: parameters may speed up your computations considerably.
2787:
2788: \syn{bnfclassunit0}{P,\fl,\var{tech},\var{prec}}.
2789:
2790: \subsecidx{bnfclgp}$(P,\{\var{tech}=[\,]\})$: as \kbd{bnfclassunit}, but only
2791: outputs $v[5]$, i.e.~the class group.
2792:
2793: \syn{bnfclassgrouponly}{P,\var{tech},\var{prec}}, where \var{tech}
2794: is as described under \kbd{bnfclassunit}.
2795:
2796: \subsecidx{bnfdecodemodule}$(\var{nf},m)$: if $m$ is a module as output in the
2797: first component of an extension given by \kbd{bnrdisclist}, outputs the
2798: true module.
2799:
2800: \syn{decodemodule}{\var{nf},m}.
2801:
2802: \subsecidx{bnfinit}$(P,\{\fl=0\},\{\var{tech}=[\,]\})$: essentially identical
2803: to \kbd{bnfclassunit} except that the output contains a lot of technical data,
2804: and should not be printed out explicitly in general. The result of
2805: \kbd{bnfinit} is used in programs such as \kbd{bnfisprincipal},
2806: \kbd{bnfisunit} or \kbd{bnfnarrow}. The result is a 10-component vector
2807: $\var{bnf}$.
2808:
2809: \noindent $\bullet$ The first 6 and last 2 components are technical and in
2810: principle are not used by the casual user. However, for the sake of
2811: completeness, their description is as follows. We use the notations explained
2812: in the book by H. Cohen, {\it A Course in Computational Algebraic Number
2813: Theory}, Graduate Texts in Maths \key{138}, Springer-Verlag, 1993, Section
2814: 6.5, and subsection 6.5.5 in particular.
2815:
2816: $\var{bnf}[1]$ contains the matrix $W$, i.e.~the matrix in Hermite normal
2817: form giving relations for the class group on prime ideal generators
2818: $(\p_i)_{1\le i\le r}$.
2819:
2820: $\var{bnf}[2]$ contains the matrix $B$, i.e.~the matrix containing the
2821: expressions of the prime ideal factorbase in terms of the $\p_i$. It is an
2822: $r\times c$ matrix.
2823:
2824: $\var{bnf}[3]$ contains the complex logarithmic embeddings of the system of
2825: fundamental units which has been found. It is an $(r_1+r_2)\times(r_1+r_2-1)$
2826: matrix.
2827:
2828: $\var{bnf}[4]$ contains the matrix $M''_C$ of Archimedean components of the
2829: relations of the matrix $(W|B)$.
2830:
2831: $\var{bnf}[5]$ contains the prime factor base, i.e.~the list of prime
2832: ideals used in finding the relations.
2833:
2834: $\var{bnf}[6]$ contains the permutation of the prime factor base which was
2835: necessary to reduce the relation matrix to the form explained in subsection
2836: 6.5.5 of GTM~138 (i.e.~with a big $c\times c$ identity matrix on the lower
2837: right). Note that in the above mentioned book, the need to permute the rows
2838: of the relation matrices which occur was not emphasized.
2839:
2840: $\var{bnf}[9]$ is a 3-element row vector used in \tet{bnfisprincipal} only
2841: and obtained as follows. Let $D = U W V$ obtained by applying the
2842: \idx{Smith normal form} algorithm to the matrix $W$ (= $\var{bnf}[1]$) and
2843: let $U_r$ be the reduction of $U$ modulo $D$. The first elements of the
2844: factorbase are given (in terms of \kbd{bnf.gen}) by the columns of $U_r$,
2845: with archimedian component $g_a$; let also $GD_a$ be the archimedian
2846: components of the generators of the (principal) ideals defined by the
2847: \kbd{bnf.gen[i]\pow bnf.cyc[i]}. Then $\var{bnf}[9]=[U_r, g_a, GD_a]$.
2848:
2849: Finally, $\var{bnf}[10]$ is by default unused and set equal to 0. This
2850: field is used to store further information about the field as it becomes
2851: available (which is rarely needed, hence would be too expensive to compute
2852: during the initial \kbd{bnfinit} call). For instance, the generators of the
2853: principal ideals \kbd{bnf.gen[i]\pow bnf.cyc[i]} (during a call to
2854: \tet{bnrisprincipal}), or those corresponding to the relations in $W$ and
2855: $B$ (when the \kbd{bnf} internal precision needs to be increased).
2856: \smallskip
2857:
2858: \noindent$\bullet$ The less technical components are as follows:
2859:
2860: $\var{bnf}[7]$ or \kbd{\var{bnf}.nf} is equal to the number field data
2861: $\var{nf}$ as would be given by \kbd{nfinit}.
2862:
2863: $\var{bnf}[8]$ is a vector containing the last 6 components of
2864: \kbd{bnfclassunit[,1]}, i.e.~the classgroup \kbd{\var{bnf}.clgp}, the
2865: regulator \kbd{\var{bnf}.reg}, the general ``check'' number which should be
2866: close to 1, the number of roots of unity and a generator \kbd{\var{bnf}.tu},
2867: the fundamental units \kbd{\var{bnf}.fu}, and finally the check on their
2868: computation. If the precision becomes insufficient, GP outputs a warning
2869: (\kbd{fundamental units too large, not given}) and does not strive to
2870: compute the units by default ($\fl=0$).
2871:
2872: When $\fl=1$, GP insists on finding the fundamental units exactly, the
2873: internal precision being doubled and the computation redone, until the exact
2874: results are obtained. The user should be warned that this can take a very
2875: long time when the coefficients of the fundamental units on the integral
2876: basis are very large.
2877:
2878: When $\fl=2$, on the contrary, it is initially agreed that GP
2879: will not compute units.
2880:
2881: When $\fl=3$, computes a very small version of \kbd{bnfinit}, a ``small big
2882: number field'' (or \var{sbnf} for short) which contains enough information
2883: to recover the full $\var{bnf}$ vector very rapidly, but which is much
2884: smaller and hence easy to store and print. It is supposed to be used in
2885: conjunction with \kbd{bnfmake}. The output is a 12 component vector $v$, as
2886: follows. Let $\var{bnf}$ be the result of a full \kbd{bnfinit}, complete with
2887: units. Then $v[1]$ is the polynomial $P$, $v[2]$ is the number of real
2888: embeddings $r_1$, $v[3]$ is the field discriminant, $v[4]$ is the integral
2889: basis, $v[5]$ is the list of roots as in the sixth component of \kbd{nfinit},
2890: $v[6]$ is the matrix $MD$ of \kbd{nfinit} giving a $\Z$-basis of the
2891: different, $v[7]$ is the matrix $\kbd{W} = \var{bnf}[1]$, $v[8]$ is the
2892: matrix $\kbd{matalpha}=\var{bnf}[2]$, $v[9]$ is the prime ideal factor base
2893: $\var{bnf}[5]$ coded in a compact way, and ordered according to the
2894: permutation $\var{bnf}[6]$, $v[10]$ is the 2-component vector giving the
2895: number of roots of unity and a generator, expressed on the integral basis,
2896: $v[11]$ is the list of fundamental units, expressed on the integral basis,
2897: $v[12]$ is a vector containing the algebraic numbers alpha corresponding to
2898: the columns of the matrix \kbd{matalpha}, expressed on the integral basis.
2899:
2900: Note that all the components are exact (integral or rational), except for
2901: the roots in $v[5]$. In practice, this is the only component which a user
2902: is allowed to modify, by recomputing the roots to a higher accuracy if
2903: desired. Note also that the member functions will \var{not} work on
2904: \var{sbnf}, you have to use \kbd{bnfmake} explicitly first.
2905:
2906: \syn{bnfinit0}{P,\fl,\var{tech},\var{prec}}.
2907:
2908: \subsecidx{bnfisintnorm}$(\var{bnf},x)$: computes a complete system of
2909: solutions (modulo units of positive norm) of the absolute norm equation
2910: $\text{Norm}(a)=x$,
2911: where $a$ is an integer in $\var{bnf}$. If $\var{bnf}$ has not been certified,
2912: the correctness of the result depends on the validity of \idx{GRH}.
2913:
2914: \syn{bnfisintnorm}{\var{bnf},x}.
2915:
2916: \subsecidx{bnfisnorm}$(\var{bnf},x,\{\fl=1\})$: tries to tell whether the
2917: rational number $x$ is the norm of some element y in $\var{bnf}$. Returns a
2918: vector $[a,b]$ where $x=Norm(a)*b$. Looks for a solution which is an $S$-unit,
2919: with $S$ a certain set of prime ideals containing (among others) all primes
2920: dividing $x$. If $\var{bnf}$ is known to be \idx{Galois}, set $\fl=0$ (in
2921: this case,
2922: $x$ is a norm iff $b=1$). If $\fl$ is non zero the program adds to $S$ the
2923: following prime ideals, depending on the sign of $\fl$. If $\fl>0$, the
2924: ideals of norm less than $\fl$. And if $\fl<0$ the ideals dividing $\fl$.
2925:
2926: If you are willing to assume \idx{GRH}, the answer is guaranteed
2927: (i.e.~$x$ is a norm iff $b=1$), if $S$ contains all primes less than
2928: $12\log(\var{disc}(\var{Bnf}))^2$,
2929: where $\var{Bnf}$ is the Galois closure of $\var{bnf}$.
2930:
2931: \syn{bnfisnorm}{\var{bnf},x,\fl,\var{prec}}, where $\fl$ and
2932: $\var{prec}$ are \kbd{long}s.
2933:
2934: \subsecidx{bnfissunit}$(\var{bnf},\var{sfu},x)$: $\var{bnf}$ being output by
2935: \kbd{bnfinit}, \var{sfu} by \kbd{bnfsunit}, gives the column vector of
2936: exponents of $x$ on the fundamental $S$-units and the roots of unity.
2937: If $x$ is not a unit, outputs an empty vector.
2938:
2939: \syn{bnfissunit}{\var{bnf},\var{sfu},x}.
2940:
2941: \subsecidx{bnfisprincipal}$(\var{bnf},x,\{\fl=1\})$: $\var{bnf}$ being the
2942: number field data output by \kbd{bnfinit}, and $x$ being either a $\Z$-basis
2943: of an ideal in the number field (not necessarily in HNF) or a prime ideal in
2944: the format output by the function \kbd{idealprimedec}, this function tests
2945: whether the ideal is principal or not. The result is more complete than a
2946: simple true/false answer: it gives a row vector $[v_1,v_2,check]$, where
2947:
2948: $v_1$ is the vector of components $c_i$ of the class of the ideal $x$ in the
2949: class group, expressed on the generators $g_i$ given by \kbd{bnfinit}
2950: (specifically \kbd{\var{bnf}.clgp.gen} which is the same as
2951: \kbd{\var{bnf}[8][1][3]}). The $c_i$ are chosen so that $0\le c_i<n_i$
2952: where $n_i$ is the order of $g_i$ (the vector of $n_i$ being
2953: \kbd{\var{bnf}.clgp.cyc}, that is \kbd{\var{bnf}[8][1][2]}).
2954:
2955: $v_2$ gives on the integral basis the components of $\alpha$ such that
2956: $x=\alpha\prod_ig_i^{c_i}$. In particular, $x$ is principal if and only if
2957: $v_1$ is equal to the zero vector, and if this the case $x=\alpha\Z_K$ where
2958: $\alpha$ is given by $v_2$. Note that if $\alpha$ is too large to be given, a
2959: warning message will be printed and $v_2$ will be set equal to the empty
2960: vector.
2961:
2962: Finally the third component \var{check} is analogous to the last component of
2963: \kbd{bnfclassunit}: it gives a check on the accuracy of the result, in bits.
2964: \var{check} should be at least $10$, and preferably much more. In any case, the
2965: result is checked for correctness.
2966:
2967: If $\fl=0$, outputs only $v_1$, which is much easier to compute.
2968:
2969: If $\fl=2$, does as if $\fl$ were $0$, but doubles the precision until a
2970: result is obtained.
2971:
2972: If $\fl=3$, as in the default behaviour ($\fl=1$), but doubles the precision
2973: until a result is obtained.
2974:
2975: The user is warned that these two last setting may induce \var{very} lengthy
2976: computations.
2977:
2978: \syn{isprincipalall}{\var{bnf},x,\fl}.
2979:
2980: \subsecidx{bnfisunit}$(\var{bnf},x)$: $\var{bnf}$ being the number field data
2981: output by
2982: \kbd{bnfinit} and $x$ being an algebraic number (type integer, rational or
2983: polmod), this outputs the decomposition of $x$ on the fundamental units and
2984: the roots of unity if $x$ is a unit, the empty vector otherwise. More
2985: precisely, if $u_1$,\dots,$u_r$ are the fundamental units, and $\zeta$ is
2986: the generator of the group of roots of unity (found by \kbd{bnfclassunit} or
2987: \kbd{bnfinit}), the output is a vector $[x_1,\dots,x_r,x_{r+1}]$ such that
2988: $x=u_1^{x_1}\cdots u_r^{x_r}\cdot\zeta^{x_{r+1}}$. The $x_i$ are integers for
2989: $i\le r$ and is an integer modulo the order of $\zeta$ for $i=r+1$.
2990:
2991: \syn{isunit}{\var{bnf},x}.
2992:
2993: \subsecidx{bnfmake}$(\var{sbnf})$: \var{sbnf} being a ``small $\var{bnf}$''
2994: as output by \kbd{bnfinit}$(x,3)$, computes the complete \kbd{bnfinit}
2995: information. The result is \var{not} identical to what \kbd{bnfinit} would
2996: yield, but is functionally identical. The execution time is very small
2997: compared to a complete \kbd{bnfinit}. Note that if the default precision in
2998: GP (or $\var{prec}$ in library mode) is greater than the precision of the
2999: roots $\var{sbnf}[5]$, these are recomputed so as to get a result with
3000: greater accuracy.
3001:
3002: Note that the member functions are \var{not} available for \var{sbnf}, you
3003: have to use \kbd{bnfmake} explicitly first.
3004:
3005: \syn{makebigbnf}{\var{sbnf},\var{prec}}, where $\var{prec}$ is a
3006: C long integer.
3007:
3008: \subsecidx{bnfnarrow}$(\var{bnf})$: $\var{bnf}$ being a big number field as
3009: output by \kbd{bnfinit}, computes the narrow class group of $\var{bnf}$. The
3010: output is a 3-component row vector $v$ analogous to the corresponding
3011: class group component \kbd{\var{bnf}.clgp} (\kbd{\var{bnf}[8][1]}): the
3012: first component is the narrow class number \kbd{$v$.no}, the second component
3013: is a vector containing the SNF\sidx{Smith normal form} cyclic components
3014: \kbd{$v$.cyc} of the narrow
3015: class group, and the third is a vector giving the generators of the
3016: corresponding \kbd{$v$.gen} cyclic groups. Note that this function is a
3017: special case of \kbd{bnrclass}.
3018:
3019: \syn{buchnarrow}{\var{bnf}}.
3020:
3021: \subsecidx{bnfsignunit}$(\var{bnf})$: $\var{bnf}$ being a big number field
3022: output by \kbd{bnfinit}, this computes an $r_1\times(r_1+r_2-1)$ matrix
3023: having $\pm1$ components, giving the signs of the real embeddings of the
3024: fundamental units.
3025:
3026: \syn{signunits}{\var{bnf}}.
3027:
3028: \subsecidx{bnfreg}$(\var{bnf})$: $\var{bnf}$ being a big number field
3029: output by \kbd{bnfinit}, computes its regulator.
3030:
3031: \syn{regulator}{\var{bnf},\var{tech},\var{prec}}, where \var{tech} is as in
3032: \kbd{bnfclassunit}.
3033:
3034: \subsecidx{bnfsunit}$(\var{bnf},S)$: computes the fundamental $S$-units of the
3035: number field $\var{bnf}$ (output by \kbd{bnfinit}), where $S$ is a list of
3036: prime ideals (output by \kbd{idealprimedec}). The output is a vector $v$ with
3037: 6 components.
3038:
3039: $v[1]$ gives a minimal system of (integral) generators of the $S$-unit group
3040: modulo the unit group.
3041:
3042: $v[2]$ contains technical data needed by \kbd{bnfissunit}.
3043:
3044: $v[3]$ is an empty vector (used to give the logarithmic embeddings of the
3045: generators in $v[1]$ in version 2.0.16).
3046:
3047: $v[4]$ is the $S$-regulator (this is the product of the regulator, the
3048: determinant of $v[2]$ and the natural logarithms of the norms of the ideals
3049: in $S$).
3050:
3051: $v[5]$ gives the $S$-class group structure, in the usual format
3052: (a row vector whose three components give in order the $S$-class number,
3053: the cyclic components and the generators).
3054:
3055: $v[6]$ is a copy of $S$.
3056:
3057: \syn{bnfsunit}{\var{bnf},S,\var{prec}}.
3058:
3059: \subsecidx{bnfunit}$(\var{bnf})$: $\var{bnf}$ being a big number field as
3060: output by
3061: \kbd{bnfinit}, outputs a two-component row vector giving in the first
3062: component the vector of fundamental units of the number field, and in the
3063: second component the number of bit of accuracy which remained in the
3064: computation (which is always correct, otherwise an error message is printed).
3065: This function is mainly for people who used the wrong flag in \kbd{bnfinit}
3066: and would like to skip part of a lengthy \kbd{bnfinit} computation.
3067:
3068: \syn{buchfu}{\var{bnf}}.
3069:
3070: \subsecidx{bnrL1}$(\var{bnr},\var{subgroup},\{\fl=0\})$:
3071: \var{bnr} being the number field data which is output by
3072: \kbd{bnrinit(,,1)} and \var{subgroup} being a square matrix defining a
3073: congruence subgroup of the ray class group corresponding to \var{bnr}
3074: (or $0$ for the trivial congruence subgroup), returns for each
3075: \idx{character} $\chi$ of the ray class group which is trivial on this
3076: subgroup, the value at $s = 1$ (or $s = 0$) of the abelian
3077: $L$-function associated to $\chi$. For the value at $s = 0$, the
3078: function returns in fact for each character $\chi$ a vector $[r_\chi ,
3079: c_\chi]$ where $r_\chi$ is the order of $L(s, \chi)$ at $s = 0$ and
3080: $c_\chi$ the first non-zero term in the expansion of $L(s,
3081: \chi)$ at $s = 0$; in other words
3082: %
3083: $$L(s, \chi) = c_\chi \cdot s^{r_\chi} + O(s^{r_\chi + 1})$$
3084: %
3085: \noindent near $0$. \fl\ is optional, default value is 0; its binary digits
3086: mean 1: compute at $s = 1$ if set to 1 or $s = 0$ if set to 0, 2: compute
3087: the primitive $L$-functions associated to $\chi$ if set to 0 or the
3088: $L$-function with Euler factors at prime ideals dividing the modulus of
3089: \var{bnr} removed if set to 1 (this is the so-called $L_S(s, \chi)$
3090: function where $S$ is the set of infinite places of the number field
3091: together with the finite prime ideals dividing the modulus of \var{bnr},
3092: see the example below), 3: returns also the character.
3093:
3094: Example:
3095: \bprog
3096: bnf = bnfinit(x^2 - 229);
3097: bnr = bnrinit(bnf,1,1);
3098: bnrL1(bnr, 0)
3099: @eprog\noindent
3100: returns the order and the first non-zero term of the abelian
3101: $L$-functions $L(s, \chi)$ at $s = 0$ where $\chi$ runs through the
3102: characters of the class group of $\Q(\sqrt{229})$. Then
3103: \bprog
3104: bnr2 = bnrinit(bnf,2,1);
3105: bnrL1(bnr2,0,2)
3106: @eprog\noindent
3107: returns the order and the first non-zero terms of the abelian
3108: $L$-functions $L_S(s, \chi)$ at $s = 0$ where $\chi$ runs through the
3109: characters of the class group of $\Q(\sqrt{229})$ and $S$ is the set
3110: of infinite places of $\Q(\sqrt{229})$ together with the finite prime
3111: $2$ (note that the ray class group modulo $2$ is in fact the class
3112: group, so \kbd{bnrL1(bnr2,0)} returns exactly the same answer as
3113: \kbd{bnrL1(bnr,0)}!).
3114:
3115: \syn{bnrL1}{\var{bnr},\var{subgroup},\fl,\var{prec}}
3116:
3117: \subsecidx{bnrclass}$(\var{bnf},\var{ideal},\{\fl=0\})$:
3118: $\var{bnf}$ being a big number field
3119: as output by \kbd{bnfinit} (the units are mandatory unless the ideal is
3120: trivial), and \var{ideal} being either an ideal in any form or a two-component
3121: row vector containing an ideal and an $r_1$-component row vector of flags
3122: indicating which real Archimedean embeddings to take in the module, computes
3123: the ray class group of the number field for the module \var{ideal}, as a
3124: 3-component vector as all other finite Abelian groups (cardinality, vector of
3125: cyclic components, corresponding generators).
3126:
3127: If $\fl=2$, the output is different. It is a 6-component vector $w$. $w[1]$
3128: is $\var{bnf}$. $w[2]$ is the result of applying
3129: $\kbd{idealstar}(\var{bnf},I,2)$. $w[3]$, $w[4]$ and $w[6]$ are technical
3130: components used only by the function \kbd{bnrisprincipal}. $w[5]$ is the
3131: structure of the ray class group as would have been output with $\fl=0$.
3132:
3133: If $\fl=1$, as above, except that the generators of the ray class group are
3134: not computed, which saves time.
3135:
3136: \syn{bnrclass0}{\var{bnf},\var{ideal},\fl}.
3137:
3138: \subsecidx{bnrclassno}$(\var{bnf},I)$: $\var{bnf}$ being a big number field
3139: as output
3140: by \kbd{bnfinit} (units are mandatory unless the ideal is trivial), and $I$
3141: being either an ideal in any form or a two-component row vector containing an
3142: ideal and an $r_1$-component row vector of flags indicating which real
3143: Archimedean embeddings to take in the modulus, computes the ray class number
3144: of the number field for the modulus $I$. This is faster than \kbd{bnrclass}
3145: and should be used if only the ray class number is desired.
3146:
3147: \syn{rayclassno}{\var{bnf},I}.
3148:
3149: \subsecidx{bnrclassnolist}$(\var{bnf},\var{list})$: $\var{bnf}$ being a
3150: big number field as output by \kbd{bnfinit} (units are mandatory unless
3151: the ideal is trivial), and \var{list} being a list of modules as output
3152: by \kbd{ideallist} of \kbd{ideallistarch},
3153: outputs the list of the class numbers of the corresponding ray class groups.
3154:
3155: \syn{rayclassnolist}{\var{bnf},\var{list}}.
3156:
3157: \subsecidx{bnrconductor}$(a_1,\{a_2\},\{a_3\}, \{\fl=0\})$: conductor of the
3158: subfield of a ray class field as defined by $[a_1,a_2,a_3]$ (see \kbd{bnr}
3159: at the beginning of this section).
3160:
3161: \syn{bnrconductor}{a_1,a_2,a_3,\fl}, where an omitted argument
3162: among the $a_i$ is input as \kbd{gzero}, and $\fl$ is a C long.
3163:
3164: \subsecidx{bnrconductorofchar}$(\var{bnr},\var{chi})$: \var{bnr} being a
3165: big ray number field
3166: as output by \kbd{bnrclass}, and \var{chi} being a row vector representing a
3167: \idx{character} as expressed on the generators of the ray class group, gives
3168: the conductor of this character as a modulus.
3169:
3170: \syn{bnrconductorofchar}{\var{bnr},\var{chi}}.
3171:
3172: \subsecidx{bnrdisc}$(a1,\{a2\},\{a3\},\{\fl=0\})$: $a1$, $a2$, $a3$
3173: defining a big ray number field $L$ over a groud field $K$ (see \kbd{bnr}
3174: at the beginning of this section for the
3175: meaning of $a1$, $a2$, $a3$), outputs a 3-component row vector $[N,R_1,D]$,
3176: where $N$ is the (absolute) degree of $L$, $R_1$ the number of real places of
3177: $L$, and $D$ the discriminant of $L/\Q$, including sign (if $\fl=0$).
3178:
3179: If $\fl=1$, as above but outputs relative data. $N$ is now the degree of
3180: $L/K$, $R_1$ is the number of real places of $K$ unramified in $L$ (so that
3181: the number of real places of $L$ is equal to $R_1$ times the relative degree
3182: $N$), and $D$ is the relative discriminant ideal of $L/K$.
3183:
3184: If $\fl=2$, does as in case 0, except that if the modulus is not the exact
3185: conductor corresponding to the $L$, no data is computed and the result is $0$
3186: (\kbd{gzero}).
3187:
3188: If $\fl=3$, as case 2, outputting relative data.
3189:
3190: \syn{bnrdisc0}{a1,a2,a3,\fl}.
3191:
3192: \subsecidx{bnrdisclist}$(\var{bnf},\var{bound},\{\var{arch}\},\{\fl=0\})$:
3193: $\var{bnf}$ being a big
3194: number field as output by \kbd{bnfinit} (the units are mandatory), computes a
3195: list of discriminants of Abelian extensions of the number field by increasing
3196: modulus norm up to bound \var{bound}, where the ramified Archimedean places are
3197: given by \var{arch} (unramified at infinity if \var{arch} is void or
3198: omitted). If
3199: \fl\ is non-zero, give \var{arch} all the possible values. (See \kbd{bnr}
3200: at the beginning of this section for the meaning of $a1$, $a2$, $a3$.)
3201:
3202: The alternative syntax $\kbd{bnrdisclist}(\var{bnf},\var{list})$
3203: is supported, where \var{list} is as output by \kbd{ideallist} or
3204: \kbd{ideallistarch} (with units).
3205:
3206: The output format is as follows. The output $v$ is a row vector of row
3207: vectors, allowing the bound to be greater than $2^{16}$ for 32-bit machines,
3208: and $v[i][j]$ is understood to be in fact $V[2^{15}(i-1)+j]$ of a unique big
3209: vector $V$ (note that $2^{15}$ is hardwired and can be increased in the
3210: source code only on 64-bit machines and higher).
3211:
3212: Such a component $V[k]$ is itself a vector $W$ (maybe of length 0) whose
3213: components correspond to each possible ideal of norm $k$. Each component
3214: $W[i]$ corresponds to an Abelian extension $L$ of $\var{bnf}$ whose modulus is
3215: an ideal of norm $k$ and no Archimedean components (hence the extension is
3216: unramified at infinity). The extension $W[i]$ is represented by a 4-component
3217: row vector $[m,d,r,D]$ with the following meaning. $m$ is the prime ideal
3218: factorization of the modulus, $d=[L:\Q]$ is the absolute degree of $L$,
3219: $r$ is the number of real places of $L$, and $D$ is the factorization of the
3220: absolute discriminant. Each prime ideal $pr=[p,\alpha,e,f,\beta]$ in the
3221: prime factorization $m$ is coded as $p\cdot n^2+(f-1)\cdot n+(j-1)$, where
3222: $n$ is the degree of the base field and $j$ is such that
3223:
3224: \kbd{pr = idealprimedec(\var{nf},p)[j]}.
3225:
3226: $m$ can be decoded using \kbd{bnfdecodemodule}.
3227:
3228: \syn{bnrdisclist0}{a1,a2,a3,\var{bound},\var{arch},\fl}.
3229:
3230: \subsecidx{bnrinit}$(\var{bnf},\var{ideal},\{\fl=0\})$: $\var{bnf}$ is as
3231: output by \kbd{bnfinit}, \var{ideal} is a valid ideal (or a module),
3232: initializes data linked
3233: to the ray class group structure corresponding to this module. This is the
3234: same as $\kbd{bnrclass}(\var{bnf},\var{ideal},\fl+1)$.
3235:
3236: \syn{bnrinit0}{\var{bnf},\var{ideal},\fl}.
3237:
3238: \subsecidx{bnrisconductor}$(a1,\{a2\},\{a3\})$: $a1$, $a2$, $a3$ represent
3239: an extension of the base field, given by class field theory for some modulus
3240: encoded in the parameters. Outputs 1 if this modulus is the conductor, and 0
3241: otherwise. This is slightly faster than \kbd{bnrconductor}.
3242:
3243: \syn{bnrisconductor}{a1,a2,a3} and the result is a \kbd{long}.
3244:
3245: \subsecidx{bnrisprincipal}$(\var{bnr},x,\{\fl=1\})$: \var{bnr} being the
3246: number field data which is output by \kbd{bnrinit}$(,,1)$ and $x$ being an
3247: ideal in any form, outputs the components of $x$ on the ray class group
3248: generators in a way similar to \kbd{bnfisprincipal}. That is a 3-component
3249: vector $v$ where $v[1]$ is the vector of components of $x$ on the ray class
3250: group generators, $v[2]$ gives on the integral basis an element $\alpha$ such
3251: that $x=\alpha\prod_ig_i^{x_i}$. Finally $v[3]$ indicates the number of bits
3252: of accuracy left in the result. In any case the result is checked for
3253: correctness, but $v[3]$ is included to see if it is necessary to increase the
3254: accuracy in other computations.
3255:
3256: If $\fl=0$, outputs only $v_1$. In that case, \var{bnr} need not contain the
3257: ray class group generators, i.e.~it may be created with \kbd{bnrinit}$(,,0)$
3258:
3259: \syn{isprincipalrayall}{\var{bnr},x,\fl}.
3260:
3261: \subsecidx{bnrrootnumber}$(\var{bnr},\var{chi},\{\fl=0\})$:
3262: if $\chi=\var{chi}$ is a (not necessarily primitive)
3263: \idx{character} over \var{bnr}, let
3264: $L(s,\chi) = \sum_{id} \chi(id) N(id)^{-s}$ be the associated
3265: \idx{Artin L-function}. Returns the so-called \idx{Artin root number}, i.e.~the
3266: complex number $W(\chi)$ of modulus 1 such that
3267: %
3268: $$\Lambda(1-s,\chi) = W(\chi) \Lambda(s,\overline{\chi})$$
3269: %
3270: \noindent where $\Lambda(s,\chi) = A(\chi)^{s/2}\gamma_\chi(s) L(s,\chi)$ is
3271: the enlarged L-function associated to $L$.
3272:
3273: The generators of the ray class group are needed, and you can set $\fl=1$ if
3274: the character is known to be primitive. Example:
3275:
3276: \bprog
3277: bnf = bnfinit(x^2 - 145);
3278: bnr = bnrinit(bnf,7,1);
3279: bnrrootnumber(bnr, [5])
3280: @eprog\noindent
3281: returns the root number of the character $\chi$ of $Cl_7(\Q(\sqrt{145}))$
3282: such that $\chi(g) = \zeta^5$, where $g$ is the generator of the ray-class
3283: field and $\zeta = e^{2i\pi/N}$ where $N$ is the order of $g$ ($N=12$ as
3284: \kbd{bnr.cyc} readily tells us).
3285:
3286: \syn{bnrrootnumber}{\var{bnf},\var{chi},\fl}
3287:
3288: \subsecidx{bnrstark}${(\var{bnr},\var{subgroup},\{\fl=0\})}$: \var{bnr}
3289: being as output by \kbd{bnrinit(,,1)}, finds a relative equation for the
3290: class field corresponding to the modulus in \var{bnr} and the given
3291: congruence subgroup using \idx{Stark units} (set $\var{subgroup}=0$ if you
3292: want the whole ray class group). The main variable of \var{bnr} must not be
3293: $x$, and the ground field and the class field must be totally real and not
3294: isomorphic to $\Q$ (over the rationnals, use \tet{polsubcyclo} or
3295: \tet{galoissubcyclo}). \fl\ is optional and may be set to 0 to obtain a
3296: reduced relative polynomial, 1 to be satisfied with any relative
3297: polynomial, 2 to obtain an absolute polynomial and 3 to obtain the
3298: irreducible relative polynomial of the Stark unit, 0 being default.
3299: Example:
3300:
3301: \bprog
3302: bnf = bnfinit(y^2 - 3);
3303: bnr = bnrinit(bnf, 5, 1);
3304: bnrstark(bnr, 0)
3305: @eprog\noindent
3306: returns the ray class field of $\Q(\sqrt{3})$ modulo $5$.
3307:
3308: \misctitle{Remark.} The result of the computation depends on the choice of
3309: a modulus verifying special conditions. By default the function will try
3310: few moduli, choosing the one giving the smallest result. In some cases
3311: where the result is however very large, you can tell the function to
3312: try more moduli by adding $4$ to the value of flag. Whether this flag is
3313: set or not, the function may fail in some extreme cases, returning the
3314: error message
3315:
3316: \kbd{"Cannot find a suitable modulus in FindModule"}.
3317:
3318: In this case, the corresponding congruence group is a product of cyclic
3319: groups and, for the time being, the class field has to be obtained by
3320: splitting this group into its cyclic components.
3321:
3322: \syn{bnrstark}{\var{bnr},\var{subgroup},\fl}.
3323:
3324: \subsecidx{dirzetak}$(\var{nf},b)$: gives as a vector the first $b$
3325: coefficients of the \idx{Dedekind} zeta function of the number field $\var{nf}$
3326: considered as a \idx{Dirichlet series}.
3327:
3328: \syn{dirzetak}{\var{nf},b}.
3329:
3330: \subsecidx{factornf}$(x,t)$: factorization of the univariate polynomial $x$
3331: over the number field defined by the (univariate) polynomial $t$. $x$ may
3332: have coefficients in $\Q$ or in the number field. The main variable of
3333: $t$ must be of \var{lower} priority than that of $x$ (in other words the
3334: variable number of $t$ must be \var{greater} than that of $x$). However if
3335: the coefficients of the number field occur explicitly (as polmods) as
3336: coefficients of $x$, the variable of these polmods \var{must} be the same as
3337: the main variable of $t$. For example
3338: \bprog
3339: ? factornf(x^2 + Mod(y, y^2+1), y^2+1);
3340: ? factornf(x^2 + 1, y^2+1); \\@com these two are OK
3341: ? factornf(x^2 + Mod(z,z^2+1), y^2+1)
3342: *** incorrect type in gmulsg
3343: @eprog
3344:
3345: \syn{polfnf}{x,t}.
3346:
3347: \subsecidx{galoisfixedfield}$(\var{gal},\var{perm},\{fl=0\},\{v=y\}))$:
3348: \var{gal} being be a Galois field as output by \tet{galoisinit} and
3349: \var{perm} an element of $\var{gal}.group$ or a vector of such elements,
3350: computes the fixed field of \var{gal} by the automorphism defined by the
3351: permutations \var{perm} of the roots $\var{gal}.roots$. $P$ is guaranteed to
3352: be squarefree modulo $\var{gal}.p$.
3353:
3354: If no flags or $\fl=0$, output format is the same as for \tet{nfsubfield},
3355: returning $[P,x]$ such that $P$ is a polynomial defining the fixed field, and
3356: $x$ is a root of $P$ expressed as a polmod in $\var{gal}.pol$.
3357:
3358: If $\fl=1$ return only the polynomial $P$.
3359:
3360: If $\fl=2$ return $[P,x,F]$ where $P$ and $x$ are as above and $F$ is the
3361: factorization of $\var{gal}.pol$ over the field defined by $P$, where
3362: variable $v$ ($y$ by default) stands for a root of $P$. The priority of $v$
3363: must be less than the priority of the variable of $\var{gal}.pol$.
3364:
3365: Example:
3366:
3367: \bprog
3368: G = galoisinit(x^4+1);
3369: galoisfixedfield(G,G.group[2],2)
3370: [x^2 + 2, Mod(x^3 + x, x^4 + 1), [x^2 - y*x - 1, x^2 + y*x - 1]]
3371: @eprog
3372: computes the factorization $x^4+1=(x^2-\sqrt{-2}x-1)(x^2+\sqrt{-2}x-1)$
3373:
3374: \syn{galoisfixedfield}{\var{gal},\var{perm},p}.
3375:
3376: \subsecidx{galoisinit}$(\var{pol},\{den\})$: computes the Galois group
3377: and all neccessary information for computing the fixed fields of the
3378: Galois extension $K/\Q$ where $K$ is the number field defined by
3379: $\var{pol}$ (monic irreducible polynomial in $\Z[X]$ or
3380: a number field as output by \tet{nfinit}). The extension $K/\Q$ must be
3381: Galois with Galois group ``weakly'' super-solvable (see \tet{nfgaloisconj})
3382:
3383: \misctitle{Warning:} The interface of this function is experimental,
3384: so the described output can be subject to important changes in the
3385: near future. However the function itself should work as described. For any
3386: remarks about this interface, please mail \kbd{allomber@math.u-bordeaux.fr}.
3387:
3388: The output is an 8-component vector \var{gal}.
3389:
3390: $\var{gal}[1]$ contains the polynomial \var{pol}
3391: (\kbd{\var{gal}.pol}).
3392:
3393: $\var{gal}[2]$ is a three--components vector $[p,e,q]$ where $p$ is a
3394: prime number (\kbd{\var{gal}.p}) such that \var{pol} totally split
3395: modulo $p$ , $e$ is an integer and $q=p^e$ (\kbd{\var{gal}.mod}) is the
3396: modulus of the roots in \kbd{\var{gal}.roots}.
3397:
3398: $\var{gal}[3]$ is a vector $L$ containing the $p$-adic roots of
3399: \var{pol} as integers implicitly modulo \kbd{\var{gal}.mod}.
3400: (\kbd{\var{gal}.roots}).
3401:
3402: $\var{gal}[4]$ is the inverse of the Van der Monde matrix of the
3403: $p$-adic roots of \var{pol}, multiplied by $\var{gal}[5]$.
3404:
3405: $\var{gal}[5]$ is a multiple of the least common denominator of the
3406: automorphisms expressed as polynomial in a root of \var{pol}.
3407:
3408: $\var{gal}[6]$ is the Galois group $G$ expressed as a vector of
3409: permutations of $L$ (\kbd{\var{gal}.group}).
3410:
3411: $\var{gal}[7]$ is a generating subset $S=[s_1,\ldots,s_g]$ of $G$
3412: expressed as a vector of permutations of $L$ (\kbd{\var{gal}.gen}).
3413:
3414: $\var{gal}[8]$ contains the relative orders $[o_1,\ldots,o_g]$ of
3415: the generators of $S$ (\kbd{\var{gal}.orders}).
3416:
3417: Let $H$ be the maximal normal supersolvable subgroup of $G$, we have the
3418: following properties:
3419:
3420: \quad$\bullet$ if $G/H\simeq A_4$ then $[o_1,\ldots,o_g]$ ends by
3421: $[2,2,3]$.
3422:
3423: \quad$\bullet$ if $G/H\simeq S_4$ then $[o_1,\ldots,o_g]$ ends by
3424: $[2,2,3,2]$.
3425:
3426: \quad$\bullet$ else $G$ is super-solvable.
3427:
3428: \quad$\bullet$ for $1\leq i \leq g$ the subgroup of $G$ generated by
3429: $[s_1,\ldots,s_g]$ is normal, with the exception of $i=g-2$ in the
3430: second case and of $i=g-3$ in the third.
3431:
3432: \quad$\bullet$ the relative order $o_i$ of $s_i$ is its order in the
3433: quotient group $G/\langle s_1,\ldots,s_{i-1}\rangle$, with the same
3434: exceptions.
3435:
3436: \quad$\bullet$ for any $x\in G$ there exists a unique family
3437: $[e_1,\ldots,e_g]$ such that (no exceptions):
3438:
3439: -- for $1\leq i \leq g$ we have $0\leq e_i<o_i$
3440:
3441: -- $x=g_1^{e_1}g_2^{e_2}\ldots g_n^{e_n}$
3442:
3443: If present $den$ must be a suitable value for $\var{gal}[5]$.
3444:
3445: \syn{galoisinit}{\var{gal},\var{den}}.
3446:
3447: \subsecidx{galoispermtopol}$(\var{gal},\var{perm})$: \var{gal} being a
3448: Galois field as output by \kbd{galoisinit} and \var{perm} a element of
3449: $\var{gal}.group$, return the polynomial defining the Galois
3450: automorphism, as output by \kbd{nfgaloisconj}, associated with the
3451: permutation \var{perm} of the roots $\var{gal}.roots$. \var{perm} can
3452: also be a vector or matrix, in this case, \kbd{galoispermtopol} is
3453: applied to all components recursively.
3454:
3455: \noindent Note that
3456: \bprog
3457: G = galoisinit(pol);
3458: galoispermtopol(G, G[6])~
3459: @eprog
3460: \noindent is equivalent to \kbd{nfgaloisconj(pol)}, if degree of \var{pol}
3461: is greater or equal to $2$.
3462:
3463: \syn{galoispermtopol}{\var{gal},\var{perm}}.
3464:
3465: \subsecidx{galoissubcyclo}$(n,H,\{Z\},\{v\},\{fl=0\})$: If $fl=0$, compute a polynomial
3466: defining the subfield of $\Q(\zeta_n)$ fixed by the subgroup \var{H} of
3467: $(\Z/n\Z)^*$. The subgroup \var{H} can be given by a generator, a set of
3468: generators given by a vector or a HNF matrix. If present \kbd{Z} must be
3469: \kbd{znstar(n)}, and is currently only used when \var{H} is a HNF matrix. If
3470: \var{v} is given, the polynomial is given in the variable \var{v}.
3471:
3472: If $fl=1$, compute only the (finite part of) conductor of the abelian extension.
3473:
3474: If $fl=2$, output $[pol, f_0]$, where $pol$ is the polynomial as output when $fl=0$ and $f_0$ the conductor as output when $fl=1$.
3475:
3476: The following function can be used to compute all subfields of
3477: $\Q(\zeta_n)$ (of order less than \kbd{d}, if \kbd{d} is set):
3478:
3479: \bprog
3480: subcyclo(n, d = -1)=
3481: {
3482: local(Z,G,S);
3483: if (d < 0, d = n);
3484: Z = znstar(n);
3485: G = matdiagonal(Z[2]);
3486: S = [];
3487: forsubgroup(H = G, d,
3488: S = concat(S, galoissubcyclo(n, mathnf(concat(G,H)),Z));
3489: );
3490: S
3491: }
3492: @eprog
3493:
3494: \misctitle{Note:} The interface to this function needs to be cleaned up, and
3495: so is subject to change.
3496:
3497: \syn{galoissubcyclo}{n,H,Z,v} where n is a C long integer.
3498:
3499: \subsecidx{idealadd}$(\var{nf},x,y)$: sum of the two ideals $x$ and $y$ in the
3500: number field $\var{nf}$. When $x$ and $y$ are given by $\Z$-bases, this does
3501: not depend on $\var{nf}$ and can be used to compute the sum of any two
3502: $\Z$-modules. The result is given in HNF.
3503:
3504: \syn{idealadd}{\var{nf},x,y}.
3505:
3506: \subsecidx{idealaddtoone}$(\var{nf},x,\{y\})$: $x$ and $y$ being two co-prime
3507: integral ideals (given in any form), this gives a two-component row vector
3508: $[a,b]$ such that $a\in x$, $b\in y$ and $a+b=1$.
3509:
3510: The alternative syntax $\kbd{idealaddtoone}(\var{nf},v)$, is supported, where
3511: $v$ is a $k$-component vector of ideals (given in any form) which sum to
3512: $\Z_K$. This outputs a $k$-component vector $e$ such that $e[i]\in x[i]$ for
3513: $1\le i\le k$ and $\sum_{1\le i\le k}e[i]=1$.
3514:
3515: \syn{idealaddtoone0}{\var{nf},x,y}, where an omitted $y$ is coded as
3516: \kbd{NULL}.
3517:
3518: \subsecidx{idealappr}$(\var{nf},x,\{\fl=0\})$: if $x$ is a fractional ideal
3519: (given in any form), gives an element $\alpha$ in $\var{nf}$ such that for
3520: all prime ideals $\p$ such that the valuation of $x$ at $\p$ is non-zero, we
3521: have $v_{\p}(\alpha)=v_{\p}(x)$, and. $v_{\p}(\alpha)\ge0$ for all other
3522: ${\p}$.
3523:
3524: If $\fl$ is non-zero, $x$ must be given as a prime ideal factorization, as
3525: output by \kbd{idealfactor}, but possibly with zero or negative exponents.
3526: This yields an element $\alpha$ such that for all prime ideals $\p$ occurring
3527: in $x$, $v_{\p}(\alpha)$ is equal to the exponent of $\p$ in $x$, and for all
3528: other prime ideals, $v_{\p}(\alpha)\ge0$. This generalizes
3529: $\kbd{idealappr}(\var{nf},x,0)$ since zero exponents are allowed. Note that
3530: the algorithm used is slightly different, so that
3531: \kbd{idealappr(\var{nf},idealfactor(\var{nf},x))} may not be the same as
3532: \kbd{idealappr(\var{nf},x,1)}.
3533:
3534: \syn{idealappr0}{\var{nf},x,\fl}.
3535:
3536: \subsecidx{idealchinese}$(\var{nf},x,y)$: $x$ being a prime ideal factorization
3537: (i.e.~a 2 by 2 matrix whose first column contain prime ideals, and the second
3538: column integral exponents), $y$ a vector of elements in $\var{nf}$ indexed by
3539: the ideals in $x$, computes an element $b$ such that
3540:
3541: $v_\p(b - y_\p) \geq v_\p(x)$ for all prime ideals in $x$ and $v_\p(b)\geq 0$
3542: for all other $\p$.
3543:
3544: \syn{idealchinese}{\var{nf},x,y}.
3545:
3546: \subsecidx{idealcoprime}$(\var{nf},x,y)$: given two integral ideals $x$ and $y$
3547: in the number field $\var{nf}$, finds a $\beta$ in the field, expressed on the
3548: integral basis $\var{nf}[7]$, such that $\beta\cdot y$ is an integral ideal
3549: coprime to $x$.
3550:
3551: \syn{idealcoprime}{\var{nf},x}.
3552:
3553: \subsecidx{idealdiv}$(\var{nf},x,y,\{\fl=0\})$: quotient $x\cdot y^{-1}$ of the
3554: two ideals $x$ and $y$ in the number field $\var{nf}$. The result is given in
3555: HNF.
3556:
3557: If $\fl$ is non-zero, the quotient $x \cdot y^{-1}$ is assumed to be an
3558: integral ideal. This can be much faster when the norm of the quotient is
3559: small even though the norms of $x$ and $y$ are large.
3560:
3561: \syn{idealdiv0}{\var{nf},x,y,\fl}. Also available
3562: are $\teb{idealdiv}(\var{nf},x,y)$ ($\fl=0$) and
3563: $\teb{idealdivexact}(\var{nf},x,y)$ ($\fl=1$).
3564:
3565: \subsecidx{idealfactor}$(\var{nf},x)$: factors into prime ideal powers the
3566: ideal $x$ in the number field $\var{nf}$. The output format is similar to the
3567: \kbd{factor} function, and the prime ideals are represented in the form
3568: output by the \kbd{idealprimedec} function, i.e.~as 5-element vectors.
3569:
3570: \syn{idealfactor}{\var{nf},x}.
3571:
3572: \subsecidx{idealhnf}$(\var{nf},a,\{b\})$: gives the \idx{Hermite normal form}
3573: matrix of the ideal $a$. The ideal can be given in any form whatsoever
3574: (typically by an algebraic number if it is principal, by a $\Z_K$-system of
3575: generators, as a prime ideal as given by \kbd{idealprimedec}, or by a
3576: $\Z$-basis).
3577:
3578: If $b$ is not omitted, assume the ideal given was $a\Z_K+b\Z_K$, where $a$
3579: and $b$ are elements of $K$ given either as vectors on the integral basis
3580: $\var{nf}[7]$ or as algebraic numbers.
3581:
3582: \syn{idealhnf0}{\var{nf},a,b} where an omitted $b$ is coded as \kbd{NULL}.
3583: Also available is $\teb{idealhermite}(\var{nf},a)$ ($b$ omitted).
3584:
3585: \subsecidx{idealintersect}$(\var{nf},x,y)$: intersection of the two ideals
3586: $x$ and $y$ in the number field $\var{nf}$. When $x$ and $y$ are given by
3587: $\Z$-bases, this does not depend on $\var{nf}$ and can be used to compute the
3588: intersection of any two $\Z$-modules. The result is given in HNF.
3589:
3590: \syn{idealintersect}{\var{nf},x,y}.
3591:
3592: \subsecidx{idealinv}$(\var{nf},x)$: inverse of the ideal $x$ in the
3593: number field $\var{nf}$. The result is the Hermite normal form of the inverse
3594: of the ideal, together with the opposite of the Archimedean information if it
3595: is given.
3596:
3597: \syn{idealinv}{\var{nf},x}.
3598:
3599: \subsecidx{ideallist}$(\var{nf},\var{bound},\{\fl=4\})$: computes the list
3600: of all ideals of norm less or equal to \var{bound} in the number field
3601: \var{nf}. The result is a row vector with exactly \var{bound} components.
3602: Each component is itself a row vector containing the information about
3603: ideals of a given norm, in no specific order. This information can be
3604: either the HNF of the ideal or the \kbd{idealstar} with possibly some
3605: additional information.
3606:
3607: If $\fl$ is present, its binary digits are toggles meaning
3608:
3609: \quad 1: give also the generators in the \kbd{idealstar}.
3610:
3611: \quad 2: output $[L,U]$, where $L$ is as before and $U$ is a vector of
3612: \kbd{zinternallog}s of the units.
3613:
3614: \quad 4: give only the ideals and not the \kbd{idealstar} or the \kbd{ideallog}
3615: of the units.
3616:
3617: \syn{ideallist0}{\var{nf},\var{bound},\fl}, where \var{bound} must
3618: be a C long integer. Also available is $\teb{ideallist}(\var{nf},\var{bound})$,
3619: corresponding to the case $\fl=0$.
3620:
3621: \subsecidx{ideallistarch}$(\var{nf},\var{list},\{\var{arch}=[\,]\},\{\fl=0\})$:
3622: vector of vectors of all \kbd{idealstarinit} (see \kbd{idealstar}) of all
3623: modules in \var{list}, with Archimedean part \var{arch} added (void if
3624: omitted). \var{list} is a vector of big ideals, as output by
3625: \kbd{ideallist}$(\ldots, \fl)$ for instance. $\fl$ is optional; its binary
3626: digits are toggles meaning: 1: give generators as well, 2: list format is
3627: $[L,U]$ (see \kbd{ideallist}).
3628:
3629: \syn{ideallistarch0}{\var{nf},\var{list},\var{arch},\fl}, where an omitted
3630: \var{arch} is coded as \kbd{NULL}.
3631:
3632: \subsecidx{ideallog}$(\var{nf},x,\var{bid})$: $\var{nf}$ being a number field,
3633: \var{bid} being a ``big ideal'' as output by \kbd{idealstar} and $x$ being a
3634: non-necessarily integral element of \var{nf} which must have valuation
3635: equal to 0 at all prime ideals dividing $I=\var{bid}[1]$, computes the
3636: ``discrete logarithm'' of $x$ on the generators given in $\var{bid}[2]$.
3637: In other words, if $g_i$ are these generators, of orders $d_i$ respectively,
3638: the result is a column vector of integers $(x_i)$ such that $0\le x_i<d_i$ and
3639: $$x\equiv\prod_ig_i^{x_i}\pmod{\ ^*I}\enspace.$$
3640: Note that when $I$ is a module, this implies also sign conditions on the
3641: embeddings.
3642:
3643: \syn{zideallog}{\var{nf},x,\var{bid}}.
3644:
3645: \subsecidx{idealmin}$(\var{nf},x,\{\var{vdir}\})$: computes a minimum of
3646: the ideal $x$ in the direction \var{vdir} in the number field \var{nf}.
3647:
3648: \syn{minideal}{\var{nf},x,\var{vdir},\var{prec}}, where an omitted
3649: \var{vdir} is coded as \kbd{NULL}.
3650:
3651: \subsecidx{idealmul}$(\var{nf},x,y,\{\fl=0\})$: ideal multiplication of the
3652: ideals $x$ and $y$ in the number field \var{nf}. The result is a generating
3653: set for the ideal product with at most $n$ elements, and is in Hermite normal
3654: form if either $x$ or $y$ is in HNF or is a prime ideal as output by
3655: \kbd{idealprimedec}, and this is given together with the sum of the
3656: Archimedean information in $x$ and $y$ if both are given.
3657:
3658: If $\fl$ is non-zero, reduce the result using \kbd{idealred}.
3659:
3660: \syn{idealmul}{\var{nf},x,y} ($\fl=0$) or
3661: $\teb{idealmulred}(\var{nf},x,y,\var{prec})$ ($\fl\neq0$), where as usual,
3662: $\var{prec}$ is a C long integer representing the precision.
3663:
3664: \subsecidx{idealnorm}$(\var{nf},x)$: computes the norm of the ideal~$x$
3665: in the number field~$\var{nf}$.
3666:
3667: \syn{idealnorm}{\var{nf}, x}.
3668:
3669: \subsecidx{idealpow}$(\var{nf},x,k,\{\fl=0\})$: computes the $k$-th power of
3670: the ideal $x$ in the number field $\var{nf}$. $k$ can be positive, negative
3671: or zero. The result is NOT reduced, it is really the $k$-th ideal power, and
3672: is given in HNF.
3673:
3674: If $\fl$ is non-zero, reduce the result using \kbd{idealred}. Note however
3675: that this is NOT the same as as $\kbd{idealpow}(\var{nf},x,k)$ followed by
3676: reduction, since the reduction is performed throughout the powering process.
3677:
3678: The library syntax corresponding to $\fl=0$ is
3679: $\teb{idealpow}(\var{nf},x,k)$. If $k$ is a \kbd{long}, you can use
3680: $\teb{idealpows}(\var{nf},x,k)$. Corresponding to $\fl=1$ is
3681: $\teb{idealpowred}(\var{nf},vp,k,\var{prec})$, where $\var{prec}$ is a
3682: \kbd{long}.
3683:
3684: \subsecidx{idealprimedec}$(\var{nf},p)$: computes the prime ideal
3685: decomposition of the prime number $p$ in the number field $\var{nf}$. $p$
3686: must be a (positive) prime number. Note that the fact that $p$ is prime is
3687: not checked, so if a non-prime number $p$ is given it may lead to
3688: unpredictable results.
3689:
3690: The result is a vector of 5-component vectors, each representing one of the
3691: prime ideals above $p$ in the number field $\var{nf}$. The representation
3692: $vp=[p,a,e,f,b]$ of a prime ideal means the following. The prime ideal is
3693: equal to $p\Z_K+\alpha\Z_K$ where $\Z_K$ is the ring of integers of the field
3694: and $\alpha=\sum_i a_i\omega_i$ where the $\omega_i$ form the integral basis
3695: \kbd{\var{nf}.zk}, $e$ is the ramification index, $f$ is the residual index,
3696: and $b$ is an $n$-component column vector representing a $\beta\in\Z_K$ such
3697: that $vp^{-1}=\Z_K+\beta/p\Z_K$ which will be useful for computing
3698: valuations, but which the user can ignore. The number $\alpha$ is guaranteed
3699: to have a valuation equal to 1 at the prime ideal (this is automatic if
3700: $e>1$).
3701:
3702: \syn{idealprimedec}{\var{nf},p}.
3703:
3704: \subsecidx{idealprincipal}$(\var{nf},x)$: creates the principal ideal
3705: generated by the algebraic number $x$ (which must be of type integer,
3706: rational or polmod) in the number field $\var{nf}$. The result is a
3707: one-column matrix.
3708:
3709: \syn{principalideal}{\var{nf},x}.
3710:
3711: \subsecidx{idealred}$(\var{nf},I,\{\var{vdir}=0\})$: \idx{LLL} reduction of
3712: the ideal $I$ in the number field \var{nf}, along the direction \var{vdir}.
3713: If \var{vdir} is present, it must be an $r1+r2$-component vector ($r1$ and
3714: $r2$ number of real and complex places of \var{nf} as usual).
3715:
3716: This function finds a ``small'' $a$ in $I$ (it is an LLL pseudo-minimum
3717: along direction \var{vdir}). The result is the \idx{Hermite normal form} of
3718: the LLL-reduced ideal $r I/a$, where $r$ is a rational number such that the
3719: resulting ideal is integral and primitive. This is often, but not always, a
3720: reduced ideal in the sense of \idx{Buchmann}. If $I$ is an idele, the
3721: logarithmic embeddings of $a$ are subtracted to the Archimedean part.
3722:
3723: More often than not, a \idx{principal ideal} will yield the identity
3724: matrix. This is a quick and dirty way to check if ideals are principal
3725: without computing a full \kbd{bnf} structure, but it's not a necessary
3726: condition; hence, a non-trivial result doesn't prove the ideal is
3727: non-trivial in the class group.
3728:
3729: Note that this is \var{not} the same as the LLL reduction of the lattice
3730: $I$ since ideal operations are involved.
3731:
3732: \syn{ideallllred}{\var{nf},x,\var{vdir},\var{prec}}, where an omitted
3733: \var{vdir} is coded as \kbd{NULL}.
3734:
3735: \subsecidx{idealstar}$(\var{nf},I,\{\fl=1\})$: \var{nf} being a number
3736: field, and $I$
3737: either and ideal in any form, or a row vector whose first component is an
3738: ideal and whose second component is a row vector of $r_1$ 0 or 1, outputs
3739: necessary data for computing in the group $(\Z_K/I)^*$.
3740:
3741: If $\fl=2$, the result is a 5-component vector $w$. $w[1]$ is the ideal
3742: or module $I$ itself. $w[2]$ is the structure of the group. The other
3743: components are difficult to describe and are used only in conjunction with
3744: the function \kbd{ideallog}.
3745:
3746: If $\fl=1$ (default), as $\fl=2$, but do not compute explicit generators
3747: for the cyclic components, which saves time.
3748:
3749: If $\fl=0$, computes the structure of $(\Z_K/I)^*$ as a 3-component vector
3750: $v$. $v[1]$ is the order, $v[2]$ is the vector of SNF\sidx{Smith normal form}
3751: cyclic components and
3752: $v[3]$ the corresponding generators. When the row vector is explicitly
3753: included, the
3754: non-zero elements of this vector are considered as real embeddings of
3755: \var{nf} in the order given by \kbd{polroots}, i.e.~in \var{nf}[6]
3756: (\kbd{\var{nf}.roots}), and then $I$ is a module with components at infinity.
3757:
3758: To solve discrete logarithms (using \kbd{ideallog}), you have to choose
3759: $\fl=2$.
3760:
3761: \syn{idealstar0}{\var{nf},I,\fl}.
3762:
3763: \subsecidx{idealtwoelt}$(\var{nf},x,\{a\})$: computes a two-element
3764: representation of the ideal $x$ in the number field $\var{nf}$, using a
3765: straightforward (exponential time) search. $x$ can be an ideal in any form,
3766: (including perhaps an Archimedean part, which is ignored) and the result is a
3767: row vector $[a,\alpha]$ with two components such that $x=a\Z_K+\alpha\Z_K$
3768: and $a\in\Z$, where $a$ is the one passed as argument if any. If $x$ is given
3769: by at least two generators, $a$ is chosen to be the positive generator of
3770: $x\cap\Z$.
3771:
3772: Note that when an explicit $a$ is given, we use an asymptotically faster
3773: method, however in practice it is usually slower.
3774:
3775: \syn{ideal_two_elt0}{\var{nf},x,a}, where an omitted $a$ is entered as
3776: \kbd{NULL}.
3777:
3778: \subsecidx{idealval}$(\var{nf},x,\var{vp})$: gives the valuation of the
3779: ideal $x$ at the prime ideal \var{vp} in the number field $\var{nf}$,
3780: where \var{vp} must be a
3781: 5-component vector as given by \kbd{idealprimedec}.
3782:
3783: \syn{idealval}{\var{nf},x,\var{vp}}, and the result is a \kbd{long}
3784: integer.
3785:
3786: \subsecidx{ideleprincipal}$(\var{nf},x)$: creates the principal idele
3787: generated by the algebraic number $x$ (which must be of type integer,
3788: rational or polmod) in the number field $\var{nf}$. The result is a
3789: two-component vector, the first being a one-column matrix representing the
3790: corresponding principal ideal, and the second being the vector with $r_1+r_2$
3791: components giving the complex logarithmic embedding of $x$.
3792:
3793: \syn{principalidele}{\var{nf},x}.
3794:
3795: \subsecidx{matalgtobasis}$(\var{nf},x)$: $\var{nf}$ being a number field in
3796: \kbd{nfinit} format, and $x$ a matrix whose coefficients are expressed as
3797: polmods in $\var{nf}$, transforms this matrix into a matrix whose
3798: coefficients are expressed on the integral basis of $\var{nf}$. This is the
3799: same as applying \kbd{nfalgtobasis} to each entry, but it would be dangerous
3800: to use the same name.
3801:
3802: \syn{matalgtobasis}{\var{nf},x}.
3803:
3804: \subsecidx{matbasistoalg}$(\var{nf},x)$: $\var{nf}$ being a number field in
3805: \kbd{nfinit} format, and $x$ a matrix whose coefficients are expressed as
3806: column vectors on the integral basis of $\var{nf}$, transforms this matrix
3807: into a matrix whose coefficients are algebraic numbers expressed as
3808: polmods. This is the same as applying \kbd{nfbasistoalg} to each entry, but
3809: it would be dangerous to use the same name.
3810:
3811: \syn{matbasistoalg}{\var{nf},x}.
3812:
3813: \subsecidx{modreverse}$(a)$: $a$ being a polmod $A(X)$ modulo $T(X)$, finds
3814: the ``reverse polmod'' $B(X)$ modulo $Q(X)$, where $Q$ is the minimal
3815: polynomial of $a$, which must be equal to the degree of $T$, and such that if
3816: $\theta$ is a root of $T$ then $\theta=B(\alpha)$ for a certain root $\alpha$
3817: of $Q$.
3818:
3819: This is very useful when one changes the generating element in algebraic
3820: extensions.
3821:
3822: \syn{polmodrecip}{x}.
3823:
3824: \subsecidx{newtonpoly}$(x,p)$: gives the vector of the slopes of the Newton
3825: polygon of the polynomial $x$ with respect to the prime number $p$. The $n$
3826: components of the vector are in decreasing order, where $n$ is equal to the
3827: degree of $x$. Vertical slopes occur iff the constant coefficient of $x$ is
3828: zero and are denoted by \kbd{VERYBIGINT}, the biggest single precision
3829: integer representable on the machine ($2^{31}-1$ (resp.~$2^{63}-1$) on 32-bit
3830: (resp.~64-bit) machines), see \secref{se:valuation}.
3831:
3832: \syn{newtonpoly}{x,p}.
3833:
3834: \subsecidx{nfalgtobasis}$(\var{nf},x)$: this is the inverse function of
3835: \kbd{nfbasistoalg}. Given an object $x$ whose entries are expressed as
3836: algebraic numbers in the number field $\var{nf}$, transforms it so that the
3837: entries are expressed as a column vector on the integral basis
3838: \kbd{\var{nf}.zk}.
3839:
3840: \syn{algtobasis}{\var{nf},x}.
3841:
3842: \subsecidx{nfbasis}$(x,\{\fl=0\},\{p\})$: \idx{integral basis} of the number
3843: field defined by the irreducible, preferably monic, polynomial $x$,
3844: using a modified version of the \idx{round 4} algorithm by
3845: default. The binary digits of $\fl$ have the following meaning:
3846:
3847: 1: assume that no square of a prime greater than the default \kbd{primelimit}
3848: divides the discriminant of $x$, i.e.~that the index of $x$ has only small
3849: prime divisors.
3850:
3851: 2: use \idx{round 2} algorithm. For small degrees and coefficient size, this is
3852: sometimes a little faster. (This program is the translation into C of a program
3853: written by David \idx{Ford} in Algeb.)
3854:
3855: Thus for instance, if $\fl=3$, this uses the round 2 algorithm and outputs
3856: an order which will be maximal at all the small primes.
3857:
3858: If $p$ is present, we assume (without checking!) that it is the two-column
3859: matrix of the factorization of the discriminant of the polynomial $x$. Note
3860: that it does \var{not} have to be a complete factorization. This is
3861: especially useful if only a local integral basis for some small set of places
3862: is desired: only factors with exponents greater or equal to 2 will be
3863: considered.
3864:
3865: \syn{nfbasis0}{x,\fl,p}. An extended version
3866: is $\teb{nfbasis}(x,\&d,\fl,p)$, where $d$ will receive the discriminant of
3867: the number field (\var{not} of the polynomial $x$), and an omitted $p$ should
3868: be input as \kbd{gzero}. Also available are $\teb{base}(x,\&d)$ ($\fl=0$),
3869: $\teb{base2}(x,\&d)$ ($\fl=2$) and $\teb{factoredbase}(x,p,\&d)$.
3870:
3871: \subsecidx{nfbasistoalg}$(\var{nf},x)$: this is the inverse function of
3872: \kbd{nfalgtobasis}. Given an object $x$ whose entries are expressed on the
3873: integral basis \kbd{\var{nf}.zk}, transforms it into an object whose entries
3874: are algebraic numbers (i.e.~polmods).
3875:
3876: \syn{basistoalg}{\var{nf},x}.
3877:
3878: \subsecidx{nfdetint}$(\var{nf},x)$: given a pseudo-matrix $x$, computes a
3879: non-zero ideal contained in (i.e.~multiple of) the determinant of $x$. This
3880: is particularly useful in conjunction with \kbd{nfhnfmod}.
3881:
3882: \syn{nfdetint}{\var{nf},x}.
3883:
3884: \subsecidx{nfdisc}$(x,\{\fl=0\},\{p\})$: \idx{field discriminant} of the
3885: number field defined by the integral, preferably monic, irreducible
3886: polynomial $x$. $\fl$ and $p$ are exactly as in \kbd{nfbasis}. That is, $p$
3887: provides the matrix of a partial factorization of the discriminant of $x$,
3888: and binary digits of $\fl$ are as follows:
3889:
3890: 1: assume that no square of a prime greater than \kbd{primelimit}
3891: divides the discriminant.
3892:
3893: 2: use the round 2 algorithm, instead of the default \idx{round 4}.
3894: This should be
3895: slower except maybe for polynomials of small degree and coefficients.
3896:
3897: \syn{nfdiscf0}{x,\fl,p} where, to omit $p$, you should input \kbd{gzero}. You
3898: can also use $\teb{discf}(x)$ ($\fl=0$).
3899:
3900: \subsecidx{nfeltdiv}$(\var{nf},x,y)$: given two elements $x$ and $y$ in
3901: \var{nf}, computes their quotient $x/y$ in the number field $\var{nf}$.
3902:
3903: \syn{element_div}{\var{nf},x,y}.
3904:
3905: \subsecidx{nfeltdiveuc}$(\var{nf},x,y)$: given two elements $x$ and $y$ in
3906: \var{nf}, computes an algebraic integer $q$ in the number field $\var{nf}$
3907: such that the components of $x-qy$ are reasonably small. In fact, this is
3908: functionally identical to \kbd{round(nfeltdiv(\var{nf},x,y))}.
3909:
3910: \syn{nfdiveuc}{\var{nf},x,y}.
3911:
3912: \subsecidx{nfeltdivmodpr}$(\var{nf},x,y,\var{pr})$: given two elements $x$
3913: and $y$ in \var{nf} and \var{pr} a prime ideal in \kbd{modpr} format (see
3914: \tet{nfmodprinit}), computes their quotient $x / y$ modulo the prime ideal
3915: \var{pr}.
3916:
3917: \syn{element_divmodpr}{\var{nf},x,y,\var{pr}}.
3918:
3919: \subsecidx{nfeltdivrem}$(\var{nf},x,y)$: given two elements $x$ and $y$ in
3920: \var{nf}, gives a two-element row vector $[q,r]$ such that $x=qy+r$, $q$ is
3921: an algebraic integer in $\var{nf}$, and the components of $r$ are
3922: reasonably small.
3923:
3924: \syn{nfdivres}{\var{nf},x,y}.
3925:
3926: \subsecidx{nfeltmod}$(\var{nf},x,y)$: given two elements $x$ and $y$ in
3927: \var{nf}, computes an element $r$ of $\var{nf}$ of the form $r=x-qy$ with
3928: $q$ and algebraic integer, and such that $r$ is small. This is functionally
3929: identical to
3930: $$\kbd{x - nfeltmul(\var{nf},round(nfeltdiv(\var{nf},x,y)),y)}.$$
3931:
3932: \syn{nfmod}{\var{nf},x,y}.
3933:
3934: \subsecidx{nfeltmul}$(\var{nf},x,y)$: given two elements $x$ and $y$ in
3935: \var{nf}, computes their product $x*y$ in the number field $\var{nf}$.
3936:
3937: \syn{element_mul}{\var{nf},x,y}.
3938:
3939: \subsecidx{nfeltmulmodpr}$(\var{nf},x,y,\var{pr})$: given two elements $x$ and
3940: $y$ in \var{nf} and \var{pr} a prime ideal in \kbd{modpr} format (see
3941: \tet{nfmodprinit}), computes their product $x*y$ modulo the prime ideal
3942: \var{pr}.
3943:
3944: \syn{element_mulmodpr}{\var{nf},x,y,\var{pr}}.
3945:
3946: \subsecidx{nfeltpow}$(\var{nf},x,k)$: given an element $x$ in \var{nf},
3947: and a positive or negative integer $k$, computes $x^k$ in the number field
3948: $\var{nf}$.
3949:
3950: \syn{element_pow}{\var{nf},x,k}.
3951:
3952: \subsecidx{nfeltpowmodpr}$(\var{nf},x,k,\var{pr})$: given an element $x$ in
3953: \var{nf}, an integer $k$ and a prime ideal \var{pr} in \kbd{modpr} format
3954: (see \tet{nfmodprinit}), computes $x^k$ modulo the prime ideal \var{pr}.
3955:
3956: \syn{element_powmodpr}{\var{nf},x,k,\var{pr}}.
3957:
3958: \subsecidx{nfeltreduce}$(\var{nf},x,\var{ideal})$: given an ideal in
3959: Hermite normal form and an element $x$ of the number field $\var{nf}$,
3960: finds an element $r$ in $\var{nf}$ such that $x-r$ belongs to the ideal
3961: and $r$ is small.
3962:
3963: \syn{element_reduce}{\var{nf},x,\var{ideal}}.
3964:
3965: \subsecidx{nfeltreducemodpr}$(\var{nf},x,\var{pr})$: given
3966: an element $x$ of the number field $\var{nf}$ and a prime ideal \var{pr} in
3967: \kbd{modpr} format compute a canonical representative for the class of $x$
3968: modulo \var{pr}.
3969:
3970: \syn{nfreducemodpr2}{\var{nf},x,\var{pr}}.
3971:
3972: \subsecidx{nfeltval}$(\var{nf},x,\var{pr})$: given an element $x$ in
3973: \var{nf} and a prime ideal \var{pr} in the format output by
3974: \kbd{idealprimedec}, computes their the valuation at \var{pr} of the
3975: element $x$. The same result could be obtained using
3976: \kbd{idealval(\var{nf},x,\var{pr})} (since $x$ would then be converted to a
3977: principal ideal), but it would be less efficient.
3978:
3979: \syn{element_val}{\var{nf},x,\var{pr}}, and the result is a \kbd{long}.
3980:
3981: \subsecidx{nffactor}$(\var{nf},x)$: factorization of the univariate
3982: polynomial $x$ over the number field $\var{nf}$ given by \kbd{nfinit}. $x$
3983: has coefficients in $\var{nf}$ (i.e.~either scalar, polmod, polynomial or
3984: column vector). The main variable of $\var{nf}$ must be of \var{lower}
3985: priority than that of $x$ (in other words, the variable number of $\var{nf}$
3986: must be \var{greater} than that of $x$). However if the polynomial defining
3987: the number field occurs explicitly in the coefficients of $x$ (as modulus of
3988: a \typ{POLMOD}), its main variable must be \var{the same} as the main
3989: variable of $x$. For example,
3990: \bprog
3991: ? nf = nfinit(y^2 + 1);
3992: ? nffactor(nf, x^2 + y); \\@com OK
3993: ? nffactor(nf, x^2 + Mod(y, y^2+1)); \\ @com OK
3994: ? nffactor(nf, x^2 + Mod(z, z^2+1)); \\ @com WRONG
3995: @eprog
3996:
3997: \syn{nffactor}{\var{nf},x}.
3998:
3999: \subsecidx{nffactormod}$(\var{nf},x,\var{pr})$: factorization of the
4000: univariate polynomial $x$ modulo the prime ideal \var{pr} in the number
4001: field $\var{nf}$. $x$ can have coefficients in the number field (scalar,
4002: polmod, polynomial, column vector) or modulo the prime ideal (integermod
4003: modulo the rational prime under \var{pr}, polmod or polynomial with
4004: integermod coefficients, column vector of integermod). The prime ideal
4005: \var{pr} \var{must} be in the format output by \kbd{idealprimedec}. The
4006: main variable of $\var{nf}$ must be of lower priority than that of $x$ (in
4007: other words the variable number of $\var{nf}$ must be greater than that of
4008: $x$). However if the coefficients of the number field occur explicitly (as
4009: polmods) as coefficients of $x$, the variable of these polmods \var{must}
4010: be the same as the main variable of $t$ (see \kbd{nffactor}).
4011:
4012: \syn{nffactormod}{\var{nf},x,\var{pr}}.
4013:
4014: \subsecidx{nfgaloisapply}$(\var{nf},\var{aut},x)$: $\var{nf}$ being a
4015: number field as output by \kbd{nfinit}, and \var{aut} being a \idx{Galois}
4016: automorphism of $\var{nf}$ expressed either as a polynomial or a polmod
4017: (such automorphisms being found using for example one of the variants of
4018: \kbd{nfgaloisconj}), computes the action of the automorphism \var{aut} on
4019: the object $x$ in the number field. $x$ can be an element (scalar, polmod,
4020: polynomial or column vector) of the number field, an ideal (either given by
4021: $\Z_K$-generators or by a $\Z$-basis), a prime ideal (given as a 5-element
4022: row vector) or an idele (given as a 2-element row vector). Because of
4023: possible confusion with elements and ideals, other vector or matrix
4024: arguments are forbidden.
4025:
4026: \syn{galoisapply}{\var{nf},\var{aut},x}.
4027:
4028: \subsecidx{nfgaloisconj}$(\var{nf},\{\fl=0\},\{d\})$: $\var{nf}$ being a
4029: number field as output by \kbd{nfinit}, computes the conjugates of a root
4030: $r$ of the non-constant polynomial $x=\var{nf}[1]$ expressed as
4031: polynomials in $r$. This can be used even if the number field $\var{nf}$ is
4032: not \idx{Galois} since some conjugates may lie in the field. As a note to
4033: old-timers of PARI, starting with version 2.0.17 this function works much
4034: better than in earlier versions.
4035:
4036: $\var{nf}$ can simply be a polynomial if $\fl\neq 1$.
4037:
4038: If no flags or $\fl=0$, if $\var{nf}$ is a number field use a
4039: combination of flag $4$ and $1$ and the result is always complete,
4040: else use a combination of flag $4$ and $2$ and the result is subject
4041: to the restriction of $\fl=2$, but a warning is issued when it is not
4042: proven complete.
4043:
4044: If $\fl=1$, use \kbd{nfroots} (require a number field).
4045:
4046: If $\fl=2$, use complex approximations to the roots and an integral
4047: \idx{LLL}. The result is not guaranteed to be complete: some
4048: conjugates may be missing (no warning issued), especially so if the
4049: corresponding polynomial has a huge index. In that case, increasing
4050: the default precision may help.
4051:
4052: If $\fl=4$, use Allombert's algorithm and permutation testing. If the
4053: field is Galois with ``weakly'' super solvable Galois group, return
4054: the complete list of automorphisms, else only the identity element. If
4055: present, $d$ is assumed to be a multiple of the least common
4056: denominator of the conjugates expressed as polynomial in a root of
4057: \var{pol}.
4058:
4059: A group G is ``weakly'' super solvable if it contains a super solvable
4060: normal subgroup $H$ such that $G=H$ , or $G/H \simeq A_4$ , or $G/H \simeq
4061: S_4$. Abelian and nilpotent groups are ``weakly'' super solvable. In
4062: practice, almost all groups of small order are ``weakly'' super solvable, the
4063: exceptions having order 36(1 exception), 48(2), 56(1), 60(1), 72(5), 75(1),
4064: 80(1), 96(10) and $\geq 108$.
4065:
4066: Hence $\fl = 4$ permits to quickly check whether a polynomial of order
4067: strictly less than $36$ is Galois or not. This method is much faster than
4068: \kbd{nfroots} and can be applied to polynomials of degree larger than $50$.
4069:
4070: \syn{galoisconj0}{\var{nf},\fl,d,\var{prec}}. Also available are
4071: $\teb{galoisconj}(\var{nf})$ for $\fl=0$,
4072: $\teb{galoisconj2}(\var{nf},n,\var{prec})$ for $\fl=2$ where $n$ is a bound
4073: on the number of conjugates, and $\teb{galoisconj4}(\var{nf},d)$
4074: corresponding to $\fl=4$.
4075:
4076: \subsecidx{nfhilbert}$(\var{nf},a,b,\{\var{pr}\})$: if \var{pr} is omitted,
4077: compute the global \idx{Hilbert symbol} $(a,b)$ in $\var{nf}$, that is $1$
4078: if $x^2 - a y^2 - b z^2$ has a non trivial solution $(x,y,z)$ in $\var{nf}$,
4079: and $-1$ otherwise. Otherwise compute the local symbol modulo the prime ideal
4080: \var{pr} (as output by \kbd{idealprimedec}).
4081:
4082: \syn{nfhilbert}{\var{nf},a,b,\var{pr}}, where an omitted \var{pr} is coded
4083: as \kbd{NULL}.
4084:
4085: \subsecidx{nfhnf}$(\var{nf},x)$: given a pseudo-matrix $(A,I)$, finds a
4086: pseudo-basis in \idx{Hermite normal form} of the module it generates.
4087:
4088: \syn{nfhermite}{\var{nf},x}.
4089:
4090: \subsecidx{nfhnfmod}$(\var{nf},x,\var{detx})$: given a pseudo-matrix $(A,I)$
4091: and an ideal \var{detx} which is contained in (read integral multiple of) the
4092: determinant of $(A,I)$, finds a pseudo-basis in \idx{Hermite normal form}
4093: of the module generated by $(A,I)$. This avoids coefficient explosion.
4094: \var{detx} can be computed using the function \kbd{nfdetint}.
4095:
4096: \syn{nfhermitemod}{\var{nf},x,\var{detx}}.
4097:
4098: \subsecidx{nfinit}$(\var{pol},\{\fl=0\})$: \var{pol} being a non-constant,
4099: preferably monic, irreducible polynomial in $\Z[X]$, initializes a
4100: \var{number field} structure (\kbd{nf}) associated to the field $K$ defined
4101: by \var{pol}. As such, it's a technical object passed as the first argument
4102: to most \kbd{nf}\var{xxx} functions, but it contains some information which
4103: may be directly useful. Access to this information via \var{member
4104: functions} is prefered since the specific data organization specified below
4105: may change in the future. Currently, \kbd{nf} is a row vector with 9
4106: components:
4107:
4108: $\var{nf}[1]$ contains the polynomial \var{pol} (\kbd{\var{nf}.pol}).
4109:
4110: $\var{nf}[2]$ contains $[r1,r2]$ (\kbd{\var{nf}.sign}), the number of real
4111: and complex places of $K$.
4112:
4113: $\var{nf}[3]$ contains the discriminant $d(K)$ (\kbd{\var{nf}.disc}) of $K$.
4114:
4115: $\var{nf}[4]$ contains the index of $\var{nf}[1]$,
4116: i.e.~$[\Z_K : \Z[\theta]]$, where $\theta$ is any root of $\var{nf}[1]$.
4117:
4118: $\var{nf}[5]$ is a vector containing 7 matrices $M$, $MC$, $T2$, $T$,
4119: $MD$, $TI$, $MDI$ useful for certain computations in the number field $K$.
4120:
4121: \quad$\bullet$ $M$ is the $(r1+r2)\times n$ matrix whose columns represent
4122: the numerical values of the conjugates of the elements of the integral
4123: basis.
4124:
4125: \quad$\bullet$ $MC$ is essentially the conjugate of the transpose of $M$,
4126: except that the last $r2$ columns are also multiplied by 2.
4127:
4128: \quad$\bullet$ $T2$ is an $n\times n$ matrix equal to the real part of the
4129: product $MC\cdot M$ (which is a real positive definite symmetric matrix), the
4130: so-called $T_2$-matrix (\kbd{\var{nf}.t2}).
4131:
4132: \quad$\bullet$ $T$ is the $n\times n$ matrix whose coefficients are
4133: $\text{Tr}(\omega_i\omega_j)$ where the $\omega_i$ are the elements of the
4134: integral basis. Note that $T=\overline{MC}\cdot M$ and in particular that
4135: $T=T_2$ if the field is totally real (in practice $T_2$ will have real
4136: approximate entries and $T$ will have integer entries). Note also that
4137: $\det(T)$ is equal to the discriminant of the field $K$.
4138:
4139: \quad$\bullet$ The columns of $MD$ (\kbd{\var{nf}.diff}) express a $\Z$-basis
4140: of the different of $K$ on the integral basis.
4141:
4142: \quad$\bullet$ $TI$ is equal to $d(K)T^{-1}$, which has integral
4143: coefficients. Note that, understood as as ideal, the matrix $T^{-1}$
4144: generates the codifferent ideal.
4145:
4146: \quad$\bullet$ Finally, $MDI$ is a two-element representation (for faster
4147: ideal product) of $d(K)$ times the codifferent ideal
4148: (\kbd{\var{nf}.disc$*$\var{nf}.codiff}, which is an integral ideal). $MDI$
4149: is only used in \tet{idealinv}.
4150:
4151: $\var{nf}[6]$ is the vector containing the $r1+r2$ roots
4152: (\kbd{\var{nf}.roots}) of $\var{nf}[1]$ corresponding to the $r1+r2$
4153: embeddings of the number field into $\C$ (the first $r1$ components are real,
4154: the next $r2$ have positive imaginary part).
4155:
4156: $\var{nf}[7]$ is an integral basis in Hermite normal form for $\Z_K$
4157: (\kbd{\var{nf}.zk}) expressed on the powers of~$\theta$.
4158:
4159: $\var{nf}[8]$ is the $n\times n$ integral matrix expressing the power
4160: basis in terms of the integral basis, and finally
4161:
4162: $\var{nf}[9]$ is the $n\times n^2$ matrix giving the multiplication table
4163: of the integral basis.
4164:
4165: If a non monic polynomial is input, \kbd{nfinit} will transform it into a
4166: monic one, then reduce it (see $\fl=3$). It is allowed, though not very
4167: useful given the existence of \tet{nfnewprec}, to input a \kbd{nf} or a
4168: \kbd{bnf} instead of a polynomial.
4169:
4170: The special input format $[x,B]$ is also accepted where $x$ is a polynomial
4171: as above and $B$ is the integer basis, as computed by \tet{nfbasis}. This can
4172: be useful since \kbd{nfinit} uses the round 4 algorithm by default, which can
4173: be very slow in pathological cases where round 2 (\kbd{nfbasis(x,2)}) would
4174: succeed very quickly.
4175:
4176: If $\fl=2$: \var{pol} is changed into another polynomial $P$ defining the same
4177: number field, which is as simple as can easily be found using the
4178: \kbd{polred} algorithm, and all the subsequent computations are done using
4179: this new polynomial. In particular, the first component of the result is the
4180: modified polynomial.
4181:
4182: If $\fl=3$, does a \kbd{polred} as in case 2, but outputs
4183: $[\var{nf},\kbd{Mod}(a,P)]$, where $\var{nf}$ is as before and
4184: $\kbd{Mod}(a,P)=\kbd{Mod}(x,\var{pol})$ gives the change of
4185: variables. This is implicit when \var{pol} is not monic: first a linear change
4186: of variables is performed, to get a monic polynomial, then a \kbd{polred}
4187: reduction.
4188:
4189: If $\fl=4$, as $2$ but uses a partial \kbd{polred}.
4190:
4191: If $\fl=5$, as $3$ using a partial \kbd{polred}.
4192:
4193: \syn{nfinit0}{x,\fl,\var{prec}}.
4194:
4195: \subsecidx{nfisideal}$(\var{nf},x)$: returns 1 if $x$ is an ideal in
4196: the number field $\var{nf}$, 0 otherwise.
4197:
4198: \syn{isideal}{x}.
4199:
4200: \subsecidx{nfisincl}$(x,y)$: tests whether the number field $K$ defined
4201: by the polynomial $x$ is conjugate to a subfield of the field $L$ defined
4202: by $y$ (where $x$ and $y$ must be in $\Q[X]$). If they are not, the output
4203: is the number 0. If they are, the output is a vector of polynomials, each
4204: polynomial $a$ representing an embedding of $K$ into $L$, i.e.~being such
4205: that $y\mid x\circ a$.
4206:
4207: If $y$ is a number field (\var{nf}), a much faster algorithm is used
4208: (factoring $x$ over $y$ using \tet{nffactor}). Before version 2.0.14, this
4209: wasn't guaranteed to return all the embeddings, hence was triggered by a
4210: special flag. This is no more the case.
4211:
4212: \syn{nfisincl}{x,y,\fl}.
4213:
4214: \subsecidx{nfisisom}$(x,y)$: as \tet{nfisincl}, but tests
4215: for isomorphism. If either $x$ or $y$ is a number field, a much faster
4216: algorithm will be used.
4217:
4218: \syn{nfisisom}{x,y,\fl}.
4219:
4220: \subsecidx{nfnewprec}$(\var{nf})$: transforms the number field $\var{nf}$
4221: into the corresponding data using current (usually larger) precision. This
4222: function works as expected if $\var{nf}$ is in fact a $\var{bnf}$ (update
4223: $\var{bnf}$ to current precision) but may be quite slow (many generators of
4224: principal ideals have to be computed).
4225:
4226: \syn{nfnewprec}{\var{nf},\var{prec}}.
4227:
4228: \subsecidx{nfkermodpr}$(\var{nf},a,\var{pr})$: kernel of the matrix $a$ in
4229: $\Z_K/\var{pr}$, where \var{pr} is in \key{modpr} format
4230: (see \kbd{nfmodprinit}).
4231:
4232: \syn{nfkermodpr}{\var{nf},a,\var{pr}}.
4233:
4234: \subsecidx{nfmodprinit}$(\var{nf},\var{pr})$: transforms the prime ideal
4235: \var{pr} into \tet{modpr} format necessary for all operations modulo
4236: \var{pr} in the number field \var{nf}. Returns a two-component vector
4237: $[P,a]$, where $P$ is the \idx{Hermite normal form} of \var{pr}, and $a$ is
4238: an integral element congruent to $1$ modulo \var{pr}, and congruent to $0$
4239: modulo $p / pr^e$. Here $p = \Z \cap \var{pr}$ and $e$
4240: is the absolute ramification index.\label{se:nfmodprinit}
4241:
4242: \syn{nfmodprinit}{\var{nf},\var{pr}}.
4243:
4244: \subsecidx{nfsubfields}$(\var{pol},\{d=0\})$: finds all subfields of degree
4245: $d$ of the number field defined by the (monic, integral) polynomial
4246: \var{pol} (all subfields if $d$ is null or omitted). The result is a vector
4247: of subfields, each being given by $[g,h]$, where $g$ is an absolute equation
4248: and $h$ expresses one of the roots of $g$ in terms of the root $x$ of the
4249: polynomial defining $\var{nf}$. This routine uses J.~Kl\"uners's algorithm,
4250: our naïve implementation would be very slow when no sufficiently inert primes
4251: can be found, e.g.~when \var{nf} is a compositum of many quadratic fields. So
4252: it may abort with an error message (\kbd{too many block systems}) if it looks
4253: like the computation is hopeless. This shall eventually be
4254: corrected, using the ideas from \kbd{nfgaloisconj}.\sidx{Galois}\sidx{subfield}
4255:
4256: %If the field is abelian, you can circonvene the problem by using
4257: %\tet{galoisinit} and \tet{galoisfixedfield}, as in
4258: %\bprog
4259: % subf(pol) =
4260: % {
4261: % local(gal,G,H,h,l,gen, L = []);
4262: % gl = galoisinit(pol);
4263: % G = matdiagonal(Vec(g.orders));
4264: % l = length(G); gen = Mat(vectorv(l,i, g.gen[i]));
4265: % forsubgroup(H = G,,
4266: % h = mathnf(concat(H,G));
4267: % perm = vector(l,i, factorback(concat(gen, h[,i])));
4268: % L = concat(L, [galoisfixedfield(g, perm)])
4269: % ); L
4270: % }
4271: %@eprog
4272: %which returns the same output as \kbd{nfsubfields(pol)}. For non-abelian
4273: %Galois fields, you can still use \tet{galoisinit} and \teb{galoisfixedfield},
4274: %but you will have to use another package than PARI to compute the subgroup
4275: %lattice, since \tet{forsubgroup} is restricted to the abelian case.
4276:
4277: \syn{subfields}{\var{nf},d}.
4278:
4279: \subsecidx{nfroots}$(\var{nf},x)$: roots of the polynomial $x$ in the number
4280: field $\var{nf}$ given by \kbd{nfinit} without multiplicity. $x$ has
4281: coefficients in the number field (scalar, polmod, polynomial, column
4282: vector). The main variable of $\var{nf}$ must be of lower priority than that
4283: of $x$ (in other words the variable number of $\var{nf}$ must be greater than
4284: that of $x$). However if the coefficients of the number field occur
4285: explicitly (as polmods) as coefficients of $x$, the variable of these
4286: polmods \var{must} be the same as the main variable of $t$ (see
4287: \kbd{nffactor}).
4288:
4289: \syn{nfroots}{\var{nf},x}.
4290:
4291: \subsecidx{nfrootsof1}$(\var{nf})$: computes the number of roots of unity
4292: $w$ and a primitive $w$-th root of unity (expressed on the integral basis)
4293: belonging to the number field $\var{nf}$. The result is a two-component
4294: vector $[w,z]$ where $z$ is a column vector expressing a primitive $w$-th
4295: root of unity on the integral basis \kbd{\var{nf}.zk}.
4296:
4297: \syn{rootsof1}{\var{nf}}.
4298:
4299: \subsecidx{nfsnf}$(\var{nf},x)$: given a torsion module $x$ as a 3-component
4300: row
4301: vector $[A,I,J]$ where $A$ is a square invertible $n\times n$ matrix, $I$ and
4302: $J$ are two ideal lists, outputs an ideal list $d_1,\dots,d_n$ which is the
4303: \idx{Smith normal form} of $x$. In other words, $x$ is isomorphic to
4304: $\Z_K/d_1\oplus\cdots\oplus\Z_K/d_n$ and $d_i$ divides $d_{i-1}$ for $i\ge2$.
4305: The link between $x$ and $[A,I,J]$ is as follows: if $e_i$ is the canonical
4306: basis of $K^n$, $I=[b_1,\dots,b_n]$ and $J=[a_1,\dots,a_n]$, then $x$ is
4307: isomorphic to
4308: $$ (b_1e_1\oplus\cdots\oplus b_ne_n) / (a_1A_1\oplus\cdots\oplus a_nA_n)
4309: \enspace, $$
4310: where the $A_j$ are the columns of the matrix $A$. Note that every finitely
4311: generated torsion module can be given in this way, and even with $b_i=Z_K$
4312: for all $i$.
4313:
4314: \syn{nfsmith}{\var{nf},x}.
4315:
4316: \subsecidx{nfsolvemodpr}$(\var{nf},a,b,\var{pr})$: solution of $a\cdot x = b$
4317: in $\Z_K/\var{pr}$, where $a$ is a matrix and $b$ a column vector, and where
4318: \var{pr} is in \key{modpr} format (see \kbd{nfmodprinit}).
4319:
4320: \syn{nfsolvemodpr}{\var{nf},a,b,\var{pr}}.
4321:
4322: \subsecidx{polcompositum}$(x,y,\{\fl=0\})$: $x$ and $y$ being polynomials
4323: in $\Z[X]$ in the same variable, outputs a vector giving the list of all
4324: possible composita of the number fields defined by $x$ and $y$, if $x$ and
4325: $y$ are irreducible, or of the corresponding \'etale algebras, if they are
4326: only squarefree. Returns an error if one of the polynomials is not
4327: squarefree. When one of the polynomials is irreducible (say $x$), it is
4328: often \var{much} faster to use \kbd{nffactor(nfinit($x$), $y$)} then
4329: \tet{rnfequation}.
4330:
4331: If $\fl=1$, outputs a vector of 4-component vectors $[z,a,b,k]$, where $z$
4332: ranges through the list of all possible compositums as above, and $a$
4333: (resp. $b$) expresses the root of $x$ (resp. $y$) as a polmod in a root of
4334: $z$, and $k$ is a small integer k such that $a+kb$ is the chosen root of
4335: $z$.
4336:
4337: The compositum will quite often be defined by a complicated polynomial,
4338: which it is advisable to reduce before further work. Here is a simple
4339: example involving the field $\Q(\zeta_5, 5^{1/5})$:
4340: \bprog
4341: ? z = polcompositum(x^5 - 5, polcyclo(5), 1)[1];
4342: ? pol = z[1] \\@com \kbd{pol} defines the compositum
4343: %2 = x^20 + 5*x^19 + 15*x^18 + 35*x^17 + 70*x^16 + 141*x^15 + 260*x^14 \
4344: + 355*x^13 + 95*x^12 - 1460*x^11 - 3279*x^10 - 3660*x^9 - 2005*x^8 \
4345: + 705*x^7 + 9210*x^6 + 13506*x^5 + 7145*x^4 - 2740*x^3 + 1040*x^2 \
4346: - 320*x + 256
4347: ? a = z[2]; a^5 - 5 \\@com \kbd{a} is a fifth root of $5$
4348: %3 = 0
4349: ? z = polredabs(pol, 1); \\@com look for a simpler polynomial
4350: ? pol = z[1]
4351: %5 = x^20 + 25*x^10 + 5
4352: ? a = subst(a.pol, x, z[2]) \\@com \kbd{a} in the new coordinates
4353: %6 = Mod(-5/22*x^19 + 1/22*x^14 - 123/22*x^9 + 9/11*x^4, x^20 + 25*x^10 + 5)
4354: @eprog
4355:
4356: \syn{polcompositum0}{x,y,\fl}.
4357:
4358: \subsecidx{polgalois}$(x)$: \idx{Galois} group of the non-constant polynomial
4359: $x\in\Q[X]$. In the present version \vers, $x$ must be irreducible and
4360: the degree of $x$ must be less than or equal to 7. On certain versions for
4361: which the data file of Galois resolvents has been installed (available
4362: in the Unix distribution as a separate package), degrees 8, 9, 10 and 11
4363: are also implemented.
4364:
4365: The output is a 3-component vector $[n,s,k]$ with the following meaning: $n$
4366: is the cardinality of the group, $s$ is its signature ($s=1$ if the group is
4367: a subgroup of the alternating group $A_n$, $s=-1$ otherwise), and $k$ is the
4368: number of the group corresponding to a given pair $(n,s)$ ($k=1$ except in 2
4369: cases). Specifically, the groups are coded as follows, using standard
4370: notations (see GTM 138, quoted at the beginning of this section; see also
4371: ``The transitive groups of degree up to eleven'', by G.~Butler and J.~McKay
4372: in Communications in Algebra, vol.~11, 1983, pp.~863--911):
4373: \smallskip
4374: In degree 1: $S_1=[1,-1,1]$.
4375: \smallskip
4376: In degree 2: $S_2=[2,-1,1]$.
4377: \smallskip
4378: In degree 3: $A_3=C_3=[3,1,1]$, $S_3=[6,-1,1]$.
4379: \smallskip
4380: In degree 4: $C_4=[4,-1,1]$, $V_4=[4,1,1]$, $D_4=[8,-1,1]$, $A_4=[12,1,1]$,
4381: $S_4=[24,-1,1]$.
4382: \smallskip
4383: In degree 5: $C_5=[5,1,1]$, $D_5=[10,1,1]$, $M_{20}=[20,-1,1]$,
4384: $A_5=[60,1,1]$, $S_5=[120,-1,1]$.
4385: \smallskip
4386: In degree 6: $C_6=[6,-1,1]$, $S_3=[6,-1,2]$, $D_6=[12,-1,1]$, $A_4=[12,1,1]$,
4387: $G_{18}=[18,-1,1]$, $S_4^-=[24,-1,1]$, $A_4\times C_2=[24,-1,2]$,
4388: $S_4^+=[24,1,1]$, $G_{36}^-=[36,-1,1]$, $G_{36}^+=[36,1,1]$,
4389: $S_4\times C_2=[48,-1,1]$, $A_5=PSL_2(5)=[60,1,1]$, $G_{72}=[72,-1,1]$,
4390: $S_5=PGL_2(5)=[120,-1,1]$, $A_6=[360,1,1]$, $S_6=[720,-1,1]$.
4391: \smallskip
4392: In degree 7: $C_7=[7,1,1]$, $D_7=[14,-1,1]$, $M_{21}=[21,1,1]$,
4393: $M_{42}=[42,-1,1]$, $PSL_2(7)=PSL_3(2)=[168,1,1]$, $A_7=[2520,1,1]$,
4394: $S_7=[5040,-1,1]$.
4395: \smallskip
4396: The method used is that of resolvent polynomials and is sensitive to the
4397: current precision. The precision is updated internally but, in very rare
4398: cases, a wrong result may be returned if the initial precision was not
4399: sufficient.
4400:
4401: \syn{galois}{x,\var{prec}}.
4402:
4403: \subsecidx{polred}$(x,\{\fl=0\},\{p\})$: finds polynomials with reasonably
4404: small coefficients defining subfields of the number field defined by $x$.
4405: One of the polynomials always defines $\Q$ (hence is equal to $x-1$),
4406: and another always defines the same number field as $x$ if $x$ is irreducible.
4407: All $x$ accepted by \tet{nfinit} are also allowed here (e.g. non-monic
4408: polynomials, \kbd{nf}, \kbd{bnf}, \kbd{[x,Z\_K\_basis]}).
4409:
4410: The following binary digits of $\fl$ are significant:
4411:
4412: 1: does a partial reduction only. This means that only a suborder of the
4413: maximal order may be used.
4414:
4415: 2: gives also elements. The result is a two-column matrix, the first column
4416: giving the elements defining these subfields, the second giving the
4417: corresponding minimal polynomials.
4418:
4419: If $p$ is given, it is assumed that it is the two-column matrix of the
4420: factorization of the discriminant of the polynomial $x$.
4421:
4422: \syn{polred0}{x,\fl,p,\var{prec}}, where an omitted $p$ is
4423: coded by $gzero$. Also available are $\teb{polred}(x,\var{prec})$ and
4424: $\teb{factoredpolred}(x,p,\var{prec})$, both corresponding to $\fl=0$.
4425:
4426: \subsecidx{polredabs}$(x,\{\fl=0\})$: finds one of the polynomial defining
4427: the same number field as the one defined by $x$, and such that the sum of the
4428: squares of the modulus of the roots (i.e.~the $T_2$-norm) is minimal.
4429: All $x$ accepted by \tet{nfinit} are also allowed here (e.g. non-monic
4430: polynomials, \kbd{nf}, \kbd{bnf}, \kbd{[x,Z\_K\_basis]}).
4431:
4432: The binary digits of $\fl$ mean
4433:
4434: 1: outputs a two-component row vector $[P,a]$, where $P$ is the default
4435: output and $a$ is an element expressed on a root of the polynomial $P$,
4436: whose minimal polynomial is equal to $x$.
4437:
4438: 4: gives \var{all} polynomials of minimal $T_2$ norm (of the two polynomials
4439: $P(x)$ and $P(-x)$, only one is given).
4440:
4441: \syn{polredabs0}{x,\fl,\var{prec}}.
4442:
4443: \subsecidx{polredord}$(x)$: finds polynomials with reasonably small
4444: coefficients and of the same degree as that of $x$ defining suborders of the
4445: order defined by $x$. One of the polynomials always defines $\Q$ (hence
4446: is equal to $(x-1)^n$, where $n$ is the degree), and another always defines
4447: the same order as $x$ if $x$ is irreducible.
4448:
4449: \syn{ordred}{x}.
4450:
4451: \subsecidx{poltschirnhaus}$(x)$: applies a random Tschirnhausen
4452: transformation to the polynomial $x$, which is assumed to be non-constant
4453: and separable, so as to obtain a new equation for the \'etale algebra
4454: defined by $x$. This is for instance useful when computing resolvents,
4455: hence is used by the \kbd{polgalois} function.
4456:
4457: \syn{tschirnhaus}{x}.
4458:
4459: \subsecidx{rnfalgtobasis}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
4460: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an element of
4461: $L$ expressed as a polynomial or polmod with polmod coefficients, expresses
4462: $x$ on the relative integral basis.
4463:
4464: \syn{rnfalgtobasis}{\var{rnf},x}.
4465:
4466: \subsecidx{rnfbasis}$(\var{bnf},x)$: given a big number field $\var{bnf}$ as
4467: output by \kbd{bnfinit}, and either a polynomial $x$ with coefficients in
4468: $\var{bnf}$ defining a relative extension $L$ of $\var{bnf}$, or a
4469: pseudo-basis $x$ of such an extension, gives either a true $\var{bnf}$-basis
4470: of $L$ if it exists, or an $n+1$-element generating set of $L$ if not, where
4471: $n$ is the rank of $L$ over $\var{bnf}$.
4472:
4473: \syn{rnfbasis}{\var{bnf},x}.
4474:
4475: \subsecidx{rnfbasistoalg}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
4476: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an element of
4477: $L$ expressed on the relative integral basis, computes the representation of
4478: $x$ as a polmod with polmods coefficients.
4479:
4480: \syn{rnfbasistoalg}{\var{rnf},x}.
4481:
4482: \subsecidx{rnfcharpoly}$(\var{nf},T,a,\{v=x\})$: characteristic polynomial of
4483: $a$ over $\var{nf}$, where $a$ belongs to the algebra defined by $T$ over
4484: $\var{nf}$, i.e.~$\var{nf}[X]/(T)$. Returns a polynomial in variable $v$
4485: ($x$ by default).
4486:
4487: \syn{rnfcharpoly}{\var{nf},T,a,v}, where $v$ is a variable number.
4488:
4489: \subsecidx{rnfconductor}$(\var{bnf},\var{pol},\{\fl=0\})$: $\var{bnf}$
4490: being a big number field as output by \kbd{bnfinit}, and \var{pol} a
4491: relative polynomial defining an \idx{Abelian extension}, computes the
4492: class field theory conductor of this Abelian extension. The result is
4493: a 3-component vector $[\var{conductor},\var{rayclgp},\var{subgroup}]$,
4494: where \var{conductor} is the conductor of the extension given as a
4495: 2-component row vector $[f_0,f_\infty]$, \var{rayclgp} is the full ray
4496: class group corresponding to the conductor given as a 3-component
4497: vector [h,cyc,gen] as usual for a group, and \var{subgroup} is a
4498: matrix in HNF defining the subgroup of the ray class group on the
4499: given generators gen. If $\fl$ is non-zero, check under GRH that
4500: \var{pol} indeed defines an Abelian extension, return 0 if it does not.
4501:
4502: \syn{rnfconductor}{\var{rnf},\var{pol},\fl}.
4503:
4504: \subsecidx{rnfdedekind}$(\var{nf},\var{pol},\var{pr})$: given a number field
4505: $\var{nf}$ as output by \kbd{nfinit} and a polynomial \var{pol} with
4506: coefficients in $\var{nf}$ defining a relative extension $L$ of $\var{nf}$,
4507: evaluates the relative \idx{Dedekind} criterion over the order defined by a
4508: root of \var{pol} for the prime ideal \var{pr} and outputs a 3-component
4509: vector as the result. The first component is a flag equal to 1 if the
4510: enlarged order could be proven to be \var{pr}-maximal and to 0 otherwise (it
4511: may be maximal in the latter case if \var{pr} is ramified in $L$), the second
4512: component is a pseudo-basis of the enlarged order and the third component is
4513: the valuation at \var{pr} of the order discriminant.
4514:
4515: \syn{rnfdedekind}{\var{nf},\var{pol},\var{pr}}.
4516:
4517: \subsecidx{rnfdet}$(\var{nf},M)$: given a pseudomatrix $M$ over the maximal
4518: order of $\var{nf}$, computes its pseudodeterminant.
4519:
4520: \syn{rnfdet}{\var{nf},M}.
4521:
4522: \subsecidx{rnfdisc}$(\var{nf},\var{pol})$: given a number field $\var{nf}$ as
4523: output by \kbd{nfinit} and a polynomial \var{pol} with coefficients in
4524: $\var{nf}$ defining a relative extension $L$ of $\var{nf}$, computes
4525: the relative
4526: discriminant of $L$. This is a two-element row vector $[D,d]$, where $D$ is
4527: the relative ideal discriminant and $d$ is the relative discriminant
4528: considered as an element of $\var{nf}^*/{\var{nf}^*}^2$. The main variable of
4529: $\var{nf}$ \var{must} be of lower priority than that of \var{pol}.
4530:
4531: Note: As usual, $\var{nf}$ can be a $\var{bnf}$ as output by \kbd{nfinit}.
4532:
4533: \syn{rnfdiscf}{\var{bnf},\var{pol}}.
4534:
4535: \subsecidx{rnfeltabstorel}$(\var{rnf},x)$: $\var{rnf}$ being a relative
4536: number field
4537: extension $L/K$ as output by \kbd{rnfinit} and $x$ being an element of $L$
4538: expressed as a polynomial modulo the absolute equation $\var{rnf}[11][1]$,
4539: computes $x$ as an element of the relative extension $L/K$ as a polmod with
4540: polmod coefficients.
4541:
4542: \syn{rnfelementabstorel}{\var{rnf},x}.
4543:
4544: \subsecidx{rnfeltdown}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
4545: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an element of
4546: $L$ expressed as a polynomial or polmod with polmod coefficients, computes
4547: $x$ as an element of $K$ as a polmod, assuming $x$ is in $K$ (otherwise an
4548: error will occur). If $x$ is given on the relative integral basis, apply
4549: \kbd{rnfbasistoalg} first, otherwise PARI will believe you are dealing with a
4550: vector.
4551:
4552: \syn{rnfelementdown}{\var{rnf},x}.
4553:
4554: \subsecidx{rnfeltreltoabs}$(\var{rnf},x)$: $\var{rnf}$ being a relative
4555: number field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an
4556: element of $L$ expressed as a polynomial or polmod with polmod
4557: coefficients, computes $x$ as an element of the absolute extension $L/\Q$ as
4558: a polynomial modulo the absolute equation $\var{rnf}[11][1]$. If $x$ is
4559: given on the relative integral basis, apply \kbd{rnfbasistoalg} first,
4560: otherwise PARI will believe you are dealing with a vector.
4561:
4562: \syn{rnfelementreltoabs}{\var{rnf},x}.
4563:
4564: \subsecidx{rnfeltup}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
4565: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an element of
4566: $K$ expressed as a polynomial or polmod, computes $x$ as an element of the
4567: absolute extension $L/\Q$ as a polynomial modulo the absolute equation
4568: $\var{rnf}[11][1]$. Note that it is unnecessary to compute $x$ as an
4569: element of the relative extension $L/K$ (its expression would be identical to
4570: itself). If $x$ is given on the integral basis of $K$, apply
4571: \kbd{nfbasistoalg} first, otherwise PARI will believe you are dealing with a
4572: vector.
4573:
4574: \syn{rnfelementup}{\var{rnf},x}.
4575:
4576: \subsecidx{rnfequation}$(\var{nf},\var{pol},\{\fl=0\})$: given a number field
4577: $\var{nf}$ as output by \kbd{nfinit} (or simply a polynomial) and a
4578: polynomial \var{pol} with coefficients in $\var{nf}$ defining a relative
4579: extension $L$ of $\var{nf}$, computes the absolute equation of $L$ over
4580: $\Q$.
4581:
4582: If $\fl$ is non-zero, outputs a 3-component row vector $[z,a,k]$, where
4583: $z$ is the absolute equation of $L$ over $\Q$, as in the default behaviour,
4584: $a$ expresses as an element of $L$ a root $\alpha$ of the polynomial
4585: defining the base field $\var{nf}$, and $k$ is a small integer such that
4586: $\theta = \beta+k\alpha$ where $\theta$ is a root of $z$ and $\beta$ a root
4587: of $\var{pol}$.
4588:
4589: The main variable of $\var{nf}$ \var{must} be of lower priority than that
4590: of \var{pol}. Note that for efficiency, this does not check whether the
4591: relative equation is irreducible over $\var{nf}$, but only if it is
4592: squarefree. If it is reducible but squarefree, the result will be the
4593: absolute equation of the \'etale algebra defined by \var{pol}. If \var{pol}
4594: is not squarefree, an error message will be issued.
4595:
4596: \syn{rnfequation0}{\var{nf},\var{pol},\fl}.
4597:
4598: \subsecidx{rnfhnfbasis}$(\var{bnf},x)$: given a big number field $\var{bnf}$
4599: as output by \kbd{bnfinit}, and either a polynomial $x$ with coefficients in
4600: $\var{bnf}$ defining a relative extension $L$ of $\var{bnf}$, or a
4601: pseudo-basis $x$ of such an extension, gives either a true $\var{bnf}$-basis
4602: of $L$ in upper triangular Hermite normal form, if it exists,
4603: zero otherwise.
4604:
4605: \syn{rnfhermitebasis}{\var{nf},x}.
4606:
4607: \subsecidx{rnfidealabstorel}$(\var{rnf},x)$: $\var{rnf}$ being a relative
4608: number field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an
4609: ideal of the absolute extension $L/\Q$ given in HNF\sidx{Hermite normal form}
4610: (if it is not, apply \kbd{idealhnf} first), computes the relative pseudomatrix
4611: in HNF giving the ideal $x$ considered as an ideal of the relative extension
4612: $L/K$.
4613:
4614: \syn{rnfidealabstorel}{\var{rnf},x}.
4615:
4616: \subsecidx{rnfidealdown}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
4617: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an ideal of
4618: the absolute extension $L/\Q$ given in HNF (if it is not, apply
4619: \kbd{idealhnf} first), gives the ideal of $K$ below $x$, i.e.~the
4620: intersection of $x$ with $K$. Note that, if $x$ is given as a relative ideal
4621: (i.e.~a pseudomatrix in HNF), then it is not necessary to use this function
4622: since the result is simply the first ideal of the ideal list of the
4623: pseudomatrix.
4624:
4625: \syn{rnfidealdown}{\var{rnf},x}.
4626:
4627: \subsecidx{rnfidealhnf}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
4628: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being a relative
4629: ideal (which can be, as in the absolute case, of many different types,
4630: including of course elements), computes as a 2-component row vector the
4631: relative Hermite normal form of $x$, the first component being the HNF matrix
4632: (with entries on the integral basis), and the second component the ideals.
4633:
4634: \syn{rnfidealhermite}{\var{rnf},x}.
4635:
4636: \subsecidx{rnfidealmul}$(\var{rnf},x,y)$: $\var{rnf}$ being a relative number
4637: field extension $L/K$ as output by \kbd{rnfinit} and $x$ and $y$ being ideals
4638: of the relative extension $L/K$ given by pseudo-matrices, outputs the ideal
4639: product, again as a relative ideal.
4640:
4641: \syn{rnfidealmul}{\var{rnf},x,y}.
4642:
4643: \subsecidx{rnfidealnormabs}$(\var{rnf},x)$: $\var{rnf}$ being a relative
4644: number field extension $L/K$ as output by \kbd{rnfinit} and $x$ being a
4645: relative ideal (which can be, as in the absolute case, of many different
4646: types, including of course elements), computes the norm of the ideal $x$
4647: considered as an ideal of the absolute extension $L/\Q$. This is identical to
4648: \kbd{idealnorm(rnfidealnormrel(\var{rnf},x))}, only faster.
4649:
4650: \syn{rnfidealnormabs}{\var{rnf},x}.
4651:
4652: \subsecidx{rnfidealnormrel}$(\var{rnf},x)$: $\var{rnf}$ being a relative
4653: number field
4654: extension $L/K$ as output by \kbd{rnfinit} and $x$ being a relative ideal
4655: (which can be, as in the absolute case, of many different types, including
4656: of course elements), computes the relative norm of $x$ as a ideal of $K$
4657: in HNF.
4658:
4659: \syn{rnfidealnormrel}{\var{rnf},x}.
4660:
4661: \subsecidx{rnfidealreltoabs}$(\var{rnf},x)$: $\var{rnf}$ being a relative
4662: number field
4663: extension $L/K$ as output by \kbd{rnfinit} and $x$ being a relative ideal
4664: (which can be, as in the absolute case, of many different types, including
4665: of course elements), computes the HNF matrix of the ideal $x$ considered
4666: as an ideal of the absolute extension $L/\Q$.
4667:
4668: \syn{rnfidealreltoabs}{\var{rnf},x}.
4669:
4670: \subsecidx{rnfidealtwoelt}$(\var{rnf},x)$: $\var{rnf}$ being a relative
4671: number field
4672: extension $L/K$ as output by \kbd{rnfinit} and $x$ being an ideal of the
4673: relative extension $L/K$ given by a pseudo-matrix, gives a vector of
4674: two generators of $x$ over $\Z_L$ expressed as polmods with polmod
4675: coefficients.
4676:
4677: \syn{rnfidealtwoelement}{\var{rnf},x}.
4678:
4679: \subsecidx{rnfidealup}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
4680: field
4681: extension $L/K$ as output by \kbd{rnfinit} and $x$ being an ideal of
4682: $K$, gives the ideal $x\Z_L$ as an absolute ideal of $L/\Q$ (the relative
4683: ideal representation is trivial: the matrix is the identity matrix, and
4684: the ideal list starts with $x$, all the other ideals being $\Z_K$).
4685:
4686: \syn{rnfidealup}{\var{rnf},x}.
4687:
4688: \subsecidx{rnfinit}$(\var{nf},\var{pol})$: $\var{nf}$ being a number field in
4689: \kbd{nfinit}
4690: format considered as base field, and \var{pol} a polynomial defining a relative
4691: extension over $\var{nf}$, this computes all the necessary data to work in the
4692: relative extension. The main variable of \var{pol} must be of higher priority
4693: (i.e.~lower number) than that of $\var{nf}$, and the coefficients of \var{pol}
4694: must be in $\var{nf}$.
4695:
4696: The result is an 11-component row vector as follows (most of the components
4697: are technical), the numbering being very close to that of \kbd{nfinit}. In
4698: the following description, we let $K$ be the base field defined by
4699: $\var{nf}$, $m$ the degree of the base field, $n$ the relative degree, $L$
4700: the large field (of relative degree $n$ or absolute degree $nm$), $r_1$ and
4701: $r_2$ the number of real and complex places of $K$.
4702:
4703: $\var{rnf}[1]$ contains the relative polynomial \var{pol}.
4704:
4705: $\var{rnf}[2]$ is a row vector with $r_1+r_2$ entries, entry $j$ being
4706: a 2-component row vector $[r_{j,1},r_{j,2}]$ where $r_{j,1}$ and $r_{j,2}$
4707: are the number of real and complex places of $L$ above the $j$-th place of
4708: $K$ so that $r_{j,1}=0$ and $r_{j,2}=n$ if $j$ is a complex place, while if
4709: $j$ is a real place we have $r_{j,1}+2r_{j,2}=n$.
4710:
4711: $\var{rnf}[3]$ is a two-component row vector $[\d(L/K),s]$ where $\d(L/K)$
4712: is the relative ideal discriminant of $L/K$ and $s$ is the discriminant of
4713: $L/K$ viewed as an element of $K^*/(K^*)^2$, in other words it is the output
4714: of \kbd{rnfdisc}.
4715:
4716: $\var{rnf}[4]$ is the ideal index $\f$, i.e.~such that
4717: $d(pol)\Z_K=\f^2\d(L/K)$.
4718:
4719: $\var{rnf}[5]$ is a vector \var{vm} with 7 entries useful for certain
4720: computations in the relative extension $L/K$. $\var{vm}[1]$ is a vector of
4721: $r_1+r_2$ matrices, the $j$-th matrix being an $(r_{1,j}+r_{2,j})\times n$
4722: matrix $M_j$ representing the numerical values of the conjugates of the
4723: $j$-th embedding of the elements of the integral basis, where $r_{i,j}$ is as
4724: in $\var{rnf}[2]$. $\var{vm}[2]$ is a vector of $r_1+r_2$ matrices, the
4725: $j$-th matrix $MC_j$ being essentially the conjugate of the matrix $M_j$
4726: except that the last $r_{2,j}$ columns are also multiplied by 2.
4727: $\var{vm}[3]$ is a vector of $r_1+r_2$ matrices $T2_j$, where $T2_j$ is
4728: an $n\times n$ matrix equal to the real part of the product $MC_j\cdot M_j$
4729: (which is a real positive definite matrix). $\var{vm}[4]$ is the $n\times n$
4730: matrix $T$ whose entries are the relative traces of $\omega_i\omega_j$
4731: expressed as polmods in $\var{nf}$, where the $\omega_i$ are the elements
4732: of the relative integral basis. Note that the $j$-th embedding of $T$ is
4733: equal to $\overline{MC_j}\cdot M_j$, and in particular will be equal to
4734: $T2_j$ if $r_{2,j}=0$. Note also that the relative ideal discriminant of
4735: $L/K$ is equal to $\det(T)$ times the square of the product of the ideals
4736: in the relative pseudo-basis (in $\var{rnf}[7][2]$). The last 3 entries
4737: $\var{vm}[5]$, $\var{vm}[6]$ and $\var{vm}[7]$ are linked to the different
4738: as in \kbd{nfinit}, but have not yet been implemented.
4739:
4740: $\var{rnf}[6]$ is a row vector with $r_1+r_2$ entries, the $j$-th entry
4741: being the
4742: row vector with $r_{1,j}+r_{2,j}$ entries of the roots of the $j$-th embedding
4743: of the relative polynomial \var{pol}.
4744:
4745: $\var{rnf}[7]$ is a two-component row vector, where the first component is
4746: the relative integral pseudo basis expressed as polynomials (in the variable of
4747: $pol$) with polmod coefficients in $\var{nf}$, and the second component is the
4748: ideal list of the pseudobasis in HNF.
4749:
4750: $\var{rnf}[8]$ is the inverse matrix of the integral basis matrix, with
4751: coefficients polmods in $\var{nf}$.
4752:
4753: $\var{rnf}[9]$ may be the multiplication table of the integral basis, but
4754: is not implemented at present.
4755:
4756: $\var{rnf}[10]$ is $\var{nf}$.
4757:
4758: $\var{rnf}[11]$ is a vector \var{vabs} with 5 entries describing the
4759: \var{absolute} extension $L/\Q$. $\var{vabs}[1]$ is an absolute equation.
4760: $\var{vabs}[2]$ expresses the generator $\alpha$ of the number field
4761: $\var{nf}$ as a polynomial modulo the absolute equation $\var{vabs}[1]$.
4762: $\var{vabs}[3]$ is a small integer $k$ such that, if $\beta$ is an abstract
4763: root of \var{pol} and $\alpha$ the generator of $\var{nf}$, the generator
4764: whose root is \var{vabs} will be $\beta + k \alpha$. Note that one must
4765: be very careful if $k\neq0$ when dealing simultaneously with absolute and
4766: relative quantities since the generator chosen for the absolute extension
4767: is not the same as for the relative one. If this happens, one can of course
4768: go on working, but we strongly advise to change the relative polynomial so
4769: that its root will be $\beta + k \alpha$. Typically, the GP instruction would
4770: be
4771:
4772: \kbd{pol = subst(pol, x, x - k*Mod(y,\var{nf}.pol))}
4773:
4774: Finally, $\var{vabs}[4]$ is the absolute integral basis of $L$ expressed in HNF
4775: (hence as would be output by \kbd{nfinit(vabs[1])}), and $\var{vabs}[5]$ the
4776: inverse matrix of the integral basis, allowing to go from polmod to integral
4777: basis representation.
4778:
4779: \syn{rnfinitalg}{\var{nf},\var{pol},\var{prec}}.
4780:
4781: \subsecidx{rnfisfree}$(\var{bnf},x)$: given a big number field $\var{bnf}$ as
4782: output by \kbd{bnfinit}, and either a polynomial $x$ with coefficients in
4783: $\var{bnf}$ defining a relative extension $L$ of $\var{bnf}$, or a
4784: pseudo-basis $x$ of such an extension, returns true (1) if $L/\var{bnf}$ is
4785: free, false (0) if not.
4786:
4787: \syn{rnfisfree}{\var{bnf},x}, and the result is a \kbd{long}.
4788:
4789: \subsecidx{rnfisnorm}$(\var{bnf},\var{ext},\var{el},\{\fl=1\})$: similar to
4790: \kbd{bnfisnorm} but in the relative case. This tries to decide whether the
4791: element \var{el} in \var{bnf} is the norm of some $y$ in \var{ext}.
4792: $\var{bnf}$ is as output by \kbd{bnfinit}.
4793:
4794: $\var{ext}$ is a relative extension which has to be a row vector whose
4795: components are:
4796:
4797: $\var{ext}[1]$: a relative equation of the number field \var{ext} over
4798: \var{bnf}. As usual, the priority of the variable of the polynomial
4799: defining the ground field \var{bnf} (say $y$) must be lower than the
4800: main variable of $\var{ext}[1]$, say $x$.
4801:
4802: $\var{ext}[2]$: the generator $y$ of the base field as a polynomial in $x$ (as
4803: given by \kbd{rnfequation} with $\fl = 1$).
4804:
4805: $\var{ext}[3]$: is the \kbd{bnfinit} of the absolute extension $\var{ext}/\Q$.
4806:
4807: This returns a vector $[a,b]$, where $\var{el}=\var{Norm}(a)*b$. It looks for a
4808: solution which is an $S$-integer, with $S$ a list of places (of \var{bnf})
4809: containing the ramified primes, the generators of the class group of
4810: \var{ext}, as well as those primes dividing \var{el}. If $\var{ext}/\var{bnf}$
4811: is known to be \idx{Galois}, set $\fl=0$ (here \var{el} is a norm iff $b=1$).
4812: If $\fl$ is non zero add to $S$ all the places above the primes which: divide
4813: $\fl$ if $\fl<0$, or are less than $\fl$ if $\fl>0$. The answer is guaranteed
4814: (i.e.~\var{el} is a norm iff $b=1$) under \idx{GRH}, if $S$ contains all
4815: primes less than $12\log^2\left|\text{disc}(\var{Ext})\right|$, where
4816: \var{Ext} is the normal closure of $\var{ext} / \var{bnf}$. Example:
4817:
4818: \bprog
4819: bnf = bnfinit(y^3 + y^2 - 2*y - 1);
4820: p = x^2 + Mod(y^2 + 2*y + 1, bnf.pol);
4821: rnf = rnfequation(bnf,p,1);
4822: ext = [p, rnf[2], bnfinit(rnf[1])];
4823: rnfisnorm(bnf,ext,17, 1)
4824: @eprog
4825: \noindent checks whether $17$ is a norm in the Galois extension $\Q(\beta) /
4826: \Q(\alpha)$, where $\alpha^3 + \alpha^2 - 2\alpha - 1 = 0$ and $\beta^2 +
4827: \alpha^2 + 2*\alpha + 1 = 0$ (it is).
4828:
4829: \syn{rnfisnorm}{\var{bnf},ext,x,\fl,\var{prec}}.
4830:
4831: \subsecidx{rnfkummer}$(\var{bnr},\var{subgroup},\{deg=0\})$: \var{bnr}
4832: being as output by \kbd{bnrinit}, finds a relative equation for the
4833: class field corresponding to the module in \var{bnr} and the given
4834: congruence subgroup. If \var{deg} is positive, outputs the list of all
4835: relative equations of degree \var{deg} contained in the ray class field
4836: defined by \var{bnr}.
4837:
4838: (THIS PROGRAM IS STILL IN DEVELOPMENT STAGE)
4839:
4840: \syn{rnfkummer}{\var{bnr},\var{subgroup},\var{deg},\var{prec}},
4841: where \var{deg} is a \kbd{long}.
4842:
4843: \subsecidx{rnflllgram}$(\var{nf},\var{pol},\var{order})$: given a polynomial
4844: \var{pol} with coefficients in \var{nf} defining a relative extension $L$ and
4845: a suborder \var{order} of $L$ (of maximal rank), as output by
4846: \kbd{rnfpseudobasis}$(\var{nf},\var{pol})$ or similar, gives
4847: $[[\var{neworder}],U]$, where \var{neworder} is a reduced order and $U$ is
4848: the unimodular transformation matrix.
4849:
4850: \syn{rnflllgram}{\var{nf},\var{pol},\var{order},\var{prec}}.
4851:
4852: \subsecidx{rnfnormgroup}$(\var{bnr},\var{pol})$: \var{bnr} being a big ray
4853: class field as output by \kbd{bnrinit} and \var{pol} a relative polynomial
4854: defining an \idx{Abelian extension}, computes the norm group (alias Artin
4855: or Takagi group) corresponding to the Abelian extension of $\var{bnf}=bnr[1]$
4856: defined by \var{pol}, where the module corresponding to \var{bnr} is assumed
4857: to be a multiple of the conductor (i.e.~polrel defines a subextension of
4858: bnr). The result is the HNF defining the norm group on the given generators
4859: of $\var{bnr}[5][3]$. Note that neither the fact that \var{pol} defines an
4860: Abelian extension nor the fact that the module is a multiple of the conductor
4861: is checked. The result is undefined if the assumption is not correct.
4862:
4863: \syn{rnfnormgroup}{\var{bnr},\var{pol}}.
4864:
4865: \subsecidx{rnfpolred}$(\var{nf},\var{pol})$: relative version of \kbd{polred}.
4866: Given a monic polynomial \var{pol} with coefficients in $\var{nf}$, finds a
4867: list of relative polynomials defining some subfields, hopefully simpler and
4868: containing the original field. In the present version \vers, this is slower
4869: than \kbd{rnfpolredabs}.
4870:
4871: \syn{rnfpolred}{\var{nf},\var{pol},\var{prec}}.
4872:
4873: \subsecidx{rnfpolredabs}$(\var{nf},\var{pol},\{\fl=0\})$: relative version of
4874: \kbd{polredabs}. Given a monic polynomial \var{pol} with coefficients in
4875: $\var{nf}$, finds a simpler relative polynomial defining the same field. If
4876: $\fl=1$, returns $[P,a]$ where $P$ is the default output and $a$ is an
4877: element expressed on a root of $P$ whose characteristic polynomial is
4878: \var{pol}, if $\fl=2$, returns an absolute polynomial (same as
4879:
4880: {\tt rnfequation(\var{nf},rnfpolredabs(\var{nf},\var{pol}))}
4881:
4882: \noindent but faster).
4883:
4884: \misctitle{Remark.} In the present implementation, this is both faster and
4885: much more efficient than \kbd{rnfpolred}, the difference being more
4886: dramatic than in the absolute case. This is because the implementation of
4887: \kbd{rnfpolred} is based on (a partial implementation of) an incomplete
4888: reduction theory of lattices over number fields (i.e.~the function
4889: \kbd{rnflllgram}) which deserves to be improved.
4890:
4891: \syn{rnfpolredabs}{\var{nf},\var{pol},\fl,\var{prec}}.
4892:
4893: \subsecidx{rnfpseudobasis}$(\var{nf},\var{pol})$: given a number field
4894: $\var{nf}$ as output by \kbd{nfinit} and a polynomial \var{pol} with
4895: coefficients in $\var{nf}$ defining a relative extension $L$ of $\var{nf}$,
4896: computes a pseudo-basis $(A,I)$ and the relative discriminant of $L$.
4897: This is output as
4898: a four-element row vector $[A,I,D,d]$, where $D$ is the relative ideal
4899: discriminant and $d$ is the relative discriminant considered as an element of
4900: $\var{nf}^*/{\var{nf}^*}^2$.
4901:
4902: Note: As usual, $\var{nf}$ can be a $\var{bnf}$ as output by \kbd{bnfinit}.
4903:
4904: \syn{rnfpseudobasis}{\var{nf},\var{pol}}.
4905:
4906: \subsecidx{rnfsteinitz}$(\var{nf},x)$: given a number field $\var{nf}$ as
4907: output by \kbd{nfinit} and either a polynomial $x$ with coefficients in
4908: $\var{nf}$ defining a relative extension $L$ of $\var{nf}$, or a pseudo-basis
4909: $x$ of such an extension as output for example by \kbd{rnfpseudobasis},
4910: computes another pseudo-basis $(A,I)$ (not in HNF in general) such that all
4911: the ideals of $I$ except perhaps the last one are equal to the ring of
4912: integers of $\var{nf}$, and outputs the four-component row vector $[A,I,D,d]$
4913: as in \kbd{rnfpseudobasis}. The name of this function comes from the fact
4914: that the ideal class of the last ideal of $I$ (which is well defined) is
4915: called the \idx{Steinitz class} of the module $\Z_L$.
4916:
4917: Note: $\var{nf}$ can be a $\var{bnf}$ as output by \kbd{bnfinit}.
4918:
4919: \syn{rnfsteinitz}{\var{nf},x}.
4920:
4921: \subsecidx{subgrouplist}$(\var{bnr},\{\var{bound}\},\{\fl=0\})$:
4922: \var{bnr} being as output by \kbd{bnrinit} or a list of cyclic components
4923: of a finite Abelian group $G$, outputs the list of subgroups of $G$
4924: (of index bounded by \var{bound}, if not omitted). Subgroups are given
4925: as HNF\sidx{Hermite normal form} left divisors of the
4926: SNF\sidx{Smith normal form} matrix corresponding to $G$. If $\fl=0$
4927: (default) and \var{bnr} is as output by
4928: \kbd{bnrinit}, gives only the subgroups whose modulus is the conductor.
4929:
4930: \syn{subgrouplist0}{\var{bnr},\var{bound},\fl}, where \var{bound} and $\fl$
4931: are long integers.
4932:
4933: \subsecidx{zetak}$(\var{znf},x,\{\fl=0\})$: \var{znf} being a number
4934: field initialized by \kbd{zetakinit} (\var{not} by \kbd{nfinit}),
4935: computes the value of the \idx{Dedekind} zeta function of the number
4936: field at the complex number $x$. If $\fl=1$ computes Dedekind $\Lambda$
4937: function instead (i.e.~the product of the
4938: Dedekind zeta function by its gamma and exponential factors).
4939:
4940: The accuracy of the result depends in an essential way on the accuracy of
4941: both the \kbd{zetakinit} program and the current accuracy, but even so the
4942: result may be off by up to 5 or 10 decimal digits.
4943:
4944: \syn{glambdak}{\var{znf},x,\var{prec}} or
4945: $\teb{gzetak}(\var{znf},x,\var{prec})$.
4946:
4947: \subsecidx{zetakinit}$(x)$: computes a number of initialization data
4948: concerning the number field defined by the polynomial $x$ so as to be able
4949: to compute the \idx{Dedekind} zeta and lambda functions (respectively
4950: $\kbd{zetak}(x)$ and $\kbd{zetak}(x,1)$). This function calls in particular
4951: the \kbd{bnfinit} program. The result is a 9-component vector $v$ whose
4952: components are very technical and cannot really be used by the user except
4953: through the \kbd{zetak} function. The only component which can be used if
4954: it has not been computed already is $v[1][4]$ which is the result of the
4955: \kbd{bnfinit} call.
4956:
4957: This function is very inefficient and should be rewritten. It needs to
4958: computes millions of coefficients of the corresponding Dirichlet series if
4959: the precision is big. Unless the discriminant is small it will not be able
4960: to handle more than 9 digits of relative precision
4961: (e.g~\kbd{zetakinit(x\pow 8 - 2)} needs 440MB of memory at default
4962: precision).
4963:
4964: \syn{initzeta}{x}.
4965:
4966: \section{Polynomials and power series}
4967:
4968: We group here all functions which are specific to polynomials or power
4969: series. Many other functions which can be applied on these objects are
4970: described in the other sections. Also, some of the functions described here
4971: can be applied to other types.
4972:
4973: \subsecidx{O}$(a$\kbd{\pow}$b)$: $p$-adic (if $a$ is an integer greater or
4974: equal to 2) or power series zero (in all other cases), with precision given
4975: by $b$.
4976:
4977: \syn{ggrandocp}{a,b}, where $b$ is a \kbd{long}.
4978:
4979: \subsecidx{deriv}$(x,\{v\})$: derivative of $x$ with respect to the main
4980: variable if $v$ is omitted, and with respect to $v$ otherwise. $x$ can be any
4981: type except polmod. The derivative of a scalar type is zero, and the
4982: derivative of a vector or matrix is done componentwise. One can use $x'$ as a
4983: shortcut if the derivative is with respect to the main variable of $x$.
4984:
4985: \syn{deriv}{x,v}, where $v$ is a \kbd{long}, and an omitted $v$ is coded as
4986: $-1$. When $x$ is a \typ{POL}, $\tet{derivpol}(x)$ is a shortcut for
4987: $\kbd{deriv}(x, -1)$.
4988:
4989: \subsecidx{eval}$(x)$: replaces in $x$ the formal variables by the values that
4990: have been assigned to them after the creation of $x$. This is mainly useful
4991: in GP, and not in library mode. Do not confuse this with substitution (see
4992: \kbd{subst}). Applying this function to a character string yields the
4993: output from the corresponding GP command, as if directly input from the
4994: keyboard (see \secref{se:strings}).\label{se:eval}
4995:
4996: \syn{geval}{x}. The more basic functions $\teb{poleval}(q,x)$,
4997: $\teb{qfeval}(q,x)$, and $\teb{hqfeval}(q,x)$ evaluate $q$ at $x$, where $q$
4998: is respectively assumed to be a polynomial, a quadratic form (a symmetric
4999: matrix), or an Hermitian form (an Hermitian complex matrix).
5000:
5001: \subsecidx{factorpadic}$(\var{pol},p,r,\{\fl=0\})$: $p$-adic factorization
5002: of the polynomial \var{pol} to precision $r$, the result being a
5003: two-column matrix as in \kbd{factor}. The factors are normalized so that
5004: their leading coefficient is a power of $p$. $r$ must be strictly larger than
5005: the $p$-adic valuation of the discriminant of \var{pol} for the result to
5006: make any sense. The method used is a modified version of the \idx{round 4}
5007: algorithm of \idx{Zassenhaus}.
5008:
5009: If $\fl=1$, use an algorithm due to \idx{Buchmann} and \idx{Lenstra}, which is
5010: usually less efficient.
5011:
5012: \syn{factorpadic4}{\var{pol},p,r}, where $r$ is a \kbd{long} integer.
5013:
5014: \subsecidx{intformal}$(x,\{v\})$: \idx{formal integration} of $x$ with
5015: respect to the main variable if $v$ is omitted, with respect to the variable
5016: $v$ otherwise. Since PARI does not know about ``abstract'' logarithms (they
5017: are immediately evaluated, if only to a power series), logarithmic terms in
5018: the result will yield an error. $x$ can be of any type. When $x$ is a
5019: rational function, it is assumed that the base ring is an integral domain of
5020: characteristic zero.
5021:
5022: \syn{integ}{x,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded
5023: as $-1$.
5024:
5025: \subsecidx{padicappr}$(\var{pol},a)$: vector of $p$-adic roots of the
5026: polynomial
5027: $pol$ congruent to the $p$-adic number $a$ modulo $p$ (or modulo 4 if $p=2$),
5028: and with the same $p$-adic precision as $a$. The number $a$ can be an
5029: ordinary $p$-adic number (type \typ{PADIC}, i.e.~an element of $\Q_p$) or
5030: can be an element of a finite extension of $\Q_p$, in which case it is of
5031: type \typ{POLMOD}, where at least one of the coefficients of the polmod is a
5032: $p$-adic number. In this case, the result is the vector of roots belonging to
5033: the same extension of $\Q_p$ as $a$.
5034:
5035: \syn{apprgen9}{\var{pol},a}, but if $a$ is known to be simply a $p$-adic number
5036: (type \typ{PADIC}), the syntax $\teb{apprgen}(\var{pol},a)$ can be used.
5037:
5038: \subsecidx{polcoeff}$(x,s,\{v\})$: coefficient of degree $s$ of the
5039: polynomial $x$, with respect to the main variable if $v$ is omitted, with
5040: respect to $v$ otherwise.
5041:
5042: \syn{polcoeff0}{x,s,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded
5043: as $-1$. Also available is \teb{truecoeff}$(x,v)$.
5044:
5045: \subsecidx{poldegree}$(x,\{v\})$: degree of the polynomial $x$ in the main
5046: variable if $v$ is omitted, in the variable $v$ otherwise. This is to be
5047: understood as follows. When $x$ is a polynomial or a rational function, it
5048: gives the degree of $x$, the degree of $0$ being $-1$ by convention. When $x$
5049: is a non-zero scalar, it gives 0, and when $x$ is a zero scalar, it gives
5050: $-1$. Return an error otherwise.
5051:
5052: \syn{poldegree}{x,v}, where $v$ and the result are \kbd{long}s (and an
5053: omitted $v$ is coded as $-1$). Also available is \teb{degree}$(x)$, which is
5054: equivalent to \kbd{poldegree($x$,-1)}.
5055:
5056: \subsecidx{polcyclo}$(n,\{v=x\})$: $n$-th cyclotomic polynomial, in variable
5057: $v$ ($x$ by default). The integer $n$ must be positive.
5058:
5059: \syn{cyclo}{n,v}, where $n$ and $v$ are \kbd{long}
5060: integers ($v$ is a variable number, usually obtained through \kbd{varn}).
5061:
5062: \subsecidx{poldisc}$(\var{pol},\{v\})$: discriminant of the polynomial
5063: \var{pol} in the main variable is $v$ is omitted, in $v$ otherwise. The
5064: algorithm used is the \idx{subresultant algorithm}.
5065:
5066: \syn{poldisc0}{x,v}. Also available is \teb{discsr}$(x)$, equivalent
5067: to \kbd{poldisc0(x,-1)}.
5068:
5069: \subsecidx{poldiscreduced}$(f)$: reduced discriminant vector of the
5070: (integral, monic) polynomial $f$. This is the vector of elementary divisors
5071: of $\Z[\alpha]/f'(\alpha)\Z[\alpha]$, where $\alpha$ is a root of the
5072: polynomial $f$. The components of the result are all positive, and their
5073: product is equal to the absolute value of the discriminant of~$f$.
5074:
5075: \syn{reduceddiscsmith}{x}.
5076:
5077: \subsecidx{polhensellift}$(x, y, p, e)$: given a prime $p$, an integral
5078: polynomial $x$ whose leading coefficient is a $p$-unit, a vector $y$ of
5079: integral polynomials that are pairwise relatively prime modulo $p$, and whose
5080: product is congruent to $x$ modulo $p$, lift the elements of $y$ to
5081: polynomials whose product is congruent to $x$ modulo $p^e$.
5082:
5083: \syn{polhensellift}{x,y,p,e} where $e$ must be a \kbd{long}.
5084:
5085: \subsecidx{polinterpolate}$(xa,\{ya\},\{v=x\},\{\&e\})$: given the data vectors
5086: $xa$ and $ya$ of the same length $n$ ($xa$ containing the $x$-coordinates,
5087: and $ya$ the corresponding $y$-coordinates), this function finds the
5088: \idx{interpolating polynomial} passing through these points and evaluates it
5089: at~$v$. If $ya$ is omitted, return the polynomial interpolating the
5090: $(i,xa[i])$. If present, $e$ will contain an error estimate on the returned
5091: value.
5092:
5093: \syn{polint}{xa,ya,v,\&e}, where $e$ will contain an error estimate on the
5094: returned value.
5095:
5096: \subsecidx{polisirreducible}$(\var{pol})$: \var{pol} being a polynomial
5097: (univariate in the present version \vers), returns 1 if \var{pol} is
5098: non-constant and irreducible, 0 otherwise. Irreducibility is checked over
5099: the smallest base field over which \var{pol} seems to be defined.
5100:
5101: \syn{gisirreducible}{\var{pol}}.
5102:
5103: \subsecidx{pollead}$(x,\{v\})$: leading coefficient of the polynomial or
5104: power series $x$. This is computed with respect to the main variable of $x$
5105: if $v$ is omitted, with respect to the variable $v$ otherwise.
5106:
5107: \syn{pollead}{x,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded as
5108: $-1$. Also available is \teb{leadingcoeff}$(x)$.
5109:
5110: \subsecidx{pollegendre}$(n,\{v=x\})$: creates the $n^{\text{th}}$
5111: \idx{Legendre polynomial}, in variable $v$.
5112:
5113: \syn{legendre}{n}, where $x$ is a \kbd{long}.
5114:
5115: \subsecidx{polrecip}$(\var{pol})$: reciprocal polynomial of \var{pol},
5116: i.e.~the coefficients are in reverse order. \var{pol} must be a polynomial.
5117:
5118: \syn{polrecip}{x}.
5119:
5120: \subsecidx{polresultant}$(x,y,\{v\},\{\fl=0\})$: resultant of the two
5121: polynomials $x$ and $y$ with exact entries, with respect to the main
5122: variables of $x$ and $y$ if $v$ is omitted, with respect to the variable $v$
5123: otherwise. The algorithm used is the \idx{subresultant algorithm} by default.
5124:
5125: If $\fl=1$, uses the determinant of Sylvester's matrix instead (here $x$ and
5126: $y$ may have non-exact coefficients).
5127:
5128: If $\fl=2$, uses Ducos's modified subresultant algorithm. It should be much
5129: faster than the default if the coefficient ring is complicated (e.g
5130: multivariate polynomials or huge coefficients), and slightly slower
5131: otherwise.
5132:
5133: \syn{polresultant0}{x,y,v,\fl}, where $v$ is a \kbd{long} and an omitted $v$
5134: is coded as $-1$. Also available are $\teb{subres}(x,y)$ ($\fl=0$) and
5135: $\teb{resultant2}(x,y)$ ($\fl=1$).
5136:
5137: \subsecidx{polroots}$(\var{pol},\{\fl=0\})$: complex roots of the polynomial
5138: \var{pol}, given as a column vector where each root is repeated according to
5139: its multiplicity. The precision is given as for transcendental functions: under
5140: GP it is kept in the variable \kbd{realprecision} and is transparent to the
5141: user, but it must be explicitly given as a second argument in library mode.
5142:
5143: The algorithm used is a modification of A.~Sch\"onhage\sidx{Sch\"onage}'s
5144: remarkable root-finding algorithm, due to and implemented by X.~Gourdon.
5145: Barring bugs, it is guaranteed to converge and to give the roots to the
5146: required accuracy.
5147:
5148: If $\fl=1$, use a variant of the Newton-Raphson method, which is \var{not}
5149: guaranteed to converge, but is rather fast. If you get the messages ``too
5150: many iterations in roots'' or ``INTERNAL ERROR: incorrect result in roots'',
5151: use the default function (i.e.~no flag or $\fl=0$). This used to be the
5152: default root-finding function in PARI until version 1.39.06.
5153:
5154: \syn{roots}{\var{pol},\var{prec}} or $\teb{rootsold}(\var{pol},\var{prec})$.
5155:
5156: \subsecidx{polrootsmod}$(\var{pol},p,\{\fl=0\})$: row vector of roots modulo
5157: $p$ of the polynomial \var{pol}. The particular non-prime value $p=4$ is
5158: accepted, mainly for $2$-adic computations. Multiple roots are \var{not}
5159: repeated.
5160:
5161: If $p<100$, you may try setting $\fl=1$, which uses a naive search. In this
5162: case, multiple roots \var{are} repeated with their order of multiplicity.
5163:
5164: \syn{rootmod}{\var{pol},p} ($\fl=0$) or
5165: $\teb{rootmod2}(\var{pol},p)$ ($\fl=1$).
5166:
5167: \subsecidx{polrootspadic}$(\var{pol},p,r)$: row vector of $p$-adic roots of the
5168: polynomial \var{pol} with $p$-adic precision equal to $r$. Multiple roots are
5169: \var{not} repeated. $p$ is assumed to be a prime.
5170:
5171: \syn{rootpadic}{\var{pol},p,r}, where $r$ is a \kbd{long}.
5172:
5173: \subsecidx{polsturm}$(\var{pol},\{a\},\{b\})$: number of real roots of the real
5174: polynomial \var{pol} in the interval $]a,b]$, using Sturm's algorithm. $a$
5175: (resp.~$b$) is taken to be $-\infty$ (resp.~$+\infty$) if omitted.
5176:
5177: \syn{sturmpart}{\var{pol},a,b}. Use \kbd{NULL} to omit an argument.
5178: \teb{sturm}\kbd{(\var{pol})} is equivalent to
5179: \key{sturmpart}\kbd{(\var{pol},NULL,NULL)}. The result is a \kbd{long}.
5180:
5181: \subsecidx{polsubcyclo}$(n,d,\{v=x\})$: gives a polynomial (in variable
5182: $v$) defining the sub-Abelian extension of degree $d$ of the cyclotomic
5183: field $\Q(\zeta_n)$, where $d\mid \phi(n)$. $(\Z/n\Z)^*$ has to be cyclic
5184: (i.e.~$n=2$, $4$, $p^k$ or $2p^k$ for an odd prime $p$). The function
5185: \tet{galoissubcyclo} covers the general case.
5186:
5187: \syn{subcyclo}{n,d,v}, where $v$ is a variable number.
5188:
5189: \subsecidx{polsylvestermatrix}$(x,y)$: forms the Sylvester matrix
5190: corresponding to the two polynomials $x$ and $y$, where the coefficients of
5191: the polynomials are put in the columns of the matrix (which is the natural
5192: direction for solving equations afterwards). The use of this matrix can be
5193: essential when dealing with polynomials with inexact entries, since
5194: polynomial Euclidean division doesn't make much sense in this case.
5195:
5196: \syn{sylvestermatrix}{x,y}.
5197:
5198: \subsecidx{polsym}$(x,n)$: creates the vector of the \idx{symmetric powers}
5199: of the roots of the polynomial $x$ up to power $n$, using Newton's
5200: formula.
5201:
5202: \syn{polsym}{x}.
5203:
5204: \subsecidx{poltchebi}$(n,\{v=x\})$: creates the $n^{\text{th}}$
5205: \idx{Chebyshev} polynomial, in variable $v$.
5206:
5207: \syn{tchebi}{n,v}, where $n$ and $v$ are \kbd{long}
5208: integers ($v$ is a variable number).
5209:
5210: \subsecidx{polzagier}$(n,m)$: creates Zagier's polynomial $P_{n,m}$ used in
5211: the functions \kbd{sumalt} and \kbd{sumpos} (with $\fl=1$). The exact
5212: definition can be found in a forthcoming paper. One must have $m\le n$.
5213:
5214: \syn{polzagreel}{n,m,\var{prec}} if the result is only wanted as a polynomial
5215: with real coefficients to the precision $\var{prec}$, or $\teb{polzag}(n,m)$
5216: if the result is wanted exactly, where $n$ and $m$ are \kbd{long}s.
5217:
5218: \subsecidx{serconvol}$(x,y)$: convolution (or \idx{Hadamard product}) of the
5219: two power series $x$ and $y$; in other words if $x=\sum a_k*X^k$ and $y=\sum
5220: b_k*X^k$ then $\kbd{serconvol}(x,y)=\sum a_k*b_k*X^k$.
5221:
5222: \syn{convol}{x,y}.
5223:
5224: \subsecidx{serlaplace}$(x)$: $x$ must be a power series with only
5225: non-negative exponents. If $x=\sum (a_k/k!)*X^k$ then the result is $\sum
5226: a_k*X^k$.
5227:
5228: \syn{laplace}{x}.
5229:
5230: \subsecidx{serreverse}$(x)$: reverse power series (i.e.~$x^{-1}$, not $1/x$)
5231: of $x$. $x$ must be a power series whose valuation is exactly equal to one.
5232:
5233: \syn{recip}{x}.
5234:
5235: \subsecidx{subst}$(x,y,z)$:
5236: replace the simple variable $y$ by the argument $z$ in the ``polynomial''
5237: expression $x$. Every type is allowed for $x$, but if it is not a genuine
5238: polynomial (or power series, or rational function), the substitution will be
5239: done as if the scalar components were polynomials of degree one. In
5240: particular, beware that:
5241:
5242: \bprog
5243: ? subst(1, x, [1,2; 3,4])
5244: %1 =
5245: [1 0]
5246:
5247: [0 1]
5248:
5249: ? subst(1, x, Mat([0,1]))
5250: *** forbidden substitution by a non square matrix
5251: @eprog
5252:
5253: If $x$ is a power series, $z$ must be either a polynomial, a power series, or
5254: a rational function. $y$ must be a simple variable name, or a monome of the
5255: form $t^k$ for some simple variable $t$. In the latter case, substitution
5256: may not always be possible since PARI doesn't know about algebraic functions.
5257:
5258: \syn{gsubst}{x,v,z}, where $v$ is the number of the variable $y$ for regular
5259: usage. Also available is \tet{gsubst0}$(x,y,z)$ where $y$ is a \kbd{GEN}
5260: monomial of the form $t^k$.
5261:
5262: \subsecidx{taylor}$(x,y)$: Taylor expansion around $0$ of $x$ with respect
5263: to\label{se:taylor}
5264: the simple variable $y$. $x$ can be of any reasonable type, for example a
5265: rational function. The number of terms of the expansion is transparent to the
5266: user under GP, but must be given as a second argument in library mode.
5267:
5268: \syn{tayl}{x,y,n}, where the \kbd{long} integer $n$ is the desired number of
5269: terms in the expansion.
5270:
5271: \subsecidx{thue}$(\var{tnf},a,\{\var{sol}\})$: solves the equation
5272: $P(x,y)=a$ in integers $x$ and $y$, where \var{tnf} was created with
5273: $\kbd{thueinit}(P)$. \var{sol}, if present, contains the solutions of
5274: $\text{Norm}(x)=a$ modulo units of positive norm in the number field
5275: defined by $P$ (as computed by \kbd{bnfisintnorm}). If \var{tnf} was
5276: computed without assuming \idx{GRH} ($\fl=1$ in \kbd{thueinit}), the
5277: result is unconditional. For instance, here's how to solve the Thue
5278: equation $x^{13} - 5y^{13} = - 4$:
5279:
5280: \bprog
5281: ? tnf = thueinit(x^13 - 5);
5282: ? thue(tnf, -4)
5283: %1 = [[1, 1]]
5284: @eprog
5285: Hence, assuming GRH, the only solution is $x = 1$, $y = 1$.
5286:
5287: \syn{thue}{\var{tnf},a,\var{sol}}, where an omitted \var{sol} is coded
5288: as \kbd{NULL}.
5289:
5290: \subsecidx{thueinit}$(P,\{\fl=0\})$: initializes the \var{tnf}
5291: corresponding to $P$. It is meant to be used in conjunction with \tet{thue}
5292: to solve Thue equations $P(x,y) = a$, where $a$ is an integer. If $\fl$ is
5293: non-zero, certify the result unconditionnaly, Otherwise, assume \idx{GRH},
5294: this being much faster of course.
5295:
5296: \syn{thueinit}{P,\fl,\var{prec}}.
5297:
5298: \section{Vectors, matrices, linear algebra and sets}
5299: \label{se:linear_algebra}
5300:
5301: Note that most linear algebra functions operating on subspaces defined by
5302: generating sets (such as \tet{mathnf}, \tet{qflll}, etc.) take matrices as
5303: arguments. As usual, the generating vectors are taken to be the
5304: \var{columns} of the given matrix.
5305:
5306: \subsecidx{algdep}$(x,k,\{\fl=0\})$:\sidx{algebraic dependence} $x$ being
5307: real, complex, or $p$-adic, finds a polynomial of degree at most $k$ with
5308: integer coefficients having $x$ as approximate root. Note that the polynomial
5309: which is obtained is not necessarily the ``correct'' one (it's not even
5310: guaranteed to be irreducible!). One can check the closeness either by a
5311: polynomial evaluation or substitution, or by computing the roots of the
5312: polynomial given by algdep.
5313:
5314: If $x$ is padic, $\fl$ is meaningless and the algorithm LLL-reduces the
5315: ``dual lattice'' corresponding to the powers of $x$.
5316:
5317: Otherwise, if $\fl$ is zero, the algorithm used is a variant of the \idx{LLL}
5318: algorithm due to Hastad, Lagarias and Schnorr (STACS 1986). If the precision
5319: is too low, the routine may enter an infinite loop.
5320:
5321: If $\fl$ is non-zero, use a standard LLL. $\fl$ then indicates a precision,
5322: which should be between $0.5$ and $1.0$ times the number of decimal digits
5323: to which $x$ was computed.
5324:
5325: \syn{algdep0}{x,k,\fl,\var{prec}}, where $k$ and $\fl$ are \kbd{long}s.
5326: Also available is $\teb{algdep}(x,k,\var{prec})$ ($\fl=0$).
5327:
5328: \subsecidx{charpoly}$(A,\{v=x\},\{\fl=0\})$: \idx{characteristic polynomial}
5329: of $A$ with respect to the variable $v$, i.e.~determinant of $v*I-A$ if $A$
5330: is a square matrix, determinant of the map ``multiplication by $A$'' if $A$
5331: is a scalar, in particular a polmod (e.g.~\kbd{charpoly(I,x)=x\pow2+1}).
5332: Note that in the latter case, the \idx{minimal polynomial} can be obtained
5333: as
5334: \bprog
5335: minpoly(A)=
5336: {
5337: local(y);
5338: y = charpoly(A);
5339: y / gcd(y,y')
5340: }
5341: @eprog
5342: \noindent The value of $\fl$ is only significant for matrices.
5343:
5344: If $\fl=0$, the method used is essentially the same as for computing the
5345: adjoint matrix, i.e.~computing the traces of the powers of $A$.
5346:
5347: If $\fl=1$, uses Lagrange interpolation which is almost always slower.
5348:
5349: If $\fl=2$, uses the Hessenberg form. This is faster than the default when
5350: the coefficients are integermod a prime or real numbers, but is usually
5351: slower in other base rings.
5352:
5353: \syn{charpoly0}{A,v,\fl}, where $v$ is the variable number. Also available
5354: are the functions $\teb{caract}(A,v)$ ($\fl=1$), $\teb{carhess}(A,v)$
5355: ($\fl=2$), and $\teb{caradj}(A,v,\var{pt})$ where, in this last case,
5356: \var{pt} is a \kbd{GEN*} which, if not equal to \kbd{NULL}, will receive
5357: the address of the adjoint matrix of $A$ (see \kbd{matadjoint}), so both
5358: can be obtained at once.
5359:
5360: \subsecidx{concat}$(x,\{y\})$: concatenation of $x$ and $y$. If $x$ or $y$ is
5361: not a vector or matrix, it is considered as a one-dimensional vector. All
5362: types are allowed for $x$ and $y$, but the sizes must be compatible. Note
5363: that matrices are concatenated horizontally, i.e.~the number of rows stays
5364: the same. Using transpositions, it is easy to concatenate them vertically.
5365:
5366: To concatenate vectors sideways (i.e.~to obtain a two-row or two-column
5367: matrix), first transform the vector into a one-row or one-column matrix using
5368: the function \tet{Mat}. Concatenating a row vector to a matrix having the
5369: same number of columns will add the row to the matrix (top row if the vector
5370: is $x$, i.e.~comes first, and bottom row otherwise).
5371:
5372: The empty matrix \kbd{[;]} is considered to have a number of rows compatible
5373: with any operation, in particular concatenation. (Note that this is
5374: definitely \var{not} the case for empty vectors \kbd{[~]} or \kbd{[~]\til}.)
5375:
5376: If $y$ is omitted, $x$ has to be a row vector or a list, in which case its
5377: elements are concatenated, from left to right, using the above rules.
5378:
5379: \bprog
5380: ? concat([1,2], [3,4])
5381: %1 = [1, 2, 3, 4]
5382: ? a = [[1,2]~, [3,4]~]; concat(a)
5383: %2 = [1, 2, 3, 4]~
5384: ? a[1] = Mat(a[1]); concat(a)
5385: %3 =
5386: [1 3]
5387:
5388: [2 4]
5389:
5390: ? concat([1,2; 3,4], [5,6]~)
5391: %4 =
5392: [1 2 5]
5393:
5394: [3 4 6]
5395: ? concat([%, [7,8]~, [1,2,3,4]])
5396: %5 =
5397: [1 2 5 7]
5398:
5399: [3 4 6 8]
5400:
5401: [1 2 3 4]
5402: @eprog
5403:
5404: \syn{concat}{x,y}.
5405:
5406: \subsecidx{lindep}$(x,\{\fl=0\})$:\sidx{linear dependence}$x$ being a
5407: vector with real or complex coefficients, finds a small integral linear
5408: combination among these coefficients.
5409:
5410: If $\fl=0$, uses a variant of the \idx{LLL} algorithm due to Hastad, Lagarias
5411: and Schnorr (STACS 1986).
5412:
5413: If $\fl>0$, uses the LLL algorithm. $\fl$ is a parameter which should be
5414: between one half the number of decimal digits of precision and that number
5415: (see \kbd{algdep}).
5416:
5417: If $\fl<0$, returns as soon as one relation has been found.
5418:
5419: \syn{lindep0}{x,\fl,\var{prec}}. Also available is
5420: $\teb{lindep}(x,\var{prec})$ ($\fl=0$).
5421:
5422: \subsecidx{listcreate}$(n)$: creates an empty list of maximal length $n$.
5423:
5424: This function is useless in library mode.
5425:
5426: \subsecidx{listinsert}$(\var{list},x,n)$: inserts the object $x$ at
5427: position $n$ in \var{list} (which must be of type \typ{LIST}). All the
5428: remaining elements of \var{list} (from position $n+1$ onwards) are shifted
5429: to the right. This and \kbd{listput} are the only commands which enable
5430: you to increase a list's effective length (as long as it remains under
5431: the maximal length specified at the time of the \kbd{listcreate}).
5432:
5433: This function is useless in library mode.
5434:
5435: \subsecidx{listkill}$(\var{list})$: kill \var{list}. This deletes all
5436: elements from \var{list} and sets its effective length to $0$. The maximal
5437: length is not affected.
5438:
5439: This function is useless in library mode.
5440:
5441: \subsecidx{listput}$(\var{list},x,\{n\})$: sets the $n$-th element of the list
5442: \var{list} (which must be of type \typ{LIST}) equal to $x$. If $n$ is omitted,
5443: or greater than the list current effective length, just appends $x$. This and
5444: \kbd{listinsert} are the only commands which enable you to increase a list's
5445: effective length (as long as it remains under the maximal length specified at
5446: the time of the \kbd{listcreate}).
5447:
5448: If you want to put an element into an occupied cell, i.e.~if you don't want to
5449: change the effective length, you can consider the list as a vector and use
5450: the usual \kbd{list[n] = x} construct.
5451:
5452: This function is useless in library mode.
5453:
5454: \subsecidx{listsort}$(\var{list},\{\fl=0\})$: sorts \var{list} (which must
5455: be of type \typ{LIST}) in place. If $\fl$ is non-zero, suppresses all repeated
5456: coefficients. This is much faster than the \kbd{vecsort} command since no
5457: copy has to be made.
5458:
5459: This function is useless in library mode.
5460:
5461: \subsecidx{matadjoint}$(x)$: \idx{adjoint matrix} of $x$, i.e.~the matrix $y$
5462: of cofactors of $x$, satisfying $x*y=\det(x)*\text{Id}$. $x$ must be a
5463: (non-necessarily invertible) square matrix.
5464:
5465: \syn{adj}{x}.
5466:
5467: \subsecidx{matcompanion}$(x)$: the left companion matrix to the polynomial $x$.
5468:
5469: \syn{assmat}{x}.
5470:
5471: \subsecidx{matdet}$(x,\{\fl=0\})$: determinant of $x$. $x$ must be a
5472: square matrix.
5473:
5474: If $\fl=0$, uses Gauss-Bareiss.
5475:
5476: If $\fl=1$, uses classical Gaussian elimination, which is better when the
5477: entries of the matrix are reals or integers for example, but usually much
5478: worse for more complicated entries like multivariate polynomials.
5479:
5480: \syn{det}{x} ($\fl=0$) and $\teb{det2}(x)$
5481: ($\fl=1$).
5482:
5483: \subsecidx{matdetint}$(x)$: $x$ being an $m\times n$ matrix with integer
5484: coefficients, this function computes a \var{multiple} of the determinant of the
5485: lattice generated by the columns of $x$ if it is of rank $m$, and returns
5486: zero otherwise. This function can be useful in conjunction with the function
5487: \kbd{mathnfmod} which needs to know such a multiple. To obtain the
5488: exact determinant (assuming the rank is maximal), you can compute
5489: \kbd{matdet(mathnfmod(x, matdetint(x)))}.
5490:
5491: Note that as soon as one of the dimensions gets large ($m$ or $n$ is larger
5492: than 20, say), it will often be much faster to use \kbd{mathnf(x, 1)} or
5493: \kbd{mathnf(x, 4)} directly.
5494:
5495: \syn{detint}{x}.
5496:
5497: \subsecidx{matdiagonal}$(x)$: $x$ being a vector, creates the diagonal matrix
5498: whose diagonal entries are those of $x$.
5499:
5500: \syn{diagonal}{x}.
5501:
5502: \subsecidx{mateigen}$(x)$: gives the eigenvectors of $x$ as columns of a
5503: matrix.
5504:
5505: \syn{eigen}{x}.
5506:
5507: \subsecidx{mathess}$(x)$: Hessenberg form of the square matrix $x$.
5508:
5509: \syn{hess}{x}.
5510:
5511: \subsecidx{mathilbert}$(x)$: $x$ being a \kbd{long}, creates the \idx{Hilbert
5512: matrix} of order $x$, i.e.~the matrix whose coefficient ($i$,$j$) is $1/
5513: (i+j-1)$.
5514:
5515: \syn{mathilbert}{x}.
5516:
5517: \subsecidx{mathnf}$(x,\{\fl=0\})$: if $x$ is a (not necessarily square)
5518: matrix, finds the \var{upper triangular} \idx{Hermite normal form} of $x$. If
5519: the rank of $x$ is equal to its number of rows, the result is a square
5520: matrix. In general, the columns of the result form a basis of the lattice
5521: spanned by the columns of $x$.
5522:
5523: If $\fl=0$, uses the naive algorithm. This should never be used if the
5524: dimension is at all large (larger than 10, say). It is recommanded to use
5525: either \kbd{mathnfmod(x, matdetint(x))} (when $x$ has maximal rank) or
5526: \kbd{mathnf(x, 1)}. Note that the latter is in general faster than
5527: \kbd{mathnfmod}, and also provides a base change matrix.
5528:
5529: If $\fl=1$, uses Batut's algorithm, which is much faster than the default.
5530: Outputs a two-component row vector $[H,U]$, where $H$ is the \var{upper
5531: triangular} Hermite normal form of $x$ defined as above, and $U$ is the
5532: unimodular transformation matrix such that $xU=[0|H]$. $U$ has in general
5533: huge coefficients, in particular when the kernel is large.
5534:
5535: If $\fl=3$, uses Batut's algorithm, but outputs $[H,U,P]$, such that $H$ and
5536: $U$ are as before and $P$ is a permutation of the rows such that $P$ applied
5537: to $xU$ gives $H$. The matrix $U$ is smaller than with $\fl=1$, but may still
5538: be large.
5539:
5540: If $\fl=4$, as in case 1 above, but uses a heuristic variant of \idx{LLL}
5541: reduction along the way. The matrix $U$ is in general close to optimal (in
5542: terms of smallest $L_2$ norm), but the reduction is slower than in case $1$.
5543:
5544: \syn{mathnf0}{x,\fl}. Also available are $\teb{hnf}(x)$ ($\fl=0$) and
5545: $\teb{hnfall}(x)$ ($\fl=1$). To reduce \var{huge} (say $400 \times 400$ and
5546: more) relation matrices (sparse with small entries), you can use the pair
5547: \kbd{hnfspec} / \kbd{hnfadd}. Since this is rather technical and the
5548: calling interface may change, they are not documented yet. Look at the code
5549: in \kbd{basemath/alglin1.c}.
5550:
5551: \subsecidx{mathnfmod}$(x,d)$: if $x$ is a (not necessarily square) matrix of
5552: maximal rank with integer entries, and $d$ is a multiple of the (non-zero)
5553: determinant of the lattice spanned by the columns of $x$, finds the
5554: \var{upper triangular} \idx{Hermite normal form} of $x$.
5555:
5556: If the rank of $x$ is equal to its number of rows, the result is a square
5557: matrix. In general, the columns of the result form a basis of the lattice
5558: spanned by the columns of $x$. This is much faster than \kbd{mathnf} when $d$
5559: is known.
5560:
5561: \syn{hnfmod}{x,d}.
5562:
5563: \subsecidx{mathnfmodid}$(x,d)$: outputs the (upper triangular)
5564: \idx{Hermite normal form} of $x$ concatenated with $d$ times
5565: the identity matrix.
5566:
5567: \syn{hnfmodid}{x,d}.
5568:
5569: \subsecidx{matid}$(n)$: creates the $n\times n$ identity matrix.
5570:
5571: \syn{idmat}{n} where $n$ is a \kbd{long}.
5572:
5573: Related functions are $\teb{gscalmat}(x,n)$, which creates $x$ times the
5574: identity matrix ($x$ being a \kbd{GEN} and $n$ a \kbd{long}), and
5575: $\teb{gscalsmat}(x,n)$ which is the same when $x$ is a \kbd{long}.
5576:
5577: \subsecidx{matimage}$(x,\{\fl=0\})$: gives a basis for the image of the
5578: matrix $x$ as columns of a matrix. A priori the matrix can have entries of
5579: any type. If $\fl=0$, use standard Gauss pivot. If $\fl=1$, use
5580: \kbd{matsupplement}.
5581:
5582: \syn{matimage0}{x,\fl}. Also available is $\teb{image}(x)$ ($\fl=0$).
5583:
5584: \subsecidx{matimagecompl}$(x)$: gives the vector of the column indices which
5585: are not extracted by the function \kbd{matimage}. Hence the number of
5586: components of \kbd{matimagecompl(x)} plus the number of columns of
5587: \kbd{matimage(x)} is equal to the number of columns of the matrix $x$.
5588:
5589: \syn{imagecompl}{x}.
5590:
5591: \subsecidx{matindexrank}$(x)$: $x$ being a matrix of rank $r$, gives two
5592: vectors $y$ and $z$ of length $r$ giving a list of rows and columns
5593: respectively (starting from 1) such that the extracted matrix obtained from
5594: these two vectors using $\tet{vecextract}(x,y,z)$ is invertible.
5595:
5596: \syn{indexrank}{x}.
5597:
5598: \subsecidx{matintersect}$(x,y)$: $x$ and $y$ being two matrices with the same
5599: number of rows each of whose columns are independent, finds a basis of the
5600: $\Q$-vector space equal to the intersection of the spaces spanned by the
5601: columns of $x$ and $y$ respectively. See also the function
5602: \tet{idealintersect}, which does the same for free $\Z$-modules.
5603:
5604: \syn{intersect}{x,y}.
5605:
5606: \subsecidx{matinverseimage}$(x,y)$: gives a column vector belonging to the
5607: inverse image of the column vector $y$ by the matrix $x$ if one exists, the
5608: empty vector otherwise. To get the complete inverse image, it suffices to add
5609: to the result any element of the kernel of $x$ obtained for example by
5610: \kbd{matker}.
5611:
5612: \syn{inverseimage}{x,y}.
5613:
5614: \subsecidx{matisdiagonal}$(x)$: returns true (1) if $x$ is a diagonal matrix,
5615: false (0) if not.
5616:
5617: \syn{isdiagonal}{x}, and this returns a \kbd{long}
5618: integer.
5619:
5620: \subsecidx{matker}$(x,\{\fl=0\})$: gives a basis for the kernel of the
5621: matrix $x$ as columns of a matrix. A priori the matrix can have entries of
5622: any type.
5623:
5624: If $x$ is known to have integral entries, set $\fl=1$.
5625:
5626: \noindent Note: The library function $\tet{ker_mod_p}(x, p)$, where $x$ has
5627: integer entries and $p$ is prime, which is equivalent to but many orders of
5628: magnitude faster than \kbd{matker(x*Mod(1,p))} and needs much less stack
5629: space. To use it under GP, type \kbd{install(ker\_mod\_p, GG)} first.
5630:
5631: \syn{matker0}{x,\fl}. Also available are $\teb{ker}(x)$ ($\fl=0$),
5632: $\teb{keri}(x)$ ($\fl=1$) and $\kbd{ker\_mod\_p}(x,p)$.
5633:
5634: \subsecidx{matkerint}$(x,\{\fl=0\})$: gives an \idx{LLL}-reduced $\Z$-basis
5635: for the lattice equal to the kernel of the matrix $x$ as columns of the
5636: matrix $x$ with integer entries (rational entries are not permitted).
5637:
5638: If $\fl=0$, uses a modified integer LLL algorithm.
5639:
5640: If $\fl=1$, uses $\kbd{matrixqz}(x,-2)$. If LLL reduction of the final result
5641: is not desired, you can save time using \kbd{matrixqz(matker(x),-2)} instead.
5642:
5643: If $\fl=2$, uses another modified LLL. In the present version \vers, only
5644: independent rows are allowed in this case.
5645:
5646: \syn{matkerint0}{x,\fl}. Also available is
5647: $\teb{kerint}(x)$ ($\fl=0$).
5648:
5649: \subsecidx{matmuldiagonal}$(x,d)$: product of the matrix $x$ by the diagonal
5650: matrix whose diagonal entries are those of the vector $d$. Equivalent to,
5651: but much faster than $x*\kbd{matdiagonal}(d)$.
5652:
5653: \syn{matmuldiagonal}{x,d}.
5654:
5655: \subsecidx{matmultodiagonal}$(x,y)$: product of the matrices $x$ and $y$
5656: knowing that the result is a diagonal matrix. Much faster than $x*y$ in
5657: that case.
5658:
5659: \syn{matmultodiagonal}{x,y}.
5660:
5661: \subsecidx{matpascal}$(x,\{q\})$: creates as a matrix the lower triangular
5662: \idx{Pascal triangle} of order $x+1$ (i.e.~with binomial coefficients
5663: up to $x$). If $q$ is given, compute the $q$-Pascal triangle (i.e.~using
5664: $q$-binomial coefficients).
5665:
5666: \syn{matqpascal}{x,q}, where $x$ is a \kbd{long} and $q=\kbd{NULL}$ is used
5667: to omit $q$. Also available is $\teb{matpascal}(x)$.
5668:
5669: \subsecidx{matrank}$(x)$: rank of the matrix $x$.
5670:
5671: \syn{rank}{x}, and the result is a \kbd{long}.
5672:
5673: \subsecidx{matrix}$(m,n,\{X\},\{Y\},\{\var{expr}=0\})$: creation of the
5674: $m\times n$ matrix whose coefficients are given by the expression
5675: \var{expr}. There are two formal parameters in \var{expr}, the first one
5676: ($X$) corresponding to the rows, the second ($Y$) to the columns, and $X$
5677: goes from 1 to $m$, $Y$ goes from 1 to $n$. If one of the last 3 parameters
5678: is omitted, fill the matrix with zeroes.
5679:
5680: \synt{matrice}{GEN nlig,GEN ncol,entree *e1,entree *e2,char *expr}.
5681:
5682: \subsecidx{matrixqz}$(x,p)$: $x$ being an $m\times n$ matrix with $m\ge n$
5683: with rational or integer entries, this function has varying behaviour
5684: depending on the sign of $p$:
5685:
5686: If $p\geq 0$, $x$ is assumed to be of maximal rank. This function returns a
5687: matrix having only integral entries, having the same image as $x$, such that
5688: the GCD of all its $n\times n$ subdeterminants is equal to 1 when $p$ is
5689: equal to 0, or not divisible by $p$ otherwise. Here $p$ must be a prime
5690: number (when it is non-zero). However, if the function is used when $p$ has
5691: no small prime factors, it will either work or give the message ``impossible
5692: inverse modulo'' and a non-trivial divisor of $p$.
5693:
5694: If $p=-1$, this function returns a matrix whose columns form a basis of the
5695: lattice equal to $\Z^n$ intersected with the lattice generated by the
5696: columns of $x$.
5697:
5698: If $p=-2$, returns a matrix whose columns form a basis of the lattice equal
5699: to $\Z^n$ intersected with the $\Q$-vector space generated by the
5700: columns of $x$.
5701:
5702: \syn{matrixqz0}{x,p}.
5703:
5704: \subsecidx{matsize}$(x)$: $x$ being a vector or matrix, returns a row vector
5705: with two components, the first being the number of rows (1 for a row vector),
5706: the second the number of columns (1 for a column vector).
5707:
5708: \syn{matsize}{x}.
5709:
5710: \subsecidx{matsnf}$(X,\{\fl=0\})$: if $X$ is a (singular or non-singular)
5711: square matrix outputs the vector of elementary divisors of $X$ (i.e.~the
5712: diagonal of the \idx{Smith normal form} of $X$).
5713:
5714: The binary digits of \fl\ mean:
5715:
5716: 1 (complete output): if set, outputs $[U,V,D]$, where $U$ and $V$ are two
5717: unimodular matrices such that $UXV$ is the diagonal matrix $D$. Otherwise
5718: output only the diagonal of $D$.
5719:
5720: 2 (generic input): if set, allows polynomial entries. Otherwise, assume
5721: that $X$ has integer coefficients.
5722:
5723: 4 (cleanup): if set, cleans up the output. This means that elementary
5724: divisors equal to $1$ will be deleted, i.e.~outputs a shortened vector $D'$
5725: instead of $D$. If complete output was required, returns $[U',V',D']$ so
5726: that $U'XV' = D'$ holds. If this flag is set, $X$ is allowed to be of the
5727: form $D$ or $[U,V,D]$ as would normally be output with the cleanup flag
5728: unset.
5729:
5730: \syn{matsnf0}{X,\fl}. Also available is $\teb{smith}(X)$ ($\fl=0$).
5731:
5732: \subsecidx{matsolve}$(x,y)$: $x$ being an invertible matrix and $y$ a column
5733: vector, finds the solution $u$ of $x*u=y$, using Gaussian elimination. This
5734: has the same effect as, but is a bit faster, than $x^{-1}*y$.
5735:
5736: \syn{gauss}{x,y}.
5737:
5738: \subsecidx{matsolvemod}$(m,d,y,\{\fl=0\})$: $m$ being any integral matrix,
5739: $d$ a vector of positive integer moduli, and $y$ an integral
5740: column vector, gives a small integer solution to the system of congruences
5741: $\sum_i m_{i,j}x_j\equiv y_i\pmod{d_i}$ if one exists, otherwise returns
5742: zero. Shorthand notation: $y$ (resp.~$d$) can be given as a single integer,
5743: in which case all the $y_i$ (resp.~$d_i$) above are taken to be equal to $y$
5744: (resp.~$d$).
5745:
5746: If $\fl=1$, all solutions are returned in the form of a two-component row
5747: vector $[x,u]$, where $x$ is a small integer solution to the system of
5748: congruences and $u$ is a matrix whose columns give a basis of the homogeneous
5749: system (so that all solutions can be obtained by adding $x$ to any linear
5750: combination of columns of $u$). If no solution exists, returns zero.
5751:
5752: \syn{matsolvemod0}{m,d,y,\fl}. Also available
5753: are $\teb{gaussmodulo}(m,d,y)$ ($\fl=0$)
5754: and $\teb{gaussmodulo2}(m,d,y)$ ($\fl=1$).
5755:
5756: \subsecidx{matsupplement}$(x)$: assuming that the columns of the matrix $x$
5757: are linearly independent (if they are not, an error message is issued), finds
5758: a square invertible matrix whose first columns are the columns of $x$,
5759: i.e.~supplement the columns of $x$ to a basis of the whole space.
5760:
5761: \syn{suppl}{x}.
5762:
5763: \subsecidx{mattranspose}$(x)$ or $x\til$: transpose of $x$.
5764: This has an effect only on vectors and matrices.
5765:
5766: \syn{gtrans}{x}.
5767:
5768: \subsecidx{qfgaussred}$(q)$: \idx{decomposition into squares} of the
5769: quadratic form represented by the symmetric matrix $q$. The result is a
5770: matrix whose diagonal entries are the coefficients of the squares, and the
5771: non-diagonal entries represent the bilinear forms. More precisely, if
5772: $(a_{ij})$ denotes the output, one has
5773: $$ q(x) = \sum_i a_{ii} (x_i + \sum_{j>i} a_{ij} x_j)^2 $$
5774:
5775: \syn{sqred}{x}.
5776:
5777: \subsecidx{qfjacobi}$(x)$: $x$ being a real symmetric matrix, this gives a
5778: vector having two components: the first one is the vector of eigenvalues of
5779: $x$, the second is the corresponding orthogonal matrix of eigenvectors of
5780: $x$. The method used is Jacobi's method for symmetric matrices.
5781:
5782: \syn{jacobi}{x}.
5783:
5784: \subsecidx{qflll}$(x,\{\fl=0\})$: \idx{LLL} algorithm applied to the
5785: \var{columns} of the (not necessarily square) matrix $x$. The columns of $x$
5786: must however be linearly independent, unless specified otherwise below. The
5787: result is a transformation matrix $T$ such that $x\cdot T$ is an LLL-reduced
5788: basis of the lattice generated by the column vectors of $x$.
5789:
5790: If $\fl=0$ (default), the computations are done with real numbers (i.e.~not
5791: with rational numbers) hence are fast but as presently programmed (version
5792: \vers) are numerically unstable.
5793:
5794: If $\fl=1$, it is assumed that the corresponding Gram matrix is integral.
5795: The computation is done entirely with integers and the algorithm is both
5796: accurate and quite fast. In this case, $x$ needs not be of maximal rank, but
5797: if it is not, $T$ will not be square.
5798:
5799: If $\fl=2$, similar to case 1, except $x$ should be an integer matrix whose
5800: columns are linearly independent. The lattice generated by the columns of
5801: $x$ is first partially reduced before applying the LLL algorithm. [A basis
5802: is said to be \var{partially reduced} if $|v_i \pm v_j| \geq |v_i|$ for any
5803: two distinct basis vectors $v_i, \, v_j$.]
5804:
5805: This can be significantly faster than $\fl=1$ when one row is huge compared
5806: to the other rows.
5807:
5808: If $\fl=3$, all computations are done in rational numbers. This does not
5809: incur numerical instability, but is extremely slow. This function is
5810: essentially superseded by case 1, so will soon disappear.
5811:
5812: If $\fl=4$, $x$ is assumed to have integral entries, but needs not be of
5813: maximal rank. The result is a two-component vector of matrices~: the
5814: columns of the first matrix represent a basis of the integer kernel of $x$
5815: (not necessarily LLL-reduced) and the second matrix is the transformation
5816: matrix $T$ such that $x\cdot T$ is an LLL-reduced $\Z$-basis of the image
5817: of the matrix $x$.
5818:
5819: If $\fl=5$, case as case $4$, but $x$ may have polynomial coefficients.
5820:
5821: If $\fl=7$, uses an older version of case $0$ above.
5822:
5823: If $\fl=8$, same as case $0$, where $x$ may have polynomial coefficients.
5824:
5825: If $\fl=9$, variation on case $1$, using content.
5826:
5827: \syn{qflll0}{x,\fl,\var{prec}}. Also available are
5828: $\teb{lll}(x,\var{prec})$ ($\fl=0$), $\teb{lllint}(x)$ ($\fl=1$), and
5829: $\teb{lllkerim}(x)$ ($\fl=4$).
5830:
5831: \subsecidx{qflllgram}$(x,\{\fl=0\})$: same as \kbd{qflll} except that the
5832: matrix $x$ which must now be a square symmetric real matrix is the Gram
5833: matrix of the lattice vectors, and not the coordinates of the vectors
5834: themselves. The result is again the transformation matrix $T$ which gives (as
5835: columns) the coefficients with respect to the initial basis vectors. The
5836: flags have more or less the same meaning, but some are missing. In brief:
5837:
5838: $\fl=0$: numerically unstable in the present version \vers.
5839:
5840: $\fl=1$: $x$ has integer entries, the computations are all done in integers.
5841:
5842: $\fl=4$: $x$ has integer entries, gives the kernel and reduced image.
5843:
5844: $\fl=5$: same as $4$ for generic $x$.
5845:
5846: $\fl=7$: an older version of case $0$.
5847:
5848: \syn{qflllgram0}{x,\fl,\var{prec}}. Also available are
5849: $\teb{lllgram}(x,\var{prec})$ ($\fl=0$), $\teb{lllgramint}(x)$ ($\fl=1$), and
5850: $\teb{lllgramkerim}(x)$ ($\fl=4$).
5851:
5852: \subsecidx{qfminim}$(x,b,m,\{\fl=0\})$: $x$ being a square and symmetric
5853: matrix representing a positive definite quadratic form, this function
5854: deals with the minimal vectors of $x$, depending on $\fl$.
5855:
5856: If $\fl=0$ (default), seeks vectors of square norm less than or equal to $b$
5857: (for the norm defined by $x$), and at most $2m$ of these vectors. The result
5858: is a three-component vector, the first component being the number of vectors,
5859: the second being the maximum norm found, and the last vector is a matrix
5860: whose columns are the vectors found, only one being given for each
5861: pair $\pm v$ (at most $m$ such pairs).
5862:
5863: If $\fl=1$, ignores $m$ and returns the first vector whose norm is less than
5864: $b$.
5865:
5866: In both these cases, $x$ {\it is assumed to have integral entries}, and the
5867: function searches for the minimal non-zero vectors whenever $b=0$.
5868:
5869: If $\fl=2$, $x$ can have non integral real entries, but $b=0$ is now
5870: meaningless (uses Fincke-Pohst algorithm).
5871:
5872: \syn{qfminim0}{x,b,m,\fl,\var{prec}}, also available are \funs{minim}{x,b,m}
5873: ($\fl=0$), \funs{minim2}{x,b,m} ($\fl=1$), and finally
5874: \funs{fincke_pohst}{x,b,m,\var{prec}} ($\fl=2$).
5875:
5876: \subsecidx{qfperfection}$(x)$: $x$ being a square and symmetric matrix with
5877: integer entries representing a positive definite quadratic form, outputs the
5878: perfection rank of the form. That is, gives the rank of the family of the $s$
5879: symmetric matrices $v_iv_i^t$, where $s$ is half the number of minimal
5880: vectors and the $v_i$ ($1\le i\le s$) are the minimal vectors.
5881:
5882: As a side note to old-timers, this used to fail bluntly when $x$ had more
5883: than $5000$ minimal vectors. Beware that the computations can now be very
5884: lengthy when $x$ has many minimal vectors.
5885:
5886: \syn{perf}{x}.
5887:
5888: \subsecidx{qfsign}$(x)$: signature of the quadratic form represented by the
5889: symmetric matrix $x$. The result is a two-component vector.
5890:
5891: \syn{signat}{x}.
5892:
5893: \subsecidx{setintersect}$(x,y)$: intersection of the two sets $x$ and $y$.
5894:
5895: \syn{setintersect}{x,y}.
5896:
5897: \subsecidx{setisset}$(x)$: returns true (1) if $x$ is a set, false (0) if
5898: not. In PARI, a set is simply a row vector whose entries are strictly
5899: increasing. To convert any vector (and other objects) into a set, use the
5900: function \kbd{Set}.
5901:
5902: \syn{setisset}{x}, and this returns a \kbd{long}.
5903:
5904: \subsecidx{setminus}$(x,y)$: difference of the two sets $x$ and $y$,
5905: i.e.~set of elements of $x$ which do not belong to $y$.
5906:
5907: \syn{setminus}{x,y}.
5908:
5909: \subsecidx{setsearch}$(x,y,\{\fl=0\})$: searches if $y$ belongs to the set
5910: $x$. If it does and $\fl$ is zero or omitted, returns the index $j$ such that
5911: $x[j]=y$, otherwise returns 0. If $\fl$ is non-zero returns the index $j$
5912: where $y$ should be inserted, and $0$ if it already belongs to $x$ (this is
5913: meant to be used in conjunction with \kbd{listinsert}).
5914:
5915: This function works also if $x$ is a \var{sorted} list (see \kbd{listsort}).
5916:
5917: \syn{setsearch}{x,y,\fl} which returns a \kbd{long}
5918: integer.
5919:
5920: \subsecidx{setunion}$(x,y)$: union of the two sets $x$ and $y$.
5921:
5922: \syn{setunion}{x,y}.
5923:
5924: \subsecidx{trace}$(x)$: this applies to quite general $x$. If $x$ is not a
5925: matrix, it is equal to the sum of $x$ and its conjugate, except for polmods
5926: where it is the trace as an algebraic number.
5927:
5928: For $x$ a square matrix, it is the ordinary trace. If $x$ is a
5929: non-square matrix (but not a vector), an error occurs.
5930:
5931: \syn{gtrace}{x}.
5932:
5933: \subsecidx{vecextract}$(x,y,\{z\})$: extraction of components of the
5934: vector or matrix $x$ according to $y$. In case $x$ is a matrix, its
5935: components are as usual the \var{columns} of $x$. The parameter $y$ is a
5936: component specifier, which is either an integer, a string describing a
5937: range, or a vector.
5938:
5939: If $y$ is an integer, it is considered as a mask: the binary bits of $y$ are
5940: read from right to left, but correspond to taking the components from left to
5941: right. For example, if $y=13=(1101)_2$ then the components 1,3 and 4 are
5942: extracted.
5943:
5944: If $y$ is a vector, which must have integer entries, these entries correspond
5945: to the component numbers to be extracted, in the order specified.
5946:
5947: If $y$ is a string, it can be
5948:
5949: $\bullet$ a single (non-zero) index giving a component number (a negative
5950: index means we start counting from the end).
5951:
5952: $\bullet$ a range of the form \kbd{"$a$..$b$"}, where $a$ and $b$ are
5953: indexes as above. Any of $a$ and $b$ can be omitted; in this case, we take
5954: as default values $a = 1$ and $b = -1$, i.e.~ the first and last components
5955: respectively. We then extract all components in the interval $[a,b]$, in
5956: reverse order if $b < a$.
5957:
5958: In addition, if the first character in the string is \kbd{\pow}, the
5959: complement of the given set of indices is taken.
5960:
5961: If $z$ is not omitted, $x$ must be a matrix. $y$ is then the \var{line}
5962: specifier, and $z$ the \var{column} specifier, where the component specifier
5963: is as explained above.
5964:
5965: \bprog
5966: ? v = [a, b, c, d, e];
5967: ? vecextract(v, 5) \\@com mask
5968: %1 = [a, c]
5969: ? vecextract(v, [4, 2, 1]) \\@com component list
5970: %2 = [d, b, a]
5971: ? vecextract(v, "2..4") \\@com interval
5972: %3 = [b, c, d]
5973: ? vecextract(v, "-1..-3") \\@com interval + reverse order
5974: %4 = [e, d, c]
5975: ? vecextract([1,2,3], "^2") \\@com complement
5976: %5 = [1, 3]
5977: ? vecextract(matid(3), "2..", "..")
5978: %6 =
5979: [0 1 0]
5980:
5981: [0 0 1]
5982: @eprog
5983:
5984: \syn{extract}{x,y} or $\teb{matextract}(x,y,z)$.
5985:
5986: \subsecidx{vecsort}$(x,\{k\},\{\fl=0\})$: sorts the vector $x$ in ascending
5987: order, using the heapsort method. $x$ must be a vector, and its components
5988: integers, reals, or fractions.
5989:
5990: If $k$ is present and is an integer, sorts according to the value of the
5991: $k$-th subcomponents of the components of~$x$. $k$ can also be a vector,
5992: in which case the
5993: sorting is done lexicographically according to the components listed in the
5994: vector $k$. For example, if $k=[2,1,3]$, sorting will be done with respect
5995: to the second component, and when these are equal, with respect to the
5996: first, and when these are equal, with respect to the third.
5997:
5998: \noindent The binary digits of \fl\ mean:
5999:
6000: $\bullet$ 1: indirect sorting of the vector $x$, i.e.~if $x$ is an
6001: $n$-component vector, returns a permutation of $[1,2,\dots,n]$ which
6002: applied to the components of $x$ sorts $x$ in increasing order.
6003: For example, \kbd{vecextract(x, vecsort(x,,1))} is equivalent to
6004: \kbd{vecsort(x)}.
6005:
6006: $\bullet$ 2: sorts $x$ by ascending lexicographic order (as per the
6007: \kbd{lex} comparison function).
6008:
6009: $\bullet$ 4: use decreasing instead of ascending order.
6010:
6011: \syn{vecsort0}{x,k,flag}. To omit $k$, use \kbd{NULL} instead. You can also
6012: use the simpler functions
6013:
6014: $\teb{sort}(x)$ (= $\kbd{vecsort0}(x,\text{NULL},0)$).
6015:
6016: $\teb{indexsort}(x)$ (= $\kbd{vecsort0}(x,\text{NULL},1)$).
6017:
6018: $\teb{lexsort}(x)$ (= $\kbd{vecsort0}(x,\text{NULL},2)$).
6019:
6020: Also available are \teb{sindexsort} and \teb{sindexlexsort} which return a
6021: vector of C-long integers (private type \typ{VECSMALL}) $v$, where
6022: $v[1]\dots v[n]$ contain the indices. Note that the resulting $v$ is
6023: \var{not} a generic PARI object, but is in general easier to use in C
6024: programs!
6025:
6026: \subsecidx{vector}$(n,\{X\},\{\var{expr}=0\})$: creates a row vector (type
6027: \typ{VEC}) with $n$ components whose components are the expression
6028: \var{expr} evaluated at the integer points between 1 and $n$. If one of the
6029: last two arguments is omitted, fill the vector with zeroes.
6030:
6031: \synt{vecteur}{GEN nmax, entree *ep, char *expr}.
6032:
6033: \subsecidx{vectorv}$(n,X,\var{expr})$: as \tet{vector}, but returns a
6034: column vector (type \typ{COL}).
6035:
6036: \synt{vvecteur}{GEN nmax, entree *ep, char *expr}.
6037:
6038: \section{Sums, products, integrals and similar functions}
6039: \label{se:sums}
6040:
6041: Although the GP calculator is programmable, it is useful to have
6042: preprogrammed a number of loops, including sums, products, and a certain
6043: number of recursions. Also, a number of functions from numerical analysis
6044: like numerical integration and summation of series will be described here.
6045:
6046: One of the parameters in these loops must be the control variable, hence a
6047: simple variable name. The last parameter can be any legal PARI expression,
6048: including of course expressions using loops. Since it is much easier to
6049: program directly the loops in library mode, these functions are mainly
6050: useful for GP programming. The use of these functions in library mode is a
6051: little tricky and its explanation will be mostly omitted, although the
6052: reader can try and figure it out by himself by checking the example given
6053: for the \tet{sum} function. In this section we only give the library
6054: syntax, with no semantic explanation.
6055:
6056: The letter $X$ will always denote any simple variable name, and represents
6057: the formal parameter used in the function.
6058:
6059: \misctitle{(numerical) integration}:\sidx{numerical integration} A number
6060: of Romberg-like integration methods are implemented (see \kbd{intnum} as
6061: opposed to \kbd{intformal} which we already described). The user should not
6062: require too much accuracy: 18 or 28 decimal digits is OK, but not much more.
6063: In addition, analytical cleanup of the integral must have been done: there
6064: must be no singularities in the interval or at the boundaries. In practice
6065: this can be accomplished with a simple change of variable. Furthermore, for
6066: improper integrals, where one or both of the limits of integration are plus
6067: or minus infinity, the function must decrease sufficiently rapidly at
6068: infinity. This can often be accomplished through integration by parts.
6069: Finally, the function to be integrated should not be very small
6070: (compared to the current precision) on the entire interval. This can
6071: of course be accomplished by just multiplying by an appropriate
6072: constant.
6073:
6074: Note that \idx{infinity} can be represented with essentially no loss of
6075: accuracy by 1e4000. However beware of real underflow when dealing with
6076: rapidly decreasing functions. For example, if one wants to compute the
6077: $\int_0^\infty e^{-x^2}\,dx$ to 28 decimal digits, then one should set
6078: infinity equal to 10 for example, and certainly not to 1e4000.
6079:
6080: The integrand may have values belonging to a vector space over the real
6081: numbers; in particular, it can be complex-valued or vector-valued.
6082:
6083: See also the discrete summation methods below (sharing the prefix \kbd{sum}).
6084:
6085: \subsecidx{intnum}$(X=a,b,\var{expr},\{\fl=0\})$: numerical integration of
6086: \var{expr} (smooth in $]a,b[$), with respect to $X$.
6087:
6088: Set $\fl=0$ (or omit it altogether) when $a$ and $b$ are not too large, the
6089: function is smooth, and can be evaluated exactly everywhere on the interval
6090: $[a,b]$.
6091:
6092: If $\fl=1$, uses a general driver routine for doing numerical integration,
6093: making no particular assumption (slow).
6094:
6095: $\fl=2$ is tailored for being used when $a$ or $b$ are infinite. One
6096: \var{must} have $ab>0$, and in fact if for example $b=+\infty$, then it is
6097: preferable to have $a$ as large as possible, at least $a\ge1$.
6098:
6099: If $\fl=3$, the function is allowed to be undefined (but continuous) at $a$
6100: or $b$, for example the function $\sin(x)/x$ at $x=0$.
6101:
6102: \synt{intnum0}{entree$\,$*e,GEN a,GEN b,char$\,$*expr,long \fl,long prec}.
6103:
6104: \subsecidx{prod}$(X=a,b,\var{expr},\{x=1\})$: product of expression \var{expr},
6105: initialized at $x$, the formal parameter $X$ going from $a$ to $b$. As for
6106: \kbd{sum}, the main purpose of the initialization parameter $x$ is to force
6107: the type of the operations being performed. For example if it is set equal to
6108: the integer 1, operations will start being done exactly. If it is set equal
6109: to the real $1.$, they will be done using real numbers having the default
6110: precision. If it is set equal to the power series $1+O(X^k)$ for a certain
6111: $k$, they will be done using power series of precision at most $k$. These
6112: are the three most common initializations.
6113:
6114: \noindent As an extreme example, compare
6115:
6116: \bprog
6117: ? prod(i=1, 100, 1 - X^i); \\@com this has degree $5050$ !!
6118: time = 3,335 ms.
6119: ? prod(i=1, 100, 1 - X^i, 1 + O(X^101))
6120: time = 43 ms.
6121: %2 = 1 - X - X^2 + X^5 + X^7 - X^12 - X^15 + X^22 + X^26 - X^35 - X^40 + \
6122: X^51 + X^57 - X^70 - X^77 + X^92 + X^100 + O(X^101)
6123: @eprog
6124:
6125: \synt{produit}{entree *ep, GEN a, GEN b, char *expr, GEN x}.
6126:
6127: \subsecidx{prodeuler}$(X=a,b,\var{expr})$: product of expression \var{expr},
6128: initialized at 1. (i.e.~to a \var{real} number equal to 1 to the current
6129: \kbd{realprecision}), the formal parameter $X$ ranging over the prime numbers
6130: between $a$ and $b$.\sidx{Euler product}
6131:
6132: \synt{prodeuler}{entree *ep, GEN a, GEN b, char *expr, long prec}.
6133:
6134: \subsecidx{prodinf}$(X=a,\var{expr},\{\fl=0\})$: \idx{infinite product} of
6135: expression \var{expr}, the formal parameter $X$ starting at $a$. The evaluation
6136: stops when the relative error of the expression minus 1 is less than the
6137: default precision. The expressions must always evaluate to an element of
6138: $\C$.
6139:
6140: If $\fl=1$, do the product of the ($1+\var{expr}$) instead.
6141:
6142: \synt{prodinf}{entree *ep, GEN a, char *expr, long prec} ($\fl=0$), or
6143: \teb{prodinf1} with the same arguments ($\fl=1$).
6144:
6145: \subsecidx{solve}$(X=a,b,\var{expr})$: find a real root of expression
6146: \var{expr} between $a$ and $b$, under the condition
6147: $\var{expr}(X=a) * \var{expr}(X=b) \le 0$.
6148: This routine uses Brent's method and can fail miserably if \var{expr} is
6149: not defined in the whole of $[a,b]$ (try \kbd{solve(x=1, 2, tan(x)}).
6150:
6151: \synt{zbrent}{entree *ep, GEN a, GEN b, char *expr, long prec}.
6152:
6153: \subsecidx{sum}$(X=a,b,\var{expr},\{x=0\})$: sum of expression \var{expr},
6154: initialized at $x$, the formal parameter going from $a$ to $b$. As for
6155: \kbd{prod}, the initialization parameter $x$ may be given to force the type
6156: of the operations being performed.
6157:
6158: \noindent As an extreme example, compare
6159:
6160: \bprog
6161: ? sum(i=1, 5000, 1/i); \\@com rational number: denominator has $2166$ digits.
6162: time = 1,241 ms.
6163: ? sum(i=1, 5000, 1/i, 0.)
6164: time = 158 ms.
6165: %2 = 9.094508852984436967261245533
6166: @eprog
6167:
6168: \synt{somme}{entree *ep, GEN a, GEN b, char *expr, GEN x}. This is to be
6169: used as follows: \kbd{ep} represents the dummy variable used in the
6170: expression \kbd{expr}
6171: \bprog
6172: /* compute a^2 + @dots + b^2 */
6173: {
6174: /* define the dummy variable "i" */
6175: entree *ep = is_entry("i");
6176: /* sum for a <= i <= b */
6177: return somme(ep, a, b, "i^2", gzero);
6178: }
6179: @eprog
6180:
6181: \subsecidx{sumalt}$(X=a,\var{expr},\{\fl=0\})$: numerical summation of the
6182: series \var{expr}, which should be an \idx{alternating series}, the formal
6183: variable $X$ starting at $a$.
6184:
6185: If $\fl=0$, use an algorithm of F.~Villegas as modified by D.~Zagier. This
6186: is much better than \idx{Euler}-Van Wijngaarden's method which was used
6187: formerly.
6188: Beware that the stopping criterion is that the term gets small enough, hence
6189: terms which are equal to 0 will create problems and should be removed.
6190:
6191: If $\fl=1$, use a variant with slightly different polynomials. Sometimes
6192: faster.
6193:
6194: Divergent alternating series can sometimes be summed by this method, as well
6195: as series which are not exactly alternating (see for example
6196: \secref{se:user_defined}).
6197:
6198: \misctitle{Important hint:} a significant speed gain can be obtained by
6199: writing the $(-1)^X$ which may occur in the expression as
6200: \kbd{(1.~- X\%2*2)}.
6201:
6202: \synt{sumalt}{entree *ep, GEN a, char *expr, long \fl, long prec}.
6203:
6204: \subsecidx{sumdiv}$(n,X,\var{expr})$: sum of expression \var{expr} over
6205: the positive divisors of $n$.
6206:
6207: Arithmetic functions like \tet{sigma} use the multiplicativity of the
6208: underlying expression to speed up the computation. In the present version
6209: \vers, there is no way to indicate that \var{expr} is multiplicative in
6210: $n$, hence specialized functions should be prefered whenever possible.
6211:
6212: \synt{divsum}{entree *ep, GEN num, char *expr}.
6213:
6214: \subsecidx{suminf}$(X=a,\var{expr})$: \idx{infinite sum} of expression
6215: \var{expr}, the formal parameter $X$ starting at $a$. The evaluation stops
6216: when the relative error of the expression is less than the default precision.
6217: The expressions must always evaluate to a complex number.
6218:
6219: \synt{suminf}{entree *ep, GEN a, char *expr, long prec}.
6220:
6221: \subsecidx{sumpos}$(X=a,\var{expr},\{\fl=0\})$: numerical summation of the
6222: series \var{expr}, which must be a series of terms having the same sign,
6223: the formal
6224: variable $X$ starting at $a$. The algorithm used is Van Wijngaarden's trick
6225: for converting such a series into an alternating one, and is quite slow.
6226: Beware that the stopping criterion is that the term gets small enough, hence
6227: terms which are equal to 0 will create problems and should be removed.
6228:
6229: If $\fl=1$, use slightly different polynomials. Sometimes faster.
6230:
6231: \synt{sumpos}{entree *ep, GEN a, char *expr, long \fl, long prec}.
6232:
6233: \section{Plotting functions}
6234:
6235: Although plotting is not even a side purpose of PARI, a number of plotting
6236: functions are provided. Moreover, a lot of people felt like suggesting
6237: ideas or submitting huge patches for this section of the code. Among these,
6238: special thanks go to Klaus-Peter Nischke who suggested the recursive plotting
6239: and the forking/resizing stuff under X11, and Ilya Zakharevich who
6240: undertook a complete rewrite of the graphic code, so that most of it is now
6241: platform-independent and should be relatively easy to port or expand.
6242:
6243: These graphic functions are either
6244:
6245: $\bullet$ high-level plotting functions (all the functions starting with
6246: \kbd{ploth}) in which the user has little to do but explain what type of plot
6247: he wants, and whose syntax is similar to the one used in the preceding
6248: section (with somewhat more complicated flags).
6249:
6250: $\bullet$ low-level plotting functions, where every drawing primitive (point,
6251: line, box, etc.) must be specified by the user. These low-level functions
6252: (called \var{rectplot} functions, sharing the prefix \kbd{plot}) work as
6253: follows. You have at your disposal 16 virtual windows which are filled
6254: independently, and can then be physically ORed on a single window at
6255: user-defined positions. These windows are numbered from 0 to 15, and must be
6256: initialized before being used by the function \kbd{plotinit}, which specifies
6257: the height and width of the virtual window (called a \var{rectwindow} in the
6258: sequel). At all times, a virtual cursor (initialized at $[0,0]$) is
6259: associated to the window, and its current value can be obtained using the
6260: function \kbd{plotcursor}.
6261:
6262: A number of primitive graphic objects (called \var{rect} objects) can then
6263: be drawn in these windows, using a default color associated to that window
6264: (which can be changed under X11, using the \kbd{plotcolor} function, black
6265: otherwise) and only the part of the object which is inside the window will be
6266: drawn, with the exception of polygons and strings which are drawn entirely
6267: (but the virtual cursor can move outside of the window). The ones sharing the
6268: prefix \kbd{plotr} draw relatively to the current position of the virtual
6269: cursor, the others use absolute coordinates. Those having the prefix
6270: \kbd{plotrecth} put in the rectwindow a large batch of rect objects
6271: corresponding to the output of the related \kbd{ploth} function.
6272:
6273: Finally, the actual physical drawing is done using the function
6274: \kbd{plotdraw}. Note that the windows are preserved so that further drawings
6275: using the same windows at different positions or different windows can be
6276: done without extra work. If you want to erase a window (and free the
6277: corresponding memory), use the function \kbd{plotkill}. It is not possible to
6278: partially erase a window. Erase it completely, initialize it again and then
6279: fill it with the graphic objects that you want to keep.
6280:
6281: In addition to initializing the window, you may want to have a scaled
6282: window to avoid unnecessary conversions. For this, use the function
6283: \kbd{plotscale} below. As long as this function is not called, the scaling is
6284: simply the number of pixels, the origin being at the upper left and the
6285: $y$-coordinates going downwards.
6286:
6287: Note that in the present version \vers\ all these plotting functions
6288: (both low and high level) have been written for the X11-window system
6289: (hence also for GUI's based on X11 such as Openwindows and Motif) only,
6290: though very little code remains which is actually platform-dependent. A
6291: Suntools/Sunview, Macintosh, and an Atari/Gem port were provided for
6292: previous versions. These \var{may} be adapted in future releases.
6293:
6294: Under X11/Suntools, the physical window (opened by \kbd{plotdraw} or any
6295: of the \kbd{ploth*} functions) is completely separated from GP (technically,
6296: a \kbd{fork} is done, and the non-graphical memory is immediately freed in
6297: the child process), which means you can go on working in the current GP
6298: session, without having to kill the window first. Under X11, this window can
6299: be closed, enlarged or reduced using the standard window manager functions.
6300: No zooming procedure is implemented though (yet).
6301:
6302: $\bullet$ Finally, note that in the same way that \kbd{printtex} allows you
6303: to have a \TeX\ output corresponding to printed results, the functions
6304: starting with \kbd{ps} allow you to have \tet{PostScript} output of the
6305: plots. This will not be absolutely identical with the screen output, but will
6306: be sufficiently close. Note that you can use PostScript output even if you do
6307: not have the plotting routines enabled. The PostScript output is written in a
6308: file whose name is derived from the \tet{psfile} default (\kbd{./pari.ps} if
6309: you did not tamper with it). Each time a new PostScript output is asked for,
6310: the PostScript output is appended to that file. Hence the user must remove
6311: this file, or change the value of \kbd{psfile}, first if he does not want
6312: unnecessary drawings from preceding sessions to appear. On the other hand, in
6313: this manner as many plots as desired can be kept in a single file. \smallskip
6314:
6315: {\it None of the graphic functions are available within the PARI library, you
6316: must be under GP to use them}. The reason for that is that you really should
6317: not use PARI for heavy-duty graphical work, there are much better specialized
6318: alternatives around. This whole set of routines was only meant as a
6319: convenient, but simple-minded, visual aid. If you really insist on using
6320: these in your program (we warned you), the source (\kbd{plot*.c}) should be
6321: readable enough for you to achieve something.
6322:
6323: \subsecidx{plot}$(X=a,b,\var{expr},\{\var{Ymin}\},\{\var{Ymax}\})$: crude
6324: (ASCII) plot of the function represented by expression \var{expr} from
6325: $a$ to $b$, with \var{Y} ranging from \var{Ymin} to \var{Ymax}. If
6326: \var{Ymin} (resp. \var{Ymax}) is not given, the minima (resp. the
6327: maxima) of the computed values of the expression is used instead.
6328:
6329: \subsecidx{plotbox}$(w,x2,y2)$: let $(x1,y1)$ be the current position of the
6330: virtual cursor. Draw in the rectwindow $w$ the outline of the rectangle which
6331: is such that the points $(x1,y1)$ and $(x2,y2)$ are opposite corners. Only
6332: the part of the rectangle which is in $w$ is drawn. The virtual cursor does
6333: \var{not} move.
6334:
6335: \subsecidx{plotclip}$(w)$: `clips' the content of rectwindow $w$, i.e
6336: remove all parts of the drawing that would not be visible on the screen.
6337: Together with \tet{plotcopy} this function enables you to draw on a
6338: scratchpad before commiting the part you're interested in to the final
6339: picture.
6340:
6341: \subsecidx{plotcolor}$(w,c)$: set default color to $c$ in rectwindow $w$.
6342: In present version \vers, this is only implemented for X11 window system,
6343: and you only have the following palette to choose from:
6344:
6345: 1=black, 2=blue, 3=sienna, 4=red, 5=cornsilk, 6=grey, 7=gainsborough.
6346:
6347: Note that it should be fairly easy for you to hardwire some more colors by
6348: tweaking the files \kbd{rect.h} and \kbd{plotX.c}. User-defined
6349: colormaps would be nice, and \var{may} be available in future versions.
6350:
6351: \subsecidx{plotcopy}$(w1,w2,dx,dy)$: copy the contents of rectwindow
6352: $w1$ to rectwindow $w2$, with offset $(dx,dy)$.
6353:
6354: \subsecidx{plotcursor}$(w)$: give as a 2-component vector the current
6355: (scaled) position of the virtual cursor corresponding to the rectwindow $w$.
6356:
6357: \subsecidx{plotdraw}$(list)$: physically draw the rectwindows given in $list$
6358: which must be a vector whose number of components is divisible by 3. If
6359: $list=[w1,x1,y1,w2,x2,y2,\dots]$, the windows $w1$, $w2$, etc.~are
6360: physically placed with their upper left corner at physical position
6361: $(x1,y1)$, $(x2,y2)$,\dots\ respectively, and are then drawn together.
6362: Overlapping regions will thus be drawn twice, and the windows are considered
6363: transparent. Then display the whole drawing in a special window on your
6364: screen.
6365:
6366: \subsecidx{plotfile}$(s)$: set the output file for plotting output. Special
6367: filename \kbd{-} redirects to the same place as PARI output.
6368:
6369: \subsecidx{ploth}$(X=a,b,\var{expr},\{\fl=0\},\{n=0\})$: high precision
6370: plot of the function $y=f(x)$ represented by the expression \var{expr}, $x$
6371: going from $a$ to $b$. This opens a specific window (which is killed
6372: whenever you click on it), and returns a four-component vector giving the
6373: coordinates of the bounding box in the form
6374: $[\var{xmin},\var{xmax},\var{ymin},\var{ymax}]$.
6375:
6376: \misctitle{Important note}: Since this may involve a lot of function calls,
6377: it is advised to keep the current precision to a minimum (e.g.~9) before
6378: calling this function.
6379:
6380: $n$ specifies the number of reference point on the graph (0 means use the
6381: hardwired default values, that is: 1000 for general plot, 1500 for
6382: parametric plot, and 15 for recursive plot).
6383:
6384: If no $\fl$ is given, \var{expr} is either a scalar expression $f(X)$, in which
6385: case the plane curve $y=f(X)$ will be drawn, or a vector
6386: $[f_1(X),\dots,f_k(X)]$, and then all the curves $y=f_i(X)$ will be drawn in
6387: the same window.
6388:
6389: \noindent The binary digits of $\fl$ mean:
6390:
6391: $\bullet$ 1: \tev{parametric plot}. Here \var{expr} must be a vector with
6392: an even number of components. Successive pairs are then understood as the
6393: parametric coordinates of a plane curve. Each of these are then drawn.
6394:
6395: For instance:
6396:
6397: \kbd{ploth(X=0,2*Pi,[sin(X),cos(X)],1)} will draw a circle.
6398:
6399: \kbd{ploth(X=0,2*Pi,[sin(X),cos(X)])} will draw two entwined sinusoidal
6400: curves.
6401:
6402: \kbd{ploth(X=0,2*Pi,[X,X,sin(X),cos(X)],1)} will draw a circle and the line
6403: $y=x$.
6404:
6405:
6406: $\bullet$ 2: \tev{recursive plot}. If this flag is set, only \var{one}
6407: curve can be drawn at time, i.e.~\var{expr} must be either a two-component
6408: vector (for a single parametric curve, and the parametric flag \var{has} to
6409: be set), or a scalar function. The idea is to choose pairs of successive
6410: reference points, and if their middle point is not too far away from the
6411: segment joining them, draw this as a local approximation to the curve.
6412: Otherwise, add the middle point to the reference points. This is very fast,
6413: and usually more precise than usual plot. Compare the results of
6414: $$\kbd{ploth(X=-1,1,sin(1/X),2)}\quad
6415: \text{and}\quad\kbd{ploth(X=-1,1,sin(1/X))}$$
6416: for instance. But beware that if you are extremely unlucky, or choose too few
6417: reference points, you may draw some nice polygon bearing little resemblance
6418: to the original curve. For instance you should \var{never} plot recursively
6419: an odd function in a symmetric interval around 0. Try
6420: \bprog
6421: ploth(x = -20, 20, sin(x), 2)
6422: @eprog
6423: \noindent to see why. Hence, it's usually a good idea to try and plot the same
6424: curve with slightly different parameters.
6425:
6426: The other values toggle various display options:
6427:
6428: $\bullet$ 4: do not rescale plot according to the computed extrema. This is
6429: meant to be used when graphing multiple functions on a rectwindow (as a
6430: \tet{plotrecth} call), in conjuction with \tet{plotscale}.
6431:
6432: $\bullet$ 8: do not print the $x$-axis.
6433:
6434: $\bullet$ 16: do not print the $y$-axis.
6435:
6436: $\bullet$ 32: do not print frame.
6437:
6438: $\bullet$ 64: only plot reference points, do not join them.
6439:
6440: $\bullet$ 256: use splines to interpolate the points.
6441:
6442: $\bullet$ 512: plot no $x$-ticks.
6443:
6444: $\bullet$ 1024: plot no $y$-ticks.
6445:
6446: $\bullet$ 2048: plot all ticks with the same length.
6447:
6448: \subsecidx{plothraw}$(\var{listx},\var{listy},\{\fl=0\})$: given
6449: \var{listx} and \var{listy} two vectors of equal length, plots (in high
6450: precision) the points whose $(x,y)$-coordinates are given in \var{listx}
6451: and \var{listy}. Automatic positioning and scaling is done, but with the
6452: same scaling factor on $x$ and $y$. If $\fl$ is 1, join points, other non-0
6453: flags toggle display options and should be combinations of bits $2^k$, $k
6454: \geq 3$ as in \kbd{ploth}.
6455:
6456: \subsecidx{plothsizes}$()$: return data corresponding to the output window
6457: in the form of a 6-component vector: window width and height, sizes for ticks
6458: in horizontal and vertical directions (this is intended for the \kbd{gnuplot}
6459: interface and is currently not significant), width and height of characters.
6460:
6461: \subsecidx{plotinit}$(w,x,y,\{\fl\})$: initialize the rectwindow $w$,
6462: destroying any rect objects you may have already drawn in $w$. The virtual
6463: cursor is set to $(0,0)$. The rectwindow size is set to width $x$ and height
6464: $y$. If $\fl=0$, $x$ and $y$ represent pixel units. Otherwise, $x$ and $y$
6465: are understood as fractions of the size of the current output device (hence
6466: must be between $0$ and $1$) and internally converted to pixels.
6467:
6468: The plotting device imposes an upper bound for $x$ and $y$, for instance the
6469: number of pixels for screen output. These bounds are available through the
6470: \tet{plothsizes} function. The following sequence initializes in a portable
6471: way (i.e independant of the output device) a window of maximal size, accessed
6472: through coordinates in the $[0,1000] \times [0,1000]$ range~:
6473:
6474: \bprog
6475: s = plothsizes();
6476: plotinit(0, s[1]-1, s[2]-1);
6477: plotscale(0, 0,1000, 0,1000);
6478: @eprog
6479:
6480: \subsecidx{plotkill}$(w)$: erase rectwindow $w$ and free the corresponding
6481: memory. Note that if you want to use the rectwindow $w$ again, you have to
6482: use \kbd{initrect} first to specify the new size. So it's better in this case
6483: to use \kbd{initrect} directly as this throws away any previous work in the
6484: given rectwindow.
6485:
6486: \subsecidx{plotlines}$(w,X,Y,\{\fl=0\})$: draw on the rectwindow $w$
6487: the polygon such that the (x,y)-coordinates of the vertices are in the
6488: vectors of equal length $X$ and $Y$. For simplicity, the whole
6489: polygon is drawn, not only the part of the polygon which is inside the
6490: rectwindow. If $\fl$ is non-zero, close the polygon. In any case, the
6491: virtual cursor does not move.
6492:
6493: $X$ and $Y$ are allowed to be scalars (in this case, both have to).
6494: There, a single segment will be drawn, between the virtual cursor current
6495: position and the point $(X,Y)$. And only the part thereof which
6496: actually lies within the boundary of $w$. Then \var{move} the virtual cursor
6497: to $(X,Y)$, even if it is outside the window. If you want to draw a
6498: line from $(x1,y1)$ to $(x2,y2)$ where $(x1,y1)$ is not necessarily the
6499: position of the virtual cursor, use \kbd{plotmove(w,x1,y1)} before using this
6500: function.
6501:
6502: \subsecidx{plotlinetype}$(w,\var{type})$: change the type of lines
6503: subsequently plotted in rectwindow $w$. \var{type} $-2$ corresponds to
6504: frames, $-1$ to axes, larger values may correspond to something else. $w =
6505: -1$ changes highlevel plotting. This is only taken into account by the
6506: \kbd{gnuplot} interface.
6507:
6508: \subsecidx{plotmove}$(w,x,y)$: move the virtual cursor of the rectwindow $w$
6509: to position $(x,y)$.
6510:
6511: \subsecidx{plotpoints}$(w,X,Y)$: draw on the rectwindow $w$ the
6512: points whose $(x,y)$-coordinates are in the vectors of equal length $X$ and
6513: $Y$ and which are inside $w$. The virtual cursor does \var{not} move. This
6514: is basically the same function as \kbd{plothraw}, but either with no scaling
6515: factor or with a scale chosen using the function \kbd{plotscale}.
6516:
6517: As was the case with the \kbd{plotlines} function, $X$ and $Y$ are allowed to
6518: be (simultaneously) scalar. In this case, draw the single point $(X,Y)$ on
6519: the rectwindow $w$ (if it is actually inside $w$), and in any case
6520: \var{move} the virtual cursor to position $(x,y)$.
6521:
6522: \subsecidx{plotpointsize}$(w,size)$: changes the ``size'' of following
6523: points in rectwindow $w$. If $w = -1$, change it in all rectwindows.
6524: This only works in the \kbd{gnuplot} interface.
6525:
6526: \subsecidx{plotpointtype}$(w,\var{type})$: change the type of
6527: points subsequently plotted in rectwindow $w$. $\var{type} = -1$
6528: corresponds to a dot, larger values may correspond to something else. $w = -1$
6529: changes highlevel plotting. This is only taken into account by the
6530: \kbd{gnuplot} interface.
6531:
6532: \subsecidx{plotrbox}$(w,dx,dy)$: draw in the rectwindow $w$ the outline of
6533: the rectangle which is such that the points $(x1,y1)$ and $(x1+dx,y1+dy)$ are
6534: opposite corners, where $(x1,y1)$ is the current position of the cursor.
6535: Only the part of the rectangle which is in $w$ is drawn. The virtual cursor
6536: does \var{not} move.
6537:
6538: \subsecidx{plotrecth}$(w,X=a,b,\var{expr},\{\fl=0\},\{n=0\})$: writes to
6539: rectwindow $w$ the curve output of \kbd{ploth}$(w,X=a,b,\var{expr},\fl,n)$.
6540:
6541: \subsecidx{plotrecthraw}$(w,\var{data},\{\fl=0\})$: plot graph(s) for
6542: \var{data} in rectwindow $w$. $\fl$ has the same significance here as in
6543: \kbd{ploth}, though recursive plot is no more significant.
6544:
6545: \var{data} is a vector of vectors, each corresponding to a list a coordinates.
6546: If parametric plot is set, there must be an even number of vectors, each
6547: successive pair corresponding to a curve. Otherwise, the first one containe
6548: the $x$ coordinates, and the other ones contain the $y$-coordinates
6549: of curves to plot.
6550:
6551: \subsecidx{plotrline}$(w,dx,dy)$: draw in the rectwindow $w$ the part of the
6552: segment $(x1,y1)-(x1+dx,y1+dy)$ which is inside $w$, where $(x1,y1)$ is the
6553: current position of the virtual cursor, and move the virtual cursor to
6554: $(x1+dx,y1+dy)$ (even if it is outside the window).
6555:
6556: \subsecidx{plotrmove}$(w,dx,dy)$: move the virtual cursor of the rectwindow
6557: $w$ to position $(x1+dx,y1+dy)$, where $(x1,y1)$ is the initial position of
6558: the cursor (i.e.~to position $(dx,dy)$ relative to the initial cursor).
6559:
6560: \subsecidx{plotrpoint}$(w,dx,dy)$: draw the point $(x1+dx,y1+dy)$ on the
6561: rectwindow $w$ (if it is inside $w$), where $(x1,y1)$ is the current position
6562: of the cursor, and in any case move the virtual cursor to position
6563: $(x1+dx,y1+dy)$.
6564:
6565: \subsecidx{plotscale}$(w,x1,x2,y1,y2)$: scale the local coordinates of the
6566: rectwindow $w$ so that $x$ goes from $x1$ to $x2$ and $y$ goes from $y1$ to
6567: $y2$ ($x2<x1$ and $y2<y1$ being allowed). Initially, after the initialization
6568: of the rectwindow $w$ using the function \kbd{plotinit}, the default scaling
6569: is the graphic pixel count, and in particular the $y$ axis is oriented
6570: downwards since the origin is at the upper left. The function \kbd{plotscale}
6571: allows to change all these defaults and should be used whenever functions are
6572: graphed.
6573:
6574: \subsecidx{plotstring}$(w,x,\{\fl=0\})$: draw on the rectwindow $w$ the
6575: String $x$ (see \secref{se:strings}), at the current position of the cursor.
6576:
6577: \fl\ is used for justification: bits 1 and 2 regulate horizontal alignment:
6578: left if 0, right if 2, center if 1. Bits 4 and 8 regulate vertical
6579: alignment: bottom if 0, top if 8, v-center if 4. Can insert additional
6580: small gap between point and string: horizontal if bit 16 is set, vertical
6581: if bit 32 is set (see the tutorial for an example).
6582:
6583: \subsecidx{plotterm}$(\var{term})$: sets terminal where high resolution
6584: plots go (this is currently only taken into account by the \kbd{gnuplot}
6585: graphical driver). Using the \kbd{gnuplot} driver, possible terminals are
6586: the same as in gnuplot. If \var{term} is "?", lists possible values.
6587:
6588: Terminal options can be appended to the terminal name and space; terminal
6589: size can be put immediately after the name, as in \kbd{"gif=300,200"}.
6590: Positive return value means success.
6591:
6592: \subsecidx{psdraw}$(\var{list})$: same as \kbd{plotdraw}, except that the
6593: output is a PostScript program appended to the \kbd{psfile}.
6594:
6595: \subsecidx{psploth}$(X=a,b,\var{expr})$: same as \kbd{ploth}, except that the
6596: output is a PostScript program appended to the \kbd{psfile}.
6597:
6598: \subsecidx{psplothraw}$(\var{listx},\var{listy})$: same as \kbd{plothraw},
6599: except that the output is a PostScript program appended to the \kbd{psfile}.
6600:
6601: \section{Programming under GP}
6602: \sidx{programming}\label{se:programming}
6603: \subsecidx{Control statements}.
6604:
6605: A number of control statements are available under GP. They are simpler and
6606: have a syntax slightly different from their C counterparts, but are quite
6607: powerful enough to write any kind of program. Some of them are specific to
6608: GP, since they are made for number theorists. As usual, $X$ will denote any
6609: simple variable name, and \var{seq} will always denote a sequence of
6610: expressions, including the empty sequence.
6611:
6612: \subsubsecidx{break}$(\{n=1\})$: interrupts execution of current \var{seq}, and
6613: immediately exits from the $n$ innermost enclosing loops, within the
6614: current function call (or the top level loop). $n$ must be bigger than 1.
6615: If $n$ is greater than the number of enclosing loops, all enclosing loops
6616: are exited.
6617:
6618: \subsubsecidx{for}$(X=a,b,\var{seq})$: the formal variable $X$ going from
6619: $a$ to $b$, the \var{seq} is evaluated. Nothing is done if $a>b$.
6620: $a$ and $b$ must be in $\R$.
6621:
6622: \subsubsecidx{fordiv}$(n,X,\var{seq})$: the formal variable $X$ ranging
6623: through the positive divisors of $n$, the sequence \var{seq} is evaluated.
6624: $n$ must be of type integer.
6625:
6626: \subsubsecidx{forprime}$(X=a,b,\var{seq})$: the formal variable $X$
6627: ranging over the prime numbers between $a$ to $b$ (including $a$ and $b$
6628: if they are prime), the \var{seq} is evaluated. More precisely, the value
6629: of $X$ is incremented to the smallest prime strictly larger than $X$ at the
6630: end of each iteration. Nothing is done if $a>b$. Note that $a$ and $b$ must
6631: be in $\R$.
6632:
6633: \bprog
6634: ? { forprime(p = 2, 12,
6635: print(p);
6636: if (p == 3, p = 6);
6637: )
6638: }
6639: 2
6640: 3
6641: 7
6642: 11
6643: @eprog
6644:
6645: \subsubsecidx{forstep}$(X=a,b,s,\var{seq})$: the formal variable $X$
6646: going from $a$ to $b$, in increments of $s$, the \var{seq} is evaluated.
6647: Nothing is done if $s>0$ and $a>b$ or if $s<0$ and $a<b$. $s$ must be in
6648: $\R^*$ or a vector of steps $[s_1,\dots,s_n]$. In the latter case, the
6649: successive steps are used in the order they appear in $s$.
6650:
6651: \bprog
6652: ? forstep(x=5, 20, [2,4], print(x))
6653: 5
6654: 7
6655: 11
6656: 13
6657: 17
6658: 19
6659: @eprog
6660:
6661: \subsubsecidx{forsubgroup}$(H=G,\{B\},\var{seq})$: executes \var{seq} for
6662: each subgroup $H$ of the \var{abelian} group $G$ (given in
6663: SNF\sidx{Smith normal form} form or as a vector of elementary divisors),
6664: whose index is bounded by $B$. The subgroups are not ordered in any
6665: obvious way, unless $G$ is a $p$-group in which case Birkhoff's algorithm
6666: produces them by decreasing index. A \idx{subgroup} is given as a matrix
6667: whose columns give its generators on the implicit generators of $G$. For
6668: example, the following prints all subgroups of index less than 2 in $G =
6669: \Z/2\Z g_1 \times \Z/2\Z g_2$~:
6670:
6671: \bprog
6672: ? G = [2,2]; forsubgroup(H=G, 2, print(H))
6673: [1; 1]
6674: [1; 2]
6675: [2; 1]
6676: [1, 0; 1, 1]
6677: @eprog
6678: The last one, for instance is generated by $(g_1, g_1 + g_2)$. This
6679: routine is intended to treat huge groups, when \tet{subgrouplist} is not an
6680: option due to the sheer size of the output.
6681:
6682: For maximal speed the subgroups have been left as produced by the algorithm.
6683: To print them in canonical form (as left divisors of $G$ in
6684: HNF\sidx{Hermite normal form} form), one can for instance use
6685: \bprog
6686: ? G = matdiagonal([2,2]); forsubgroup(H=G, 2, print(mathnf(concat(G,H))))
6687: [2, 1; 0, 1]
6688: [1, 0; 0, 2]
6689: [2, 0; 0, 1]
6690: [1, 0; 0, 1]
6691: @eprog
6692: Note that in this last representation, the index $[G:H]$ is given by the
6693: determinant. See \tet{galoissubcyclo} and \tet{galoisfixedfield} for
6694: \tet{nfsubfields} applications to \idx{Galois} theory.
6695:
6696: \subsubsecidx{forvec}$(X=v,\var{seq},\{\fl=0\})$: $v$ being an $n$-component
6697: vector (where $n$ is arbitrary) of two-component vectors $[a_i,b_i]$
6698: for $1\le i\le n$, the \var{seq} is evaluated with the formal variable
6699: $X[1]$ going from $a_1$ to $b_1$,\dots,$X[n]$ going from $a_n$ to $b_n$.
6700: The formal variable with the highest index moves the fastest. If $\fl=1$,
6701: generate only nondecreasing vectors $X$, and if $\fl=2$, generate only
6702: strictly increasing vectors $X$.
6703:
6704: \subsubsecidx{if}$(a,\{\var{seq1}\},\{\var{seq2}\})$: if $a$ is non-zero,
6705: the expression sequence \var{seq1} is evaluated, otherwise the expression
6706: \var{seq2} is evaluated. Of course, \var{seq1} or \var{seq2} may be empty,
6707: so \kbd{if ($a$,\var{seq})} evaluates \var{seq} if $a$ is not equal to zero
6708: (you don't have to write the second comma), and does nothing otherwise,
6709: whereas \kbd{if ($a$,,\var{seq})} evaluates \var{seq} if $a$ is equal to
6710: zero, and does nothing otherwise. You could get the same result using
6711: the \kbd{!} (\kbd{not}) operator: \kbd{if (!$a$,\var{seq})}.
6712:
6713: Note that the boolean operators \kbd{\&\&} and \kbd{||} are evaluated
6714: according to operator precedence as explained in \secref{se:operators}, but
6715: that, contrary to other operators, the evaluation of the arguments is
6716: stopped as soon as the final truth value has been determined. For instance
6717: \bprog
6718: if (reallydoit && longcomplicatedfunction(), ...)%
6719: @eprog
6720: \noindent is a perfectly safe statement.
6721:
6722: Recall that functions such as \kbd{break} and \kbd{next} operate on
6723: \var{loops} (such as \kbd{for$xxx$}, \kbd{while}, \kbd{until}). The \kbd{if}
6724: statement is \var{not} a loop (obviously!).
6725:
6726: \subsubsecidx{next}$(\{n=1\})$: interrupts execution of current $seq$,
6727: resume the next iteration of the innermost enclosing loop, within the
6728: current fonction call (or top level loop). If $n$ is specified, resume at
6729: the $n$-th enclosing loop. If $n$ is bigger than the number of enclosing
6730: loops, all enclosing loops are exited.
6731:
6732: \subsubsecidx{return}$(\{x=0\})$: returns from current subroutine, with
6733: result $x$.
6734:
6735: \subsubsecidx{until}$(a,\var{seq})$: evaluates expression sequence \var{seq}
6736: until $a$ is not equal to 0 (i.e.~until $a$ is true). If $a$ is initially
6737: not equal to 0, \var{seq} is evaluated once (more generally, the condition
6738: on $a$ is tested \var{after} execution of the \var{seq}, not before as in
6739: \kbd{while}).
6740:
6741: \subsubsecidx{while}$(a,\var{seq})$: while $a$ is non-zero evaluate the
6742: expression sequence \var{seq}. The test is made \var{before} evaluating
6743: the $seq$, hence in particular if $a$ is initially equal to zero the
6744: \var{seq} will not be evaluated at all.\smallskip
6745:
6746: \subsec{Specific functions used in GP programming}.
6747: \label{se:gp_program}
6748:
6749: In addition to the general PARI functions, it is necessary to have some
6750: functions which will be of use specifically for GP, though a few of these can
6751: be accessed under library mode. Before we start describing these, we recall
6752: the difference between \var{strings} and \var{keywords} (see
6753: \secref{se:strings}): the latter don't get expanded at all, and you can type
6754: them without any enclosing quotes. The former are dynamic objects, where
6755: everything outside quotes gets immediately expanded.
6756:
6757: We need an additional notation for this chapter. An argument between braces,
6758: followed by a star, like $\{\var{str}\}*$, means that any number of such
6759: arguments (possibly none) can be given.
6760:
6761: \subsubsecidx{addhelp}$(S,\var{str})$:\label{se:addhelp} changes the help
6762: message for the symbol $S$. The string \var{str} is expanded on the spot
6763: and stored as the online help for $S$. If $S$ is a function \var{you} have
6764: defined, its definition will still be printed before the message \var{str}.
6765: It is recommended that you document global variables and user functions in
6766: this way. Of course GP won't protest if you don't do it.
6767:
6768: There's nothing to prevent you from modifying the help of built-in PARI
6769: functions (but if you do, we'd like to hear why you needed to do it!).
6770:
6771: \subsubsecidx{alias}$(\var{newkey},\var{key})$: defines the keyword
6772: \var{newkey} as an alias for keyword \var{key}. \var{key} must correspond
6773: to an existing \var{function} name. This is different from the general user
6774: macros in that alias expansion takes place immediately upon execution,
6775: without having to look up any function code, and is thus much faster. A
6776: sample alias file \kbd{misc/gpalias} is provided with the standard
6777: distribution. Alias commands are meant to be read upon startup from the
6778: \kbd{.gprc} file, to cope with function names you are dissatisfied with, and
6779: should be useless in interactive usage.
6780:
6781: \subsubsecidx{allocatemem}$(\{x=0\})$: this is a very special operation which
6782: allows the user to change the stack size \var{after} initialization. $x$
6783: must be a non-negative integer. If $x!=0$, a new stack of size $16*\lceil
6784: x/16\rceil$ bytes will be allocated, all the PARI data on the old stack will
6785: be moved to the new one, and the old stack will be discarded. If $x=0$, the
6786: size of the new stack will be twice the size of the old one.
6787:
6788: Although it is a function, this must be the \var{last} instruction in any GP
6789: sequence. The technical reason is that this routine usually moves the stack,
6790: so objects from the current sequence might not be correct anymore. Hence, to
6791: prevent such problems, this routine terminates by a \kbd{longjmp} (just as an
6792: error would) and not by a return.
6793:
6794: \syn{allocatemoremem}{x}, where $x$ is an unsigned long, and the return type
6795: is void. GP uses a variant which ends by a \kbd{longjmp}.
6796:
6797: \subsubsecidx{default}$(\{\var{key}\},\{\var{val}\},\{\fl\})$: sets the default
6798: corresponding to keyword \var{key} to value \var{val}. \var{val} is a string
6799: (which of course accepts numeric arguments without adverse effects, due to the
6800: expansion mechanism). See \secref{se:defaults} for a list of available
6801: defaults, and \secref{se:meta} for some shortcut alternatives. Typing
6802: \kbd{default()} (or \b{d}) yields the complete default list as well as
6803: their current values.\label{se:default}
6804:
6805: If \var{val} is omitted, prints the current value of default \var{key}.
6806: If $\fl$ is set, returns the result instead of printing it.
6807:
6808: \subsubsecidx{error}$(\{\var{str}\}*)$: outputs its argument list (each of
6809: them interpreted as a string), then interrupts the running GP program,
6810: returning to the input prompt.
6811:
6812: Example: \kbd{error("n = ", n, " is not squarefree !")}.
6813:
6814: Note that, due to the automatic concatenation of strings, you could in fact
6815: use only one argument, just by suppressing the commas.
6816:
6817: \subsubsecidxunix{extern}$(\var{str})$: the string \var{str} is the name
6818: of an external command (i.e.~one you would type from your UNIX shell prompt).
6819: This command is immediately run and its input fed into GP, just as if read
6820: from a file.
6821:
6822: \subsubsecidx{getheap}$()$: returns a two-component row vector giving the
6823: number of objects on the heap and the amount of memory they occupy in long
6824: words. Useful mainly for debugging purposes.
6825:
6826: \syn{getheap}{}.
6827:
6828: \subsubsecidx{getrand}$()$: returns the current value of the random number
6829: seed. Useful mainly for debugging purposes.
6830:
6831: \syn{getrand}{}, returns a C long.
6832:
6833: \subsubsecidx{getstack}$()$: returns the current value of
6834: \kbd{top${}-{}$avma},
6835: i.e.~the number of bytes used up to now on the stack. Should be equal to 0
6836: in between commands. Useful mainly for debugging purposes.
6837:
6838: \syn{getstack}{}, returns a C long.
6839:
6840: \subsubsecidx{gettime}$()$: returns the time (in milliseconds) elapsed since
6841: either the last call to \kbd{gettime}, or to the beginning of the containing
6842: GP instruction (if inside GP), whichever came last.
6843:
6844: \syn{gettime}{}, returns a C long.
6845:
6846: \subsubsecidx{global}$(\{\hbox{\it list of variables}\})$: \label{se:global}
6847: declares the corresponding variables to be global. From now on, you will be
6848: forbidden to use them as formal parameters for function definitions or as
6849: loop indexes. This is especially useful when patching together various
6850: scripts, possibly written with different naming conventions. For instance the
6851: following situation is dangerous:
6852: %
6853: \bprog
6854: p = 3 \\@com fix characteristic
6855: ...
6856: forprime(p = 2, N, ...)
6857: f(p) = ...
6858: @eprog
6859: since within the loop or within the function's body (even worse: in the
6860: subroutines called in that scope), the true global value of \kbd{p} will be
6861: hidden. If the statement \kbd{global(p = 3)} appears at the beginning of
6862: the script, then both expressions will trigger syntax errors.
6863:
6864: Calling \kbd{global} without arguments prints the list of global variables in
6865: use. In particular, \kbd{eval(global)} will output the values of all local
6866: variables.
6867:
6868: \subsubsecidx{input}$()$: reads a string, interpreted as a GP expression,
6869: from the input file, usually standard input (i.e.~the keyboard). If a
6870: sequence of expressions is given, the result is the result of the last
6871: expression of the sequence. When using this instruction, it is useful to
6872: prompt for the string by using the \kbd{print1} function. Note that in the
6873: present version 2.19 of \kbd{pari.el}, when using GP under GNU Emacs (see
6874: \secref{se:emacs}) one \var{must} prompt for the string, with a string
6875: which ends with the same prompt as any of the previous ones (a \kbd{"? "}
6876: will do for instance).
6877:
6878: \subsubsecidxunix{install}$(\var{name},\var{code},\{\var{gpname}\},\{\var{lib}\})$:
6879: loads from dynamic library \var{lib} the function \var{name}. Assigns to it
6880: the name \var{gpname} in this GP session, with argument code \var{code} (see
6881: \secref{se:gp.interface} for an explanation of those). If \var{lib} is
6882: omitted, uses \kbd{libpari.so}. If \var{gpname} is omitted, uses
6883: \var{name}.\label{se:install}
6884:
6885: This function is useful for adding custom functions to the GP interpreter,
6886: or picking useful functions from unrelated libraries. For instance, it
6887: makes the function \tet{system} obsolete:
6888:
6889: \bprog
6890: ? install(system, vs, sys, "libc.so")
6891: ? sys("ls gp*")
6892: gp.c gp.h gp_rl.c
6893: @eprog
6894:
6895: But it also gives you access to all (non static) functions defined in the
6896: PARI library. For instance, the function \kbd{GEN addii(GEN x, GEN y)} adds
6897: two PARI integers, and is not directly accessible under GP (it's eventually
6898: called by the \kbd{+} operator of course):
6899:
6900: \bprog
6901: ? install("addii", "GG")
6902: ? addii(1, 2)
6903: %1 = 3
6904: @eprog
6905:
6906: \misctitle{Caution:} This function may not work on all systems, especially
6907: when GP has been compiled statically. In that case, the first use of an
6908: installed function will provoke a Segmentation Fault, i.e.~a major internal
6909: blunder (this should never happen with a dynamically linked executable).
6910: Hence, if you intend to use this function, please check first on some
6911: harmless example such as the ones above that it works properly on your
6912: machine.
6913:
6914: \subsubsecidx{kill}$(s)$:\label{se:kill} kills the present value of the
6915: variable, alias or user-defined function $s$. The corresponding identifier
6916: can now be used to name any GP object (variable or function). This is the
6917: only way to replace a variable by a function having the same name (or the
6918: other way round), as in the following example:
6919:
6920: \bprog
6921: ? f = 1
6922: %1 = 1
6923: ? f(x) = 0
6924: *** unused characters: f(x)=0
6925: ^----
6926: ? kill(f)
6927: ? f(x) = 0
6928: ? f()
6929: %2 = 0
6930: @eprog
6931:
6932: When you kill a variable, all objects that used it become invalid. You
6933: can still display them, even though the killed variable will be printed in a
6934: funny way (following the same convention as used by the library function
6935: \kbd{fetch\_var}, see~\secref{se:vars}). For example:
6936:
6937: \bprog
6938: ? a^2 + 1
6939: %1 = a^2 + 1
6940: ? kill(a)
6941: ? %1
6942: %2 = #<1>^2 + 1
6943: @eprog
6944:
6945: If you simply want to restore a variable to its ``undefined'' value
6946: (monomial of degree one), use the \idx{quote} operator: \kbd{a = 'a}.
6947: Predefined symbols (\kbd{x} and GP function names) cannot be killed.
6948:
6949: \subsubsecidx{print}$(\{\var{str}\}*)$: outputs its (string) arguments in raw
6950: format, ending with a newline.
6951:
6952: \subsubsecidx{print1}$(\{\var{str}\}*)$: outputs its (string) arguments in raw
6953: format, without ending with a newline (note that you can still embed newlines
6954: within your strings, using the \b{n} notation~!).
6955:
6956: \subsubsecidx{printp}$(\{\var{str}\}*)$: outputs its (string) arguments in
6957: prettyprint (beautified) format, ending with a newline.
6958:
6959: \subsubsecidx{printp1}$(\{\var{str}\}*)$: outputs its (string) arguments in
6960: prettyprint (beautified) format, without ending with a newline.
6961:
6962: \subsubsecidx{printtex}$(\{\var{str}\}*)$: outputs its (string) arguments in
6963: \TeX\ format. This output can then be used in a \TeX\ manuscript.
6964: The printing is done on the standard output. If you want to print it to a
6965: file you should use \kbd{writetex} (see there).
6966:
6967: Another possibility is to enable the \tet{log} default
6968: (see~\secref{se:defaults}).
6969: You could for instance do:\sidx{logfile}
6970: %
6971: \bprog
6972: default(logfile, "new.tex");
6973: default(log, 1);
6974: printtex(result);
6975: @eprog
6976: \noindent
6977: (You can use the automatic string expansion/concatenation process to have
6978: dynamic file names if you wish).
6979:
6980: \subsubsecidx{quit}$()$: exits GP.\label{se:quit}
6981:
6982: \subsubsecidx{read}$(\{\var{str}\})$: reads in the file whose name results
6983: from the expansion of the string \var{str}. If \var{str} is omitted,
6984: re-reads the last file that was fed into GP. The return value is the result of
6985: the last expression evaluated.\label{se:read} If a GP \tet{binary file} is
6986: read using this command (see \secref{se:writebin}), the file is loaded and
6987: the last object in the file is returned.
6988:
6989: \subsubsecidx{reorder}$(\{x=[\,]\})$: $x$ must be a vector. If $x$ is the
6990: empty vector, this gives the vector whose components are the existing
6991: variables in increasing order (i.e.~in decreasing importance). Killed
6992: variables (see \kbd{kill}) will be shown as \kbd{0}. If $x$ is
6993: non-empty, it must be a permutation of variable names, and this permutation
6994: gives a new order of importance of the variables, {\it for output only}. For
6995: example, if the existing order is \kbd{[x,y,z]}, then after
6996: \kbd{reorder([z,x])} the order of importance of the variables, with respect
6997: to output, will be \kbd{[z,y,x]}. The internal representation is unaffected.
6998: \label{se:reorder}
6999:
7000: \subsubsecidx{setrand}$(n)$: reseeds the random number generator to the value
7001: $n$. The initial seed is $n=1$.
7002:
7003: \syn{setrand}{n}, where $n$ is a \kbd{long}. Returns $n$.
7004:
7005: \subsubsecidxunix{system}$(\var{str})$: \var{str} is a string representing
7006: a system command. This command is executed, its output written to the
7007: standard output (this won't get into your logfile), and control returns
7008: to the PARI system. This simply calls the C \kbd{system} command.
7009:
7010: \subsubsecidx{trap}$(\{e\}, \{\var{rec}\}, \{\var{seq}\})$: tries to
7011: execute \var{seq}, trapping error $e$, that is effectively preventing it
7012: from aborting computations in the usual way; the recovery sequence
7013: \var{rec} is executed if the error occurs and the evaluation of \var{rec}
7014: becomes the result of the command. If $e$ is omitted, all exceptions are
7015: trapped. Note in particular that hitting \kbd{\pow C} (Control-C) raises an
7016: exception.
7017:
7018: \bprog
7019: ? \\@com trap division by 0
7020: ? inv(x) = trap (gdiver2, INFINITY, 1/x)
7021: ? inv(2)
7022: %1 = 1/2
7023: ? inv(0)
7024: %2 = INFINITY
7025: @eprog
7026:
7027: If \var{seq} is omitted, defines \var{rec} as a default action when
7028: encountering exception $e$. The error message is printed, as well as the
7029: result of the evaluation of \var{rec}, and the control is given back to the
7030: GP prompt. In particular, current computation is then lost.
7031:
7032: The following error handler prints the list of all user variables, then
7033: stores in a file their name and their values:
7034: \bprog
7035: ? { trap( ,
7036: print(reorder);
7037: write("crash", reorder);
7038: write("crash", eval(reorder))) }
7039: @eprog
7040:
7041: If no recovery code is given (\var{rec} is omitted) a so-called
7042: {\it\idx{break loop}} will be started. During a break loop, all commands are
7043: read and evaluated as during the main GP loop (except that no history of
7044: results is kept).
7045:
7046: To get out of the break loop, you can use \tet{next}, \tet{break} or
7047: \tet{return}; reading in a file by \b{r} will also terminate the loop once
7048: the file has been read (\kbd{read} will remain in the break loop). If the
7049: error is not fatal (\kbd{\pow C} is the only non-fatal error), \kbd{next}
7050: will continue the computation as if nothing had happened (except of course,
7051: you may have changed GP state during the break loop); otherwise control
7052: will come back to the GP prompt. After a user interrupt (\kbd{\pow C}),
7053: entering an empty input line (i.e hitting the return key) has the same
7054: effect as \kbd{next}.
7055:
7056: Break loops are useful as a debugging tool to inspect the values of GP
7057: variables to understand why a problem occurred, or to change GP behaviour
7058: (increase debugging level, start storing results in a logfile, modify
7059: parameters\dots) in the middle of a long computation (hit \kbd{\pow C}, type
7060: in your modifications, then type \kbd{next}).
7061:
7062: If \var{rec} is the empty string \kbd{""} the last default handler is popped
7063: out, and replaced by the previous one for that error.
7064:
7065: \misctitle{Note:} The interface is currently not adequate for trapping
7066: individual exceptions. In the current version \vers, the following keywords
7067: are recognized, but the name list will be expanded and changed in the
7068: future (all library mode errors can be trapped: it's a matter of defining
7069: the keywords to GP, and there are currently far too many useless ones):
7070:
7071: \kbd{accurer}: accuracy problem
7072:
7073: \kbd{gdiver2}: division by 0
7074:
7075: \kbd{invmoder}: impossible inverse modulo
7076:
7077: \kbd{archer}: not available on this architecture or operating system
7078:
7079: \kbd{typeer}: wrong type
7080:
7081: \kbd{errpile}: the PARI stack overflows
7082:
7083: \subsubsecidx{type}$(x,\{t\})$: this is useful only under GP. If $t$ is
7084: not present, returns the internal type number of the PARI object $x$.
7085: Otherwise, makes a copy of $x$ and sets its type equal to type $t$, which
7086: can be either a number or, preferably since internal codes may eventually
7087: change, a symbolic name such as \typ{FRACN} (you can skip the \typ{}
7088: part here, so that \kbd{FRACN} by itself would also be all right). Check out
7089: existing type names with the metacommand \b{t}.\label{se:gptype}
7090:
7091: GP won't let you create meaningless objects in this way where the internal
7092: structure doesn't match the type. This function can be useful to create
7093: reducible rationals (type \typ{FRACN}) or rational functions (type
7094: \typ{RFRACN}). In fact it's the only way to do so in GP. In this case, the
7095: created object, as well as the objects created from it, will not be reduced
7096: automatically, making some operations a bit faster.
7097:
7098: There is no equivalent library syntax, since the internal functions \kbd{typ}
7099: and \kbd{settyp} are available. Note that \kbd{settyp} does \var{not}
7100: create a copy of \kbd{x}, contrary to most PARI functions. It also doesn't
7101: check for consistency. \kbd{settyp} just changes the type in place and
7102: returns nothing. \kbd{typ} returns a C long integer. Note also the different
7103: spellings of the internal functions (\kbd{set})\kbd{typ} and of the GP
7104: function \kbd{type}, which is due to the fact that \kbd{type} is a reserved
7105: identifier for some C compilers.
7106:
7107: \subsubsecidx{whatnow}$(\var{key})$: if keyword \var{key} is the name
7108: of a function that was present in GP version 1.39.15 or lower, outputs
7109: the new function name and syntax, if it changed at all ($387$ out of $560$
7110: did).\label{se:whatnow}
7111:
7112: \subsubsecidx{write}$(\var{filename},\{\var{str}*\})$: writes (appends)
7113: to \var{filename} the remaining arguments, and appends a newline (same output
7114: as \kbd{print}).\label{se:write}
7115:
7116: \subsubsecidx{write1}$(\var{filename},\{\var{str}*\})$: writes (appends) to
7117: \var{filename} the remaining arguments without a trailing newline
7118: (same output as \kbd{print1}).
7119:
7120: \subsubsecidx{writebin}$(\var{filename},\{x\})$: writes (appends) to
7121: \var{filename} the object $x$ in binary format. This format is not human
7122: readable, but contains the exact internal structure of $x$, and is much
7123: faster to save/load than a string expression, as would be produced by
7124: \tet{write}. The binary file format includes a magic number, so that such a
7125: file can be recognized and correctly input by the regular \tet{read} or \b{r}
7126: function. If saved objects refer to (polynomial) variables that are not
7127: defined in the new session, they will be displayed in a funny way (see
7128: \secref{se:kill}).
7129:
7130: If $x$ is omitted, saves all user variables from the session, together with
7131: their names. Reading such a ``named object'' back in a GP session will set
7132: the corresponding user variable to the saved value. E.g after
7133: \bprog
7134: x = 1; writebin("log")
7135: @eprog
7136: \noindent reading \kbd{log} into a clean session will set \kbd{x} to $1$.
7137: The relative variables priorities of new variables set in this way remain the
7138: same (preset variables retain their former priority, but are set to the new
7139: value). In particular, reading such a session log into a clean session will
7140: restore all variables exactly as they were in the original one.
7141:
7142: User functions, installed functions and history objects can not be saved via
7143: this function. Just as a regular input file, a binary file can be compressed
7144: using \tet{gzip}, provided the file name has the standard \kbd{.gz}
7145: extension. \label{se:writebin}\sidx{binary file}
7146:
7147: \subsubsecidx{writetex}$(\var{filename},\{\var{str}*\})$: as \kbd{write},
7148: in \TeX\ format.\label{se:writetex}
7149:
7150: \vfill\eject
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to usersch3.tex CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM_contrib / pari-2.2 / doc