Annotation of OpenXM_contrib/pari/doc/usersch3.tex, Revision 1.1.1.1
1.1 maekawa 1: \chapter{Functions and Operations Available in PARI and GP}
2: \label{se:functions}
3:
4: The functions and operators available in PARI and in the GP/PARI calculator
5: are numerous and everexpanding. Here is a description of the ones available
6: in version \vers. It should be noted that many of these functions accept
7: quite different types as arguments, but others are more restricted. The list
8: of acceptable types will be given for each function or class of functions.
9: Except when stated otherwise, it is understood that a function or operation
10: which should make natural sense is legal. In this chapter, we will describe
11: the functions according to a rough classification. For the functions in
12: alphabetical order, see the general index. The general entry looks something
13: like:
14:
15: \key{foo}$(x,\{\fl=0\})$: short description.
16:
17: \syn{foo}{x,\fl}.
18:
19: \noindent
20: This means that the GP function \kbd{foo} has one mandatory argument $x$, and
21: an optional one, $\fl$, whose default value is 0 (the $\{\}$ should never be
22: typed, it is just a convenient notation we will use throughout to denote
23: optional arguments). That is, you can type \kbd{foo(x,2)}, or \kbd{foo(x)},
24: which is then understood to mean \kbd{foo(x,0)}. As well, a comma or closing
25: parenthesis, where an optional argument should have been, signals to GP it
26: should use the default. Thus, the syntax \kbd{foo(x,)} is also accepted as a
27: synonym for our last expression. When a function has more than one optional
28: argument, the argument list is filled with user supplied values, in order.
29: And when none are left, the defaults are used instead. Thus, assuming that
30: \kbd{foo}'s prototype had been
31: $$\hbox{%
32: \key{foo}$(\{x=1\},\{y=2\},\{z=3\})$,%
33: }$$
34: typing in \kbd{foo(6,4)} would give
35: you \kbd{foo(6,4,3)}. In the rare case when you want to set some far away
36: flag, and leave the defaults in between as they stand, you can use the
37: ``empty arg'' trick alluded to above: \kbd{foo(6,,1)} would yield
38: \kbd{foo(6,2,1)}. By the way, \kbd{foo()} by itself yields
39: \kbd{foo(1,2,3)} as was to be expected. In this rather special case of a
40: function having no mandatory argument, you can even omit the $()$: a
41: standalone \kbd{foo} would be enough (though we don't really recommend it for
42: your scripts, for the sake of clarity). In defining GP syntax, we strove
43: to put optional arguments at the end of the argument list (of course, since
44: they would not make sense otherwise), and in order of decreasing usefulness
45: so that, most of the time, you will be able to ignore them.
46:
47: For some of these optional flags, we adopted the customary binary notation as
48: a compact way to represent many toggles with just one number. Letting
49: $(p_0,\dots,p_n)$ be a list of switches (i.e.~of properties which can be
50: assumed to take either the value $0$ or~$1$), the number $2^3 + 2^5=40$
51: means that $p_3$ and $p_5$ have been set (that is, set to $1$), and none
52: of the others were (that is, they were set to 0). This will usually be
53: announced as ``The binary digits of $\fl$ mean 1: $p_0$, 2: $p_1$, 4:
54: $p_2$'', and so on, using the available consecutive powers of~$2$.
55:
56: To finish with our generic simple-minded example, the {\it library\/} function
57: \kbd{foo}, as defined above, is seen to have two mandatory arguments,
58: $x$ and \fl (no PARI mathematical function has been implemented so
59: as to accept a variable number of arguments). When not mentioned otherwise,
60: the result and arguments of a function are assumed implicitly to be of type
61: \kbd{GEN}. Most other functions return an object of type \kbd{long} integer
62: in C (see Chapter~4). The variable or parameter names \var{prec} and \fl\
63: always denote \kbd{long} integers.
64:
65: \misctitle{Pointers}. If a parameter in the function prototype is prefixed
66: with a \& sign, as in
67:
68: \key{foo}$(x,\&e)$
69:
70: \noindent it means that, besides the normal return value, the variable named
71: $e$ may be set as a side effect. When passing the argument, the \& sign has
72: to be typed in explicitly. As of version \vers{}, this \tet{pointer} argument
73: is optional for all documented functions, hence the \& will always appear
74: between brackets as in \kbd{issquare}$(x,\{\&e\})$.
75:
76: \section{Standard monadic or dyadic operators}
77:
78: \subseckbd{+$/$-}: The expressions \kbd{+}$x$ and \kbd{-}$x$ refer
79: to monadic operators (the first does nothing, the second negates $x$).
80:
81: \syn{gneg}{x} for \kbd{-}$x$.
82:
83: \subseckbd{+}, \kbd{-}: The expression $x$ \kbd{+} $y$ is the \idx{sum} and
84: $x$ \kbd{-} $y$ is the \idx{difference} of $x$ and $y$. Among the prominent
85: impossibilities are addition/subtraction between a scalar type and a vector
86: or a matrix, between vector/matrices of incompatible sizes and between an
87: integermod and a real number.
88:
89: \syn{gadd}{x,y} $x$ \kbd{+} $y$, $\teb{gsub}(x,y)$ for $x$ \kbd{-} $y$.
90:
91: \subseckbd{*}: The expression $x$ \kbd{*} $y$ is the \idx{product} of $x$
92: and $y$. Among the prominent impossibilities are multiplication between
93: vector/matrices of incompatible sizes, between an integermod and a real
94: number. Note that because of vector and matrix operations, \kbd{*} is not
95: necessarily commutative. Note also that since multiplication between two
96: column or two row vectors is not allowed, to obtain the \idx{scalar product}
97: of two vectors of the same length, you must multiply a line vector by a
98: column vector, if necessary by transposing one of the vectors (using
99: the operator \kbd{\til} or the function \kbd{mattranspose}, see
100: \secref{se:linear_algebra}).
101:
102: If $x$ and $y$ are binary quadratic forms, compose them. See also
103: \kbd{qfbnucomp} and \kbd{qfbnupow}.
104:
105: \syn{gmul}{x,y} for $x$ \kbd{*} $y$. Also available is
106: $\teb{gsqr}(x)$ for $x$ \kbd{*} $x$ (faster of course!).
107:
108: \subseckbd{/}: The expression $x$ \kbd{/} $y$ is the \idx{quotient} of $x$
109: and $y$. In addition to the impossibilities for multiplication, note that if
110: the divisor is a matrix, it must be an invertible square matrix, and in that
111: case the result is $x*y^{-1}$. Furthermore note that the result is as exact
112: as possible: in particular, division of two integers always gives a rational
113: number (which may be an integer if the quotient is exact) and {\it not\/} the
114: Euclidean quotient (see $x$ \kbd{\bs} $y$ for that), and similarly the
115: quotient of two polynomials is a rational function in general. To obtain the
116: approximate real value of the quotient of two integers, add \kbd{0.} to the
117: result; to obtain the approximate $p$-adic value of the quotient of two
118: integers, add \kbd{O(p\pow k)} to the result; finally, to obtain the
119: \idx{Taylor series} expansion of the quotient of two polynomials, add
120: \kbd{O(X\pow k)} to the result or use the \kbd{taylor} function
121: (see \secref{se:taylor}). \label{se:gdiv}
122:
123: \syn{gdiv}{x,y}for $x$ \kbd{/} $y$.
124:
125: \subseckbd{\bs}: The expression $x$ \kbd{\bs} $y$ is the
126: % keep "Euclidean" and "quotient" on same line for gphelp
127: \idx{Euclidean quotient} of $x$ and $y$. The types must be either both
128: integer or both polynomials. The result is the Euclidean quotient. In the
129: case of integer division, the quotient is such that the corresponding
130: remainder is non-negative.
131:
132: \syn{gdivent}{x,y} for $x$ \kbd{\bs} $y$.
133:
134: \subseckbd{\bs/}: The expression $x$ \b{/} $y$ is the Euclidean
135: quotient of $x$ and $y$. The types must be either both integer or both
136: polynomials. The result is the rounded Euclidean quotient. In the case of
137: integer division, the quotient is such that the corresponding remainder is
138: smallest in absolute value and in case of a tie the quotient closest to
139: $+\infty$ is chosen.
140:
141: \syn{gdivround}{x,y} for $x$ \b{/} $y$.
142:
143: \subseckbd{\%}: The expression $x$ \kbd{\%} $y$ is the
144: % keep "Euclidean" and "remainder" on same line for gphelp
145: \idx{Euclidean remainder} of $x$ and $y$. The modulus $y$ must be of type
146: integer or polynomial. The result is the remainder, always non-negative in
147: the case of integers. Allowed dividend types are scalar exact types when
148: the modulus is an integer, and polynomials, polmods and rational functions
149: when the modulus is a polynomial.
150:
151: \syn{gmod}{x,y} for $x$ \kbd{\%} $y$.
152:
153: \subsecidx{divrem}$(x,y)$: creates a column vector with two components,
154: the first being the Euclidean quotient, the second the Euclidean remainder,
155: of the division of $x$ by $y$. This avoids the need to do two divisions if
156: one needs both the quotient and the remainder. The arguments must be both
157: integers or both polynomials; in the case of integers, the remainder is
158: non-negative.
159:
160: \syn{gdiventres}{x,y}.
161:
162: \subseckbd{\pow}: The expression $x\hbox{\kbd{\pow}}y$ is \idx{powering}. If
163: the exponent is an integer, then exact operations are performed using binary
164: (left-shift) powering techniques. In particular, in this case the first
165: argument cannot be a vector or matrix unless it is a square matrix (and
166: moreover invertible if the exponent is negative). If the exponent is not of
167: type integer, this is treated as a transcendental function (see
168: \secref{se:trans}), and in particular has the effect of componentwise
169: powering on vector or matrices.
170:
171: \syn{gpow}{x,y,\var{prec}} for $x\hbox{\kbd{\pow}}y$.
172:
173: \subsecidx{shift}$(x,n)$ or $x$ \kbd{<<} $n$ (= $x$ \kbd{>>} $(-n)$): shifts
174: $x$ componentwise left by $n$ bits if $n\ge0$ and right by $|n|$ bits if
175: $n<0$. A left shift by $n$ corresponds to multiplication by $2^n$. A right
176: shift of an integer $x$ by $|n|$ corresponds to a Euclidean division of
177: $x$ by $2^{|n|}$ with a
178: remainder of the same sign as $x$, hence is not the same (in general) as
179: $x \kbd{\bs} 2^n$.
180:
181: \syn{gshift}{x,n} where $n$ is a \kbd{long}.
182:
183: \subsecidx{shiftmul}$(x,n)$: multiplies $x$ by $2^n$. The difference with
184: \kbd{shift} is that when $n<0$, ordinary division takes place, hence for
185: example if $x$ is an integer the result may be a fraction, while for
186: \kbd{shift} Euclidean division takes place when $n<0$ hence if $x$ is an
187: integer the result is still an integer.
188:
189: \syn{gmul2n}{x,n} where $n$ is a \kbd{long}.
190:
191: \subsec{Comparison and boolean operators}.\sidx{boolean operators}
192: The six standard \idx{comparison operators} \kbd{<=}, \kbd{<}, \kbd{>=},
193: \kbd{>}, \kbd{==}, \kbd{!=} are available in GP, and in library mode under
194: the names \teb{gle}, \teb{glt}, \teb{gge}, \teb{ggt}, \teb{geq}, \teb{gne}
195: respectively. The library syntax is ${\it co}(x,y)$, where {\it co} is the
196: comparison operator. The result is 1 (as a \kbd{GEN}) if the comparison is
197: true, 0 (as a \kbd{GEN}) if it is false.
198:
199: The standard boolean functions \kbd{||} (\idx{inclusive or}), \kbd{\&\&}
200: (\idx{and})\sidx{or} and \kbd{!} (\idx{not}) are also available, and the
201: library syntax is $\teb{gor}(x,y)$, $\teb{gand}(x,y)$ and $\teb{gnot}(x)$
202: respectively.
203:
204: In library mode, it is in fact usually preferable to use the two basic
205: functions which are $\teb{gcmp}(x,y)$ which gives the sign (1, 0, or -1) of
206: $x-y$, where $x$ and $y$ must be in $\R$, and $\teb{gegal}(x,y)$ which
207: can be applied to any two PARI objects $x$ and $y$ and gives 1 (i.e.~true) if
208: they are equal (but not necessarily identical), 0 (i.e.~false) otherwise.
209: Particular cases of \teb{gegal} which should be used are $\teb{gcmp0}(x)$
210: ($x==0$ ?), $\teb{gcmp1}(x)$ ($x==1$ ?), and\sidx{gcmp\string\_1}
211: \key{gcmp\_1}$(x)$ ($x==-1$ ?).
212:
213: Note that $\teb{gcmp0}(x)$ tests whether $x$ is equal to zero, even if $x$ is
214: not an exact object. To test whether $x$ is an exact object which is equal to
215: zero, one must use $\teb{isexactzero}$.
216:
217: Also note that the \kbd{gcmp} and \kbd{gegal} functions return a C-integer,
218: and {\it not\/} a \kbd{GEN} like \kbd{gle} etc.
219:
220: \smallskip
221: GP accepts the following synonyms for some of the above functions: since
222: there is no bitwise \kbd{and} or bitwise \kbd{or}, \kbd{|} and \kbd{\&} are
223: accepted as\sidx{bitwise and}\sidx{bitwise or} synonyms of \kbd{||} and
224: \kbd{\&\&} respectively. Also, \kbd{<>} is accepted as a synonym for
225: \kbd{!=}. On the other hand, \kbd{=} is definitely {\it not\/} a synonym for
226: \kbd{==} since it is the assignment statement.
227:
228: \subsecidx{lex}$(x,y)$: gives the result of a lexicographic comparison
229: between $x$ and $y$. This is to be interpreted in quite a wide sense. For
230: example, the vector $[1,3]$ will be considered smaller than the longer
231: vector $[1,3,-1]$ (but of course larger than $[1,2,5]$),
232: i.e.~\kbd{lex([1,3], [1,3,-1])} will return $-1$.
233:
234: \syn{lexcmp}{x,y}.
235:
236: \subsecidx{sign}$(x)$: \idx{sign} ($0$, $1$ or $-1$) of $x$, which must be of
237: type integer, real or fraction.
238:
239: \syn{gsigne}{x}. The result is a \kbd{long}.
240:
241: \subsecidx{max}$(x,y)$ and \teb{min}$(x,y)$: creates the
242: maximum and minimum of $x$ and $y$ when they can be compared.
243:
244: \syn{gmax}{x,y} and $\teb{gmin}(x,y)$.
245:
246: \subsecidx{vecmax}$(x)$: if $x$ is a vector or a matrix, returns the maximum
247: of the elements of $x$, otherwise returns a copy of $x$. Returns $-\infty$
248: in the form of $-(2^{31}-1)$ (or $-(2^{63}-1)$ for 64-bit machines) if $x$ is
249: empty.
250:
251: \syn{vecmax}{x}.
252:
253: \subsecidx{vecmin}$(x)$: if $x$ is a vector or a matrix, returns the minimum
254: of the elements of $x$, otherwise returns a copy of $x$. Returns $+\infty$
255: in the form of $2^{31}-1$ (or $2^{63}-1$ for 64-bit machines) if $x$ is empty.
256:
257: \syn{vecmin}{x}.
258:
259: \section{Conversions and similar elementary functions or commands}
260: \label{se:conversion}
261:
262: \noindent
263: Many of the conversion functions are rounding or truncating operations. In
264: this case, if the argument is a rational function, the result is the
265: Euclidean quotient of the numerator by the denominator, and if the argument
266: is a vector or a matrix, the operation is done componentwise. This will not
267: be restated for every function.
268:
269: \subsecidx{List}$({x=[\,]})$: transforms a (row or column) vector $x$
270: into a list. The only other way to create a \typ{LIST} is to use the
271: function \kbd{listcreate}.
272:
273: This is useless in library mode.
274:
275: \subsecidx{Mat}$({x=[\,]})$: transforms the object $x$ into a matrix.
276: If $x$ is not a vector or a matrix, this creates a $1\times 1$ matrix.
277: If $x$ is a row (resp. column) vector, this creates a 1-row (resp.
278: 1-column) matrix. If $x$ is already a matrix, a copy of $x$ is created.
279:
280: This function can be useful in connection with the function \kbd{concat}
281: (see there).
282:
283: \syn{gtomat}{x}.
284:
285: \subsecidx{Mod}$(x,y,\{\fl=0\})$:\label{se:Mod} creates the PARI object
286: $(x \mod y)$, i.e.~an integermod or a polmod. $y$ must be an integer or a
287: polynomial. If $y$ is an integer, $x$ must be an integer. If $y$ is a
288: polynomial, $x$ must be a scalar or a polynomial. The result is put on the
289: PARI stack.
290:
291: This function is not the same as $x$ \kbd{\%} $y$, the result of which is an
292: integer or a polynomial.
293:
294: If $\fl$ is equal to $1$, the modulus of the created result is put on the
295: heap and not on the stack, and hence becomes a permanent copy which cannot be
296: erased later by garbage collecting (see \secref{se:garbage}). In particular,
297: care should be taken to avoid creating too many such objects, since the heap
298: is very small (typically a few thousand objects at most).
299:
300: \syn{Mod0}{x,y,\fl}. Also available are
301:
302: $\bullet$ for $\fl=1$: $\teb{gmodulo}(x,y)$.
303:
304: $\bullet$ for $\fl=0$: $\teb{gmodulcp}(x,y)$.
305:
306: \subsecidx{Pol}$(x,\{v=x\})$: transforms the object $x$ into a polynomial with
307: main variable $v$. If $x$ is a scalar, this gives a constant polynomial. If
308: $x$ is a power series, the effect is identical to \kbd{truncate} (see there),
309: i.e.~it chops off the $O(X^k)$. If $x$ is a vector, this function creates
310: the polynomial whose coefficients are given in $x$, with $x[1]$ being the
311: leading coefficient (which can be zero).
312:
313: Warning: this is {\it not\/} a substitution function. It is intended to be
314: quick and dirty. So if you try \kbd{Pol(a,y)} on the polynomial \kbd{a = x+y},
315: you will get \kbd{y+y}, which is not a valid PARI object.
316:
317: \syn{gtopoly}{x,v}, where $v$ is a variable number.
318:
319: \subsecidx{Polrev}$(x,\{v=x\})$: transform the object $x$ into a polynomial
320: with main variable $v$. If $x$ is a scalar, this gives a constant polynomial.
321: If $x$ is a power series, the effect is identical to \kbd{truncate} (see
322: there), i.e.~it chops off the $O(X^k)$. If $x$ is a vector, this function
323: creates the polynomial whose coefficients are given in $x$, with $x[1]$ being
324: the constant term. Note that this is the reverse of \kbd{Pol} if $x$ is a
325: vector, otherwise it is identical to \kbd{Pol}.
326:
327: \syn{gtopolyrev}{x,v}, where $v$ is a variable number.
328:
329: \subsecidx{Ser}$(x,\{v=x\})$: transforms the object $x$ into a power series
330: with main variable $v$ ($x$ by default). If $x$ is a scalar, this gives a
331: constant power series with precision given by the default \kbd{serieslength}
332: (corresponding to the C global variable \kbd{precdl}). If $x$ is a
333: polynomial, the precision is the greatest of \kbd{precdl} and the degree of
334: the polynomial. If $x$ is a vector, the precision is similarly given, and the
335: coefficients of the vector are understood to be the coefficients of the power
336: series starting from the constant term (i.e.~the reverse of the function
337: \kbd{Pol}).
338:
339: The warning given for \kbd{Pol} applies here: this is not a substitution
340: function.
341:
342: \syn{gtoser}{x,v}, where $v$ is a variable number (i.e.~a C integer).
343:
344: \subsecidx{Set}$(\{x=[\,]\})$: converts $x$ into a set, i.e.~into a row vector
345: with strictly increasing entries. $x$ can be of any type, but is most useful
346: when $x$ is already a vector. The components of $x$ are put in canonical form
347: (type \typ{STR}) so as to be easily sorted. To recover an ordinary \kbd{GEN}
348: from such an element, you can apply \tet{eval} to it.
349:
350: \syn{gtoset}{x}.
351:
352: \subsecidx{Str}$(\{x=\hbox{\kbd{""}}\},\{\fl=0\})$: converts $x$ into a
353: character string (type \typ{STR}, the empty string if $x$ is omitted). To
354: recover an ordinary \kbd{GEN} from a string, apply \kbd{eval} to it. The
355: arguments of \kbd{Str} are evaluated in string context (see
356: \secref{se:strings}). If \fl\ is set, treat $x$ as a filename and perform
357: \idx{environment expansion} on the string. This feature can be used to read
358: \idx{environment variable} values.
359:
360: \bprog%
361: ? i = 1; Str("x" i)
362: \%1 = "x1"
363: ? eval(\%)
364: \%2 = x1;
365: ? Str("\$HOME", 1)
366: \%2 = "/home/pari"
367: \eprog
368:
369: \syn{strtoGENstr}{x,\fl}. This function is mostly useless in library mode. Use
370: the pair \tet{strtoGEN}/\tet{GENtostr} to convert between \kbd{char*} and
371: \kbd{GEN}.
372:
373: \subsecidx{Vec}$({x=[\,]})$: transforms the object $x$ into a row vector. The
374: vector will be with one component only, except when $x$ is a vector/matrix or
375: a quadratic form (in which case the resulting vector is simply the initial
376: object considered as a row vector), but more importantly when $x$ is a
377: polynomial or a power series. In the case of a polynomial, the coefficients
378: of the vector start with the leading coefficient of the polynomial, while
379: for power series only the significant coefficients are taken into account,
380: but this time by increasing order of degree.
381:
382: \syn{gtovec}{x}.
383:
384: \subsecidx{binary}$(x)$: outputs the vector of the binary digits of $|x|$.
385: Here $x$ can be an integer, a real number (in which case the result has two
386: components, one for the integer part, one for the fractional part) or a
387: vector/matrix.
388:
389: \syn{binaire}{x}.
390:
391: \subsecidx{bittest}$(x,n)$: outputs the $n^{\text{th}}$ bit of $|x|$ starting
392: from the right (i.e.~the coefficient of $2^n$ in the binary expansion of $x$).
393: The result is 0 or 1. To extract several bits at once as a vector, pass a
394: vector for $n$.
395:
396: \syn{bittest}{x,n}, where $n$ and the result are \kbd{long}s.
397:
398: \subsecidx{ceil}$(x)$: ceiling of $x$. When $x$ is in $\R$,
399: the result is the smallest integer greater than or equal to $x$.
400:
401: \syn{gceil}{x}.
402:
403: \subsecidx{centerlift}$(x,\{v\})$: lifts an element $x=a \bmod n$ of $\Z/n\Z$
404: to $a$ in $\Z$, and similarly lifts a polmod to a polynomial. This is the
405: same as \kbd{lift} except that in the particular case of elements of
406: $\Z/n\Z$, the lift $y$ is such that $-n/2<y\le n/2$. If $x$ is of type
407: fraction, complex, quadratic, polynomial, power series, rational function,
408: vector or matrix, the lift is done for each coefficient. Real and $p$-adics
409: are forbidden.
410:
411: \syn{centerlift0}{x,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded
412: as $-1$. Also available is \teb{centerlift}$(x)$ = \kbd{centerlift0($x$,-1)}.
413:
414: \subsecidx{changevar}$(x,y)$: creates a copy of the object $x$ where its
415: variables are modified according to the permutation specified by the vector
416: $y$. For example, assume that the variables have been introduced in the
417: order \kbd{x}, \kbd{a}, \kbd{b}, \kbd{c}. Then, if $y$ is the vector
418: \kbd{[x,c,a,b]}, the variable \kbd{a} will be replaced by \kbd{c}, \kbd{b} by
419: \kbd{a}, and \kbd{c} by \kbd{b}, \kbd{x} being unchanged. Note that the
420: permutation must be completely specified, e.g.~\kbd{[c,a,b]} would not work,
421: since this would replace \kbd{x} by \kbd{c}, and leave \kbd{a} and \kbd{b}
422: unchanged (as well as \kbd{c} which is the fourth variable of the initial
423: list). In particular, the new variable names must be distinct.
424:
425: \syn{changevar}{x,y}.
426:
427: \subsec{components of a PARI object}:
428:
429: There are essentially three ways to extract the \idx{components} from a PARI
430: object.
431:
432: The first and most general, is the function $\teb{component}(x,n)$ which
433: extracts the $n^{\text{th}}$-component of $x$. This is to be understood as
434: follows: every PARI type has one or two initial \idx{code words}. The
435: components are counted, starting at 1, after these code words. In particular
436: if $x$ is a vector, this is indeed the $n^{\text{th}}$-component of $x$, if
437: $x$ is a matrix, the $n^{\text{th}}$ column, if $x$ is a polynomial, the
438: $n^{\text{th}}$ coefficient (i.e.~of degree $n-1$), and for power series, the
439: $n^{\text{th}}$ significant coefficient. The use of the function
440: \kbd{component} implies the knowledge of the structure of the different PARI
441: types, which can be recalled by typing \b{t} under GP.
442:
443: \syn{compo}{x,n}, where $n$ is a \kbd{long}.
444:
445: The two other methods are more natural but more restricted. First, the
446: function $\teb{polcoeff}(x,n)$ gives the coefficient of degree $n$ of the
447: polynomial or power series $x$, with respect to the main variable of $x$ (to
448: see the order of the variables or to change it, use the function
449: \tet{reorder}, see \secref{se:reorder}). In particular if $n$ is less than
450: the valuation of $x$ or in the case of a polynomial, greater than the degree,
451: the result is zero (contrary to \kbd{compo} which would send an error
452: message). If $x$ is a power series and $n$ is greater than the largest
453: significant degree, then an error message is issued.
454:
455: For greater flexibility, vector or matrix types are also accepted for $x$,
456: and the meaning is then identical with that of \kbd{compo}.
457:
458: Finally note that a scalar type is considered by \kbd{polcoeff} as a
459: polynomial of degree zero.
460:
461: \syn{truecoeff}{x,n}.
462:
463: The third method is specific to vectors or matrices under GP. If $x$ is a
464: (row or column) vector, then \tet{x[n]} represents the $n^{\text{th}}$
465: component of $x$, i.e.~\kbd{compo(x,n)}. It is more natural and shorter to
466: write. If $x$ is a matrix, \tet{x[m,n]} represents the coefficient of
467: row \kbd{m} and column \kbd{n} of the matrix, \tet{x[m,]} represents
468: the $m^{\text{th}}$ {\it row\/} of $x$, and \tet{x[,n]} represents
469: the $n^{\text{th}}$ {\it column\/} of $x$.
470:
471: Finally note that in library mode, the macros \teb{coeff} and \teb{mael}
472: are available to deal with the non-recursivity of the \kbd{GEN} type from the
473: compiler's point of view. See the discussion on typecasts in Chapter 4.
474:
475: \subsecidx{conj}$(x)$: conjugate of $x$. The meaning of this
476: is clear, except that for real quadratic numbers, it means conjugation in the
477: real quadratic field. This function has no effect on integers, reals,
478: integermods, fractions or $p$-adics. The only forbidden type is polmod
479: (see \kbd{conjvec} for this).
480:
481: \syn{gconj}{x}.
482:
483: \subsecidx{conjvec}$(x)$: conjugate vector representation of $x$. If $x$ is a
484: polmod, equal to \kbd{Mod}$(a,q)$, this gives a vector of length
485: $\text{degree}(q)$ containing the complex embeddings of the polmod if $q$ has
486: integral or rational coefficients, and the conjugates of the polmod if $q$
487: has some integermod coefficients. The order is the same as that of the
488: \kbd{polroots} functions. If $x$ is an integer or a rational number, the
489: result is~$x$. If $x$ is a (row or column) vector, the result is a matrix
490: whose columns are the conjugate vectors of the individual elements of $x$.
491:
492: \syn{conjvec}{x,\var{prec}}.
493:
494: \subsecidx{denominator}$(x)$: lowest denominator of $x$. The meaning of this
495: is clear when $x$ is a rational number or function. When $x$ is an integer
496: or a polynomial, the result is equal to $1$. When $x$ is a vector or a matrix,
497: the lowest common denominator of the components of $x$ is computed. All other
498: types are forbidden.
499:
500: \syn{denom}{x}.
501:
502: \subsecidx{floor}$(x)$: floor of $x$. When $x$ is in $\R$,
503: the result is the largest integer smaller than or equal to $x$.
504:
505: \syn{gfloor}{x}.
506:
507: \subsecidx{frac}$(x)$: fractional part of $x$. Identical to
508: $x-\text{floor}(x)$. If $x$ is real, the result is in $[0,1[$.
509:
510: \syn{gfrac}{x}.
511:
512: \subsecidx{imag}$(x)$: imaginary part of $x$. When
513: $x$ is a quadratic number, this is the coefficient of $\omega$ in
514: the ``canonical'' integral basis $(1,\omega)$.
515:
516: \syn{gimag}{x}.
517:
518: \subsecidx{length}$(x)$: number of non-code words in $x$ really used (i.e.~the
519: effective length minus 2 for integers and polynomials). In particular,
520: the degree of a polynomial is equal to its length minus 1. If $x$ has type
521: \typ{STR}, output number of letters.
522:
523: \syn{glength}{x} and the result is a C long.
524:
525: \subsecidx{lift}$(x,\{v\})$: lifts an element $x=a \bmod n$ of $\Z/n\Z$ to
526: $a$ in $\Z$, and similarly lifts a polmod to a polynomial if $v$ is omitted.
527: Otherwise, lifts only polmods with main variable $v$ (if $v$ does not occur
528: in $x$, lifts only intmods). If $x$ is of type fraction, complex, quadratic,
529: polynomial, power series, rational function, vector or matrix, the lift is
530: done for each coefficient. Forbidden types for $x$ are reals and $p$-adics.
531:
532: \syn{lift0}{x,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded as
533: $-1$. Also available is \teb{lift}$(x)$ = \kbd{lift0($x$,-1)}.
534:
535: \subsecidx{norm}$(x)$: algebraic norm of $x$, i.e.~the product of $x$ with
536: its conjugate (no square roots are taken), or conjugates for polmods. For
537: vectors and matrices, the norm is taken componentwise and hence is not the
538: $L^2$-norm (see \kbd{norml2}). Note that the norm of an element of
539: $\R$ is its square, so as to be compatible with the complex norm.
540:
541: \syn{gnorm}{x}.
542:
543: \subsecidx{norml2}$(x)$: square of the $L^2$-norm of $x$. $x$ must
544: be a (row or column) vector.
545:
546: \syn{gnorml2}{x}.
547:
548: \subsecidx{numerator}$(x)$: numerator of $x$. When $x$ is a rational number
549: or function, the meaning is clear. When $x$ is an integer or a polynomial,
550: the result is $x$ itself. When $x$ is a vector or a matrix, then
551: \kbd{numerator(x)} is defined to be \kbd{denominator(x)*x}. All other types
552: are forbidden.
553:
554: \syn{numer}{x}.
555:
556: \subsecidx{numtoperm}$(n,k)$: generates the $k$-th permutation (as a
557: row vector of length $n$) of the numbers $1$ to $n$. The number $k$ is taken
558: modulo $n!\,$, i.e.~inverse function of \tet{permtonum}.
559:
560: \syn{permute}{n,k}, where $n$ is a \kbd{long}.
561:
562: \subsecidx{padicprec}$(x,p)$: absolute $p$-adic precision of the object $x$.
563: This is the minimum precision of the components of $x$. The result is
564: \kbd{VERYBIGINT} ($2^{31}-1$ for 32-bit machines or $2^{63}-1$ for 64-bit
565: machines) if $x$ is an exact object.
566:
567: \syn{padicprec}{x,p} and the result is a \kbd{long}
568: integer.
569:
570: \subsecidx{permtonum}$(x)$: given a permutation $x$ on $n$ elements,
571: gives the number $k$ such that $x=\kbd{numtoperm(n,k)}$, i.e.~inverse
572: function of \tet{numtoperm}.
573:
574: \syn{permuteInv}{x}.
575:
576: \subsecidx{precision}$(x,\{n\})$: gives the precision in decimal digits of the
577: PARI object $x$. If $x$ is an exact object, the largest single precision
578: integer is returned. If $n$ is not omitted, creates a new object equal to $x$
579: with a new precision $n$. This is to be understood as follows:
580:
581: For exact types, no change. For $x$ a vector or a matrix, the operation
582: is done componentwise.
583:
584: For real $x$, $n$ is the number of desired significant {\it decimal} digits.
585: If $n$ is smaller than the precision of $x$, $x$ is truncated, otherwise $x$
586: is extended with zeros.
587:
588: For $x$ a $p$-adic or a power series, $n$ is the desired number of
589: significant $p$-adic or $X$-adic digits, where $X$ is the main variable of
590: $x$.
591:
592: Note that the function \kbd{precision} never changes the type of the result.
593: In particular it is not possible to use it to obtain a polynomial from a
594: power series. For that, see \kbd{truncate}.
595:
596: \syn{precision0}{x,n}, where $n$ is a \kbd{long}. Also available are
597: $\teb{ggprecision}(x)$ (result is a \kbd{GEN}) and $\teb{gprec}(x,n)$, where
598: $n$ is a \kbd{long}.
599:
600: \subsecidx{random}$(\{N=2^{31}\})$: gives a random integer between 0 and
601: $N-1$. $N$ can be arbitrary large. This is an internal PARI function and does
602: not depend on the system's random number generator. Note that the resulting
603: integer is obtained by means of linear congruences and will not be well
604: distributed in arithmetic progressions.
605:
606: \syn{genrand}{N}.
607:
608: \subsecidx{real}$(x)$: real part of $x$. In the case where $x$ is a quadratic
609: number, this is the coefficient of $1$ in the ``canonical'' integral basis
610: $(1,\omega)$.
611:
612: \syn{greal}{x}.
613:
614: \subsecidx{round}$(x,\{\&e\})$: If $x$ is in $\R$, rounds $x$ to the nearest
615: integer and set $e$ to the number of error bits, that is the binary exponent
616: of the difference between the original and the rounded value (the
617: ``fractional part''). If the exponent of $x$ is too large compared to its
618: precision (i.e.~$e>0$), the result is undefined and an error occurs if $e$
619: was not given.
620:
621: \misctitle{Important remark:} note that, contrary to the other truncation
622: functions, this function operates on every coefficient at every level of a
623: PARI object. For example
624: $$\text{truncate}\left(\dfrac{2.4*X^2-1.7}{X}\right)=2.4*X,$$ whereas
625: $$\text{round}\left(\dfrac{2.4*X^2-1.7}{X}\right)=\dfrac{2*X^2-2}{X}.$$
626: An important use of \kbd{round} is to get exact results after a long
627: approximate computation, when theory tells you that the coefficients
628: must be integers.
629:
630: \syn{grndtoi}{x,\&e}, where $e$ is a \kbd{long} integer. Also available is
631: $\teb{ground}(x)$.
632:
633: \subsecidx{simplify}$(x)$: this function tries to simplify the object $x$ as
634: much as it can. The simplifications do not concern rational functions (which
635: PARI automatically tries to simplify), but type changes. Specifically, a
636: complex or quadratic number whose imaginary part is exactly equal to 0
637: (i.e.~not a real zero) is converted to its real part, and a polynomial of
638: degree zero is converted to its constant term. For all types, this of course
639: occurs recursively. This function is useful in any case, but in particular
640: before the use of arithmetic functions which expect integer arguments, and
641: not for example a complex number of 0 imaginary part and integer real part
642: (which is however printed as an integer).
643:
644: \syn{simplify}{x}.
645:
646: \subsecidx{sizebyte}$(x)$: outputs the total number of bytes occupied by the
647: tree representing the PARI object $x$.
648:
649: \syn{taille2}{x} which returns a \kbd{long}. The
650: function \teb{taille} returns the number of {\it words} instead.
651:
652: \subsecidx{sizedigit}$(x)$: outputs a quick bound for the number of decimal
653: digits of (the components of) $x$, off by at most $1$. If you want the
654: exact value, you an use \kbd{length(Str(x))}, which is much slower.
655:
656: \syn{gsize}{x} which returns a \kbd{long}.
657:
658: \subsecidx{truncate}$(x,\{\&e\})$: truncate $x$ and set $e$ to the number of
659: error bits. When $x$ is in $\R$, this means that the part after the decimal
660: point is chopped away, integer and set $e$ to the number of error bits that
661: is the binary exponent of the difference between the original and the
662: truncated value (the ``fractional part''). If the exponent of $x$ is too
663: large compared to its precision (i.e.~$e>0$), the result is undefined and an
664: error occurs if $e$ was not given.
665:
666: Note a very special use of \kbd{truncate}: when applied to a power series, it
667: transforms it into a polynomial or a rational function with denominator
668: a power of $X$, by chopping away the $O(X^k)$. Similarly, when applied to
669: a $p$-adic number, it transforms it into an integer or a rational number
670: by chopping away the $O(p^k)$.
671:
672: \syn{gcvtoi}{x,\&e}, where $e$ is a \kbd{long} integer. Also available is
673: \teb{gtrunc}$(x)$.
674:
675: \subsecidx{valuation}$(x,p)$:\label{se:valuation} computes the highest
676: exponent of $p$ dividing $x$. If $p$ is of type integer, $x$ must be an
677: integer, an integermod whose modulus is divisible by $p$, a fraction, a
678: $q$-adic number with $q=p$, or a polynomial or power series in which case the
679: valuation is the minimum of the valuation of the coefficients.
680:
681: If $p$ is of type polynomial, $x$ must be of type polynomial or rational
682: function, and also a power series if $x$ is a monomial. Finally, the
683: valuation of a vector, complex or quadratic number is the minimum of the
684: component valuations.
685:
686: If $x=0$, the result is \kbd{VERYBIGINT} ($2^{31}-1$ for 32-bit machines or
687: $2^{63}-1$ for 64-bit machines) if $x$ is an exact object. If $x$ is a
688: $p$-adic numbers or power series, the result is the exponent of the zero.
689: Any other type combinations gives an error.
690:
691: \syn{ggval}{x,p}, and the result is a \kbd{long}.
692:
693: \subsecidx{variable}$(x)$: gives the main variable of the object $x$, and
694: $p$ if $x$ is a $p$-adic number. Gives an error if $x$ has no variable
695: associated to it. Note that this function is useful only in GP, since in
696: library mode the function \kbd{gvar} is more appropriate.
697:
698: \syn{gpolvar}{x}. However, in library mode, this function should not be used.
699: Instead, test whether $x$ is a $p$-adic (type \typ{PADIC}), in which case $p$
700: is in $x[2]$, or call the function $\key{gvar}(x)$ which returns the variable
701: {\it number\/} of $x$ if it exists, \kbd{BIGINT} otherwise.
702:
703: \section{Transcendental functions}\label{se:trans}
704:
705: As a general rule, which of course in some cases may have exceptions,
706: transcendental functions operate in the following way:
707:
708: $\bullet$ If the argument is either an integer, a real, a rational, a complex
709: or a quadratic number, it is, if necessary, first converted to a real (or
710: complex) number using the current \idx{precision} held in the default
711: \kbd{realprecision}. Note that only exact arguments are converted, while
712: inexact arguments such as reals are not.
713:
714: Under GP this is transparent to the user, but when programming in library
715: mode, care must be taken to supply a meaningful parameter \var{prec} as the
716: last argument of the function if the first argument is an exact object.
717: This parameter is ignored if the argument is inexact.
718:
719: Note that in library mode the precision argument \var{prec} is a word
720: count including codewords, i.e.~represents the length in words of a real
721: number, while under GP the precision (which is changed by the metacommand
722: \b{p} or using \kbd{default(realprecision,...)}) is the number of significant
723: decimal digits.
724:
725: Note that some accuracies attainable on 32-bit machines cannot be attained
726: on 64-bit machines for parity reasons. For example the default GP accuracy
727: is 28 decimal digits on 32-bit machines, corresponding to \var{prec} having
728: the value 5, but this cannot be attained on 64-bit machines.\smallskip
729:
730: After possible conversion, the function is computed. Note that even if the
731: argument is real, the result may be complex (e.g.~$\text{acos}(2.0)$ or
732: $\text{acosh}(0.0)$). Note also that the principal branch is always chosen.
733:
734: $\bullet$ If the argument is an integermod or a $p$-adic, at present only a
735: few functions like \kbd{sqrt} (square root), \kbd{sqr} (square), \kbd{log},
736: \kbd{exp}, powering, \kbd{teichmuller} (Teichm\"uller character) and
737: \kbd{agm} (arithmetic-geometric mean) are implemented. Note that in the case
738: of a $2$-adic number, $\kbd{sqr}(x)$ is not identical to $x*x$: for example
739: if $x = 1+O(2^5)$ then $x*x = 1+O(2^5)$ while $\kbd{sqr}(x) = 1+O(2^6)$.
740: (Remark: note that if we wanted to be strictly consistent with the PARI
741: philosophy, we should have $x*y= (4 \mod 8)$ when both $x$ and $y$ are
742: congruent to $2$ modulo $4$, or $\kbd{sqr}(x)=(4\mod 32)$ when $x$ is
743: congruent to $2$ modulo $4$. However, since an integermod is an exact object,
744: PARI assumes that the modulus must not change, and the result is hence $0\,
745: \mod\, 4$ in both cases. On the other hand, $p$-adics are not exact objects,
746: hence are treated differently.)
747:
748: $\bullet$ If the argument is a polynomial, power series or rational function,
749: it is, if necessary, first converted to a power series using the current
750: precision held in the variable \tet{precdl}. Under GP this again is
751: transparent to the user. When programming in library mode, however, the
752: global variable \kbd{precdl} must be set before calling the function if the
753: argument has an exact type (i.e.~not a power series). Here \kbd{precdl} is
754: not an argument of the function, but a global variable.
755:
756: Then the Taylor series expansion of the function around $X=0$ (where $X$ is
757: the main variable) is computed to a number of terms depending on the number
758: of terms of the argument and the function being computed.
759:
760: $\bullet$ If the argument is a vector or a matrix, the result is the
761: componentwise evaluation of the function. In particular, transcendental
762: functions on square matrices, which are not implemented in the present
763: version \vers{} (see Appendix~B however), will have a slightly different name
764: if they are implemented some day.
765:
766: \subseckbd{\pow}: If $y$ is not of type integer, \kbd{x\pow y} has the same
767: effect as \kbd{exp(y*ln(x))}. It can be applied to $p$-adic numbers as
768: well as to the more usual types.\sidx{powering}
769:
770: \syn{gpow}{x,y,\var{prec}}.
771:
772: \subsecidx{Euler}: Euler's constant $0.57721\cdots$. Note that \kbd{Euler}
773: is one of the few special reserved names which cannot be used for variables
774: (the others are \kbd{I} and \kbd{Pi}, as well as all function names).
775: \label{se:euler}
776:
777: \syn{mpeuler}{\var{prec}} where $\var{prec}$ {\it must\/} be
778: given. Note that this creates $\gamma$ on the PARI stack. If one does not
779: want to create it on the stack but stash it for later use under the global
780: name \teb{geuler} (with no parentheses), use instead
781: $\teb{consteuler}(\var{prec})$.
782:
783: \subsecidx{I}: the complex number $\sqrt{-1}$.
784:
785: The library syntax is the global variable \kbd{gi} (of type \kbd{GEN}).
786:
787: \subsecidx{Pi}: the constant $\pi$ ($3.14159\cdots$).\label{se:pi}
788:
789: \syn{mppi}{\var{prec}} where $\var{prec}$ {\it must\/} be given.
790: Note that this creates $\pi$ on the PARI stack. If one does not want to
791: create it on the stack but stash it for later use under the global
792: name \teb{gpi} (with no parentheses), use instead $\teb{constpi}(\var{prec})$.
793:
794: \subsecidx{abs}$(x)$: absolute value of $x$ (modulus if $x$ is complex).
795: Polynomials, power series and rational functions are not allowed.
796: Contrary to most transcendental functions, an integer is {\it not\/}
797: converted to a real number before applying \kbd{abs}.
798:
799: \syn{gabs}{x,\var{prec}}.
800:
801: \subsecidx{acos}$(x)$: principal branch of $\text{cos}^{-1}(x)$,
802: i.e.~such that $\text{Re(acos}(x))\in [0,\pi]$. If
803: $x\in \R$ and $|x|>1$, then $\text{acos}(x)$ is complex.
804:
805: \syn{gacos}{x,\var{prec}}.
806:
807: \subsecidx{acosh}$(x)$: principal branch of $\text{cosh}^{-1}(x)$,
808: i.e.~such that $\text{Im(acosh}(x))\in [0,\pi]$. If
809: $x\in \R$ and $x<1$, then $\text{acosh}(x)$ is complex.
810:
811: \syn{gach}{x,\var{prec}}.
812:
813: \subsecidx{agm}$(x,y)$: arithmetic-geometric mean of $x$ and $y$. In the
814: case of complex or negative numbers, the principal square root is always
815: chosen. $p$-adic or power series arguments are also allowed. Note that
816: a $p$-adic agm exists only if $x/y$ is congruent to 1 modulo $p$ (modulo
817: 16 for $p=2$). $x$ and $y$ cannot both be vectors or matrices.
818:
819: \syn{agm}{x,y,\var{prec}}.
820:
821: \subsecidx{arg}$(x)$: argument of the complex number $x$, such that
822: $-\pi<\text{arg}(x)\le\pi$.
823:
824: \syn{garg}{x,\var{prec}}.
825:
826: \subsecidx{asin}$(x)$: principal branch of $\text{sin}^{-1}(x)$, i.e.~such
827: that $\text{Re(asin}(x))\in [-\pi/2,\pi/2]$. If $x\in \R$ and $|x|>1$ then
828: $\text{asin}(x)$ is complex.
829:
830: \syn{gasin}{x,\var{prec}}.
831:
832: \subsecidx{asinh}$(x)$: principal branch of $\text{sinh}^{-1}(x)$, i.e.~such
833: that $\text{Im(asinh}(x))\in [-\pi/2,\pi/2]$.
834:
835: \syn{gash}{x,\var{prec}}.
836:
837: \subsecidx{atan}$(x)$: principal branch of $\text{tan}^{-1}(x)$, i.e.~such
838: that $\text{Re(atan}(x))\in{} ]-\pi/2,\pi/2[$.
839:
840: \syn{gatan}{x,\var{prec}}.
841:
842: \subsecidx{atanh}$(x)$: principal branch of $\text{tanh}^{-1}(x)$, i.e.~such
843: that $\text{Im(atanh}(x))\in{} ]-\pi/2,\pi/2]$. If $x\in \R$ and $|x|>1$ then
844: $\text{atanh}(x)$ is complex.
845:
846: \syn{gath}{x,\var{prec}}.
847:
848: \subsecidx{bernfrac}$(x)$: Bernoulli number\sidx{Bernoulli numbers} $B_x$,
849: where $B_0=1$, $B_1=-1/2$, $B_2=1/6$,\dots, expressed as a rational number.
850: The argument $x$ should be of type integer.
851:
852: \syn{bernfrac}{x}.
853:
854: \subsecidx{bernreal}$(x)$: Bernoulli number\sidx{Bernoulli numbers}
855: $B_x$, as \kbd{bernfrac}, but $B_x$ is returned as a real number
856: (with the current precision).
857:
858: \syn{bernreal}{x,\var{prec}}.
859:
860: \subsecidx{bernvec}$(x)$: creates a vector containing, as rational numbers,
861: the \idx{Bernoulli numbers} $B_0$, $B_2$,\dots, $B_{2x}$. These Bernoulli
862: numbers can then be used as follows. Assume that this vector has been put
863: into a variable, say \kbd{bernint}. Then you can define under GP:
864:
865: \bprog
866: bern(x) =
867: \obr
868: \q if (x==1, return(-1/2));
869: \q if ((x<0) || (x\%2), return(0));
870: \q bernint[x/2+1]
871: \cbr
872: \eprog
873: \noindent and then \kbd{bern(k)} gives the Bernoulli number of index $k$ as a
874: rational number, exactly as \kbd{bernreal(k)} gives it as a real number. If
875: you need only a few values, calling \kbd{bernfrac(k)} each time will be much
876: more efficient than computing the huge vector above.
877:
878:
879: \syn{bernvec}{x}.
880:
881: \subsecidx{besseljh}$(n,x)$: $J$-Bessel function of half integral index.
882: More precisely, $\kbd{besseljh}(n,x)$ computes $J_{n+1/2}(x)$ where $n$
883: must be of type integer, and $x$ is any element of $\C$. In the
884: present version \vers, this function is not very accurate when $x$ is
885: small.
886:
887: \syn{jbesselh}{n,x,\var{prec}}.
888:
889: \subsecidx{besselk}$(\var{nu},x,\{\fl=0\})$: $K$-Bessel function of index
890: \var{nu} (which can be complex) and argument $x$. Only real and positive
891: arguments
892: $x$ are allowed in the present version \vers. If $\fl$ is equal to 1,
893: uses another implementation of this function which is often faster.
894:
895: \syn{kbessel}{\var{nu},x,\var{prec}} and
896: $\teb{kbessel2}(\var{nu},x,\var{prec})$ respectively.
897:
898: \subsecidx{cos}$(x)$: cosine of $x$.
899:
900: \syn{gcos}{x,\var{prec}}.
901:
902: \subsecidx{cosh}$(x)$: hyperbolic cosine of $x$.
903:
904: \syn{gch}{x,\var{prec}}.
905:
906: \subsecidx{cotan}$(x)$: cotangent of $x$.
907:
908: \syn{gcotan}{x,\var{prec}}.
909:
910: \subsecidx{dilog}$(x)$: principal branch of the dilogarithm of $x$,
911: i.e.~analytic continuation of the power series $\log_2(x)=\sum_{n\ge1}x^n/n^2$.
912:
913: \syn{dilog}{x,\var{prec}}.
914:
915: \subsecidx{eint1}$(x,\{n\})$: exponential integral
916: $\int_x^\infty \dfrac{e^{-t}}{t}\,dt$ ($x\in\R$)
917:
918: If $n$ is present, outputs the $n$-dimensional vector
919: $[\kbd{eint1}(x),\dots,\kbd{eint1}(nx)]$ ($x \geq 0$). This is faster than
920: repeatedly calling \kbd{eint1($i$ * x)}.
921:
922: \syn{veceint1}{x,n,\var{prec}}. Also available is
923: $\teb{eint1}(x,\var{prec})$.
924:
925: \subsecidx{erfc}$(x)$: complementary error function
926: $(2/\sqrt\pi)\int_x^\infty e^{-t^2}\,dt$.
927:
928: \syn{erfc}{x,\var{prec}}.
929:
930: \subsecidx{eta}$(x,\{\fl=0\})$: \idx{Dedekind}'s $\eta$ function, without the
931: $q^{1/24}$. This means the following: if $x$ is a complex number with positive
932: imaginary part, the result is $\prod_{n=1}^\infty(1-q^n)$, where
933: $q=e^{2i\pi x}$. If $x$ is a power series (or can be converted to a power
934: series) with positive valuation, the result is $\prod_{n=1}^\infty(1-x^n)$.
935:
936: If $\fl=1$ and $x$ can be converted to a complex number (i.e.~is not a power
937: series), computes the true $\eta$ function, including the leading $q^{1/24}$.
938:
939: \syn{eta}{x,\var{prec}}.
940:
941: \subsecidx{exp}$(x)$: exponential of $x$.
942: $p$-adic arguments with positive valuation are accepted.
943:
944: \syn{gexp}{x,\var{prec}}.
945:
946: \subsecidx{gammah}$(x)$: gamma function evaluated at the argument
947: $x+1/2$. When $x$ is an integer, this is much faster than using
948: $\kbd{gamma}(x+1/2)$.
949:
950: \syn{ggamd}{x,\var{prec}}.
951:
952: \subsecidx{gamma}$(x)$: gamma function of $x$. In the present version
953: \vers{} the $p$-adic gamma function is not implemented.
954:
955: \syn{ggamma}{x,\var{prec}}.
956:
957: \subsecidx{hyperu}$(a,b,x)$: $U$-confluent hypergeometric function with
958: parameters $a$ and $b$.
959:
960: \syn{hyperu}{a,b,x,\var{prec}}.
961:
962: \subsecidx{incgam}$(s,x,{y})$: incomplete gamma function.
963:
964: The arguments $s$ and $x$ must be positive. The result returned is
965: $\int_x^\infty e^{-t}t^{s-1}\,dt$. When $y$ is given, assume (of course
966: without checking!) that $y=\Gamma(s)$. For small $x$, this will tremendously
967: speed up the computation.
968:
969: \syn{incgam}{s,x,\var{prec}} and $\teb{incgam4}(s,x,y,\var{prec})$,
970: respectively. There exist also the functions \teb{incgam1} and
971: \teb{incgam2} which are used for internal purposes.
972:
973: \subsecidx{incgamc}$(s,x)$: complementary incomplete gamma function.
974:
975: The arguments $s$ and $x$ must be positive. The result returned is
976: $\int_0^x e^{-t}t^{s-1}\,dt$, when $x$ is not too large.
977:
978: \syn{incgam3}{s,x,\var{prec}}.
979:
980: \subsecidx{log}$(x,\{\fl=0\})$: principal branch of the natural logarithm of
981: $x$, i.e.~such that $\text{Im(ln}(x))\in{} ]-\pi,\pi]$. The result is complex
982: (with imaginary part equal to $\pi$) if $x\in \R$ and $x<0$.
983:
984: $p$-adic arguments are also accepted for $x$, with the convention that
985: $\ln(p)=0$. Hence in particular $\exp(\ln(x))/x$ will not in general be
986: equal to 1 but to a $(p-1)$-th root of unity (or $\pm1$ if $p=2$)
987: times a power of $p$.
988:
989: If $\fl$ is equal to 1, use an agm formula suggested by Mestre, when $x$ is
990: real, otherwise identical to \kbd{log}.
991:
992: \syn{glog}{x,\var{prec}} or $\teb{glogagm}(x,\var{prec})$.
993:
994: \subsecidx{lngamma}$(x)$: principal branch of the logarithm of the gamma
995: function of $x$. Can have much larger arguments than \kbd{gamma} itself.
996: In the present version \vers, the $p$-adic \kbd{lngamma} function is not
997: implemented.
998:
999: \syn{glngamma}{x,\var{prec}}.
1000:
1001: \subsecidx{polylog}$(m,x,{\fl=0})$: one of the different polylogarithms,
1002: depending on \fl:
1003:
1004: If $\fl=0$ or is omitted: $m^\text{th}$ polylogarithm of $x$, i.e.~analytic
1005: continuation of the power series $\text{Li}_m(x)=\sum_{n\ge1}x^n/n^m$. The
1006: program uses the power series when $|x|^2\le1/2$, and the power series
1007: expansion in $\log(x)$ otherwise. It is valid in a large domain (at least
1008: $|x|<230$), but should not be used too far away from the unit circle since it
1009: is then better to use the functional equation linking the value at $x$ to the
1010: value at $1/x$, which takes a trivial form for the variant below. Power
1011: series, polynomial, rational and vector/matrix arguments are allowed.
1012:
1013: For the variants to follow we need a notation: let $\Re_m$
1014: denotes $\Re$ or $\Im$ depending whether $m$ is odd or even.
1015:
1016: If $\fl=1$: modified $m^\text{th}$ polylogarithm of $x$, called
1017: $\tilde D_m(x)$ in Zagier, defined for $|x|\le1$ by
1018: $$\Re_m\left(\sum_{k=0}^{m-1} \dfrac{(-\log|x|)^k}{k!}\text{Li}_{m-k}(x)
1019: +\dfrac{(-\log|x|)^{m-1}}{m!}\log|1-x|\right).$$
1020:
1021: If $\fl=2$: modified $m^\text{th}$ polylogarithm of $x$,
1022: called $D_m(x)$ in Zagier, defined for $|x|\le1$ by
1023: $$\Re_m\left(\sum_{k=0}^{m-1}\dfrac{(-\log|x|)^k}{k!}\text{Li}_{m-k}(x)
1024: -\dfrac{1}{2}\dfrac{(-\log|x|)^m}{m!}\right).$$
1025:
1026: If $\fl=3$: another modified $m^\text{th}$
1027: polylogarithm of $x$, called $P_m(x)$ in Zagier, defined for $|x|\le1$ by
1028: $$\Re_m\left(\sum_{k=0}^{m-1}\dfrac{2^kB_k}{k!}(\log|x|)^k\text{Li}_{m-k}(x)
1029: -\dfrac{2^{m-1}B_m}{m!}(\log|x|)^m\right).$$
1030:
1031: These three functions satisfy the functional equation
1032: $f_m(1/x)=(-1)^{m-1}f_m(x)$.
1033:
1034: \syn{polylog0}{m,x,\fl,\var{prec}}.
1035:
1036: \subsecidx{psi}$(x)$: the $\psi$-function of $x$, i.e.~the
1037: logarithmic derivative $\Gamma'(x)/\Gamma(x)$.
1038:
1039: \syn{gpsi}{x,\var{prec}}.
1040:
1041: \subsecidx{sin}$(x)$: sine of $x$.
1042:
1043: \syn{gsin}{x,\var{prec}}.
1044:
1045: \subsecidx{sinh}$(x)$: hyperbolic sine of $x$.
1046:
1047: \syn{gsh}{x,\var{prec}}.
1048:
1049: \subsecidx{sqr}$(x)$: square of $x$. Not identical to $x*x$ in
1050: the case of $2$-adics, where it returns a more precise result.
1051:
1052: \syn{gsqr}{x}.
1053:
1054: \subsecidx{sqrt}$(x)$: principal branch of the square root of $x$,
1055: i.e.~such that $\text{Arg}(\text{sqrt}(x))\in{} ]-\pi/2, \pi/2]$, or in other
1056: words such that $\Re(\text{sqrt}(x))>0$ or $\Re(\text{sqrt}(x))=0$ and
1057: $\Im(\text{sqrt}(x))\ge 0$. If $x\in \R$ and $x<0$, then the result is
1058: complex with positive imaginary part.
1059:
1060: Integermod a prime and $p$-adics are allowed as arguments. In that case,
1061: the square root (if it exists) which is returned is the one whose
1062: first $p$-adic digit (or its unique $p$-adic digit in the case of
1063: integermods) is in the interval $[0,p/2]$. When the argument is an
1064: integermod a non-prime (or a non-prime-adic), the result is undefined
1065: (and the function may not even return).
1066:
1067: \syn{gsqrt}{x,\var{prec}}.
1068:
1069: \subsecidx{tan}$(x)$: tangent of $x$.
1070:
1071: \syn{gtan}{x,\var{prec}}.
1072:
1073: \subsecidx{tanh}$(x)$: hyperbolic tangent of $x$.
1074:
1075: \syn{gth}{x,\var{prec}}.
1076:
1077: \subsecidx{teichmuller}$(x)$: Teichm\"uller character of the $p$-adic number
1078: $x$.
1079:
1080: \syn{teich}{x}.
1081:
1082: \subsecidx{theta}$(q,z)$: Jacobi sine theta-function.
1083:
1084: \syn{theta}{q,z,\var{prec}}.
1085:
1086: \subsecidx{thetanullk}$(q,k)$: $k$-th derivative at $z=0$ of
1087: $\kbd{theta}(q,z)$.
1088:
1089: \syn{thetanullk}{q,k,\var{prec}}, where $k$ is a \kbd{long}.
1090:
1091: \subsecidx{weber}$(x,\{\fl=0\})$: one of Weber's three $f$ functions.
1092: If $\fl=0$, returns
1093: $$f(x)=\exp(-i\pi/24)\cdot\eta((x+1)/2)\,/\,\eta(x) \quad\hbox{such that}\quad
1094: j=(f^{24}-16)^3/f^{24}\,,$$
1095: where $j$ is the elliptic $j$-invariant (see the function \kbd{ellj}).
1096: If $\fl=1$, returns
1097: $$f_1(x)=\eta(x/2)\,/\,\eta(x)\quad\hbox{such that}\quad
1098: j=(f_1^{24}+16)^3/f_1^{24}\,.$$
1099: Finally, if $\fl=2$, returns
1100: $$f_2(x)=\sqrt{2}\eta(2x)\,/\,\eta(x)\quad\hbox{such that}\quad
1101: j=(f_2^{24}+16)^3/f_2^{24}.$$
1102: Note the identities $f^8=f_1^8+f_2^8$ and $ff_1f_2=\sqrt2$.
1103:
1104: \syn{weber0}{x,\fl,\var{prec}}, or
1105: $\teb{wf}(x,\var{prec})$, $\teb{wf1}(x,\var{prec})$ or
1106: $\teb{wf2}(x,\var{prec})$.
1107:
1108: \subsecidx{zeta}$(s)$: Riemann's zeta function\sidx{Riemann zeta-function}
1109: $\zeta(s)=\sum_{n\ge1}n^{-s}$, computed using the \idx{Euler-Maclaurin}
1110: summation formula, except when $s$ is of type integer, in which case it
1111: is computed using \idx{Bernoulli numbers} for
1112: $s\le0$ or $s>0$ and even, and using modular forms for $s>0$ and odd.
1113:
1114: \syn{gzeta}{s,\var{prec}}.
1115:
1116: \section{Arithmetic functions}\label{se:arithmetic}
1117:
1118: These functions are by definition functions whose natural domain of
1119: definition is either $\Z$ (or $\Z_{>0}$), or sometimes polynomials
1120: over a base ring. Functions which concern polynomials exclusively will be
1121: explained in the next section. The way these functions are used is
1122: completely different from transcendental functions: in general only the types
1123: integer and polynomial are accepted as arguments. If a vector or matrix type
1124: is given, the function will be applied on each coefficient independently.
1125:
1126: In the present version \vers{}, all arithmetic functions in the narrow
1127: sense of the word~--- Euler's totient\sidx{Euler totient function}
1128: function, the M\"obius\sidx{moebius} function, the sums over divisors or
1129: powers of divisors etc.--- call, after trial division by small primes, the
1130: same versatile factoring machinery described under \kbd{factorint}.
1131: It includes \idx{Pollard Rho}, \idx{ECM} and \idx{MPQS}
1132: stages, and has an early exit option for the functions \teb{moebius} and (the
1133: integer function underlying) \teb{issquarefree}.
1134: Note that it relies on a (fairly strong) probabilistic primality test:
1135: numbers found to be strong pseudo-primes after 10 successful trials of
1136: the \idx{Rabin-Miller} test are declared primes.
1137:
1138: \bigskip
1139: \subsecidx{Qfb}$(a,b,c,\{D=0.\})$: creates the binary quadratic form
1140: $ax^2+bxy+cy^2$. If $b^2-4ac>0$, initialize \idx{Shanks}' distance
1141: function to $D$.
1142:
1143: \syn{Qfb0}{a,b,c,D,\var{prec}}. Also available are
1144: $\teb{qfi}(a,b,c)$ (when $b^2-4ac<0$), and
1145: $\teb{qfr}(a,b,c,d)$ (when $b^2-4ac>0$).\sidx{binary quadratic form}
1146:
1147:
1148: \subsecidx{addprimes}$(\{x=[\,]\})$: adds the primes contained in the vector
1149: $x$ (or the single integer $x$) to the table computed upon GP initialization
1150: (by \kbd{pari\_init} in library mode), and returns a row vector whose first
1151: entries contain all primes added by the user and whose last entries have been
1152: filled up with 1's. In total the returned row vector has 100 components.
1153: Whenever \kbd{factor} or \kbd{smallfact} is subsequently called, first the
1154: primes in the table computed by \kbd{pari\_init} will be checked, and then
1155: the additional primes in this table. If $x$ is empty or omitted, just returns
1156: the current list of extra primes.
1157:
1158: The entries in $x$ are not checked for primality. They need only be positive
1159: integers not divisible by any of the pre-computed primes. It's in fact a nice
1160: trick to add composite numbers, which for example the function
1161: $\kbd{factor}(x,0)$ was not able to factor. In case the message ``impossible
1162: inverse modulo $\langle${\it some integermod}$\rangle$'' shows up afterwards,
1163: you have just stumbled over a non-trivial factor. Note that the arithmetic
1164: functions in the narrow sense, like \teb{eulerphi}, do {\it not\/} use this
1165: extra table.
1166:
1167: The present PARI version \vers{} allows up to 100 user-specified
1168: primes to be appended to the table. This limit may be changed
1169: by altering \kbd{NUMPRTBELT} in file \kbd{init.c}. To remove primes from the
1170: list use \kbd{removeprimes}.
1171:
1172: \syn{addprimes}{x}.
1173:
1174: \subsecidx{bestappr}$(x,k)$: if $x\in\R$, finds the best rational
1175: approximation to $x$ with denominator at most equal to $k$ using continued
1176: fractions.
1177:
1178: \syn{bestappr}{x,k}.
1179:
1180: \subsecidx{bezout}$(x,y)$: finds $u$ and $v$ minimal in a
1181: natural sense such that $x*u+y*v=\text{gcd}(x,y)$. The arguments
1182: must be both integers or both polynomials, and the result is a
1183: row vector with three components $u$, $v$, and $\text{gcd}(x,y)$.
1184:
1185: \syn{vecbezout}{x,y} to get the vector, or $\teb{gbezout}(x,y, \&u, \&v)$
1186: which gives as result the address of the created gcd, and puts
1187: the addresses of the corresponding created objects into $u$ and $v$.
1188:
1189: \subsecidx{bezoutres}$(x,y)$: as \kbd{bezout}, with the resultant of $x$ and
1190: $y$ replacing the gcd.
1191:
1192: \syn{vecbezoutres}{x,y} to get the vector, or $\teb{subresext}(x,y, \&u,
1193: \&v)$ which gives as result the address of the created gcd, and puts the
1194: addresses of the corresponding created objects into $u$ and $v$.
1195:
1196: \subsecidx{bigomega}$(x)$: number of prime divisors of $x$ counted with
1197: multiplicity. $x$ must be an integer.
1198:
1199: \syn{bigomega}{x}, the result is a \kbd{long}.
1200:
1201: \subsecidx{binomial}$(x,y)$: \idx{binomial coefficient} $\binom x y$.
1202: Here $y$ must be an integer, but $x$ can be any PARI object.
1203:
1204: \syn{binome}{x,y}, where $y$ must be a \kbd{long}.
1205:
1206: \subsecidx{chinese}$(x,y)$: if $x$ and $y$ are both integermods or both
1207: polmods, creates (with the same type) a $z$ in the same residue class
1208: as $x$ and in the same residue class as $y$, if it is possible.
1209:
1210: This function also allows vector and matrix arguments, in which case the
1211: operation is recursively applied to each component of the vector or matrix.
1212: For polynomial arguments, it is applied to each coefficient. Finally
1213: $\kbd{chinese}(x,x) = x$ regardless of the type of $x$; this allows vector
1214: arguments to contain other data, so long as they are identical in both
1215: vectors.
1216:
1217: \syn{chinois}{x,y}.
1218:
1219: \subsecidx{content}$(x)$: computes the gcd of all the coefficients of $x$,
1220: when this gcd makes sense. If $x$ is a scalar, this simply returns $x$. If $x$
1221: is a polynomial (and by extension a power series), it gives the usual content
1222: of $x$. If $x$ is a rational function, it gives the ratio of the contents of
1223: the numerator and the denominator. Finally, if $x$ is a vector or a matrix,
1224: it gives the gcd of all the entries.
1225:
1226: \syn{content}{x}.
1227:
1228: \subsecidx{contfrac}$(x,\{b\},\{lmax\})$: creates the row vector whose
1229: components are the partial quotients of the \idx{continued fraction}
1230: expansion of $x$, the number of partial quotients being limited to $lmax$.
1231: If $x$ is a real number, the expansion stops at the last significant partial
1232: quotient if $lmax$ is omitted. $x$ can also be a rational function or a power
1233: series.
1234:
1235: If a vector $b$ is supplied, the numerators will be equal to the coefficients
1236: of $b$. The length of the result is then equal to the length of $b$, unless a
1237: partial remainder is encountered which is equal to zero. In which case the
1238: expansion stops. In the case of real numbers, the stopping criterion is thus
1239: different from the one mentioned above since, if $b$ is too long, some partial
1240: quotients may not be significant.
1241:
1242: \syn{contfrac0}{x,b,lmax}. Also available are
1243: $\teb{gboundcf}(x,lmax)$, $\teb{gcf}(x)$, or $\teb{gcf2}(b,x)$, where $lmax$
1244: is a C integer.
1245:
1246: \subsecidx{contfracpnqn}$(x)$: when $x$ is a vector or a one-row matrix, $x$
1247: is considered as the list of partial quotients $[a_0,a_1,\dots,a_n]$ of a
1248: rational number, and the result is the 2 by 2 matrix
1249: $[p_n,p_{n-1};q_n,q_{n-1}]$ in the standard notation of continued fractions,
1250: so $p_n/q_n=a_0+1/(a_1+\dots+1/a_n)\dots)$. If $x$ is a matrix with two rows
1251: $[b_0,b_1,\dots,b_n]$ and $[a_0,a_1,\dots,a_n]$, this is then considered as a
1252: generalized continued fraction and we have similarly
1253: $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
1254: usually has $b_0=1$.
1255:
1256: \syn{pnqn}{x}.
1257:
1258: \subsecidx{core}$(n,\{\fl=0\})$: if $n$ is a non-zero integer written as
1259: $n=df^2$ with $d$ squarefree, returns $d$. If $\fl$ is non-zero,
1260: returns the two-element row vector $[d,f]$.
1261:
1262: \syn{core0}{n,\fl}.
1263: Also available are
1264: $\teb{core}(n)$ (= \teb{core}$(n,0)$) and
1265: $\teb{core2}(n)$ (= \teb{core}$(n,1)$).
1266:
1267: \subsecidx{coredisc}$(n,\{\fl\})$: if $n$ is a non-zero integer written as
1268: $n=df^2$ with $d$ fundamental discriminant (including 1), returns $d$. If
1269: $\fl$ is non-zero, returns the two-element row vector $[d,f]$. Note that if
1270: $n$ is not congruent to 0 or 1 modulo 4, $f$ will be a half integer and not
1271: an integer.
1272:
1273: \syn{coredisc0}{n,\fl}.
1274: Also available are
1275: $\teb{coredisc}(n)$ (= \teb{coredisc}$(n,0)$) and
1276: $\teb{coredisc2}(n)$ (= \teb{coredisc}$(n,1)$).
1277:
1278: \subsecidx{dirdiv}$(x,y)$: $x$ and $y$ being vectors of perhaps different
1279: lengths but with $y[1]\neq 0$ considered as \idx{Dirichlet series}, computes
1280: the quotient of $x$ by $y$, again as a vector.
1281:
1282: \syn{dirdiv}{x,y}.
1283:
1284: \subsecidx{direuler}$(p=a,b,\var{expr})$: computes the \idx{Dirichlet series}
1285: to $b$ terms of the \idx{Euler product} of expression \var{expr} as $p$ ranges
1286: through the primes from $a$ to $b$. \var{expr} must be a polynomial or
1287: rational function in
1288: another variable than $p$ (say $X$) and $\var{expr}(X)$ is understood as the
1289: Dirichlet series (or more precisely the local factor) $\var{expr}(p^{-s})$.
1290:
1291: \synt{direuler}{entree *ep, GEN a, GEN b, char *expr}
1292: (see the section on sums and products for explanations of this).
1293:
1294: \subsecidx{dirmul}$(x,y)$: $x$ and $y$ being vectors of perhaps different
1295: lengths considered as \idx{Dirichlet series}, computes the product of
1296: $x$ by $y$, again as a vector.
1297:
1298: \syn{dirmul}{x,y}.
1299:
1300: \subsecidx{divisors}$(x)$: creates a row vector whose components are the
1301: positive divisors of the integer $x$ in increasing order. The factorization
1302: of $x$ (as output by \tet{factor}) can be used instead.
1303:
1304: \syn{divisors}{x}.
1305:
1306: \subsecidx{eulerphi}$(x)$: Euler's $\phi$
1307: (totient)\sidx{Euler totient function} function of $x$.
1308: $x$ must be of type integer.
1309:
1310: \syn{phi}{x}.
1311:
1312: \subsecidx{factor}$(x,\{\var{lim}=-1\})$: general factorization function.
1313: If $x$ is of type integer, rational, polynomial or rational function,
1314: the result is a
1315: two-column matrix, the first column being the irreducibles dividing $x$
1316: (prime numbers or polynomials), and the second the exponents. If $x$ is a
1317: vector or a matrix, the factoring is done componentwise (hence the result is
1318: a vector or matrix of two-column matrices).
1319:
1320: If $x$ is of type integer or rational, an argument \var{lim} can be added,
1321: meaning that we look only for factors up to \var{lim}, or to \kbd{primelimit},
1322: whichever is lowest (except when $\var{lim}=0$ where the effect is identical
1323: to setting $\var{lim}=\kbd{primelimit}$). Hence in this case, the remaining
1324: part is not necessarily prime. See \teb{factorint} for more information about
1325: the algorithms used.
1326:
1327: The polynomials or rational functions to be factored must have scalar
1328: coefficients. In particular PARI does {\it not\/} know how to factor
1329: multivariate polynomials.
1330:
1331: Note that PARI tries to guess in a sensible way over which ring you want to
1332: factor. Note also that factorization of polynomials is done up to
1333: multiplication by a constant. In particular, the factors of rational
1334: polynomials will have integer coefficients, and the content of a polynomial or
1335: rational function is discarded and not included in the factorization. If
1336: you need to, you can always ask for the content explicitly:
1337:
1338: \bprog%
1339: ? factor(t\pow2 + 5/2*t + 1)
1340: \%1 =
1341: [2*t + 1 1]
1342: \smallskip%
1343: [t + 2 1]
1344: \smallskip%
1345: ? content(t\pow2 + 5/2*t + 1)
1346: \%2 = 1/2%
1347: \eprog
1348:
1349: \noindent See also \teb{factornf}.
1350:
1351: \syn{factor0}{x,\var{lim}}, where \var{lim} is a C integer.
1352: Also available are
1353: $\teb{factor}(x)$ (= $\teb{factor0}(x,-1)$),
1354: $\teb{smallfact}(x)$ (= $\teb{factor0}(x,0)$).
1355:
1356: \subsecidx{factorback}$(f,\{nf\})$: $f$ being any factorization, gives back
1357: the factored object. If a second argument $\var{nf}$ is supplied, $f$ is
1358: assumed to be a prime ideal factorization in the number field $\var{nf}$.
1359: The resulting ideal is given in HNF\sidx{Hermite normal form} form.
1360:
1361: \syn{factorback}{f,\var{nf\/}}, where an omitted
1362: $\var{nf}$ is entered as \kbd{NULL}.
1363:
1364: \subsecidx{factorcantor}$(x,p)$: factors the polynomial $x$ modulo the
1365: prime $p$, using distinct degree plus
1366: \idx{Cantor-Zassenhaus}\sidx{Zassenhaus}. The coefficients of $x$ must be
1367: operation-compatible with $\Z/p\Z$. The result is a two-column matrix, the
1368: first column being the irreducible polynomials dividing $x$, and the second
1369: the exponents. If you want only the {\it degrees\/} of the irreducible
1370: polynomials (for example for computing an $L$-function), use
1371: $\kbd{factormod}(x,p,1)$. Note that the \kbd{factormod} algorithm is
1372: usually faster than \kbd{factorcantor}.
1373:
1374: \syn{factcantor}{x,p}.
1375:
1376: \subsecidx{factorff}$(x,p,a)$: factors the polynomial $x$ in the field
1377: $\F_q$ defined by the irreducible polynomial $a$ over $\F_p$. The
1378: coefficients of $x$ must be operation-compatible with $\Z/p\Z$. The result
1379: is a two-column matrix, the first column being the irreducible polynomials
1380: dividing $x$, and the second the exponents. It is recommended to use for
1381: the variable of $a$ (which will be used as variable of a polmod) a name
1382: distinct from the other variables used, so that a \kbd{lift()} of the
1383: result will be legible.
1384:
1385: \syn{factmod9}{x,p,a}.
1386:
1387: \subsecidx{factorial}$(x)$ or $x!$: factorial of $x$. The expression $x!$
1388: gives a result which is an integer, while $\kbd{fact}(x)$ gives a real
1389: number.
1390:
1391: \syn{mpfact}{x} for $x!$ and
1392: $\teb{mpfactr}(x,\var{prec})$ for $\kbd{fact}(x)$. $x$ must be a \kbd{long}
1393: integer and not a PARI integer.
1394:
1395: \subsecidx{factorint}$(n,\{\fl=0\})$: factors the integer n using a
1396: combination of the \idx{Pollard Rho} method (with modifications due to
1397: Brent), \idx{Lenstra}'s \idx{ECM} (with modifications by Montgomery),
1398: and \idx{MPQS} (the latter adapted from the \idx{LiDIA} code with the kind
1399: permission of the LiDIA
1400: maintainers), as well as a search for pure powers with exponents$\le 10$.
1401: The output is a two-column matrix as for \kbd{factor}.
1402:
1403: This gives direct access to the integer factoring engine called by most
1404: arithmetical functions. \fl\ is optional; its binary digits mean 1: avoid
1405: MPQS, 2: skip first stage ECM (we may still fall back to it later), 4: avoid
1406: Rho, 8: don't run final ECM (as a result, a huge composite may be declared
1407: to be prime). Note that a (strong) probabilistic primality test is used;
1408: thus composites might (very rarely) not be detected.
1409:
1410: The machinery underlying this function is still in a somewhat experimental
1411: state, but should be much faster on average than pure ECM as used by all
1412: PARI versions up to 2.0.8, at the expense of heavier memory use. You are
1413: invited to play with the flag settings and watch the internals at work by
1414: using GP's \tet{debuglevel} default parameter (level 3 shows just the
1415: outline, 4 turns on time keeping, 5 and above show an increasing amount
1416: of internal details). If you see anything funny happening, please let
1417: us know.
1418:
1419: \syn{factorint}{n,\fl}.
1420:
1421: \subsecidx{factormod}$(x,p,\{\fl=0\})$: factors the polynomial $x$ modulo
1422: the prime integer $p$, using \idx{Berlekamp}. The coefficients of $x$ must be
1423: operation-compatible with $\Z/p\Z$. The result is a two-column matrix, the
1424: first column being the irreducible polynomials dividing $x$, and the second
1425: the exponents. If $\fl$ is non-zero, outputs only the {\it degrees} of the
1426: irreducible polynomials (for example, for computing an $L$-function). A
1427: different algorithm for computing the mod $p$ factorization is
1428: \kbd{factorcantor} which is sometimes faster.
1429:
1430: \syn{factormod}{x,p,\fl}. Also available are
1431: $\teb{factmod}(x,p)$ (which is equivalent to $\teb{factormod}(x,p,0)$) and
1432: $\teb{simplefactmod}(x,p)$ (= $\teb{factormod}(x,p,1)$).
1433:
1434: \subsecidx{fibonacci}$(x)$: $x^{\text{th}}$ Fibonacci number.
1435:
1436: \syn{fibo}{x}. $x$ must be a \kbd{long}.
1437:
1438: \subsecidx{gcd}$(x,y,\{\fl=0\})$: creates the greatest common divisor of $x$
1439: and $y$. $x$ and $y$ can be of quite general types, for instance both
1440: rational numbers. Vector/matrix types are also accepted, in which case
1441: the GCD is taken recursively on each component. Note that for these
1442: types, \kbd{gcd} is not commutative.
1443:
1444: If $\fl=0$, use \idx{Euclid}'s algorithm.
1445:
1446: If $\fl=1$, use the modular gcd algorithm ($x$ and $y$ have to be
1447: polynomials, with integer coefficients).
1448:
1449: If $\fl=2$, use the \idx{subresultant algorithm}.
1450:
1451: \syn{gcd0}{x,y,\fl}. Also available are
1452: $\teb{ggcd}(x,y)$, $\teb{modulargcd}(x,y)$, and $\teb{srgcd}(x,y)$
1453: corresponding to $\fl=0$, $1$ and $2$ respectively.
1454:
1455: \subsecidx{hilbert}$(x,y,\{p\})$: \idx{Hilbert symbol} of $x$ and $y$ modulo
1456: $p$. If $x$ and $y$ are of type integer or fraction, an explicit third
1457: parameter $p$ must be supplied, $p=0$ meaning the place at infinity.
1458: Otherwise, $p$ needs not be given, and $x$ and $y$ can be of compatible types
1459: integer, fraction, real, integermod or $p$-adic.
1460:
1461: \syn{hil}{x,y,p}.
1462:
1463: \subsecidx{isfundamental}$(x)$: true (1) if $x$ is equal to 1 or to the
1464: discriminant of a quadratic field, false (0) otherwise.
1465:
1466: \syn{gisfundamental}{x}, but the
1467: simpler function $\teb{isfundamental}(x)$ which returns a \kbd{long}
1468: should be used if $x$ is known to be of type integer.
1469:
1470: \subsecidx{isprime}$(x)$: true (1) if $x$ is a strong pseudo-prime
1471: for 10 randomly chosen bases, false (0) otherwise.
1472:
1473: \syn{gisprime}{x}, but the
1474: simpler function $\teb{isprime}(x)$ which returns a \kbd{long}
1475: should be used if $x$ is known to be of type integer.
1476:
1477: \subsecidx{ispseudoprime}$(x)$: true (1) if $x$ is a strong
1478: pseudo-prime for a randomly chosen base, false (0) otherwise.
1479:
1480: \syn{gispsp}{x}, but the
1481: simpler function $\teb{ispsp}(x)$ which returns a \kbd{long}
1482: should be used if $x$ is known to be of type integer.
1483:
1484: \subsecidx{issquare}$(x,\{\&n\})$: true (1) if $x$ is square, false (0) if
1485: not. $x$ can be of any type. If $n$ is given and an exact square root had to
1486: be computed in the checking process, puts that square root in $n$. This is in
1487: particular the case when $x$ is an integer or a polynomial. This is {\it not}
1488: the case for intmods (use quadratic reciprocity) or series (only check the
1489: leading coefficient).
1490:
1491: \syn{gcarrecomplet}{x,\&n}. Also available is $\teb{gcarreparfait}(x)$.
1492:
1493: \subsecidx{issquarefree}$(x)$: true (1) if $x$ is squarefree, false (0) if not.
1494: Here $x$ can be an integer or a polynomial.
1495:
1496: \syn{gissquarefree}{x}, but the
1497: simpler function $\teb{issquarefree}(x)$ which returns a \kbd{long}
1498: should be used if $x$ is known to be of type integer. This \teb{issquarefree}
1499: is just the square of the M\"obius\sidx{moebius} function, and is computed
1500: as a multiplicative arithmetic function much like the latter.
1501:
1502: \subsecidx{kronecker}$(x,y)$:
1503: Kronecker\sidx{Kronecker symbol}\sidx{Legendre symbol}
1504: (i.e.~generalized Legendre) symbol $\left(\dfrac{x}{y}\right)$. $x$ and $y$
1505: must be of type integer.
1506:
1507: \syn{kronecker}{x,y}, the result ($0$ or $\pm 1$) is a \kbd{long}.
1508:
1509: \subsecidx{lcm}$(x,y)$: least common multiple of $x$ and $y$, i.e.~such
1510: that $\text{lcm}(x,y)*\text{gcd}(x,y)=\text{abs}(x*y)$.
1511:
1512: \syn{glcm}{x,y}.
1513:
1514: \subsecidx{moebius}$(x)$: M\"obius $\mu$-function of $x$. $x$ must be of type
1515: integer.
1516:
1517: \syn{mu}{x}, the result ($0$ or $\pm 1$) is a \kbd{long}.
1518:
1519: \subsecidx{nextprime}$(x)$: finds the smallest prime greater than or
1520: equal to $x$. $x$ can be of any real type. Note that if $x$ is a prime,
1521: this function returns $x$ and not the smallest prime strictly larger than $x$.
1522:
1523: \syn{nextprime}{x}.
1524:
1525: \subsecidx{numdiv}$(x)$: number of divisors of $x$. $x$ must be of type
1526: integer, and the result is a \kbd{long}.
1527:
1528: \syn{numbdiv}{x}.
1529:
1530: \subsecidx{omega}$(x)$: number of distinct prime divisors of $x$. $x$ must be
1531: of type integer.
1532:
1533: \syn{omega}{x}, the result is a \kbd{long}.
1534:
1535: \subsecidx{precprime}$(x)$: finds the largest prime less than or equal to
1536: $x$. $x$ can be of any real type. Returns 0 if $x\le1$.
1537: Note that if $x$ is a prime, this function returns $x$ and not the largest
1538: prime strictly smaller than $x$.
1539:
1540: \syn{precprime}{x}.
1541:
1542: \subsecidx{prime}$(x)$: the $x^{\text{th}}$ prime number, which must be among
1543: the precalculated primes.
1544:
1545: \syn{prime}{x}. $x$ must be a \kbd{long}.
1546:
1547: \subsecidx{primes}$(x)$: creates a row vector whose components
1548: are the first $x$ prime numbers, which must be among the precalculated primes.
1549:
1550: \syn{primes}{x}. $x$ must be a \kbd{long}.
1551:
1552: \subsecidx{qfbclassno}$(x,\{\fl=0\})$: class number of the quadratic field
1553: of discriminant $x$. In the present version \vers, a simple algorithm is used
1554: for $x>0$, so $x$ should not be too large (say $x<10^7$) for the time to be
1555: reasonable. On the other hand, for $x<0$ one can reasonably compute
1556: classno($x$) for $|x|<10^{25}$, since the method used is \idx{Shanks}' method
1557: which is in $O(|x|^{1/4})$. For larger values of $|D|$, see
1558: \kbd{quadclassunit}.
1559:
1560: If $\fl=1$, compute the class number using \idx{Euler product}s and the
1561: functional equation. However, it is in $O(|x|^{1/2})$.
1562:
1563: \misctitle{Important warning.} For $D<0$, this function often gives
1564: incorrect results when the class group is non-cyclic, because the authors
1565: were too lazy to implement \idx{Shanks}' method completely. It is therefore
1566: strongly recommended to use either the version with $\fl=1$, the function
1567: $\kbd{qfhclassno}(-x)$ if $x$ is known to be a fundamental discriminant, or
1568: the function \kbd{quadclassunit}.
1569:
1570: \syn{qfbclassno0}{x,\fl}. Also available are
1571: $\teb{classno}(x)$ (= $\teb{qfbclassno}(x)$),
1572: $\teb{classno2}(x)$ (= $\teb{qfbclassno}(x,1)$), and finally
1573: there exists the function $\teb{hclassno}(x)$ which computes the class
1574: number of an imaginary quadratic field by counting reduced forms, an $O(|x|)$
1575: algorithm. See also \kbd{qfbhclassno}.
1576:
1577: \subsecidx{qfbcompraw}$(x,y)$ \idx{composition} of the binary quadratic forms
1578: $x$ and $y$, without \idx{reduction} of the result. This is useful e.g.~to
1579: compute a generating element of an ideal.
1580:
1581: \syn{compraw}{x,y}.
1582:
1583: \subsecidx{qfbhclassno}$(x)$: \idx{Hurwitz class number} of $x$, where $x$ is
1584: non-negative and congruent to 0 or 3 modulo 4. See also \kbd{qfbclassno}.
1585:
1586: \syn{hclassno}{x}.
1587:
1588: \subsecidx{qfbnucomp}$(x,y,l)$: \idx{composition} of the primitive positive
1589: definite binary quadratic forms $x$ and $y$ using the NUCOMP and NUDUPL
1590: algorithms of \idx{Shanks} (\`a la Atkin). $l$ is any positive constant,
1591: but for optimal speed, one should take $l=|D|^{1/4}$, where $D$ is the common
1592: discriminant of $x$ and $y$.
1593:
1594: \syn{nucomp}{x,y,l}. The auxiliary function
1595: $\teb{nudupl}(x,l)$ should be used instead for speed when $x=y$.
1596:
1597: \subsecidx{qfbnupow}$(x,n)$: $n$-th power of the primitive positive definite
1598: binary quadratic form $x$ using the NUCOMP and NUDUPL algorithms (see
1599: \kbd{qfbnucomp}).
1600:
1601: \syn{nupow}{x,n}.
1602:
1603: \subsecidx{qfbpowraw}$(x,n)$: $n$-th power of the binary quadratic form
1604: $x$, computed without doing any \idx{reduction} (i.e.~using \kbd{qfbcompraw}).
1605: Here $n$ must be non-negative and $n<2^{31}$.
1606:
1607: \syn{powraw}{x,n} where $n$ must be a \kbd{long}
1608: integer.
1609:
1610: \subsecidx{qfbprimeform}$(x,p)$: prime binary quadratic form of discriminant
1611: $x$ whose first coefficient is the prime number $p$. Returns an error if $x$ is not a
1612: quadratic residue mod $p$. In the case where $x>0$, the ``distance''
1613: component of the form is set equal to zero according to the current
1614: precision.
1615:
1616: \subsecidx{qfbred}$(x,\{\fl=0\},\{D\},\{\var{isqrtD}\},\{\var{sqrtD}\})$:
1617: reduces the binary quadratic form $x$. $\fl$ can be any of $0$:
1618: default behaviour, uses \idx{Shanks}' distance function $d$,
1619: $1$: uses $d$, but performs only a single \idx{reduction} step,
1620: $2$: does not compute the distance function $d$, or $3$:
1621: does not use $d$, single reduction step.
1622:
1623: $D$, \var{isqrtD}, \var{sqrtD}, if present, supply the values of the
1624: discriminant, $\lfloor \sqrt{D}\rfloor$, and $\sqrt{D}$ respectively
1625: (no checking is done of these facts). If $D<0$ these values are useless,
1626: and all references to Shanks's distance are irrelevant.
1627:
1628: \syn{qfbred0}{x,\fl,D,\var{isqrtD},\var{sqrtD\/}}. Use \kbd{NULL}
1629: to omit any of $D$, \var{isqrtD}, \var{sqrtD}.
1630:
1631: \noindent Also available are
1632:
1633: $\teb{redimag}(x)$ (= $\teb{qfbred}(x)$ where $x$ is definite),
1634:
1635: \noindent and for indefinite forms:
1636:
1637: $\teb{redreal}(x)$ (= $\teb{qfbred}(x)$),
1638:
1639: $\teb{rhoreal}(x)$ (= $\teb{qfbred}(x,1)$),
1640:
1641: $\teb{redrealnod}(x,sq)$ (= $\teb{qfbred}(x,2,,isqrtD)$),
1642:
1643: $\teb{rhorealnod}(x,sq)$ (= $\teb{qfbred}(x,3,,isqrtD)$).
1644:
1645: \syn{primeform}{x,p,\var{prec}}, where the third variable $\var{prec}$ is a
1646: \kbd{long}, but is only taken into account when $x>0$.
1647:
1648: \subsecidx{quadclassunit}$(D,\{\fl=0\},\{\var{tech}=[]\})$:
1649: \idx{Buchmann-McCurley}'s sub-exponential algorithm for computing the class
1650: group of a quadratic field of discriminant $D$. If $D$ is not fundamental,
1651: the function may or may not be defined, but usually is, and often gives the
1652: right answer (a warning is issued). The more general function \tet{bnrinit}
1653: should be used to compute the class group of an order.
1654:
1655: This function should be used instead of \kbd{qfbclassno} or \kbd{quadregula}
1656: when $D<-10^{25}$, $D>10^{10}$, or when the {\it structure\/} is wanted.
1657:
1658: If $\fl$ is non-zero {\it and\/} $D>0$, computes the narrow class group and
1659: regulator, instead of the ordinary (or wide) ones. In the current version
1660: \vers, this doesn't work at all~: use the general function \tet{bnfnarrow}.
1661:
1662: \var{tech} is a row vector of the form $[c_1,c_2]$, where $c_1$ and $c_2$
1663: are positive real numbers which control the execution time and the stack
1664: size. To get maximum speed, set $c_2=c$. To get a rigorous result (under
1665: \idx{GRH}) you must take $c_2=6$. Reasonable values for $c$ are between
1666: $0.1$ and $2$.
1667:
1668: The result of this function is a vector $v$ with 4 components if $D<0$, and
1669: $5$ otherwise. The correspond respectively to
1670:
1671: $\bullet$ $v[1]$~: the class number
1672:
1673: $\bullet$ $v[2]$~: a vector giving the structure of the class group as a
1674: product of cyclic groups;
1675:
1676: $\bullet$ $v[3]$~: a vector giving generators of those cyclic groups (as
1677: binary quadratic forms).
1678:
1679: $\bullet$ $v[4]$~: (omitted if $D < 0$) the regulator, computed to an
1680: accuracy which is the maximum of an internal accuracy determined by the
1681: program and the current default (note that once the regulator is known to a
1682: small accuracy it is trivial to compute it to very high accuracy, see the
1683: tutorial).
1684:
1685: $\bullet$ $v[5]$~: a measure of the correctness of the result. If it is
1686: close to 1, the result is correct (under \idx{GRH}). If it is close to a
1687: larger integer, this shows that the class number is off by a factor equal
1688: to this integer, and you must start again with a larger value for $c_1$ or
1689: a different random seed. In this case, a warning message is printed.
1690:
1691: \syn{quadclassunit0}{D,\fl,tech}. Also available are
1692: $\teb{buchimag}(D,c_1,c_2)$ and $\teb{buchreal}(D,\fl,c_1,c_2)$.
1693:
1694: \subsecidx{quaddisc}$(x)$: discriminant of the quadratic field
1695: $\Q(\sqrt{x})$, where $x\in\Q$.
1696:
1697: \syn{quaddisc}{x}.
1698:
1699: \subsecidx{quadhilbert}$(D,\{\fl=0\})$: relative equation defining the
1700: \idx{Hilbert class field} of the quadratic field of discriminant $D$.
1701: If $\fl$ is non-zero
1702: and $D<0$, outputs $[\var{form},\var{root}(\var{form})]$ (to be used for
1703: constructing subfields).
1704: Uses complex multiplication in the imaginary case and \idx{Stark units}
1705: in the real case.
1706:
1707: \syn{quadhilbert}{D,\fl,\var{prec}}.
1708:
1709: \subsecidx{quadgen}$(x)$: creates the quadratic number\sidx{omega}
1710: $\omega=(a+\sqrt{x})/2$ where $a=0$ if $x\equiv0\mod4$,
1711: $a=1$ if $x\equiv1\mod4$, so that $(1,\omega)$ is an integral basis for
1712: the quadratic order of discriminant $x$. $x$ must be an integer congruent to
1713: 0 or 1 modulo 4.
1714:
1715: \syn{quadgen}{x}.
1716:
1717: \subsecidx{quadpoly}$(D,\{v=x\})$: creates the ``canonical'' quadratic
1718: polynomial (in the variable $v$) corresponding to the discriminant $D$,
1719: i.e.~the minimal polynomial of $\kbd{quadgen}(x)$. $D$ must be an integer
1720: congruent to 0 or 1 modulo 4.
1721:
1722: \syn{quadpoly0}{x,v}.
1723:
1724: \subsecidx{quadray}$(D,f,\{\fl=0\})$: relative equation for the ray class
1725: field of conductor $f$ for the quadratic field of discriminant $D$ (which
1726: can also be a \kbd{bnf}). \fl\ is only meaningful when $D<0$. If it's an odd
1727: integer, outputs instead the vector of $[\var{ideal},
1728: \var{corresponding root}]$.
1729:
1730: If $\fl=0$ or 1, uses the $\sigma$ function, while if $\fl>1$, uses the
1731: Weierstrass $\wp$ function, which is less efficient and may disappear in
1732: future versions (not all special cases have been implemented in this case).
1733: Finally, \fl\ can also be a two-component vector $[\lambda,\fl]$, where
1734: \fl\ is as above and $\lambda$ is the technical element of bnf necessary
1735: for Schertz's method using $\sigma$. In that case, returns 0 if $\lambda$
1736: is not suitable.
1737:
1738: If $D>0$, the function may fail with the following message
1739: \bprog%
1740: "Cannot find a suitable modulus in FindModulus"
1741: \eprog
1742: See the comments in \tet{bnrstark} about this problem.
1743:
1744: \syn{quadray}{D,f,\fl}.
1745:
1746: \subsecidx{quadregulator}$(x)$: regulator of the quadratic field of positive
1747: discriminant $x$. Returns an error if $x$ is not a discriminant (fundamental or not) or
1748: if $x$ is a square. See also \kbd{quadclassunit} if $x$ is large.
1749:
1750: \syn{regula}{x,\var{prec}}.
1751:
1752: \subsecidx{quadunit}$(x)$: fundamental unit\sidx{fundamental units} of the
1753: real quadratic field $\Q(\sqrt x)$ where $x$ is the positive discriminant
1754: of the field. If $x$ is not a fundamental discriminant, this probably gives
1755: the fundamental unit of the corresponding order. $x$ must be of type
1756: integer, and the result is a quadratic number.
1757:
1758: \syn{fundunit}{x}.
1759:
1760: \subsecidx{removeprimes}$(\{x=[\,]\})$: removes the primes listed in $x$ from
1761: the prime number table. $x$ can also be a single integer. List the current
1762: extra primes if $x$ is omitted.
1763:
1764: \syn{removeprimes}{x}.
1765:
1766: \subsecidx{sigma}$(x,\{k=1\})$: sum of the $k^{\text{th}}$ powers of the
1767: positive divisors of $x$. $x$ must be of type integer.
1768:
1769: \syn{sumdiv}{x} (= $\teb{sigma}(x)$) or
1770: $\teb{gsumdivk}(x,k)$ (= $\teb{sigma}(x,k)$), where $k$ is a C long integer.
1771:
1772: \subsecidx{sqrtint}$(x)$: integer square root of $x$, which must be of PARI
1773: type integer. The result is non-negative and rounded towards zero. A
1774: negative $x$ is allowed, and the result in that case is \kbd{I*sqrtint(-x)}.
1775:
1776: \syn{racine}{x}.
1777:
1778: \subsecidx{znlog}$(x,g)$: $g$ must be a primitive root mod a prime $p$, and
1779: the result is the discrete log of $x$ in the multiplicative group
1780: $(\Z/p\Z)^*$. This function using a simple-minded baby-step/giant-step
1781: approach and requires $O(\sqrt{p})$ storage, hence it cannot be used for
1782: $p$ greater than about $10^13$.
1783:
1784: \syn{znlog}{x,g}.
1785:
1786: \subsecidx{znorder}$(x)$: $x$ must be an integer mod $n$, and the result is the
1787: order of $x$ in the multiplicative group $(\Z/n\Z)^*$. Returns an error if $x$
1788: is not invertible.
1789:
1790: \syn{order}{x}.
1791:
1792: \subsecidx{znprimroot}$(x)$: returns a primitive root of $x$, where $x$
1793: is a prime power.
1794:
1795: \syn{gener}{x}.
1796:
1797: \subsecidx{znstar}$(n)$: gives the structure of the multiplicative group
1798: $(\Z/n\Z)^*$ as a 3-component row vector $v$, where $v[1]=\phi(n)$ is the
1799: order of that group, $v[2]$ is a $k$-component row-vector $d$ of integers
1800: $d[i]$ such that $d[i]>1$ and $d[i]\mid d[i-1]$ for $i \ge 2$ and
1801: $(\Z/n\Z)^* \simeq \prod_{i=1}^k(\Z/d[i]\Z)$, and $v[3]$ is a $k$-component row
1802: vector giving generators of the image of the cyclic groups $\Z/d[i]\Z$.
1803:
1804: \syn{znstar}{n}.
1805:
1806: \section{Functions related to elliptic curves}
1807:
1808: We have implemented a number of functions which are useful for number
1809: theorists working on elliptic curves. We always use \idx{Tate}'s notations.
1810: The functions assume that the curve is given by a general Weierstrass
1811: model\sidx{Weierstrass equation}
1812: $$
1813: y^2+a_1xy+a_3y=x^3+a_2x^2+a_4x+a_6,
1814: $$
1815: where a priori the $a_i$ can be of any scalar type. This curve can be
1816: considered as a five-component vector \kbd{E=[a1,a2,a3,a4,a6]}. Points on
1817: \kbd{E} are represented as two-component vectors \kbd{[x,y]}, except for the
1818: point at infinity, i.e.~the identity element of the group law, represented by
1819: the one-component vector \kbd{[0]}.
1820:
1821: It is useful to have at one's disposal more information. This is given by
1822: the function \tet{ellinit} (see there), which usually gives a 19 component
1823: vector (which we will call a long vector in this section). If a specific flag
1824: is added, a vector with only 13 component will be output (which we will call
1825: a medium vector). A medium vector just gives the first 13 components of the
1826: long vector corresponding to the same curve, but is of course faster to
1827: compute. The following \idx{member functions} are available to deal with the
1828: output of \kbd{ellinit}:
1829: \settabs\+xxxxxxxxxxxxxxxxxx&: &\cr
1830:
1831: \+ \kbd{a1}--\kbd{a6}, \kbd{b2}--\kbd{b8}, \kbd{c4}--\kbd{c6} &: &
1832: coefficients of the elliptic curve.\cr
1833:
1834: \+ \tet{area} &: & volume of the complex lattice defining $E$.\cr
1835:
1836: \+ \tet{disc} &: & discriminant of the curve.\cr
1837:
1838: \+ \tet{j} &: & $j$-invariant of the curve.\cr
1839:
1840: \+ \tet{omega}&: & $[\omega_1,\omega_2]$, periods forming a basis of
1841: the complex lattice defining $E$ ($\omega_1$ is the\cr
1842:
1843: \+ & & real period, and $\omega_2/\omega_1$ belongs to
1844: Poincar\'e's half-plane).\cr
1845:
1846: \+ \tet{eta} &: & quasi-periods $[\eta_1, \eta_2]$, such that
1847: $\eta_1\omega_2-\eta_2\omega_1=i\pi$.\cr
1848:
1849: \+ \tet{roots}&: & roots of the associated Weierstrass equation.\cr
1850:
1851: \+ \tet{tate} &: & $[u^2,u,v]$ in the notation of Tate.\cr
1852:
1853: \+ \tet{w} &: & Mestre's $w$ (this is technical).\cr
1854:
1855: Their use is best described by an example: assume that $E$ was output by
1856: \kbd{ellinit}, then typing \kbd{$E$.disc} will retrieve the curve's
1857: discriminant. The member functions \kbd{area}, \kbd{eta} and \kbd{omega} are
1858: only available for curves over $\Q$. Conversely, \kbd{tate} and \kbd{w} are
1859: only available for curves defined over $\Q_p$.\smallskip
1860:
1861: Some functions, in particular those relative to height computations (see
1862: \kbd{ellheight}) require also that the curve be in minimal Weierstrass
1863: form. This is achieved by the function \kbd{ellglobalred}.
1864:
1865: All functions related to elliptic curves share the prefix \kbd{ell}, and the
1866: precise curve we are interested in is always the first argument, in either
1867: one of the three formats discussed above, unless otherwise specified. For
1868: instance, in functions which do not use the extra information given by long
1869: vectors, the curve can be given either as a five-component vector, or by one
1870: of the longer vectors computed by \kbd{ellinit}.
1871:
1872: \subsecidx{elladd}$(E,z1,z2)$: sum of the points $z1$ and $z2$ on the
1873: elliptic curve corresponding to the vector $E$.
1874:
1875: \syn{addell}{E,z1,z2}.
1876:
1877: \subsecidx{ellak}$(E,n)$: computes the coefficient $a_n$ of the $L$-function
1878: of the elliptic curve $E$, i.e.~in principle coefficients of a newform of
1879: weight 2 assuming \idx{Taniyama-Weil}. $E$ must be a medium or long vector
1880: of the type given by \kbd{ellinit}.
1881: For this function to work for every $n$ and not
1882: just those prime to the conductor, $E$ must be a minimal Weierstrass
1883: equation. If this is not the case, use the function \kbd{ellglobalred} first
1884: before using \kbd{ellak}.
1885:
1886: \syn{akell}{E,n}.
1887:
1888: \subsecidx{ellan}$(E,n)$: computes the vector of the first $n$ $a_k$
1889: corresponding to the elliptic curve $E$. All comments in \kbd{ellak}
1890: description remain valid.
1891:
1892: \syn{anell}{E,n}, where $n$ is a C integer.
1893:
1894: \subsecidx{ellap}$(E,p,\{\fl=0\})$: computes the $a_p$ corresponding to the
1895: elliptic curve $E$ and the prime number $p$. These are defined by the
1896: equation $\#E(\F_p) = p+1 - a_p$, where $\#E(\F_p)$ stands for the number
1897: of points of the curve $E$ over the finite field $\F_p$. When $\fl$ is $0$,
1898: this uses the baby-step giant-step method and a trick due to Mestre. This
1899: runs in time $O(p^{1/4})$ and requires $O(p^{1/4})$ storage, hence becomes
1900: unreasonable when $p$ has about 30 digits.
1901:
1902: If $\fl$ is $1$, computes the $a_p$ as a sum of Legendre symbols. This is
1903: slower than the previous method as soon as $p$ is greater than 100, say.
1904:
1905: No checking is done that $p$ is indeed prime. $E$ must be a medium or long
1906: vector of the type given by \kbd{ellinit}, defined over $\Q$, $\F_p$ or
1907: $\Q_p$.
1908:
1909: \syn{ellap0}{E,p,\fl}. Also available are $\teb{apell}(E,p)$, corresponding
1910: to $\fl=0$, and $\teb{apell2}(E,p)$ ($\fl=1$).
1911:
1912: \subsecidx{ellbil}$(E,z1,z2)$: if $z1$ and $z2$ are points on the elliptic
1913: curve $E$, this function computes the value of the canonical bilinear form on
1914: $z1$, $z2$:
1915: $$
1916: \kbd{ellheight}(E,z1\kbd{+}z2) - \kbd{ellheight}(E,z1) - \kbd{ellheight}(E,z2)
1917: $$
1918: where \kbd{+} denotes of course addition on $E$. In addition, $z1$ or $z2$
1919: (but not both) can be vectors or matrices. Note that this is equal to twice
1920: some normalizations. $E$ is assumed to be integral, given by a minimal model.
1921:
1922: \syn{bilhell}{E,z1,z2,\var{prec}}.
1923:
1924: \subsecidx{ellchangecurve}$(E,v)$: changes the data for the elliptic curve $E$
1925: by changing the coordinates using the vector \kbd{v=[u,r,s,t]}, i.e.~if $x'$
1926: and $y'$ are the new coordinates, then $x=u^2x'+r$, $y=u^3y'+su^2x'+t$.
1927: The vector $E$ must be a medium or long vector of the type given by
1928: \kbd{ellinit}.
1929:
1930: \syn{coordch}{E,v}.
1931:
1932: \subsecidx{ellchangepoint}$(x,v)$: changes the coordinates of the point or
1933: vector of points $x$ using the vector \kbd{v=[u,r,s,t]}, i.e.~if $x'$ and
1934: $y'$ are the new coordinates, then $x=u^2x'+r$, $y=u^3y'+su^2x'+t$ (see also
1935: \kbd{ellchangecurve}).
1936:
1937: \syn{pointch}{x,v}.
1938:
1939: \subsecidx{elleisnum}$(E,k,\{\fl=0\})$: $E$ being an elliptic curve as
1940: output by \kbd{ellinit} (or, alternatively, given by a 2-component vector
1941: $[\omega_1,\omega_2]$), and $k$ being an even positive integer, computes
1942: the numerical value of the Eisenstein series of weight $k$ at $E$. When
1943: \fl\ is non-zero and $k=4$ or 6, returns $g_2$ or $g_3$ with the correct
1944: normalization.
1945:
1946: \syn{elleisnum}{E,k,\fl}.
1947:
1948: \subsecidx{elleta}$(om)$: returns the two-component row vector
1949: $[\eta_1,\eta_2]$ of quasi-periods associated to $\kbd{om} = [\omega_1,
1950: \omega_2]$
1951:
1952: \syn{elleta}{om, \var{prec}}
1953:
1954: \subsecidx{ellglobalred}$(E)$: calculates the arithmetic conductor, the global
1955: minimal model of $E$ and the global \idx{Tamagawa number} $c$. Here $E$ is an
1956: elliptic curve given by a medium or long vector of the type given by
1957: \kbd{ellinit}, {\it and is supposed to have all its coefficients $a_i$ in}
1958: $\Q$. The result is a 3 component vector $[N,v,c]$. $N$ is the arithmetic
1959: conductor of the curve, $v$ is itself a vector $[u,r,s,t]$ with rational
1960: components. It gives a coordinate change for $E$ over $\Q$ such that the
1961: resulting model has integral coefficients, is everywhere minimal, $a_1$ is 0
1962: or 1, $a_2$ is 0, 1 or $-1$ and $a_3$ is 0 or 1. Such a model is unique, and
1963: the vector $v$ is unique if we specify that $u$ is positive. To get the new
1964: model, simply type \kbd{ellchangecurve(E,v)}. Finally $c$ is the product of
1965: the local Tamagawa numbers $c_p$, a quantity which enters in the
1966: \idx{Birch and Swinnerton-Dyer conjecture}.
1967:
1968: \syn{globalreduction}{E}.
1969:
1970: \subsecidx{ellheight}$(E,z,\{\fl=0\})$: global \idx{N\'eron-Tate height} of
1971: the point $z$ on the elliptic curve $E$. The vector $E$ must be a long vector
1972: of the type given by \kbd{ellinit}, with $\fl=1$. If $\fl=0$, this
1973: computation is done using sigma and theta-functions and a trick due to J.
1974: Silverman. If $\fl=1$, use Tate's $4^n$ algorithm, which is much slower.
1975:
1976: \syn{ellheight0}{E,z,\fl,\var{prec}}. The Archimedean
1977: contribution alone is given by the library function
1978: $\teb{hell}(E,z,\var{prec})$.
1979: Also available are $\teb{ghell}(E,z,\var{prec})$ ($\fl=0$) and
1980: $\teb{ghell2}(E,z,\var{prec})$ ($\fl=1$).
1981:
1982: \subsecidx{ellheightmatrix}$(E,x)$: $x$ being a vector of points, this
1983: function outputs the Gram matrix of $x$ with respect to the N\'eron-Tate
1984: height, in other words, the $(i,j)$ component of the matrix is equal to
1985: \kbd{ellbil($E$,x[$i$],x[$j$])}. The rank of this matrix, at least in some
1986: approximate sense, gives the rank of the set of points, and if $x$ is a
1987: basis of the \idx{Mordell-Weil group} of $E$, its determinant is equal to
1988: the regulator of $E$. Note that this matrix should be divided by 2 to be in
1989: accordance with certain normalizations. $E$ is assumed to be integral,
1990: given by a minimal model.
1991:
1992: \syn{mathell}{E,x,\var{prec}}.
1993:
1994: \subsecidx{ellinit}$(E,\{\fl=0\})$: computes some fixed data concerning the
1995: elliptic curve given by the five-component vector $E$, which will be
1996: essential for most further computations on the curve. The result is a
1997: 19-component vector E (called a long vector in this section), shortened
1998: to 13 components (medium vector) if $\fl=1$. Both contain the
1999: following information in the first 13 components:
2000: %
2001: $$ a_1,a_2,a_3,a_4,a_6,b_2,b_4,b_6,b_8,c_4,c_6,\Delta,j.$$
2002: %
2003: In particular, the discriminant is $E[12]$ (or \kbd{$E$.disc}), and the
2004: $j$-invariant is $E[13]$ (or \kbd{$E$.j}).
2005:
2006: The other six components are only present if $\fl$ is $0$ (or omitted!).
2007: Their content depends on whether the curve is defined over $\R$ or not:
2008: \smallskip
2009: $\bullet$ When $E$ is defined over $\R$, $E[14]$ (\kbd{$E$.roots}) is a
2010: vector whose three components contain the roots of the associated Weierstrass
2011: equation. If the roots are all real, then they are ordered by decreasing
2012: value. If only one is real, it is the first component of $E[14]$.
2013:
2014: $E[15]$ (\kbd{$E$.omega[1]}) is the real period of $E$ (integral of
2015: $dx/(2y+a_1x+a_3)$ over the connected component of the identity element of
2016: the real points of the curve), and $E[16]$ (\kbd{$E$.omega[2]}) is a complex
2017: period. In other words, $\omega_1=E[15]$ and $\omega_2=E[16]$ form a basis of
2018: the complex lattice defining $E$ (\kbd{$E$.omega}), with
2019: $\tau=\dfrac{\omega_2}{\omega_1}$ having positive imaginary part.
2020:
2021: $E[17]$ and $E[18]$ are the corresponding values $\eta_1$ and $\eta_2$ such
2022: that $\eta_1\omega_2-\eta_2\omega_1=i\pi$, and both can be retrieved by
2023: typing \kbd{$E$.eta} (as a row vector whose components are the $\eta_i$).
2024:
2025: Finally, $E[19]$ (\kbd{$E$.area}) is the volume of the complex lattice defining
2026: $E$.\smallskip
2027:
2028: $\bullet$ When $E$ is defined over $\Q_p$, the $p$-adic valuation of $j$
2029: must be negative. Then $E[14]$ (\kbd{$E$.roots}) is the vector with a single
2030: component equal to the $p$-adic root of the associated Weierstrass equation
2031: corresponding to $-1$ under the Tate parametrization.
2032:
2033: $E[15]$ is equal to the square of the $u$-value, in the notation of Tate.
2034:
2035: $E[16]$ is the $u$-value itself, if it belongs to $\Q_p$, otherwise zero.
2036:
2037: $E[17]$ is the value of Tate's $q$ for the curve $E$.
2038:
2039: \kbd{$E$.tate} will yield the three-component vector $[u^2,u,q]$.
2040:
2041: $E[18]$ (\kbd{$E$.w}) is the value of Mestre's $w$ (this is technical), and
2042: $E[19]$ is arbitrarily set equal to zero.
2043: \smallskip
2044: For all other base fields or rings, the last six components are arbitrarily
2045: set equal to zero (see also the description of member functions related to
2046: elliptic curves at the beginning of this section).
2047:
2048: \syn{ellinit0}{E,\fl,\var{prec}}. Also available are
2049: $\teb{initell}(E,\var{prec})$ ($\fl=0$) and
2050: $\teb{smallinitell}(E,\var{prec})$ ($\fl=1$).
2051:
2052: \subsecidx{ellisoncurve}$(E,z)$: gives 1 (i.e.~true) if the point $z$ is on
2053: the elliptic curve $E$, 0 otherwise. If $E$ or $z$ have imprecise coefficients,
2054: an attempt is made to take this into account, i.e.~an imprecise equality is
2055: checked, not a precise one.
2056:
2057: \syn{oncurve}{E,z}, and the result is a \kbd{long}.
2058:
2059: \subsecidx{ellj}$(x)$: elliptic $j$-invariant. $x$ must be a complex number
2060: with positive imaginary part, or convertible into a power series or a
2061: $p$-adic number with positive valuation.
2062:
2063: \syn{jell}{x,\var{prec}}.
2064:
2065: \subsecidx{elllocalred}$(E,p)$: calculates the \idx{Kodaira} type of the
2066: local fiber of the elliptic curve $E$ at the prime $p$.
2067: $E$ must be given by a medium or
2068: long vector of the type given by \kbd{ellinit}, and is assumed to have all
2069: its coefficients $a_i$ in $\Z$. The result is a 4-component vector
2070: $[f,kod,v,c]$. Here $f$ is the exponent of $p$ in the arithmetic conductor of
2071: $E$, and $kod$ is the Kodaira type which is coded as follows:
2072:
2073: 1 means good reduction (type I$_0$), 2, 3 and 4 mean types II, III and IV
2074: respectively, $4+\nu$ with $\nu>0$ means type I$_\nu$;
2075: finally the opposite values $-1$, $-2$, etc.~refer to the starred types
2076: I$_0^*$, II$^*$, etc. The third component $v$ is itself a vector $[u,r,s,t]$
2077: giving the coordinate changes done during the local reduction. Normally, this
2078: has no use if $u$ is 1, that is, if the given equation was already minimal.
2079: Finally, the last component $c$ is the local \idx{Tamagawa number} $c_p$.
2080:
2081: \syn{localreduction}{E,p}.
2082:
2083: \subsecidx{elllseries}$(E,s,\{A=1\})$: $E$ being a medium or long vector
2084: given by \kbd{ellinit}, this computes the value of the L-series of $E$ at
2085: $s$. It is assumed that $E$ is a minimal model over $\Z$ and that the curve
2086: is a modular elliptic curve. The optional parameter $A$ is a cutoff point for
2087: the integral, which must be chosen close to 1 for best speed. The result
2088: must be independent of $A$, so this allows some internal checking of the
2089: function.
2090:
2091: Note that if the conductor of the curve is large, say greater than $10^{12}$,
2092: this function will take an unreasonable amount of time since it uses an
2093: $O(N^{1/2})$ algorithm.
2094:
2095: \syn{lseriesell}{E,s,A,\var{prec}} where $\var{prec}$ is a \kbd{long} and an
2096: omitted $A$ is coded as \kbd{NULL}.
2097:
2098: \subsecidx{ellorder}$(E,z)$: gives the order of the point $z$ on the elliptic
2099: curve $E$ if it is a torsion point, zero otherwise. In the present version
2100: \vers{}, this is implemented only for elliptic curves defined over $\Q$.
2101:
2102: \syn{orderell}{E,z}.
2103:
2104: \subsecidx{ellordinate}$(E,x)$: gives a 0, 1 or 2-component vector containing
2105: the $y$-coordinates of the points of the curve $E$ having $x$ as
2106: $x$-coordinate.
2107:
2108: \syn{ordell}{E,x}.
2109:
2110: \subsecidx{ellpointtoz}$(E,z)$: if $E$ is an elliptic curve with coefficients
2111: in $\R$, this computes a complex number $t$ (modulo the lattice defining
2112: $E$) corresponding to the point $z$, i.e.~such that, in the standard
2113: Weierstrass model, $\wp(t)=z[1],\wp'(t)=z[2]$. In other words, this is the
2114: inverse function of \kbd{ellztopoint}.
2115:
2116: If $E$ has coefficients in $\Q_p$, then either Tate's $u$ is in $\Q_p$, in
2117: which case the output is a $p$-adic number $t$ corresponding to the point $z$
2118: under the Tate parametrization, or only its square is, in which case the
2119: output is $t+1/t$. $E$ must be a long vector output by \kbd{ellinit}.
2120:
2121: \syn{zell}{E,z,\var{prec}}.
2122:
2123: \subsecidx{ellpow}$(E,z,n)$: computes $n$ times the point $z$ for the
2124: group law on the elliptic curve $E$. Here, $n$ can be in $\Z$, or $n$
2125: can be a complex quadratic integer if the curve $E$ has complex multiplication
2126: by $n$ (if not, an error message is issued).
2127:
2128: \syn{powell}{E,z,n}.
2129:
2130: \subsecidx{ellrootno}$(E,\{p=1\})$: $E$ being a medium or long vector given
2131: by \kbd{ellinit}, this computes the local (if $p\neq 1$) or global (if $p=1$)
2132: root number of the L-series of the elliptic curve $E$. Note that the global
2133: root number is the sign of the functional equation and conjecturally is the
2134: parity of the rank of the \idx{Mordell-Weil group}.
2135: The equation for $E$ must have
2136: coefficients in $\Q$ but need {\it not\/} be minimal.
2137:
2138: \syn{ellrootno}{E,p} and the result (equal to $\pm1$) is a \kbd{long}.
2139:
2140: \subsecidx{ellsigma}$(E,z,\{\fl=0\})$: value of the Weierstrass $\sigma$
2141: function of the lattice associated to $E$ as given by \kbd{ellinit}
2142: (alternatively, $E$ can be given as a lattice $[\omega_1,\omega_2]$).
2143:
2144: If $\fl=1$, computes an (arbitrary) determination of $\log(\sigma(z))$.
2145:
2146: If $\fl=2,3$, same using the product expansion instead of theta series.
2147: \syn{ellsigma}{E,z,\fl}
2148:
2149: \subsecidx{ellsub}$(E,z1,z2)$: difference of the points $z1$ and $z2$ on the
2150: elliptic curve corresponding to the vector $E$.
2151:
2152: \syn{subell}{E,z1,z2}.
2153:
2154: \subsecidx{elltaniyama}$(E)$: computes the modular parametrization of the
2155: elliptic curve $E$, where $E$ is given in the (long or medium) format output
2156: by \kbd{ellinit}, in the form of a two-component vector $[u,v]$ of power
2157: series, given to the current default series precision. This vector is
2158: characterized by the following two properties. First the point $(x,y)=(u,v)$
2159: satisfies the equation of the elliptic curve. Second, the differential
2160: $du/(2v+a_1u+a_3)$ is equal to $f(z)dz$, a differential form on
2161: $H/\Gamma_0(N)$ where $N$ is the conductor of the curve. The variable used in
2162: the power series for $u$ and $v$ is $x$, which is implicitly understood to be
2163: equal to $\exp(2i\pi z)$. It is assumed that the curve is a {\it strong\/}
2164: \idx{Weil curve}, and the Manin constant is equal to 1. The equation of
2165: the curve $E$ must be minimal (use \kbd{ellglobalred} to get a minimal
2166: equation).
2167:
2168: \syn{taniyama}{E}, and the precision of the result is determined by the
2169: global variable \kbd{precdl}.
2170:
2171: \subsecidx{elltors}$(E,\{\fl=0\})$: if $E$ is an elliptic curve {\it defined
2172: over $\Q$}, outputs the torsion subgroup of $E$ as a 3-component vector
2173: \kbd{[t,v1,v2]}, where \kbd{t} is the order of the torsion group, \kbd{v1}
2174: gives the structure of the torsion group as a product of cyclic groups
2175: (sorted by decreasing order), and \kbd{v2} gives generators for these cyclic
2176: groups. $E$ must be a long vector as output by \kbd{ellinit}.
2177:
2178: \bprog%
2179: ? E = ellinit([0,0,0,-1,0]);
2180: ? elltors(E)
2181: \%1 = [4, [2, 2], [[0, 0], [1, 0]]]
2182: \eprog
2183: Here, the torsion subgroup is isomorphic to $\Z/2\Z \times \Z/2\Z$, with
2184: generators $[0,0]$ and $[1,0]$.
2185:
2186: If $\fl = 0$, use Doud's algorithm~: bound torsion by computing $\#E(\F_p)$
2187: for small primes of good reduction, then look for torsion points using
2188: Weierstrass parametrization (and Mazur's classification).
2189:
2190: If $\fl = 1$, use Lutz--Nagell ({\it much} slower), $E$ is allowed to be a
2191: medium vector.
2192:
2193: \syn{elltors0}{E,flag}.
2194:
2195: \subsecidx{ellwp}$(E,\{z=x\},\{\fl=0\})$:
2196:
2197: Computes the value at $z$ of the Weierstrass $\wp$ function attached to the
2198: elliptic curve $E$ as given by \kbd{ellinit} (alternatively, $E$ can be
2199: given as a lattice $[\omega_1,\omega_2]$).
2200:
2201: If $z$ is omitted or is a simple variable, computes the {\it power
2202: series\/} expansion in $z$ (starting $z^{-2}+O(z^2)$). The number of terms
2203: to an {\it even\/} power in the expansion is the default serieslength in
2204: GP, and the second argument (C long integer) in library mode.
2205:
2206: Optional \fl\ is (for now) only taken into account when $z$ is numeric, and
2207: means 0: compute only $\wp(z)$, 1: compute $[\wp(z),\wp'(z)]$.
2208:
2209: \syn{ellwp0}{E,z,\fl,\var{prec},\var{precdl}}. Also available is
2210: \teb{weipell}$(E,\var{precdl})$ for the power series (in
2211: $x=\kbd{polx[0]}$).
2212:
2213: \subsecidx{ellzeta}$(E,z)$: value of the Weierstrass $\zeta$ function of the
2214: lattice associated to $E$ as given by \kbd{ellinit} (alternatively, $E$ can
2215: be given as a lattice $[\omega_1,\omega_2]$).
2216:
2217: \syn{ellzeta}{E,z}.
2218:
2219: \subsecidx{ellztopoint}$(E,z)$: $E$ being a long vector, computes the
2220: coordinates $[x,y]$ on the curve $E$ corresponding to the complex number $z$.
2221: Hence this is the inverse function of \kbd{ellpointtoz}. In other words, if
2222: the curve is put in Weierstrass form, $[x,y]$ represents the
2223: \idx{Weierstrass $\wp$-function} and its derivative.
2224: If $z$ is in the lattice defining $E$ over
2225: $\C$, the result is the point at infinity $[0]$.
2226:
2227: \syn{pointell}{E,z,\var{prec}}.
2228:
2229: \section{Functions related to general number fields}
2230:
2231: In this section can be found functions which are used almost exclusively for
2232: working in general number fields. Other less specific functions can be found
2233: in the next section on polynomials. Functions related to quadratic number
2234: fields can be found in the section \secref{se:arithmetic} (Arithmetic
2235: functions).
2236:
2237: \noindent We shall use the following conventions:
2238:
2239: $\bullet$ $\var{\idx{nf}}$ denotes a number field, i.e.~a 9-component vector
2240: in the format output by \tet{nfinit}. This contains the basic arithmetic data
2241: associated to the number field: signature, maximal order, discriminant, etc.
2242:
2243: $\bullet$ $\var{\idx{bnf}}$ denotes a big number field, i.e.~a 10-component
2244: vector in the format output by \tet{bnfinit}. This contains $\var{nf}$ and
2245: the deeper invariants of the field: units, class groups, as well as a lot of
2246: technical data necessary for some complex fonctions like \kbd{bnfisprincipal}.
2247:
2248: $\bullet$ $\var{\idx{bnr}}$ denotes a big ``ray number field'', i.e.~some data
2249: structure output by \kbd{bnrinit}, even more complicated than $\var{bnf}$,
2250: corresponding to the ray class group structure of the field, for some
2251: modulus.
2252:
2253: $\bullet$ $\var{\idx{rnf}}$ denotes a relative number field (see below).
2254: \smallskip
2255:
2256: $\bullet$ ${\it \idx{ideal}}$ can mean any of the following:
2257:
2258: \quad -- a $\Z$-basis, in \idx{Hermite normal form}
2259: (HNF) or not. In this case $x$ is a square matrix.
2260:
2261: \quad -- an {\it \idx{idele}}, i.e.~a 2-component vector, the first
2262: being an ideal given as a $\Z$--basis, the second being a $r_1+r_2$-component
2263: row vector giving the complex logarithmic Archimedean information.
2264:
2265: \quad -- a $\Z_K$-generating system for an ideal.
2266:
2267: \quad -- a {\it column} vector $x$ expressing an element of the number field
2268: on the integral basis, in which case the ideal is treated as being the
2269: principal idele (or ideal) generated by $x$.
2270:
2271: \quad -- a prime ideal, i.e.~a 5-component vector in the format output by
2272: \kbd{idealprimedec}.
2273:
2274: \quad -- a polmod $x$, i.e.~an algebraic integer, in which case the ideal
2275: is treated as being the principal idele generated by $x$.
2276:
2277: \quad -- an integer or a rational number, also treated as a principal idele.
2278:
2279: $\bullet$ a {\it\idx{character}} on the Abelian group
2280: $\bigoplus (\Z/N_i\Z) g_i$
2281: is given by a row vector $\chi = [a_1,\ldots,a_n]$ such that
2282: $\chi(\prod g_i^{n_i}) = exp(2i\pi\sum a_i n_i / N_i)$.
2283:
2284:
2285: \misctitle{Warnings:}
2286:
2287: 1) An element in $\var{nf}$ can be expressed either as a polmod or as a
2288: vector of components on the integral basis \kbd{\var{nf}.zk}. It is absolutely
2289: essential that all such vectors be {\it column\/} vectors.
2290:
2291: 2) When giving an ideal by a $\Z_K$ generating system to a function expecting
2292: an ideal, it must be ensured that the function understands that it is a
2293: $\Z_K$-generating system and not a $\Z$-generating system. When the number of
2294: generators is strictly less than the degree of the field, there is no
2295: ambiguity and the program assumes that one is giving a $\Z_K$-generating set.
2296: When the number of generators is greater than or equal to the degree of the
2297: field, however, the program assumes on the contrary that you are giving a
2298: $\Z$-generating set. If this is not the case, you {\it must\/} absolutely
2299: change it into a $\Z$-generating set, the simplest manner being to use
2300: \kbd{idealhnf(\var{nf},$x$)}.
2301:
2302: Concerning relative extensions, some additional definitions are necessary.
2303:
2304: $\bullet$ A {\it\idx{relative matrix}\/} will be a matrix whose entries are
2305: elements of a (given) number field $\var{nf}$, always expressed as column
2306: vectors on the integral basis \kbd{\var{nf}.zk}. Hence it is a matrix of
2307: vectors.
2308:
2309: $\bullet$ An {\it\idx{ideal list}\/} will be a row vector of (fractional)
2310: ideals of the number field $\var{nf}$.
2311:
2312: $\bullet$ A {\it\idx{pseudo-matrix}\/} will be a pair $(A,I)$ where $A$ is a
2313: relative matrix and $I$ an ideal list whose length is the same as the number
2314: of columns of $A$. This pair will be represented by a 2-component row vector.
2315:
2316: $\bullet$ The {\it\idx{module}\/} generated by a pseudo-matrix $(A,I)$ is
2317: the sum $\sum_i{\Bbb a}_jA_j$ where the ${\Bbb a}_j$ are the ideals of $I$
2318: and $A_j$ is the $j$-th column of $A$.
2319:
2320: $\bullet$ A pseudo-matrix $(A,I)$ is a {\it\idx{pseudo-basis}} of the module it
2321: generates if $A$ is a square matrix with non-zero determinant and all the
2322: ideals of $I$ are non-zero. We say that it is in Hermite Normal
2323: Form\sidx{Hermite normal form} (HNF) if
2324: it is upper triangular and all the elements of the diagonal are equal to 1.
2325:
2326: $\bullet$ The {\it determinant\/} of a pseudo-basis $(A,I)$ is the ideal
2327: equal to the product of the determinant of $A$ by all the ideals of $I$. The
2328: determinant of a pseudo-matrix is the determinant of any pseudo-basis of the
2329: module it generates.
2330:
2331: Finally, when defining a relative extension, the base field should be
2332: defined by a variable having a lower priority (i.e.~a higher number)
2333: than the variable defining the extension. For example, under GP you can
2334: use the variable name $y$ (or $t$) to define the base field, and the
2335: variable name $x$ to define the relative extension.
2336:
2337: Now a last set of definitions concerning the way big ray number fields
2338: (or \var{bnr}) are input, using class field theory.
2339: These are defined by a triple
2340: $a1$, $a2$, $a3$, where the defining set $[a1,a2,a3]$ can have any of the
2341: following forms: $[\var{bnr}]$, $[\var{bnr},\var{subgroup}]$,
2342: $[\var{bnf},\var{module}]$, $[\var{bnf},\var{module},\var{subgroup}]$, where:
2343:
2344: $\bullet$ $\var{bnf}$ is as output by \kbd{bnfclassunit} or \kbd{bnfinit},
2345: where units are mandatory unless the ideal is trivial; \var{bnr} by
2346: \kbd{bnrclass} (with $\fl>0$) or \kbd{bnrinit}. This is the ground field.
2347:
2348: $\bullet$ \var{module} is either an ideal in any form (see above) or a
2349: two-component row vector containing an ideal and an $r_1$-component row
2350: vector of flags indicating which real Archimedean embeddings to take in the
2351: module.
2352:
2353: $\bullet$ \var{subgroup} is the HNF matrix of a subgroup of the ray class group
2354: of the ground field for the modulus \var{module}. This is input as a square
2355: matrix expressing generators of a subgroup of the ray class group
2356: \kbd{\var{bnr}.clgp} on the given generators.
2357:
2358: The corresponding \var{bnr} is then the subfield of the ray class field of the
2359: ground field for the given modulus, associated to the given subgroup.
2360:
2361: All the functions which are specific to relative extensions, number fields,
2362: big number fields, big number rays, share the prefix \kbd{rnf}, \kbd{nf},
2363: \kbd{bnf}, \kbd{bnr} respectively. They are meant to take as first argument a
2364: number field of that precise type, respectively output by \kbd{rnfinit},
2365: \kbd{nfinit}, \kbd{bnfinit}, and \kbd{bnrinit}.
2366:
2367: However, and even though it may not be specified in the descriptions of the
2368: functions below, it is permissible, if the function expects a $\var{nf}$, to
2369: use a $\var{bnf}$ instead (which contains much more information). The program
2370: will make the effort of converting to what it needs. On the other hand, if
2371: the program requires a big number field, the program will {\it not\/} launch
2372: \kbd{bnfinit} for you, which can be a costly operation. Instead, it will give
2373: you a specific error message.
2374:
2375: The data types corresponding to the structures described above are rather
2376: complicated. Thus, as we already have seen it with elliptic curves, GP
2377: provides you with some ``member functions'' to retrieve the data you need
2378: from these structures (once they have been initialized of course). The
2379: relevant types of number fields are indicated between parentheses:
2380: \smallskip
2381:
2382: \sidx{member functions}
2383: \settabs\+xxxxxxx&(\var{bnr},x&\var{bnf},x&nf\hskip2pt&)x&: &\cr
2384:
2385: \+\tet{bnf} &(\var{bnr},& \var{bnf}&&)&: & big number field.\cr
2386:
2387: \+\tet{clgp} &(\var{bnr},& \var{bnf}&&)&: & classgroup. This one admits the
2388: following three subclasses:\cr
2389:
2390: \+ \quad \tet{cyc} &&&&&: & \quad cyclic decomposition
2391: (SNF)\sidx{Smith normal form}.\cr
2392:
2393: \+ \quad \kbd{gen}\sidx{gen (member function)} &&&&&: &
2394: \quad generators.\cr
2395:
2396: \+ \quad \tet{no} &&&&&: & \quad number of elements.\cr
2397:
2398: \+\tet{diff} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & the different ideal.\cr
2399:
2400: \+\tet{codiff}&(\var{bnr},& \var{bnf},& \var{nf}&)&: & the codifferent
2401: (inverse of the different in the ideal group).\cr
2402:
2403: \+\tet{disc} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & discriminant.\cr
2404:
2405: \+\tet{fu} &(\var{bnr},& \var{bnf},& \var{nf}&)&: &
2406: \idx{fundamental units}.\cr
2407:
2408: \+\tet{futu} &(\var{bnr},& \var{bnf}&&)&: & $[u,w]$, $u$ is a vector of
2409: fundamental units, $w$ generates the torsion.\cr
2410:
2411: \+\tet{nf} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & number field.\cr
2412:
2413: \+\tet{reg} &(\var{bnr},& \var{bnf},&&)&: & regulator.\cr
2414:
2415: \+\tet{roots}&(\var{bnr},& \var{bnf},& \var{nf}&)&: & roots of the
2416: polnomial generating the field.\cr
2417:
2418: \+\tet{sign} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & $[r_1,r_2]$ the
2419: signature of the field. This means that the field has $r_1$ real \cr
2420: \+ &&&&&& embeddings, $2r_2$ complex ones.\cr
2421:
2422: \+\tet{t2} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & the T2 matrix (see
2423: \kbd{nfinit}).\cr
2424:
2425: \+\tet{tu} &(\var{bnr},& \var{bnf},&&)&: & a generator for the torsion
2426: units.\cr
2427:
2428: \+\tet{tufu} &(\var{bnr},& \var{bnf},&&)&: & as \kbd{futu}, but outputs
2429: $[w,u]$.\cr
2430:
2431: \+\tet{zk} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & integral basis, i.e.~a
2432: $\Z$-basis of the maximal order.\cr
2433:
2434: \+\tet{zkst} &(\var{bnr}& & &)&: & structure of $(\Z_K/m)^*$ (can be
2435: extracted also from an \var{idealstar}).\cr
2436:
2437: For instance, assume that $\var{bnf} = \kbd{bnfinit}(\var{pol})$, for some
2438: polynomial. Then \kbd{\var{bnf}.clgp} retrieves the class group, and
2439: \kbd{\var{bnf}.clgp.no} the class number. If we had set $\var{bnf} =
2440: \kbd{nfinit}(\var{pol})$, both would have output an error message. All these
2441: functions are completely recursive, thus for instance
2442: \kbd{\var{bnr}.bnf.nf.zk} will yield the maximal order of \var{bnr} (which
2443: you could get directly with a simple \kbd{\var{bnr}.zk} of course).
2444:
2445: \medskip
2446: The following functions, starting with \kbd{buch} in library mode, and with
2447: \kbd{bnf} under GP, are implementations of the sub-exponential algorithms for
2448: finding class and unit groups under \idx{GRH}, due to Hafner-McCurley,
2449: \idx{Buchmann} and Cohen-Diaz-Olivier.
2450:
2451: The general call to the functions concerning class groups of general number
2452: fields (i.e.~excluding \kbd{quadclassunit}) involves a polynomial $P$ and a
2453: technical vector
2454: $$\var{tech} = [c,c2,\var{nrel},\var{borne},\var{nrpid},\var{minsfb}],$$
2455: where the parameters are to be understood as follows:
2456:
2457: $P$ is the defining polynomial for the number field, which must be in
2458: $\Z[X]$, irreducible and, preferably, monic. In fact, if you supply a
2459: non-monic polynomial at this point, GP will issue a warning, then
2460: {\it transform your polynomial\/} so that it becomes monic. Instead of
2461: the normal
2462: result, say \kbd{res}, you then get a vector \kbd{[res,Mod(a,Q)]}, where
2463: \kbd{Mod(a,Q)=Mod(X,P)} gives the change of variables.
2464:
2465: The numbers $c$ and $c2$ are positive real numbers which control the
2466: execution time and the stack size. To get maximum speed, set $c2=c$. To get a
2467: rigorous result (under \idx{GRH}) you must take $c2=12$ (or $c2=6$ in the
2468: quadratic case, but then you should use the much faster function
2469: \kbd{quadclassunit}). Reasonable values for $c$ are between $0.1$ and
2470: $2$. (The defaults are $c=c2=0.3$).
2471:
2472: $\var{nrel\/}$ is the number of initial extra relations requested in
2473: computing the
2474: relation matrix. Reasonable values are between 5 and 20. (The default is 5).
2475:
2476: $\var{borne\/}$ is a multiplicative coefficient of the Minkowski bound which
2477: controls
2478: the search for small norm relations. If this parameter is set equal to 0, the
2479: program does not search for small norm relations. Otherwise reasonable values
2480: are between $0.5$ and $2.0$. (The default is $1.0$).
2481:
2482: $\var{nrpid\/}$ is the maximal number of small norm relations associated to each
2483: ideal in the factor base. Irrelevant when $\var{borne}=0$. Otherwise,
2484: reasonable values are between 4 and 20. (The default is 4).
2485:
2486: $\var{minsfb\/}$ is the minimal number of elements in the ``sub-factorbase''.
2487: If the
2488: program does not seem to succeed in finding a full rank matrix (which you can
2489: see in GP by typing \kbd{\bs g 2}), increase this number. Reasonable values
2490: are between 2 and 5. (The default is 3).
2491:
2492: \misctitle{Remarks.}
2493:
2494: Apart from the polynomial $P$, you don't need to supply any of the technical
2495: parameters (under the library you still need to send at least an empty
2496: vector, \kbd{cgetg(1,t\_VEC)}). However, should you choose to set some of
2497: them, they {\it must\/} be given in the requested order. For example, if you
2498: want to specify a given value of $nrel$, you must give some values as well
2499: for $c$ and $c2$, and provide a vector $[c,c2,nrel]$.
2500:
2501: Note also that you can use an $\var{nf}$ instead of $P$, which avoids
2502: recomputing the integral basis and analogous quantities.
2503:
2504: \smallskip
2505: \subsecidx{bnfcertify}$(\var{bnf\/})$: $\var{bnf}$ being a big number field
2506: as output by \kbd{bnfinit} or \kbd{bnfclassunit}, checks whether the result
2507: is correct, i.e.~whether it is possible to remove the assumption of the
2508: Generalized Riemann Hypothesis\sidx{GRH}. If it is correct, the answer is 1.
2509: If not, the program may output some error message, but more probably will loop
2510: indefinitely. In {\it no\/} occasion can the program give a wrong answer
2511: (barring bugs of course): if the program answers 1, the answer is certified.
2512:
2513: \syn{certifybuchall}{\var{bnf\/}}, and the result is a C long.
2514:
2515: \subsecidx{bnfclassunit}$(P,\{\fl=0\},\{\var{tech}=[\,]\})$: \idx{Buchmann}'s
2516: sub-exponential algorithm for computing the class group, the regulator and a
2517: system of \idx{fundamental units} of the general algebraic number field $K$
2518: defined by the irreducible polynomial $P$ with integer coefficients.
2519:
2520: The result of this function is a vector $v$ with 10 components (it is {\it
2521: not\/} a $\var{bnf}$, you need \kbd{bnfinit} for that), which for ease of
2522: presentation is in fact output as a one column matrix. First we describe the
2523: default behaviour ($\fl=0$):
2524:
2525: $v[1]$ is equal to the polynomial $P$. Note that for optimum performance,
2526: $P$ should have gone through \kbd{polred} or $\kbd{nfinit}(x,2)$.
2527:
2528: $v[2]$ is the 2-component vector $[r1,r2]$, where $r1$ and $r2$ are as usual
2529: the number of real and half the number of complex embeddings of the number
2530: field $K$.
2531:
2532: $v[3]$ is the 2-component vector containing the field discriminant and the
2533: index.
2534:
2535: $v[4]$ is an integral basis in Hermite normal form.
2536:
2537: $v[5]$ (\kbd{$v$.clgp}) is a 3-component vector containing the class number
2538: (\kbd{$v$.clgp.no}), the structure of the class group as a product of cyclic
2539: groups of order $n_i$ (\kbd{$v$.clgp.cyc}), and the corresponding generators
2540: of the class group of respective orders $n_i$ (\kbd{$v$.clgp.gen}).
2541:
2542: $v[6]$ (\kbd{$v$.reg}) is the regulator computed to an accuracy which is the
2543: maximum of an internally determined accuracy and of the default.
2544:
2545: $v[7]$ is a measure of the correctness of the result. If it is close to 1,
2546: the results are correct (under \idx{GRH}). If it is close to a larger integer,
2547: this shows that the product of the class number by the regulator is off by a
2548: factor equal to this integer, and you must start again with a larger value
2549: for $c$ or a different random seed, i.e.~use the function \kbd{setrand}.
2550: (Since the computation involves a random process, starting again with exactly
2551: the same parameters may give the correct result.) In this case a warning
2552: message is printed.
2553:
2554: $v[8]$ (\kbd{$v$.tu}) a vector with 2 components, the first being the number
2555: $w$ of roots of unity in $K$ and the second a primitive $w$-th root of unity
2556: expressed as a polynomial.
2557:
2558: $v[9]$ (\kbd{$v$.fu}) is a system of fundamental units also expressed as
2559: polynomials.
2560:
2561: $v[10]$ gives a measure of the correctness of the computations of the
2562: fundamental units (not of the regulator), expressed as a number of bits. If
2563: this number is greater than $20$, say, everything is OK. If $v[10]\le0$,
2564: then we have lost all accuracy in computing the units (usually an error
2565: message will be printed and the units not given). In the intermediate cases,
2566: one must proceed with caution (for example by increasing the current
2567: precision).
2568:
2569: If $\fl=1$, and the precision happens to be insufficient for obtaining the
2570: fundamental units exactly, the internal precision is doubled and the
2571: computation redone, until the exact results are obtained. The user should be
2572: warned that this can take a very long time when the coefficients of the
2573: fundamental units on the integral basis are very large, for example in the
2574: case of large real quadratic fields. In that case, there are alternate
2575: methods for representing algebraic numbers which are not implemented in PARI.
2576:
2577: If $\fl=2$, the fundamental units and roots of unity are not computed.
2578: Hence the result has only 7 components, the first seven ones.
2579:
2580: $\var{tech\/}$ is a technical vector (empty by default) containing $c$, $c2$,
2581: \var{nrel}, \var{borne}, \var{nbpid}, \var{minsfb}, in this order (see
2582: the beginning of the section or the keyword \kbd{bnf}).
2583: You can supply any number of these {\it provided you give an actual value to
2584: each of them} (the ``empty arg'' trick won't work here). Careful use of these
2585: parameters may speed up your computations considerably.
2586:
2587: \syn{bnfclassunit0}{P,\fl,\var{tech},\var{prec}}.
2588:
2589: \subsecidx{bnfclgp}$(P,\{\var{tech}=[\,]\})$: as \kbd{bnfclassunit}, but only
2590: outputs $v[5]$, i.e.~the class group.
2591:
2592: \syn{bnfclassgrouponly}{P,\var{tech},\var{prec}}, where \var{tech}
2593: is as described under \kbd{bnfclassunit}.
2594:
2595: \subsecidx{bnfdecodemodule}$(\var{nf},m)$: if $m$ is a module as output in the
2596: first component of an extension given by \kbd{bnrdisclist}, outputs the
2597: true module.
2598:
2599: \syn{decodemodule}{\var{nf},m}.
2600:
2601: \subsecidx{bnf{}init}$(P,\{\fl=0\},\{\var{tech}=[\,]\})$: essentially identical
2602: to \kbd{bnfclassunit} except that the output contains a lot of technical data,
2603: and should not be printed out explicitly in general. The result of
2604: \kbd{bnfinit} is used in programs such as \kbd{bnfisprincipal},
2605: \kbd{bnfisunit} or \kbd{bnfnarrow}. The result is a 10-component vector
2606: $\var{bnf}$.
2607:
2608: \noindent $\bullet$ The first 6 and last 2 components are technical and in
2609: principle are not used by the casual user. However, for the sake of
2610: completeness, their description is as follows. We use the notations explained
2611: in the book by H. Cohen, {\it A Course in Computational Algebraic Number
2612: Theory\/}, Graduate Texts in Maths \key{138}, Springer-Verlag, 1993, Section
2613: 6.5, and subsection 6.5.5 in particular.
2614:
2615: $\var{bnf\/}[1]$ contains the matrix $W$, i.e.~the matrix in Hermite normal
2616: form giving relations for the class group on prime ideal generators
2617: $(\p_i)_{1\le i\le r}$.
2618:
2619: $\var{bnf\/}[2]$ contains the matrix $B$, i.e.~the matrix containing the
2620: expressions of the prime ideal factorbase in terms of the $\p_i$. It is an
2621: $r\times c$ matrix.
2622:
2623: $\var{bnf\/}[3]$ contains the complex logarithmic embeddings of the system of
2624: fundamental units which has been found. It is an $(r_1+r_2)\times(r_1+r_2-1)$
2625: matrix.
2626:
2627: $\var{bnf\/}[4]$ contains the matrix $M''_C$ of Archimedean components of the
2628: relations of the matrix $M''$, except that the first $r_1+r_2-1$ columns are
2629: suppressed since they are already in $\var{bnf\/}[3]$.
2630:
2631: $\var{bnf\/}[5]$ contains the prime factor base, i.e.~the list of $k$ prime
2632: ideals used in finding the relations.
2633:
2634: $\var{bnf\/}[6]$ contains the permutation of the prime factor base which was
2635: necessary
2636: to reduce the relation matrix to the form explained in subsection 6.5.5
2637: of GTM~138 (i.e.~with a
2638: big $c\times c$ identity matrix on the lower right). Note that in the above
2639: mentioned book, the need to permute the rows of the relation matrices which
2640: occur was not emphasized.
2641:
2642: $\var{bnf\/}[9]$ is a 3-element row vector obtained as follows. Let
2643: $b=u_1^{-1}\var{bnf\/}[1]u_2$ obtained by applying the \idx{Smith normal form}
2644: algorithm to the matrix $W$ (= $\var{bnf}[1]$). Then
2645: $\var{bnf\/}[9]=[u_1,u_2,b]$. Note that the final class group generators
2646: given by \kbd{bnfinit} or \kbd{bnfclassunit} are obtained by
2647: \idx{LLL}-reducing the generators whose list is $b$.
2648:
2649: Finally, $\var{bnf\/}[10]$ is unused and set equal to 0, but it is essential
2650: that this component be present, because PARI distinguishes a number field
2651: \var{nf} from a big number field \var{bnf} by the number of its
2652: components. \smallskip
2653:
2654: \noindent$\bullet$ The less technical components are as follows:
2655:
2656: $\var{bnf\/}[7]$ or \kbd{\var{bnf}.nf} is equal to the number field data
2657: $\var{nf}$ as would be given by \kbd{nfinit}.
2658:
2659: $\var{bnf\/}[8]$ is a vector containing the last 6 components of
2660: \kbd{bnfclassunit[,1]}, i.e.~the classgroup \kbd{\var{bnf}.clgp}, the
2661: regulator \kbd{\var{bnf}.reg}, the general ``check'' number which should be
2662: close to 1, the number of roots of unity and a generator \kbd{\var{bnf}.tu},
2663: the fundamental units \kbd{\var{bnf}.fu}, and finally the check on their
2664: computation. If the precision becomes insufficient, GP outputs a warning
2665: (\kbd{fundamental units too large, not given}) and does not strive to
2666: compute the units by default ($\fl=0$).
2667:
2668: When $\fl=1$, GP insists on finding the fundamental units exactly, the
2669: internal precision being doubled and the computation redone, until the exact
2670: results are obtained. The user should be warned that this can take a very
2671: long time when the coefficients of the fundamental units on the integral
2672: basis are very large.
2673:
2674: When $\fl=2$, on the contrary, it is initially agreed that GP
2675: will not compute units.
2676:
2677: When $\fl=3$, computes a very small version of \kbd{bnfinit}, a ``small big
2678: number field'' (or \var{sbnf} for short) which contains enough information
2679: to recover the full $\var{bnf}$ vector very rapidly, but which is much
2680: smaller and hence easy to store and print. It is supposed to be used in
2681: conjunction with \kbd{bnfmake}. The output is a 12 component vector $v$, as
2682: follows. Let $\var{bnf}$ be the result of a full \kbd{bnfinit}, complete with
2683: units. Then $v[1]$ is the polynomial $P$, $v[2]$ is the number of real
2684: embeddings $r_1$, $v[3]$ is the field discriminant, $v[4]$ is the integral
2685: basis, $v[5]$ is the list of roots as in the sixth component of \kbd{nfinit},
2686: $v[6]$ is the matrix $MD$ of \kbd{nfinit} giving a $\Z$-basis of the
2687: different, $v[7]$ is the matrix $\kbd{W} = \var{bnf\/}[1]$, $v[8]$ is the
2688: matrix $\kbd{matalpha}=\var{bnf\/}[2]$, $v[9]$ is the prime ideal factor base
2689: $\var{bnf\/}[5]$ coded in a compact way, and ordered according to the
2690: permutation $\var{bnf\/}[6]$, $v[10]$ is the 2-component vector giving the
2691: number of roots of unity and a generator, expressed on the integral basis,
2692: $v[11]$ is the list of fundamental units, expressed on the integral basis,
2693: $v[12]$ is a vector containing the algebraic numbers alpha corresponding to
2694: the columns of the matrix \kbd{matalpha}, expressed on the integral basis.
2695:
2696: Note that all the components are exact (integral or rational), except for
2697: the roots in $v[5]$. In practice, this is the only component which a user
2698: is allowed to modify, by recomputing the roots to a higher accuracy if
2699: desired. Note also that the member functions will {\it not\/} work on
2700: \var{sbnf}, you have to use \kbd{bnfmake} explicitly first.
2701:
2702: \syn{bnf{}init0}{P,\fl,\var{tech},\var{prec}}.
2703:
2704: \subsecidx{bnf{}isintnorm}$(\var{bnf},x)$: computes a complete system of
2705: solutions (modulo units of positive norm) of the absolute norm equation
2706: $\text{Norm}(a)=x$,
2707: where $a$ is an integer in $\var{bnf}$. If $\var{bnf}$ has not been certified,
2708: the correctness of the result depends on the validity of \idx{GRH}.
2709:
2710: \syn{bnf{}isintnorm}{\var{bnf},x}.
2711:
2712: \subsecidx{bnf{}isnorm}$(\var{bnf},x,\{\fl=1\})$: tries to tell whether the
2713: rational number $x$ is the norm of some element y in $\var{bnf}$. Returns a
2714: vector $[a,b]$ where $x=Norm(a)*b$. Looks for a solution which is an $S$-unit,
2715: with $S$ a certain set of prime ideals containing (among others) all primes
2716: dividing $x$. If $\var{bnf}$ is known to be \idx{Galois}, set $\fl=0$ (in
2717: this case,
2718: $x$ is a norm iff $b=1$). If $\fl$ is non zero the program adds to $S$ the
2719: following prime ideals, depending on the sign of $\fl$. If $\fl>0$, the
2720: ideals of norm less than $\fl$. And if $\fl<0$ the ideals dividing $\fl$.
2721:
2722: If you are willing to assume \idx{GRH}, the answer is guaranteed
2723: (i.e.~$x$ is a norm iff $b=1$), if $S$ contains all primes less than
2724: $12\log(\var{disc}(\var{Bnf}))^2$,
2725: where $\var{Bnf}$ is the Galois closure of $\var{bnf}$.
2726:
2727: \syn{bnf{}isnorm}{\var{bnf},x,\fl,\var{prec}}, where $\fl$ and
2728: $\var{prec}$ are \kbd{long}s.
2729:
2730: \subsecidx{bnf{}issunit}$(\var{bnf},\var{sfu},x)$: $\var{bnf}$ being output by
2731: \kbd{bnfinit}, \var{sfu} by \kbd{bnfsunit}, gives the column vector of
2732: exponents of $x$ on the fundamental $S$-units and the roots of unity.
2733: If $x$ is not a unit, outputs an empty vector.
2734:
2735: \syn{bnf{}issunit}{\var{bnf},\var{sfu},x}.
2736:
2737: \subsecidx{bnf{}isprincipal}$(\var{bnf},x,\{\fl=1\})$: $\var{bnf}$ being the
2738: number field data output by \kbd{bnfinit}, and $x$ being either a $\Z$-basis
2739: of an ideal in the number field (not necessarily in HNF) or a prime ideal in
2740: the format output by the function \kbd{idealprimedec}, this function tests
2741: whether the ideal is principal or not. The result is more complete than a
2742: simple true/false answer: it gives a row vector $[v_1,v_2,check]$, where
2743:
2744: $v_1$ is the vector of components $c_i$ of the class of the ideal $x$ in the
2745: class group, expressed on the generators $g_i$ given by \kbd{bnfinit}
2746: (specifically \kbd{\var{bnf}.clgp.gen} which is the same as
2747: \kbd{\var{bnf\/}[8][1][3]}). The $c_i$ are chosen so that $0\le c_i<n_i$
2748: where $n_i$ is the order of $g_i$ (the vector of $n_i$ being
2749: \kbd{\var{bnf}.clgp.cyc}, that is \kbd{\var{bnf\/}[8][1][2]}).
2750:
2751: $v_2$ gives on the integral basis the components of $\alpha$ such that
2752: $x=\alpha\prod_ig_i^{c_i}$. In particular, $x$ is principal if and only if
2753: $v_1$ is equal to the zero vector, and if this the case $x=\alpha\Z_K$ where
2754: $\alpha$ is given by $v_2$. Note that if $\alpha$ is too large to be given, a
2755: warning message will be printed and $v_2$ will be set equal to the empty
2756: vector.
2757:
2758: Finally the third component \var{check} is analogous to the last component of
2759: \kbd{bnfclassunit}: it gives a check on the accuracy of the result, in bits.
2760: \var{check} should be at least $10$, and preferably much more. In any case, the
2761: result is checked for correctness.
2762:
2763: If $\fl=0$, outputs only $v_1$, which is much easier to compute.
2764:
2765: If $\fl=2$, does as if $\fl$ were $0$, but doubles the precision until a result is
2766: obtained.
2767:
2768: If $\fl=3$, as in the default behaviour ($\fl=1$), but doubles the precision
2769: until a result is obtained.
2770:
2771: The user is warned that these two last setting may induce {\it very\/} lengthy
2772: computations.
2773:
2774: \syn{isprincipalall}{\var{bnf},x,\fl}.
2775:
2776: \subsecidx{bnf{}isunit}$(\var{bnf},x)$: $\var{bnf}$ being the number field data
2777: output by
2778: \kbd{bnfinit} and $x$ being an algebraic number (type integer, rational or
2779: polmod), this outputs the decomposition of $x$ on the fundamental units and
2780: the roots of unity if $x$ is a unit, the empty vector otherwise. More
2781: precisely, if $u_1$,\dots,$u_r$ are the fundamental units, and $\zeta$ is
2782: the generator of the group of roots of unity (found by \kbd{bnfclassunit} or
2783: \kbd{bnfinit}), the output is a vector $[x_1,\dots,x_r,x_{r+1}]$ such that
2784: $x=u_1^{x_1}\cdots u_r^{x_r}\cdot\zeta^{x_{r+1}}$. The $x_i$ are integers for
2785: $i\le r$ and is an integer modulo the order of $\zeta$ for $i=r+1$.
2786:
2787: \syn{isunit}{\var{bnf},x}.
2788:
2789: \subsecidx{bnfmake}$(\var{sbnf})$: \var{sbnf} being a ``small $\var{bnf}$''
2790: as output
2791: by \kbd{bnfinit}$(x,3)$, computes the complete \kbd{bnfinit} information. The
2792: result is {\it not\/} identical to what \kbd{bnfinit} would yield, but is
2793: functionally identical. The execution time is very small compared to a
2794: complete \kbd{bnfinit}. Note that if the default precision in GP (or
2795: $\var{prec}$ in library mode) is greater than the precision of the roots
2796: $\var{sbnf}[5]$, these are recomputed so as to get a result with greater
2797: accuracy.
2798:
2799: Note that the member functions are {\it not\/} available for \var{sbnf}, you
2800: have to use \kbd{bnfmake} explicitly first.
2801:
2802: \syn{makebigbnf}{\var{sbnf},\var{prec}}, where $\var{prec}$ is a
2803: C long integer.
2804:
2805: \subsecidx{bnfnarrow}$(\var{bnf\/})$: $\var{bnf}$ being a big number field as
2806: output by \kbd{bnfinit}, computes the narrow class group of $\var{bnf}$. The
2807: output is a 3-component row vector $v$ analogous to the corresponding
2808: class group component \kbd{\var{bnf}.clgp} (\kbd{\var{bnf\/}[8][1]}): the
2809: first component is the narrow class number \kbd{$v$.no}, the second component
2810: is a vector containing the SNF\sidx{Smith normal form} cyclic components
2811: \kbd{$v$.cyc} of the narrow
2812: class group, and the third is a vector giving the generators of the
2813: corresponding \kbd{$v$.gen} cyclic groups. Note that this function is a
2814: special case of \kbd{bnrclass}.
2815:
2816: \syn{buchnarrow}{\var{bnf\/}}.
2817:
2818: \subsecidx{bnfsignunit}$(\var{bnf\/})$: $\var{bnf}$ being a big number field
2819: output by \kbd{bnfinit}, this computes an $r_1\times(r_1+r_2-1)$ matrix
2820: having $\pm1$ components, giving the signs of the real embeddings of the
2821: fundamental units.
2822:
2823: \syn{signunits}{\var{bnf\/}}.
2824:
2825: \subsecidx{bnfreg}$(\var{bnf\/})$: $\var{bnf}$ being a big number field
2826: output by \kbd{bnfinit}, computes its regulator.
2827:
2828: \syn{regulator}{\var{bnf},\var{tech},\var{prec}}, where \var{tech} is as in
2829: \kbd{bnfclassunit}.
2830:
2831: \subsecidx{bnfsunit}$(\var{bnf},S)$: computes the fundamental $S$-units of the
2832: number field $\var{bnf}$ (output by \kbd{bnfinit}), where $S$ is a list of
2833: prime ideals (output by \kbd{idealprimedec}). The output is a vector $v$ with
2834: 6 components.
2835:
2836: $v[1]$ gives a minimal system of (integral) generators of the $S$-unit group
2837: modulo the unit group.
2838:
2839: $v[2]$ contains technical data needed by \kbd{bnfissunit}.
2840:
2841: $v[3]$ is an empty vector (used to give the logarithmic embeddings of the
2842: generators in $v[1]$ in version 2.0.16).
2843:
2844: $v[4]$ is the $S$-regulator (this is the product of the regulator, the
2845: determinant of $v[2]$ and the natural logarithms of the norms of the ideals
2846: in $S$).
2847:
2848: $v[5]$ gives the $S$-class group structure, in the usual format
2849: (a row vector whose three components give in order the $S$-class number,
2850: the cyclic components and the generators).
2851:
2852: $v[6]$ is a copy of $S$.
2853:
2854: \syn{bnfsunit}{\var{bnf},S,\var{prec}}.
2855:
2856: \subsecidx{bnfunit}$(\var{bnf\/})$: $\var{bnf}$ being a big number field as
2857: output by
2858: \kbd{bnfinit}, outputs a two-component row vector giving in the first
2859: component the vector of fundamental units of the number field, and in the
2860: second component the number of bit of accuracy which remained in the
2861: computation (which is always correct, otherwise an error message is printed).
2862: This function is mainly for people who used the wrong flag in \kbd{bnfinit}
2863: and would like to skip part of a lengthy \kbd{bnfinit} computation.
2864:
2865: \syn{buchfu}{\var{bnf\/}}.
2866:
2867: \subsecidx{bnrL1}$(\var{bnr},\{\fl=0\})$:
2868: \var{bnr} being the number field data which is output by
2869: \kbd{bnrinit(,,1)}, returns for each \idx{character} $\chi$ of the
2870: corresponding ray class group, the value at $s = 1$ (or $s = 0$) of
2871: the abelian $L$-functions associated to $\chi$. For the value at $s =
2872: 0$, the function returns in fact for each character $\chi$ a vector
2873: $[r_\chi , c_\chi]$ where $r_\chi$ is the order of $L(s, \chi)$ at $s
2874: = 0$ and $c_\chi$ the first non-zero term in the expansion of $L(s,
2875: \chi)$ at $s = 0$; in other words
2876: %
2877: $$L(s, \chi) = c_\chi \cdot s^{r_\chi} + O(s^{r_\chi + 1})$$
2878: %
2879: \noindent near $0$. \fl\ is optional, default value is 0; its binary digits
2880: mean 1: compute at $s = 1$ if set to 1 or $s = 0$ if set to 0, 2: compute
2881: the primitive $L$-functions associated to $\chi$ if set to 0 or the
2882: $L$-function with Euler factors at prime ideals dividing the modulus of
2883: \var{bnr} removed if set to 1 (this is the so-called $L_S(s, \chi)$
2884: function where $S$ is the set of infinite places of the number field
2885: together with the finite prime ideals dividing the modulus of \var{bnr},
2886: see the example below), 3: returns also the character.
2887:
2888: Example:
2889:
2890: \bprog%
2891: bnf = bnfinit(x\pow 2-229);
2892: bnr = bnrinit(bnf,1,1);
2893: bnrL1(bnr)%
2894: \eprog\noindent
2895: returns the order and the first non-zero term of the abelian
2896: $L$-functions $L(s, \chi)$ at $s = 0$ where $\chi$ runs through the
2897: characters of the class group of $\Q(\sqrt{229})$. Then
2898: \bprog%
2899: bnr2 = bnrinit(bnf,2,1);
2900: bnrL1(bnr2,2)%
2901: \eprog\noindent
2902: returns the order and the first non-zero terms of the abelian
2903: $L$-functions $L_S(s, \chi)$ at $s = 0$ where $\chi$ runs through the
2904: characters of the class group of $\Q(\sqrt{229})$ and $S$ is the set
2905: of infinite places of $\Q(\sqrt{229})$ together with the finite prime
2906: $2$ (note that the ray class group modulo $2$ is in fact the class
2907: group, so \kbd{bnrL1(bnr2)} returns exactly the same answer as
2908: \kbd{bnrL1(bnr)}!).
2909:
2910: \syn{bnrL1}{\var{bnr},\fl,\var{prec}}
2911:
2912: \subsecidx{bnrclass}$(\var{bnf},\var{ideal},\{\fl=0\})$:
2913: $\var{bnf}$ being a big number field
2914: as output by \kbd{bnfinit} (the units are mandatory unless the ideal is
2915: trivial), and \var{ideal} being either an ideal in any form or a two-component
2916: row vector containing an ideal and an $r_1$-component row vector of flags
2917: indicating which real Archimedean embeddings to take in the module, computes
2918: the ray class group of the number field for the module \var{ideal}, as a
2919: 3-component vector as all other finite Abelian groups (cardinality, vector of
2920: cyclic components, corresponding generators).
2921:
2922: If $\fl=2$, the output is different. It is a 6-component vector $w$. $w[1]$
2923: is $\var{bnf}$. $w[2]$ is the result of applying
2924: $\kbd{idealstar}(\var{bnf},I,2)$. $w[3]$, $w[4]$ and $w[6]$ are technical
2925: components used only by the function \kbd{bnrisprincipal}. $w[5]$ is the
2926: structure of the ray class group as would have been output with $\fl=0$.
2927:
2928: If $\fl=1$, as above, except that the generators of the ray class group are
2929: not computed, which saves time.
2930:
2931: \syn{bnrclass0}{\var{bnf},\var{ideal},\fl,\var{prec}}.
2932:
2933: \subsecidx{bnrclassno}$(\var{bnf},I)$: $\var{bnf}$ being a big number field
2934: as output
2935: by \kbd{bnfinit} (units are mandatory unless the ideal is trivial), and $I$
2936: being either an ideal in any form or a two-component row vector containing an
2937: ideal and an $r_1$-component row vector of flags indicating which real
2938: Archimedean embeddings to take in the modulus, computes the ray class number
2939: of the number field for the modulus $I$. This is faster than \kbd{bnrclass}
2940: and should be used if only the ray class number is desired.
2941:
2942: \syn{rayclassno}{\var{bnf},I}.
2943:
2944: \subsecidx{bnrclassnolist}$(\var{bnf},\var{list})$: $\var{bnf}$ being a
2945: big number field as output by \kbd{bnfinit} (units are mandatory unless
2946: the ideal is trivial), and \var{list} being a list of modules as output
2947: by \kbd{ideallist} of \kbd{ideallistarch},
2948: outputs the list of the class numbers of the corresponding ray class groups.
2949:
2950: \syn{rayclassnolist}{\var{bnf},\var{list}}.
2951:
2952: \subsecidx{bnrconductor}$(a_1,\{a_2\},\{a_3\}, \{\fl=0\})$: conductor of the
2953: subfield of a ray class field as defined by $[a_1,a_2,a_3]$ (see \kbd{bnr}
2954: at the beginning of this section).
2955:
2956: \syn{bnrconductor}{a_1,a_2,a_3,\fl,\var{prec}}, where an omitted argument
2957: among the $a_i$ is input as \kbd{gzero}, and $\fl$ is a C long.
2958:
2959: \subsecidx{bnrconductorofchar}$(\var{bnr},\var{chi})$: \var{bnr} being a
2960: big ray number field
2961: as output by \kbd{bnrclass}, and \var{chi} being a row vector representing a
2962: \idx{character} as expressed on the generators of the ray class group, gives
2963: the conductor of this character as a modulus.
2964:
2965: \syn{bnrconductorofchar}{\var{bnr},\var{chi},\var{prec}} where $\var{prec}$
2966: is a \kbd{long}.
2967:
2968: \subsecidx{bnrdisc}$(a1,\{a2\},\{a3\},\{\fl=0\})$: $a1$, $a2$, $a3$
2969: defining a big ray number field $L$ over a groud field $K$ (see \kbd{bnr}
2970: at the beginning of this section for the
2971: meaning of $a1$, $a2$, $a3$), outputs a 3-component row vector $[N,R_1,D]$,
2972: where $N$ is the (absolute) degree of $L$, $R_1$ the number of real places of
2973: $L$, and $D$ the discriminant of $L/\Q$, including sign (if $\fl=0$).
2974:
2975: If $\fl=1$, as above but outputs relative data. $N$ is now the degree of
2976: $L/K$, $R_1$ is the number of real places of $K$ unramified in $L$ (so that
2977: the number of real places of $L$ is equal to $R_1$ times the relative degree
2978: $N$), and $D$ is the relative discriminant ideal of $L/K$.
2979:
2980: If $\fl=2$, does as in case 0, except that if the modulus is not the exact
2981: conductor corresponding to the $L$, no data is computed and the result is $0$
2982: (\kbd{gzero}).
2983:
2984: If $\fl=3$, as case 2, outputting relative data.
2985:
2986: \syn{bnrdisc0}{a1,a2,a3,\fl,\var{prec}}.
2987:
2988: \subsecidx{bnrdisclist}$(\var{bnf},\var{bound},\{\var{arch}\},\{\fl=0\})$:
2989: $\var{bnf}$ being a big
2990: number field as output by \kbd{bnfinit} (the units are mandatory), computes a
2991: list of discriminants of Abelian extensions of the number field by increasing
2992: modulus norm up to bound {\it bound}, where the ramified Archimedean places are
2993: given by \var{arch} (unramified at infinity if \var{arch} is void or
2994: omitted). If
2995: \fl\ is non-zero, give \var{arch} all the possible values. (See \kbd{bnr}
2996: at the beginning of this section for the meaning of $a1$, $a2$, $a3$.)
2997:
2998: The alternative syntax $\kbd{bnrdisclist}(\var{bnf},\var{list})$
2999: is supported, where \var{list} is as output by \kbd{ideallist} or
3000: \kbd{ideallistarch} (with units).
3001:
3002: The output format is as follows. The output $v$ is a row vector of row
3003: vectors, allowing the bound to be greater than $2^{16}$ for 32-bit machines,
3004: and $v[i][j]$ is understood to be in fact $V[2^{15}(i-1)+j]$ of a unique big
3005: vector $V$ (note that $2^{15}$ is hardwired and can be increased in the
3006: source code only on 64-bit machines and higher).
3007:
3008: Such a component $V[k]$ is itself a vector $W$ (maybe of length 0) whose
3009: components correspond to each possible ideal of norm $k$. Each component
3010: $W[i]$ corresponds to an Abelian extension $L$ of $\var{bnf}$ whose modulus is
3011: an ideal of norm $k$ and no Archimedean components (hence the extension is
3012: unramified at infinity). The extension $W[i]$ is represented by a 4-component
3013: row vector $[m,d,r,D]$ with the following meaning. $m$ is the prime ideal
3014: factorization of the modulus, $d=[L:\Q]$ is the absolute degree of $L$,
3015: $r$ is the number of real places of $L$, and $D$ is the factorization of the
3016: absolute discriminant. Each prime ideal $pr=[p,\alpha,e,f,\beta]$ in the
3017: prime factorization $m$ is coded as $p\cdot n^2+(f-1)\cdot n+(j-1)$, where
3018: $n$ is the degree of the base field and $j$ is such that
3019:
3020: \kbd{pr=idealprimedec(\var{nf},p)[j]}.
3021:
3022: $m$ can be decoded using \kbd{bnfdecodemodule}.
3023:
3024: \syn{bnrdisclist0}{a1,a2,a3,\var{bound},\var{arch},\fl}.
3025:
3026: \subsecidx{bnrinit}$(\var{bnf},\var{ideal},\{\fl=0\})$: $\var{bnf}$ is as
3027: output by \kbd{bnfinit}, \var{ideal} is a valid ideal (or a module),
3028: initializes data linked
3029: to the ray class group structure corresponding to this module. This is the
3030: same as $\kbd{bnrclass}(\var{bnf},\var{ideal},\fl+1)$.
3031:
3032: \syn{bnrinit0}{\var{bnf},\var{ideal},\fl,\var{prec}}.
3033:
3034: \subsecidx{bnrisconductor}$(a1,\{a2\},\{a3\})$: $a1$, $a2$, $a3$ represent
3035: an extension of the base field, given by class field theory for some modulus
3036: encoded in the parameters. Outputs 1 if this modulus is the conductor, and 0
3037: otherwise. This is slightly faster than \kbd{bnrconductor}.
3038:
3039: \syn{bnrisconductor}{a1,a2,a3} and the result is a \kbd{long}.
3040:
3041: \subsecidx{bnrisprincipal}$(\var{bnr},x,\{\fl=1\})$: \var{bnr} being the
3042: number field
3043: data which is output by \kbd{bnrinit} and $x$ being an ideal in any form,
3044: outputs the components of $x$ on the ray class group generators in a way
3045: similar to \kbd{bnfisprincipal}. That is a 3-component vector $v$ where
3046: $v[1]$ is the vector of components of $x$ on the ray class group generators,
3047: $v[2]$ gives on the integral basis an element $\alpha$ such that
3048: $x=\alpha\prod_ig_i^{x_i}$. Finally $v[3]$ indicates the number of bits of
3049: accuracy left in the result. In any case the result is checked for
3050: correctness, but $v[3]$ is included to see if it is necessary to increase the
3051: accuracy in other computations.
3052:
3053: If $\fl=0$, outputs only $v_1$.
3054:
3055: {\it The settings $\fl=2$ or $3$ are not available in this case}.
3056:
3057: \syn{isprincipalrayall}{\var{bnr},x,\fl}.
3058:
3059: \subsecidx{bnrrootnumber}$(\var{bnr},\var{chi},\{\fl=0\})$:
3060: if $\chi=\var{chi}$ is a (not necessarily primitive)
3061: \idx{character} over \var{bnr}, let
3062: $L(s,\chi) = \sum_{id} \chi(id) N(id)^{-s}$ be the associated
3063: \idx{Artin L-function}. Returns the so-called \idx{Artin root number}, i.e.~the
3064: complex number $W(\chi)$ of modulus 1 such that
3065: %
3066: $$\Lambda(1-s,\chi) = W(\chi) \Lambda(s,\overline{\chi})$$
3067: %
3068: \noindent where $\Lambda(s,\chi) = A(\chi)^{s/2}\gamma_\chi(s) L(s,\chi)$ is
3069: the enlarged L-function associated to $L$.
3070:
3071: The generators of the ray class group are needed, and you can set $\fl=1$ if
3072: the character is known to be primitive. Example:
3073:
3074: \bprog%
3075: bnf = bnfinit(x\pow 2-145);
3076: bnr = bnrinit(bnf,7,1);
3077: bnrrootnumber(bnr, [5])%
3078: \eprog\noindent
3079: returns the root number of the character $\chi$ of $Cl_7(\Q(\sqrt{145}))$
3080: such that $\chi(g) = \zeta^5$, where $g$ is the generator of the ray-class
3081: field and $\zeta = e^{2i\pi/N}$ where $N$ is the order of $g$ ($N=12$ as
3082: \kbd{bnr.cyc} readily tells us).
3083:
3084: \syn{bnrrootnumber}{\var{bnf},\var{chi},\fl}
3085:
3086: \subsecidx{bnrstark}${(\var{bnr},\var{subgroup},\{\fl=0\})}$: \var{bnr}
3087: being as output by \kbd{bnrinit(,,1)}, finds a relative equation for the
3088: class field corresponding to the modulus in \var{bnr} and the given
3089: congruence subgroup using \idx{Stark units} (set $\var{subgroup}=0$ if you
3090: want the whole ray class group). The main variable of \var{bnr} must not be
3091: $x$, and the ground field and the class field must be totally real and not
3092: isomorphic to $\Q$. \fl\ is optional and may be set to 0 to obtain a
3093: reduced relative polynomial, 1 to be satisfied with any relative
3094: polynomial, 2 to obtain an absolute polynomial and 3 to obtain the
3095: irreducible relative polynomial of the Stark unit, 0 being default.
3096: Example:
3097:
3098: \bprog%
3099: bnf = bnfinit(y\pow 2-3);
3100: bnr = bnrinit(bnf,5,1);
3101: bnrstark(bnr,0)%
3102: \eprog\noindent
3103: returns the ray class field of $\Q(\sqrt{3})$ modulo $5$.
3104:
3105: \misctitle{Remark.} The function may fail, returning the error message
3106:
3107: \kbd{"Cannot find a suitable modulus in FindModule"}.
3108:
3109: In this case, the corresponding congruence group is a product of cyclic
3110: groups and, for the time being, the class field has to be obtained by
3111: splitting this group into its cyclic components.
3112:
3113: \syn{bnrstark}{\var{bnr},\var{subgroup},\fl}.
3114:
3115: \subsecidx{dirzetak}$(\var{nf},b)$: gives as a vector the first $b$
3116: coefficients of the \idx{Dedekind} zeta function of the number field $\var{nf}$
3117: considered as a \idx{Dirichlet series}.
3118:
3119: \syn{dirzetak}{\var{nf},b}.
3120:
3121: \subsecidx{factornf}$(x,t)$: factorization of the univariate polynomial $x$
3122: over the number field defined by the (univariate) polynomial $t$. $x$ may
3123: have coefficients in $\Q$ or in the number field. The main variable of
3124: $t$ must be of {\it lower\/} priority than that of $x$ (in other words the
3125: variable number of $t$ must be {\it greater\/} than that of $x$). However if
3126: the coefficients of the number field occur explicitly (as polmods) as
3127: coefficients of $x$, the variable of these polmods {\it must\/} be the same as
3128: the main variable of $t$. For example
3129: \kbd{factornf(x\pow 2 + Mod(y,y\pow 2+1), y\pow 2+1)} and
3130: \kbd{factornf(x\pow 2+1, y\pow 2+1)} are legal but
3131: \kbd{factornf(x\pow 2 + Mod(z,z\pow 2+1), y\pow 2+1)} is not.
3132:
3133: \syn{polfnf}{x,t}.
3134:
3135: \subsecidx{ffinit}$(p,n,\{v=x\})$: computes a monic polynomial of degree
3136: $n$ which is irreducible over $\F_p$. For instance if
3137: \kbd{P = ffinit(3,2,y)}, you can represent elements in $\F_{3^2}$ as polmods
3138: modulo \kbd{P}. This function is rather crude and expects $p$ to be
3139: relatively small ($p < 2^31$).
3140:
3141: \syn{ffinit}{p,n,v}, where $v$ is a variable number.
3142:
3143: \subsecidx{idealadd}$(\var{nf},x,y)$: sum of the two ideals $x$ and $y$ in the
3144: number field $\var{nf}$. When $x$ and $y$ are given by $\Z$-bases, this does
3145: not depend on $\var{nf}$ and can be used to compute the sum of any two
3146: $\Z$-modules. The result is given in HNF.
3147:
3148: \syn{idealadd}{\var{nf},x,y}.
3149:
3150: \subsecidx{idealaddtoone}$(\var{nf},x,\{y\})$: $x$ and $y$ being two co-prime
3151: integral ideals (given in any form), this gives a two-component row vector
3152: $[a,b]$ such that $a\in x$, $b\in y$ and $a+b=1$.
3153:
3154: The alternative syntax $\kbd{idealaddtoone}(\var{nf},v)$, is supported, where
3155: $v$ is a $k$-component vector of ideals (given in any form) which sum to
3156: $\Z_K$. This outputs a $k$-component vector $e$ such that $e[i]\in x[i]$ for
3157: $1\le i\le k$ and $\sum_{1\le i\le k}e[i]=1$.
3158:
3159: \syn{idealaddtoone0}{\var{nf},x,y}, where an omitted $y$ is coded as
3160: \kbd{NULL}.
3161:
3162: \subsecidx{idealappr}$(\var{nf},x,\{\fl=0\})$: if $x$ is a fractional ideal
3163: (given in any form), gives an element $\alpha$ in $\var{nf}$ such that for
3164: all prime ideals $\p$ such that the valuation of $x$ at $\p$ is non-zero, we
3165: have $v_{\p}(\alpha)=v_{\p}(x)$, and. $v_{\p}(\alpha)\ge0$ for all other
3166: ${\p}$.
3167:
3168: If $\fl$ is non-zero, $x$ must be given as a prime ideal factorization, as
3169: output by \kbd{idealfactor}, but possibly with zero or negative exponents.
3170: This yields an element $\alpha$ such that for all prime ideals $\p$ occurring
3171: in $x$, $v_{\p}(\alpha)$ is equal to the exponent of $\p$ in $x$, and for all
3172: other prime ideals, $v_{\p}(\alpha)\ge0$. This generalizes
3173: $\kbd{idealappr}(\var{nf},x,0)$ since zero exponents are allowed. Note that
3174: the algorithm used is slightly different, so that
3175: \kbd{idealapp(\var{nf},idealfactor(\var{nf},x))} may not be the same as
3176: \kbd{idealappr(\var{nf},x,1)}.
3177:
3178: \syn{idealappr0}{\var{nf},x,\fl}.
3179:
3180: \subsecidx{idealchinese}$(\var{nf},x,y)$: $x$ being a prime ideal factorization
3181: (i.e.~a 2 by 2 matrix whose first column contain prime ideals, and the second
3182: column integral exponents), $y$ a vector of elements in $\var{nf}$ indexed by
3183: the ideals in $x$, computes an element $b$ such that
3184:
3185: $v_\p(b - y_\p) \geq v_\p(x)$ for all prime ideals in $x$ and $v_\p(b)\geq 0$
3186: for all other $\p$.
3187:
3188: \syn{idealchinese}{\var{nf},x,y}.
3189:
3190: \subsecidx{idealcoprime}$(\var{nf},x,y)$: given two integral ideals $x$ and $y$
3191: in the number field $\var{nf}$, finds a $\beta$ in the field, expressed on the
3192: integral basis $\var{nf\/}[7]$, such that $\beta\cdot y$ is an integral ideal
3193: coprime to $x$.
3194:
3195: \syn{idealcoprime}{\var{nf},x}.
3196:
3197: \subsecidx{idealdiv}$(\var{nf},x,y,\{\fl=0\})$: quotient $x\cdot y^{-1}$ of the
3198: two ideals $x$ and $y$ in the number field $\var{nf}$. The result is given in
3199: HNF.
3200:
3201: If $\fl$ is non-zero, the quotient $x \cdot y^{-1}$ is assumed to be an
3202: integral ideal. This can be much faster when the norm of the quotient is
3203: small even though the norms of $x$ and $y$ are large.
3204:
3205: \syn{idealdiv0}{\var{nf},x,y,\fl}. Also available
3206: are $\teb{idealdiv}(\var{nf},x,y)$ ($\fl=0$) and
3207: $\teb{idealdivexact}(\var{nf},x,y)$ ($\fl=1$).
3208:
3209: \subsecidx{idealfactor}$(\var{nf},x)$: factors into prime ideal powers the
3210: ideal $x$ in the number field $\var{nf}$. The output format is similar to the
3211: \kbd{factor} function, and the prime ideals are represented in the form
3212: output by the \kbd{idealprimedec} function, i.e.~as 5-element vectors.
3213:
3214: \syn{idealfactor}{\var{nf},x}.
3215:
3216: \subsecidx{idealhnf}$(\var{nf},a,\{b\})$: gives the \idx{Hermite normal form}
3217: matrix of the ideal $a$. The ideal can be given in any form whatsoever
3218: (typically by an algebraic number if it is principal, by a $\Z_K$-system of
3219: generators, as a prime ideal as given by \kbd{idealprimedec}, or by a
3220: $\Z$-basis).
3221:
3222: If $b$ is not omitted, assume the ideal given was $a\Z_K+b\Z_K$, where $a$
3223: and $b$ are elements of $K$ given either as vectors on the integral basis
3224: $\var{nf\/}[7]$ or as algebraic numbers.
3225:
3226: \syn{idealhnf0}{\var{nf},a,b} where an omitted $b$ is coded as \kbd{NULL}.
3227: Also available is $\teb{idealhermite}(\var{nf},a)$ ($b$ omitted).
3228:
3229: \subsecidx{idealintersect}$(\var{nf},x,y)$: intersection of the two ideals
3230: $x$ and $y$ in the number field $\var{nf}$. When $x$ and $y$ are given by
3231: $\Z$-bases, this does not depend on $\var{nf}$ and can be used to compute the
3232: intersection of any two $\Z$-modules. The result is given in HNF.
3233:
3234: \syn{idealintersect}{\var{nf},x,y}.
3235:
3236: \subsecidx{idealinv}$(\var{nf},x,\{\fl=0\})$: inverse of the ideal $x$ in the
3237: number field $\var{nf}$. The result is the Hermite normal form of the inverse
3238: of the ideal, together with the opposite of the Archimedean information if it
3239: is given.
3240:
3241: If $\fl=1$, uses the different. This is usually slower.
3242:
3243: \syn{idealinv0}{\var{nf},x,\fl}. Also available is
3244: $\teb{idealinv}(\var{nf},x)$ ($\fl=0$).
3245:
3246: \subsecidx{ideallist}$(\var{nf},\var{bound},\{\fl=4\})$: computes the list
3247: of all ideals of norm less or equal to \var{bound} in the number field
3248: \var{nf}. The result is a row vector with exactly \var{bound} components.
3249: Each component is itself a row vector containing the information about
3250: ideals of a given norm, in no specific order. This information can be
3251: either the HNF of the ideal or the \kbd{idealstar} with possibly some
3252: additional information.
3253:
3254: If $\fl$ is present, its binary digits are toggles meaning
3255:
3256: \quad 1: give also the generators in the \kbd{idealstar}.
3257:
3258: \quad 2: output $[L,U]$, where $L$ is as before and $U$ is a vector of
3259: \kbd{zinternallog}s of the units.
3260:
3261: \quad 4: give only the ideals and not the \kbd{idealstar} or the \kbd{ideallog}
3262: of the units.
3263:
3264: \syn{ideallist0}{\var{nf},\var{bound},\fl}, where \var{bound} must
3265: be a C long integer. Also available is $\teb{ideallist}(\var{nf},\var{bound})$,
3266: corresponding to the case $\fl=0$.
3267:
3268: \subsecidx{ideallistarch}$(\var{nf},\var{list},\{\var{arch}=[\,]\},\{\fl=0\})$:
3269: vector of vectors of all \kbd{idealstarinit} (see \kbd{idealstar}) of all
3270: modules in \var{list}, with Archimedean part \var{arch} added (void if
3271: omitted). \var{list} is a vector of big ideals, as output by
3272: \kbd{ideallist}$(\ldots, \fl)$ for instance. $\fl$ is optional; its binary
3273: digits are toggles meaning: 1: give generators as well, 2: list format is
3274: $[L,U]$ (see \kbd{ideallist}).
3275:
3276: \syn{ideallistarch0}{\var{nf},\var{list},\var{arch},\fl}, where an omitted
3277: \var{arch} is coded as \kbd{NULL}.
3278:
3279: \subsecidx{ideallog}$(\var{nf},x,\var{bid})$: $\var{nf}$ being a number field,
3280: \var{bid} being a ``big ideal'' as output by \kbd{idealstar} and $x$ being a
3281: non-necessarily integral element of \var{nf} which must have valuation
3282: equal to 0 at all prime ideals dividing $I=\var{bid}[1]$, computes the
3283: ``discrete logarithm'' of $x$ on the generators given in $\var{bid}[2]$.
3284: In other words, if $g_i$ are these generators, of orders $d_i$ respectively,
3285: the result is a column vector of integers $(x_i)$ such that $0\le x_i<d_i$ and
3286: $$x\equiv\prod_ig_i^{x_i}\pmod{\ ^*I}\enspace.$$
3287: Note that when $I$ is a module, this implies also sign conditions on the
3288: embeddings.
3289:
3290: \syn{zideallog}{\var{nf},x,\var{bid}}.
3291:
3292: \subsecidx{idealmin}$(\var{nf},x,\var{vdir})$: computes a minimum of the
3293: ideal $x$ in the direction \var{vdir} in the number field \var{nf}.
3294:
3295: \syn{minideal}{\var{nf},x,\var{vdir},\var{prec}}.
3296:
3297: \subsecidx{idealmul}$(\var{nf},x,y,\{\fl=0\})$: ideal multiplication of the
3298: ideals $x$ and $y$ in the number field \var{nf}. The result is a generating
3299: set for the ideal product with at most $n$ elements, and is in Hermite normal
3300: form if either $x$ or $y$ is in HNF or is a prime ideal as output by
3301: \kbd{idealprimedec}, and this is given together with the sum of the
3302: Archimedean information in $x$ and $y$ if both are given.
3303:
3304: If $\fl$ is non-zero, reduce the result using \kbd{idealred}.
3305:
3306: \syn{idealmul}{\var{nf},x,y} ($\fl=0$) or
3307: $\teb{idealmulred}(\var{nf},x,y,\var{prec})$ ($\fl\neq0$), where as usual,
3308: $\var{prec}$ is a C long integer representing the precision.
3309:
3310: \subsecidx{idealnorm}$(\var{nf},x)$: computes the norm of the ideal~$x$
3311: in the number field~$\var{nf}$.
3312:
3313: \syn{idealnorm}{\var{nf}, x}.
3314:
3315: \subsecidx{idealpow}$(\var{nf},x,k,\{\fl=0\})$: computes the $k$-th power of
3316: the ideal $x$ in the number field $\var{nf}$. $k$ can be positive, negative
3317: or zero. The result is NOT reduced, it is really the $k$-th ideal power, and
3318: is given in HNF.
3319:
3320: If $\fl$ is non-zero, reduce the result using \kbd{idealred}. Note however
3321: that this is NOT the same as as $\kbd{idealpow}(\var{nf},x,k)$ followed by
3322: reduction, since the reduction is performed throughout the powering process.
3323:
3324: The library syntax corresponding to $\fl=0$ is
3325: $\teb{idealpow}(\var{nf},x,k)$. If $k$ is a \kbd{long}, you can use
3326: $\teb{idealpows}(\var{nf},x,k)$. Corresponding to $\fl=1$ is
3327: $\teb{idealpowred}(\var{nf},vp,k,\var{prec})$, where $\var{prec}$ is a
3328: \kbd{long}.
3329:
3330: \subsecidx{idealprimedec}$(\var{nf},p)$: computes the prime ideal
3331: decomposition of the prime number $p$ in the number field $\var{nf}$. $p$
3332: must be a (positive) prime number. Note that the fact that $p$ is prime is
3333: not checked, so if a non-prime number $p$ is given it may lead to
3334: unpredictable results.
3335:
3336: The result is a vector of 5-component vectors, each representing one of the
3337: prime ideals above $p$ in the number field $\var{nf}$. The representation
3338: $vp=[p,a,e,f,b]$ of a prime ideal means the following. The prime ideal is
3339: equal to $p\Z_K+\alpha\Z_K$ where $\Z_K$ is the ring of integers of the field
3340: and $\alpha=\sum_i a_i\omega_i$ where the $\omega_i$ form the integral basis
3341: \kbd{\var{nf}.zk}, $e$ is the ramification index, $f$ is the residual index,
3342: and $b$ is an $n$-component column vector representing a $\beta\in\Z_K$ such
3343: that $vp^{-1}=\Z_K+\beta/p\Z_K$ which will be useful for computing
3344: valuations, but which the user can ignore. The number $\alpha$ is guaranteed
3345: to have a valuation equal to 1 at the prime ideal (this is automatic if
3346: $e>1$).
3347:
3348: \syn{idealprimedec}{\var{nf},p}.
3349:
3350: \subsecidx{idealprincipal}$(\var{nf},x)$: creates the principal ideal
3351: generated by the algebraic number $x$ (which must be of type integer,
3352: rational or polmod) in the number field $\var{nf}$. The result is a
3353: one-column matrix.
3354:
3355: \syn{principalideal}{\var{nf},x}.
3356:
3357: \subsecidx{idealred}$(\var{nf},x,\{\var{vdir}=0\})$: \idx{LLL} reduction of
3358: the ideal $x$ in the number field \var{nf}, along the direction \var{vdir}.
3359: Here \var{vdir} must be either an $r1+r2$-component vector ($r1$ and $r2$
3360: number of real and complex places of \var{nf} as usual), or the PARI zero,
3361: in which case \var{vdir} is assumed to be equal to the vector having only
3362: components equal to 1. The notion of reduction along a direction is
3363: technical and cannot be explained here. Note that this is {\it not\/} the
3364: same as the LLL reduction of the lattice $x$ since ideal operations are
3365: involved. The result is the \idx{Hermite normal form} of the LLL-reduced
3366: ideal, which is usually, but not always, a reduced ideal. $x$ may also be a
3367: 2-component vector, the first being as above, and the second containing a
3368: matrix of Archimedean information. In that case, this matrix is suitably
3369: updated.
3370:
3371: \syn{ideallllred}{\var{nf},x,\var{vdir},\var{prec}}.
3372:
3373: \subsecidx{idealstar}$(\var{nf},I,\{\fl=1\})$: \var{nf} being a number
3374: field, and $I$
3375: either and ideal in any form, or a row vector whose first component is an
3376: ideal and whose second component is a row vector of $r_1$ 0 or 1, outputs
3377: necessary data for computing in the group $(\Z_K/I)^*$.
3378:
3379: If $\fl=2$, the result is a 5-component vector $w$. $w[1]$ is the ideal
3380: or module $I$ itself. $w[2]$ is the structure of the group. The other
3381: components are difficult to describe and are used only in conjunction with
3382: the function \kbd{ideallog}.
3383:
3384: If $\fl=1$ (default), as $\fl=2$, but do not compute explicit generators
3385: for the cyclic components, which saves time.
3386:
3387: If $\fl=0$, computes the structure of $(\Z_K/I)^*$ as a 3-component vector
3388: $v$. $v[1]$ is the order, $v[2]$ is the vector of SNF\sidx{Smith normal form}
3389: cyclic components and
3390: $v[3]$ the corresponding generators. When the row vector is explicitly
3391: included, the
3392: non-zero elements of this vector are considered as real embeddings of
3393: \var{nf} in the order given by \kbd{polroots}, i.e.~in \var{nf\/}[6]
3394: (\kbd{\var{nf}.roots}), and then $I$ is a module with components at infinity.
3395:
3396: To solve discrete logarithms (using \kbd{ideallog}), you have to choose
3397: $\fl=2$.
3398:
3399: \syn{idealstar0}{\var{nf},I,\fl}.
3400:
3401: \subsecidx{idealtwoelt}$(\var{nf},x,\{a\})$: computes a two-element
3402: representation of the ideal $x$ in the number field $\var{nf}$, using a
3403: straightforward (exponential time) search. $x$ can be an ideal in any form,
3404: (including perhaps an Archimedean part, which is ignored) and the result is a
3405: row vector $[a,\alpha]$ with two components such that $x=a\Z_K+\alpha\Z_K$
3406: and $a\in\Z$, where $a$ is the one passed as argument if any. If $x$ is given
3407: by at least two generators, $a$ is chosen to be the positive generator of
3408: $x\cap\Z$.
3409:
3410: Note that when an explicit $a$ is given, we use an asymptotically faster
3411: method, however in practice it is usually slower.
3412:
3413: \synx{ideal\_two\_elt0}{\var{nf},x,a}{ideal\string\_two\string\_elt0}, where
3414: an omitted $a$ is entered as \kbd{NULL}.
3415:
3416: \subsecidx{idealval}$(\var{nf},x,\var{vp})$: gives the valuation of the
3417: ideal $x$ at the prime ideal \var{vp} in the number field $\var{nf}$,
3418: where \var{vp} must be a
3419: 5-component vector as given by \kbd{idealprimedec}.
3420:
3421: \syn{idealval}{\var{nf},x,\var{vp}}, and the result is a \kbd{long}
3422: integer.
3423:
3424: \subsecidx{ideleprincipal}$(\var{nf},x)$: creates the principal idele
3425: generated by the algebraic number $x$ (which must be of type integer,
3426: rational or polmod) in the number field $\var{nf}$. The result is a
3427: two-component vector, the first being a one-column matrix representing the
3428: corresponding principal ideal, and the second being the vector with $r_1+r_2$
3429: components giving the complex logarithmic embedding of $x$.
3430:
3431: \syn{principalidele}{\var{nf},x}.
3432:
3433: \subsecidx{matalgtobasis}$(\var{nf},x)$: $\var{nf}$ being a number field in
3434: \kbd{nfinit} format, and $x$ a matrix whose coefficients are expressed as
3435: polmods in $\var{nf}$, transforms this matrix into a matrix whose
3436: coefficients are expressed on the integral basis of $\var{nf}$. This is the
3437: same as applying \kbd{nfalgtobasis} to each entry, but it would be dangerous
3438: to use the same name.
3439:
3440: \syn{matalgtobasis}{\var{nf},x}.
3441:
3442: \subsecidx{matbasistoalg}$(\var{nf},x)$: $\var{nf}$ being a number field in
3443: \kbd{nfinit} format, and $x$ a matrix whose coefficients are expressed as
3444: column vectors on the integral basis of $\var{nf}$, transforms this matrix
3445: into a matrix whose coefficients are algebraic numbers expressed as
3446: polmods. This is the same as applying \kbd{nfbasistoalg} to each entry, but
3447: it would be dangerous to use the same name.
3448:
3449: \syn{matbasistoalg}{\var{nf},x}.
3450:
3451: \subsecidx{modreverse}$(a)$: $a$ being a polmod $A(X)$ modulo $T(X)$, finds
3452: the ``reverse polmod'' $B(X)$ modulo $Q(X)$, where $Q$ is the minimal
3453: polynomial of $a$, which must be equal to the degree of $T$, and such that if
3454: $\theta$ is a root of $T$ then $\theta=B(\alpha)$ for a certain root $\alpha$
3455: of $Q$.
3456:
3457: This is very useful when one changes the generating element in algebraic
3458: extensions.
3459:
3460: \syn{polmodrecip}{x}.
3461:
3462: \subsecidx{newtonpoly}$(x,p)$: gives the vector of the slopes of the Newton
3463: polygon of the polynomial $x$ with respect to the prime number $p$. The $n$
3464: components of the vector are in decreasing order, where $n$ is equal to the
3465: degree of $x$. Vertical slopes occur iff the constant coefficient of $x$ is
3466: zero and are denoted by \kbd{VERYBIGINT}, the biggest single precision
3467: integer representable on the machine ($2^{31}-1$ (resp.~$2^{63}-1$) on 32-bit
3468: (resp.~64-bit) machines), see \secref{se:valuation}.
3469:
3470: \syn{newtonpoly}{x,p}.
3471:
3472: \subsecidx{nfalgtobasis}$(\var{nf},x)$: this is the inverse function of
3473: \kbd{nfbasistoalg}. Given an object $x$ whose entries are expressed as
3474: algebraic numbers in the number field $\var{nf}$, transforms it so that the
3475: entries are expressed as a column vector on the integral basis
3476: \kbd{\var{nf}.zk}.
3477:
3478: \syn{algtobasis}{\var{nf},x}.
3479:
3480: \subsecidx{nfbasis}$(x,\{\fl=0\},\{p\})$: \idx{integral basis} of the number
3481: field defined by the irreducible, preferably monic, polynomial $x$, using the
3482: \idx{round 4} algorithm by default. (This program is the translation into C by
3483: Pascal Letard of a program written by David \idx{Ford} in Maple.) The binary
3484: digits of $\fl$ have the following meaning:
3485:
3486: 1: assume that no square of a prime greater than the default \kbd{primelimit}
3487: divides the discriminant of $x$, i.e.~that the index of $x$ has only small
3488: prime divisors.
3489:
3490: 2: use \idx{round 2} algorithm. For small degrees and coefficient size, this is
3491: sometimes a little faster. (This program is the translation into C of a program
3492: written by David \idx{Ford} in Algeb.)
3493:
3494: Thus for instance, if $\fl=3$, this uses the round 2 algorithm and outputs
3495: an order which will be maximal at all the small primes.
3496:
3497: If $p$ is present, we assume (without checking!) that it is the two-column
3498: matrix of the factorization of the discriminant of the polynomial $x$. Note
3499: that it does {\it not\/} have to be a complete factorization. This is
3500: especially useful if only a local integral basis for some small set of places
3501: is desired: only factors with exponents greater or equal to 2 will be
3502: considered.
3503:
3504: \syn{nfbasis0}{x,\fl,p}. An extended version
3505: is $\teb{nfbasis}(x,\&d,\fl,p)$, where $d$ will receive the discriminant of
3506: the number field ({\it not\/} of the polynomial $x$), and an omitted $p$ should
3507: be input as \kbd{gzero}. Also available are $\teb{base}(x,\&d)$ ($\fl=0$),
3508: $\teb{base2}(x,\&d)$ ($\fl=2$) and $\teb{factoredbase}(x,p,\&d)$.
3509:
3510: \subsecidx{nfbasistoalg}$(\var{nf},x)$: this is the inverse function of
3511: \kbd{nfalgtobasis}. Given an object $x$ whose entries are expressed on the
3512: integral basis \kbd{\var{nf}.zk}, transforms it into an object whose entries
3513: are algebraic numbers (i.e.~polmods).
3514:
3515: \syn{basistoalg}{\var{nf},x}.
3516:
3517: \subsecidx{nfdetint}$(\var{nf},x)$: given a pseudo-matrix $x$, computes a
3518: non-zero ideal contained in (i.e.~multiple of) the determinant of $x$. This
3519: is particularly useful in conjunction with \kbd{nfhnfmod}.
3520:
3521: \syn{nfdetint}{\var{nf},x}.
3522:
3523: \subsecidx{nfdisc}$(x,\{\fl=0\},\{p\})$: \idx{field discriminant} of the
3524: number field defined by the integral, preferably monic, irreducible
3525: polynomial $x$. $\fl$ and $p$ are exactly as in \kbd{nfbasis}. That is, $p$
3526: provides the matrix of a partial factorization of the discriminant of $x$,
3527: and binary digits of $\fl$ are as follows:
3528:
3529: 1: assume that no square of a prime greater than \kbd{primelimit}
3530: divides the discriminant.
3531:
3532: 2: use the round 2 algorithm, instead of the default \idx{round 4}.
3533: This should be
3534: slower except maybe for polynomials of small degree and coefficients.
3535:
3536: \syn{nfdiscf0}{x,\fl,p} where, to omit $p$, you should input \kbd{gzero}. You
3537: can also use $\teb{discf}(x)$ ($\fl=0$).
3538:
3539: \subsecidx{nfeltdiv}$(\var{nf},x,y)$: given two elements $x$ and $y$ in
3540: \var{nf}, computes their quotient $x/y$ in the number field $\var{nf}$.
3541:
3542: \synx{element\_div}{\var{nf},x,y}{element\string\_div}.
3543:
3544: \subsecidx{nfeltdiveuc}$(\var{nf},x,y)$: given two elements $x$ and $y$ in
3545: \var{nf}, computes an algebraic integer $q$ in the number field $\var{nf}$
3546: such that the components of $x-qy$ are reasonably small. In fact, this is
3547: functionally identical to \kbd{round(nfeltdiv(\var{nf},x,y))}.
3548:
3549: \syn{nfdiveuc}{\var{nf},x,y}.
3550:
3551: \subsecidx{nfeltdivmodpr}$(\var{nf},x,y,\var{pr})$: given two elements $x$
3552: and $y$ in \var{nf} and \var{pr} a prime ideal in \kbd{modpr} format (see
3553: \tet{nfmodprinit}), computes their quotient $x / y$ modulo the prime ideal
3554: \var{pr}.
3555:
3556: \synx{element\_divmodpr}{\var{nf},x,y,\var{pr}}{element\string\_divmodpr}.
3557:
3558: \subsecidx{nfeltdivrem}$(\var{nf},x,y)$: given two elements $x$ and $y$ in
3559: \var{nf}, gives a two-element row vector $[q,r]$ such that $x=qy+r$, $q$ is
3560: an algebraic integer in $\var{nf}$, and the components of $r$ are
3561: reasonably small.
3562:
3563: \syn{nfdivres}{\var{nf},x,y}.
3564:
3565: \subsecidx{nfeltmod}$(\var{nf},x,y)$: given two elements $x$ and $y$ in
3566: \var{nf}, computes an element $r$ of $\var{nf}$ of the form $r=x-qy$ with
3567: $q$ and algebraic integer, and such that $r$ is small. This is functionally
3568: identical to
3569: $$\kbd{x - nfeltmul(\var{nf},round(nfeltdiv(\var{nf},x,y)),y)}.$$
3570:
3571: \syn{nfmod}{\var{nf},x,y}.
3572:
3573: \subsecidx{nfeltmul}$(\var{nf},x,y)$: given two elements $x$ and $y$ in
3574: \var{nf}, computes their product $x*y$ in the number field $\var{nf}$.
3575:
3576: \synx{element\_mul}{\var{nf},x,y}{element\string\_mul}.
3577:
3578: \subsecidx{nfeltmulmodpr}$(\var{nf},x,y,\var{pr})$: given two elements $x$ and
3579: $y$ in \var{nf} and \var{pr} a prime ideal in \kbd{modpr} format (see
3580: \tet{nfmodprinit}), computes their product $x*y$ modulo the prime ideal
3581: \var{pr}.
3582:
3583: \synx{element\_mulmodpr}{\var{nf},x,y,\var{pr}}{element\string\_mulmodpr}.
3584:
3585: \subsecidx{nfeltpow}$(\var{nf},x,k)$: given an element $x$ in \var{nf},
3586: and a positive or negative integer $k$, computes $x^k$ in the number field
3587: $\var{nf}$.
3588:
3589: \synx{element\_pow}{\var{nf},x,k}{element\string\_pow}.
3590:
3591: \subsecidx{nfeltpowmodpr}$(\var{nf},x,k,\var{pr})$: given an element $x$ in
3592: \var{nf}, an integer $k$ and a prime ideal \var{pr} in \kbd{modpr} format
3593: (see \tet{nfmodprinit}), computes $x^k$ modulo the prime ideal \var{pr}.
3594:
3595: \synx{element\_powmodpr}{\var{nf},x,k,\var{pr}}{element\string\_powmodpr}.
3596:
3597: \subsecidx{nfeltreduce}$(\var{nf},x,\var{ideal})$: given an ideal in
3598: Hermite normal form and an element $x$ of the number field $\var{nf}$,
3599: finds an element $r$ in $\var{nf}$ such that $x-r$ belongs to the ideal
3600: and $r$ is small.
3601:
3602: \synx{element\_reduce}{\var{nf},x,\var{ideal}}{element\string\_reduce}.
3603:
3604: \subsecidx{nfeltreducemodpr}$(\var{nf},x,\var{pr})$: given
3605: an element $x$ of the number field $\var{nf}$ and a prime ideal \var{pr} in
3606: \kbd{modpr} format compute a canonical representative for the class of $x$
3607: modulo \var{pr}.
3608:
3609: \syn{nfreducemodpr2}{\var{nf},x,\var{pr}}.
3610:
3611: \subsecidx{nfeltval}$(\var{nf},x,\var{pr})$: given an element $x$ in
3612: \var{nf} and a prime ideal \var{pr} in the format output by
3613: \kbd{idealprimedec}, computes their the valuation at \var{pr} of the
3614: element $x$. The same result could be obtained using
3615: \kbd{idealval(\var{nf},x,\var{pr})} (since $x$ would then be converted to a
3616: principal ideal), but it would be less efficient.
3617:
3618: \synx{element\_val}{\var{nf},x,\var{pr}}{element\string\_val},
3619: and the result is a \kbd{long}.
3620:
3621: \subsecidx{nf{}factor}$(\var{nf},x)$: factorization of the univariate
3622: polynomial $x$ over the number field $\var{nf}$ given by \kbd{nfinit}. $x$
3623: has coefficients in $\var{nf}$ (i.e.~either scalar, polmod, polynomial or
3624: column vector). The main variable of $\var{nf}$ must be of {\it lower\/}
3625: priority than that of $x$ (in other words, the variable number of $\var{nf}$
3626: must be {\it greater\/} than that of $x$). However if the polynomial defining
3627: the number field occurs explicitly in the coefficients of $x$ (as modulus of
3628: a \typ{POLMOD}), its main variable must be {\it the same\/} as the main
3629: variable of $x$. For example, if $\var{nf}=\hbox{\kbd{nfinit(y\pow 2+1)}}$
3630: then
3631: \hbox{\kbd{nffactor(\var{nf},x\pow 2+Mod(y,y\pow 2+1))}} and
3632: \hbox{\kbd{nffactor(\var{nf},x\pow 2+1)}} are both legal but
3633: \hbox{\kbd{nffactor(\var{nf},x\pow 2+Mod(z,z\pow 2+1))}} is not.
3634:
3635: \syn{nf{}factor}{\var{nf},x}.
3636:
3637: \subsecidx{nf{}factormod}$(\var{nf},x,\var{pr})$: factorization of the
3638: univariate polynomial $x$ modulo the prime ideal \var{pr} in the number
3639: field $\var{nf}$. $x$ can have coefficients in the number field (scalar,
3640: polmod, polynomial, column vector) or modulo the prime ideal (integermod
3641: modulo the rational prime under \var{pr}, polmod or polynomial with
3642: integermod coefficients, column vector of integermod). The prime ideal
3643: \var{pr} {\it must\/} be in the format output by \kbd{idealprimedec}. The
3644: main variable of $\var{nf}$ must be of lower priority than that of $x$ (in
3645: other words the variable number of $\var{nf}$ must be greater than that of
3646: $x$). However if the coefficients of the number field occur explicitly (as
3647: polmods) as coefficients of $x$, the variable of these polmods {\it must\/}
3648: be the same as the main variable of $t$ (see \kbd{nffactor}).
3649:
3650: \syn{nf{}factormod}{\var{nf},x,\var{pr}}.
3651:
3652: \subsecidx{nfgaloisapply}$(\var{nf},\var{aut},x)$: $\var{nf}$ being a
3653: number field as output by \kbd{nfinit}, and \var{aut} being a \idx{Galois}
3654: automorphism of $\var{nf}$ expressed either as a polynomial or a polmod
3655: (such automorphisms being found using for example one of the variants of
3656: \kbd{nfgaloisconj}), computes the action of the automorphism \var{aut} on
3657: the object $x$ in the number field. $x$ can be an element (scalar, polmod,
3658: polynomial or column vector) of the number field, an ideal (either given by
3659: $\Z_K$-generators or by a $\Z$-basis), a prime ideal (given as a 5-element
3660: row vector) or an idele (given as a 2-element row vector). Because of
3661: possible confusion with elements and ideals, other vector or matrix
3662: arguments are forbidden.
3663:
3664: \syn{galoisapply}{\var{nf},\var{aut},x}.
3665:
3666: \subsecidx{nfgaloisconj}$(\var{nf},\{\fl=0\},\{d\})$: $\var{nf}$ being a
3667: number field as output by \kbd{nfinit}, computes the conjugates of a root
3668: $r$ of the non-constant polynomial $x=\var{nf\/}[1]$ expressed as
3669: polynomials in $r$. This can be used even if the number field $\var{nf}$ is
3670: not \idx{Galois} since some conjugates may lie in the field. As a note to
3671: old-timers of PARI, starting with version 2.0.17 this function works much
3672: better than in earlier versions.
3673:
3674: $\var{nf}$ can simply be a polynomial if $\fl\neq 1$.
3675:
3676: If no flags or $\fl=0$, if $\var{nf}$ is a number field use a combination
3677: of flag $4$ and $1$ and the result is always complete, else use a
3678: combination of flag $4$ and $2$ and the result is subject to the
3679: restriction of $\fl=2$.
3680:
3681: If $\fl=1$, use \kbd{nfroots} (require a number field).
3682:
3683: If $\fl=2$, use complex approximations to the roots and an integral
3684: \idx{LLL}. The result is not guaranteed to be complete: some conjugates may
3685: be missing (especially so if the corresponding polynomial has a huge
3686: index). In that case, increasing the default precision may help.
3687:
3688: If $\fl=4$, use Allombert's algorithm and permutation testing. If the field
3689: is Galois with ``weakly'' super solvable Galois group, return the complete
3690: list of automorphisms, else only the identity element. If present, $d$ is
3691: assumed to be a multiple of the index of the power basis in the maximal
3692: order.
3693:
3694: A group G is ``weakly'' super solvable if it contains a super solvable
3695: normal subgroup $H$ such that $G=H$ , or $G/H \simeq A_4$ , or $G/H \simeq
3696: S_4$. Abelian and nilpotent groups are ``weakly'' super solvable. In
3697: practice, almost all groups of small order are weakly super solvable, the
3698: exceptions having order 36(1 exception), 48(2), 56(1), 60(1), 72(5), 75(1),
3699: 80(1), 96(10) and $\geq 108$.
3700:
3701: Hence $\fl = 4$ permits to quickly check whether a polynomial of order
3702: strictly less than $36$ is Galois or not. This method is much faster than
3703: \kbd{nfroots} and be applied to polynomial of degree more than $50$.
3704:
3705: \syn{galoisconj0}{\var{nf},\fl,d,\var{prec}}. Also available are
3706: $\teb{galoisconj}(\var{nf})$ for $\fl=0$,
3707: $\teb{galoisconj2}(\var{nf},n,\var{prec})$ for $\fl=2$ where $n$ is a bound
3708: on the number of conjugates, and $\teb{galoisconj4}(\var{nf},d)$
3709: corresponding to $\fl=4$.
3710:
3711: \subsecidx{nfhilbert}$(\var{nf},a,b,\{\var{pr}\})$: if \var{pr} is omitted,
3712: compute the global \idx{Hilbert symbol} $(a,b)$ in $\var{nf}$, that is $1$
3713: if $x^2 - a y^2 - b z^2$ has a non trivial solution $(x,y,z)$ in $\var{nf}$,
3714: and $-1$ otherwise. Otherwise compute the local symbol modulo the prime ideal
3715: \var{pr} (as output by \kbd{idealprimedec}).
3716:
3717: \syn{nfhilbert}{\var{nf},a,b,\var{pr}}, where an omitted \var{pr} is coded
3718: as \kbd{NULL}.
3719:
3720: \subsecidx{nfhnf}$(\var{nf},x)$: given a pseudo-matrix $(A,I)$, finds a
3721: pseudo-basis in \idx{Hermite normal form} of the module it generates.
3722:
3723: \syn{nfhermite}{\var{nf},x}.
3724:
3725: \subsecidx{nfhnfmod}$(\var{nf},x,\var{detx})$: given a pseudo-matrix $(A,I)$
3726: and an ideal \var{detx} which is contained in (read integral multiple of) the
3727: determinant of $(A,I)$, finds a pseudo-basis in \idx{Hermite normal form}
3728: of the module generated by $(A,I)$. This avoids coefficient explosion.
3729: \var{detx} can be computed using the function \kbd{nfdetint}.
3730:
3731: \syn{nfhermitemod}{\var{nf},x,\var{detx}}.
3732:
3733: \subsecidx{nf{}init}$(\var{pol},\{\fl=0\})$: \var{pol} being a non-constant,
3734: preferably monic, irreducible polynomial in $\Z[X]$, computes a 9-component
3735: vector \var{nf} useful in working in the number field $K$ defined by
3736: \var{pol}.
3737:
3738: $\var{nf\/}[1]$ contains the polynomial \var{pol} (\kbd{\var{nf}.pol}).
3739:
3740: $\var{nf\/}[2]$ contains $[r1,r2]$ (\kbd{\var{nf}.sign}), the number of real
3741: and complex places of $K$.
3742:
3743: $\var{nf\/}[3]$ contains the discriminant $d(K)$ (\kbd{\var{nf}.disc}) of
3744: the number field $K$.
3745:
3746: $\var{nf\/}[4]$ contains the index of $\var{nf\/}[1]$,
3747: i.e.~$[\Z_K:\Z[\theta]]$, where $\theta$ is any root of $\var{nf\/}[1]$.
3748:
3749: $\var{nf\/}[5]$ is a vector containing 7 matrices $M$, $MC$, $T2$, $T$,
3750: $MD$, $TI$, $MDI$ useful for certain computations in the number field $K$.
3751:
3752: \quad$\bullet$ $M$ is the $(r1+r2)\times n$ matrix whose columns represent
3753: the numerical values of the conjugates of the elements of the integral
3754: basis.
3755:
3756: \quad$\bullet$ $MC$ is essentially the conjugate of the transpose of $M$,
3757: except that the last $r2$ columns are also multiplied by 2.
3758:
3759: \quad$\bullet$ $T2$ is an $n\times n$ matrix equal to the real part of the
3760: product $MC\cdot M$ (which is a real positive definite symmetric matrix), the
3761: so-called $T_2$-matrix (\kbd{\var{nf}.t2}).
3762:
3763: \quad$\bullet$ $T$ is the $n\times n$ matrix whose coefficients are
3764: $\text{Tr}(\omega_i\omega_j)$ where the $\omega_i$ are the elements of the
3765: integral basis. Note that $T=\overline{MC}\cdot M$ and in particular that
3766: $T=T_2$ if the field is totally real (in practice $T_2$ will have real
3767: approximate entries and $T$ will have integer entries). Note also that
3768: $\det(T)$ is equal to the discriminant of the field $K$.
3769:
3770: \quad$\bullet$ The columns of $MD$ (\kbd{\var{nf}.diff}) express a $\Z$-basis
3771: of the different of $K$ on the integral basis.
3772:
3773: \quad$\bullet$ $TI$ is equal to $d(K)T^{-1}$, which has integral
3774: coefficients.
3775:
3776: \quad$\bullet$ Finally, $MDI$ has the form $[x,y,n]$, where $(x,y)$ expresses
3777: a $\Z_K$-basis of $d(K)$ times the codifferent ideal
3778: (\kbd{\var{nf}.disc$*$\var{nf}.codiff}, which is an integral ideal) and $n$
3779: is its norm (this ideal is used in \tet{idealinv}).
3780:
3781: $\var{nf\/}[6]$ is the vector containing the $r1+r2$ roots
3782: (\kbd{\var{nf}.roots}) of $\var{nf\/}[1]$ corresponding to the $r1+r2$
3783: embeddings of the number field into $\C$ (the first $r1$ components are real,
3784: the next $r2$ have positive imaginary part).
3785:
3786: $\var{nf\/}[7]$ is an integral basis in Hermite normal form for $\Z_K$
3787: (\kbd{\var{nf}.zk}) expressed on the powers of~$\theta$.
3788:
3789: $\var{nf\/}[8]$ is the $n\times n$ integral matrix expressing the power
3790: basis in terms of the integral basis, and finally
3791:
3792: $\var{nf\/}[9]$ is the $n\times n^2$ matrix giving the multiplication table
3793: of the integral basis.
3794:
3795: If a non monic polynomial is input, \kbd{nfinit} will transform it into a
3796: monic one, then reduce it (see $\fl=3$). It is allowed, though not very
3797: useful given the existence of \teb{nfnewprec}, to input a \kbd{nf} or a
3798: \kbd{bnf} instead of a polynomial.
3799:
3800: The special input format $[x,B]$ is also accepted where $x$ is a polynomial
3801: as above and $B$ is the integer basis, as computed by \tet{nfbasis}. This can
3802: be useful since \kbd{nfinit} uses the round 4 algorithm by default, which can
3803: be very slow in pathological cases where round 2 (\kbd{nfbasis(x,2)}) would
3804: succeed very quickly.
3805:
3806: If $\fl=1$: does not compute the different, replace it by a dummy $0$.
3807:
3808: If $\fl=2$: \var{pol} is changed into another polynomial $P$ defining the same
3809: number field, which is as simple as can easily be found using the
3810: \kbd{polred} algorithm, and all the subsequent computations are done using
3811: this new polynomial. In particular, the first component of the result is the
3812: modified polynomial.
3813:
3814: If $\fl=3$, does a \kbd{polred} as in case 2, but outputs
3815: $[\var{nf},\kbd{Mod}(a,P)]$, where $\var{nf}$ is as before and
3816: $\kbd{Mod}(a,P)=\kbd{Mod}(x,\var{pol})$ gives the change of
3817: variables. This is implicit when \var{pol} is not monic: first a linear change
3818: of variables is performed, to get a monic polynomial, then a \kbd{polred}
3819: reduction.
3820:
3821: If $\fl=4$, as $2$ but uses a partial \kbd{polred}.
3822:
3823: If $\fl=5$, as $3$ using a partial \kbd{polred}.
3824:
3825: \syn{nf{}init0}{x,\fl,\var{prec}}.
3826:
3827: \subsecidx{nf{}isideal}$(\var{nf},x)$: returns 1 if $x$ is an ideal in
3828: the number field $\var{nf}$, 0 otherwise.
3829:
3830: \syn{isideal}{x}.
3831:
3832: \subsecidx{nf{}isincl}$(x,y)$: tests whether the number field $K$ defined
3833: by the polynomial $x$ is conjugate to a subfield of the field $L$ defined
3834: by $y$ (where $x$ and $y$ must be in $\Q[X]$). If they are not, the output
3835: is the number 0. If they are, the output is a vector of polynomials, each
3836: polynomial $a$ representing an embedding of $K$ into $L$, i.e.~being such
3837: that $y\mid x\circ a$.
3838:
3839: If $y$ is a number field (\var{nf}), a much faster algorithm is used
3840: (factoring $x$ over $y$ using \tet{nffactor}). Before version 2.0.14, this
3841: wasn't guaranteed to return all the embeddings, hence was triggered by a
3842: special flag. This is no more the case.
3843:
3844: \syn{nf{}isincl}{x,y,\fl}.
3845:
3846: \subsecidx{nf{}isisom}$(x,y)$: as \tet{nfisincl}, but tests
3847: for isomorphism. If either $x$ or $y$ is a number field, a much faster
3848: algorithm will be used.
3849:
3850: \syn{nf{}isisom}{x,y,\fl}.
3851:
3852: \subsecidx{nfnewprec}$(\var{nf\/})$: transforms the number field $\var{nf}$
3853: into the corresponding data using current (usually larger) precision. This
3854: function works as expected if $\var{nf}$ is in fact a $\var{bnf}$ (update
3855: $\var{bnf}$ to current precision) but may be quite slow (many generators of
3856: principal ideals have to be computed).
3857:
3858: \syn{nfnewprec}{\var{nf},\var{prec}}.
3859:
3860: \subsecidx{nfkermodpr}$(\var{nf},a,\var{pr})$: kernel of the matrix $a$ in
3861: $\Z_K/\var{pr}$, where \var{pr} is in \key{modpr} format
3862: (see \kbd{nfmodprinit}).
3863:
3864: \syn{nfkermodpr}{\var{nf},a,\var{pr}}.
3865:
3866: \subsecidx{nfmodprinit}$(\var{nf},\var{pr})$: transforms the prime ideal
3867: \var{pr} into \tet{modpr} format necessary for all operations modulo
3868: \var{pr} in the number field \var{nf}. Returns a two-component vector
3869: $[P,a]$, where $P$ is the \idx{Hermite normal form} of \var{pr}, and $a$ is
3870: an integral element congruent to $1$ modulo \var{pr}, and congruent to $0$
3871: modulo $p / pr^e$. Here $p = \Z \cap \var{pr}$ and $e$
3872: is the absolute ramification index.\label{se:nfmodprinit}
3873:
3874: \syn{nfmodprinit}{\var{nf},\var{pr}}.
3875:
3876: \subsecidx{nfsubfields}$(\var{nf},\{d=0\})$: finds all subfields of degree $d$
3877: of the number field $\var{nf}$ (all subfields if $d$ is null or omitted).
3878: The result is a vector of subfields, each being given by $[g,h]$, where $g$ is an
3879: absolute equation and $h$ expresses one of the roots of $g$ in terms of the
3880: root $x$ of the polynomial defining $\var{nf}$. This is a crude
3881: implementation by M.~Olivier of an algorithm due to J.~Kl\"uners.
3882:
3883: \syn{subfields}{\var{nf},d}.
3884:
3885: \subsecidx{nfroots}$(\var{nf},x)$: roots of the polynomial $x$ in the number
3886: field $\var{nf}$ given by \kbd{nfinit} without multiplicity. $x$ has
3887: coefficients in the number field (scalar, polmod, polynomial, column
3888: vector). The main variable of $\var{nf}$ must be of lower priority than that
3889: of $x$ (in other words the variable number of $\var{nf}$ must be greater than
3890: that of $x$). However if the coefficients of the number field occur
3891: explicitly (as polmods) as coefficients of $x$, the variable of these
3892: polmods {\it must\/} be the same as the main variable of $t$ (see
3893: \kbd{nffactor}).
3894:
3895: \syn{nfroots}{\var{nf},x}.
3896:
3897: \subsecidx{nfrootsof1}$(\var{nf\/})$: computes the number of roots of unity
3898: $w$ and a primitive $w$-th root of unity (expressed on the integral basis)
3899: belonging to the number field $\var{nf}$. The result is a two-component
3900: vector $[w,z]$ where $z$ is a column vector expressing a primitive $w$-th
3901: root of unity on the integral basis \kbd{\var{nf}.zk}.
3902:
3903: \syn{rootsof1}{\var{nf\/}}.
3904:
3905: \subsecidx{nfsnf}$(\var{nf},x)$: given a torsion module $x$ as a 3-component
3906: row
3907: vector $[A,I,J]$ where $A$ is a square invertible $n\times n$ matrix, $I$ and
3908: $J$ are two ideal lists, outputs an ideal list $d_1,\dots,d_n$ which is the
3909: \idx{Smith normal form} of $x$. In other words, $x$ is isomorphic to
3910: $\Z_K/d_1\oplus\cdots\oplus\Z_K/d_n$ and $d_i$ divides $d_{i-1}$ for $i\ge2$.
3911: The link between $x$ and $[A,I,J]$ is as follows: if $e_i$ is the canonical
3912: basis of $K^n$, $I=[b_1,\dots,b_n]$ and $J=[a_1,\dots,a_n]$, then $x$ is
3913: isomorphic to
3914: $$ (b_1e_1\oplus\cdots\oplus b_ne_n) / (a_1A_1\oplus\cdots\oplus a_nA_n)
3915: \enspace, $$
3916: where the $A_j$ are the columns of the matrix $A$. Note that every finitely
3917: generated torsion module can be given in this way, and even with $b_i=Z_K$
3918: for all $i$.
3919:
3920: \syn{nfsmith}{\var{nf},x}.
3921:
3922: \subsecidx{nfsolvemodpr}$(\var{nf},a,b,\var{pr})$: solution of $a\cdot x = b$
3923: in $\Z_K/\var{pr}$, where $a$ is a matrix and $b$ a column vector, and where
3924: \var{pr} is in \key{modpr} format (see \kbd{nfmodprinit}).
3925:
3926: \syn{nfsolvemodpr}{\var{nf},a,b,\var{pr}}.
3927:
3928: \subsecidx{polcompositum}$(x,y,\{\fl=0\})$: $x$ and $y$ being polynomials in
3929: $\Z[x]$ in the same variable, outputs a vector giving the list of all
3930: possible composita of the number fields defined by $x$ and $y$, if $x$ and
3931: $y$ are irreducible, or of the corresponding \'etale algebras, if they are
3932: only squarefree. Returns an error if one of the polynomials is not squarefree.
3933:
3934: If $\fl=1$, outputs a vector of 4-component vectors $[z,a,b,k]$, where $z$
3935: ranges through the list of all possible compositums as above, and $a$ (resp.
3936: $b$) expresses the root of $x$ (resp. $y$) as a polmod in a root of $z$,
3937: and $k$ is a small integer k such that $a+kb$ is the chosen root of $z$.
3938:
3939: \syn{polcompositum0}{x,y,\fl}.
3940:
3941: \subsecidx{polgalois}$(x)$: \idx{Galois} group of the non-constant polynomial
3942: $x\in\Q[X]$. In the present version \vers, $x$ must be irreducible and
3943: the degree of $x$ must be less than or equal to 7. On certain versions for
3944: which the data file of Galois resolvents has been installed (available
3945: in the Unix distribution as a separate package), degrees 8, 9, 10 and 11
3946: are also implemented.
3947:
3948: The output is a 3-component vector $[n,s,k]$ with the following meaning: $n$
3949: is the cardinality of the group, $s$ is its signature ($s=1$ if the group is
3950: a subgroup of the alternating group $A_n$, $s=-1$ otherwise), and $k$ is the
3951: number of the group corresponding to a given pair $(n,s)$ ($k=1$ except in 2
3952: cases). Specifically, the groups are coded as follows, using standard
3953: notations (see GTM 138, quoted at the beginning of this section):
3954: \smallskip
3955: In degree 1: $S_1=[1,-1,1]$.
3956: \smallskip
3957: In degree 2: $S_2=[2,-1,1]$.
3958: \smallskip
3959: In degree 3: $A_3=C_3=[3,1,1]$, $S_3=[6,-1,1]$.
3960: \smallskip
3961: In degree 4: $C_4=[4,-1,1]$, $V_4=[4,1,1]$, $D_4=[8,-1,1]$, $A_4=[12,1,1]$,
3962: $S_4=[24,-1,1]$.
3963: \smallskip
3964: In degree 5: $C_5=[5,1,1]$, $D_5=[10,1,1]$, $M_{20}=[20,-1,1]$,
3965: $A_5=[60,1,1]$, $S_5=[120,-1,1]$.
3966: \smallskip
3967: In degree 6: $C_6=[6,-1,1]$, $S_3=[6,-1,2]$, $D_6=[12,-1,1]$, $A_4=[12,1,1]$,
3968: $G_{18}=[18,-1,1]$, $S_4^-=[24,-1,1]$, $A_4\times C_2=[24,-1,2]$,
3969: $S_4^+=[24,1,1]$, $G_{36}^-=[36,-1,1]$, $G_{36}^+=[36,1,1]$,
3970: $S_4\times C_2=[48,-1,1]$, $A_5=PSL_2(5)=[60,1,1]$, $G_{72}=[72,-1,1]$,
3971: $S_5=PGL_2(5)=[120,-1,1]$, $A_6=[360,1,1]$, $S_6=[720,-1,1]$.
3972: \smallskip
3973: In degree 7: $C_7=[7,1,1]$, $D_7=[14,-1,1]$, $M_{21}=[21,1,1]$,
3974: $M_{42}=[42,-1,1]$, $PSL_2(7)=PSL_3(2)=[168,1,1]$, $A_7=[2520,1,1]$,
3975: $S_7=[5040,-1,1]$.
3976: \smallskip
3977: The method used is that of resolvent polynomials and is sensitive to the
3978: current precision. The precision is updated internally but, in very rare
3979: cases, a wrong result may be returned if the initial precision was not
3980: sufficient.
3981:
3982: \syn{galois}{x,\var{prec}}.
3983:
3984: \subsecidx{polred}$(x,\{\fl=0\},\{p\})$: finds polynomials with reasonably
3985: small coefficients defining subfields of the number field defined by $x$.
3986: One of the polynomials always defines $\Q$ (hence is equal to $x-1$),
3987: and another always defines the same number field as $x$ if $x$ is irreducible.
3988: All $x$ accepted by \tet{nfinit} are also allowed here (e.g. non-monic
3989: polynomials, \kbd{nf}, \kbd{bnf}, \kbd{[x,Z\_K\_basis]}).
3990:
3991: The following binary digits of $\fl$ are significant:
3992:
3993: 1: does a partial reduction only. This means that only a suborder of the
3994: maximal order may be used.
3995:
3996: 2: gives also elements. The result is a two-column matrix, the first column
3997: giving the elements defining these subfields, the second giving the
3998: corresponding minimal polynomials.
3999:
4000: If $p$ is given, it is assumed that it is the two-column matrix of the
4001: factorization of the discriminant of the polynomial $x$.
4002:
4003: \syn{polred0}{x,\fl,p,\var{prec}}, where an omitted $p$ is
4004: coded by $gzero$. Also available are $\teb{polred}(x,\var{prec})$ and
4005: $\teb{factoredpolred}(x,p,\var{prec})$, both corresponding to $\fl=0$.
4006:
4007: \subsecidx{polredabs}$(x,\{\fl=0\})$: finds one of the polynomial defining
4008: the same number field as the one defined by $x$, and such that the sum of the
4009: squares of the modulus of the roots (i.e.~the $T_2$-norm) is minimal.
4010: All $x$ accepted by \tet{nfinit} are also allowed here (e.g. non-monic
4011: polynomials, \kbd{nf}, \kbd{bnf}, \kbd{[x,Z\_K\_basis]}).
4012:
4013: The binary digits of $\fl$ mean
4014:
4015: 1: outputs a two-component row vector $[P,a]$, where $P$ is the default
4016: output and $a$ is an element expressed on a root of the polynomial $P$,
4017: whose minimal polynomial is equal to $x$.
4018:
4019: 4: gives {\it all} polynomials of minimal $T_2$ norm (of the two polynomials
4020: $P(x)$ and $P(-x)$, only one is given).
4021:
4022: \syn{polredabs0}{x,\fl,\var{prec}}.
4023:
4024: \subsecidx{polredord}$(x)$: finds polynomials with reasonably small
4025: coefficients and of the same degree as that of $x$ defining suborders of the
4026: order defined by $x$. One of the polynomials always defines $\Q$ (hence
4027: is equal to $(x-1)^n$, where $n$ is the degree), and another always defines
4028: the same order as $x$ if $x$ is irreducible.
4029:
4030: \syn{ordred}{x}.
4031:
4032: \subsecidx{poltschirnhaus}$(x)$: applies a random Tschirnhausen
4033: transformation to the polynomial $x$, which is assumed to be non-constant
4034: and separable, so as to obtain a new equation for the \'etale algebra
4035: defined by $x$. This is for instance useful when computing resolvents,
4036: hence is used by the \kbd{polgalois} function.
4037:
4038: \syn{tschirnhaus}{x}.
4039:
4040: \subsecidx{rnfalgtobasis}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
4041: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an element of
4042: $L$ expressed as a polynomial or polmod with polmod coefficients, expresses
4043: $x$ on the relative integral basis.
4044:
4045: \syn{rnfalgtobasis}{\var{rnf},x}.
4046:
4047: \subsecidx{rnfbasis}$(\var{bnf},x)$: given a big number field $\var{bnf}$ as
4048: output by \kbd{bnfinit}, and either a polynomial $x$ with coefficients in
4049: $\var{bnf}$ defining a relative extension $L$ of $\var{bnf}$, or a
4050: pseudo-basis $x$ of such an extension, gives either a true $\var{bnf}$-basis
4051: of $L$ if it exists, or an $n+1$-element generating set of $L$ if not, where
4052: $n$ is the rank of $L$ over $\var{bnf}$.
4053:
4054: \syn{rnfbasis}{\var{bnf},x}.
4055:
4056: \subsecidx{rnfbasistoalg}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
4057: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an element of
4058: $L$ expressed on the relative integral basis, computes the representation of
4059: $x$ as a polmod with polmods coefficients.
4060:
4061: \syn{rnfbasistoalg}{\var{rnf},x}.
4062:
4063: \subsecidx{rnfcharpoly}$(\var{nf},T,a,\{v=x\})$: characteristic polynomial of
4064: $a$ over $\var{nf}$, where $a$ belongs to the algebra defined by $T$ over
4065: $\var{nf}$, i.e.~$\var{nf\/}[X]/(T)$. Returns a polynomial in variable $v$
4066: ($x$ by default).
4067:
4068: \syn{rnfcharpoly}{\var{nf},T,a,v}, where $v$ is a variable number.
4069:
4070: \subsecidx{rnfconductor}$(\var{bnf},\var{pol})$: $\var{bnf}$ being a big number
4071: field as output by \kbd{bnfinit}, and \var{pol} a relative polynomial defining
4072: an \idx{Abelian extension}, computes the class field theory conductor of this
4073: Abelian extension. The result is a 3-component vector
4074: $[\var{conductor},\var{rayclgp},\var{subgroup}]$, where \var{conductor} is
4075: the conductor of the extension given as a 2-component row vector
4076: $[f_0,f_\infty]$, \var{rayclgp} is the full ray class group corresponding to
4077: the conductor given as a 3-component vector [h,cyc,gen] as usual for a group,
4078: and \var{subgroup} is a matrix in HNF defining the subgroup of the ray class
4079: group on the given generators gen.
4080:
4081: \syn{rnfconductor}{\var{rnf},\var{pol},\var{prec}}.
4082:
4083: \subsecidx{rnfdedekind}$(\var{nf},\var{pol},\var{pr})$: given a number field
4084: $\var{nf}$ as output by \kbd{nfinit} and a polynomial \var{pol} with
4085: coefficients in $\var{nf}$ defining a relative extension $L$ of $\var{nf}$,
4086: evaluates the relative \idx{Dedekind} criterion over the order defined by a
4087: root of \var{pol} for the prime ideal \var{pr}
4088: and outputs a 3-component vector as the result. The first component is a flag
4089: equal to 1 if the enlarged order is \var{pr}-maximal and to 0 otherwise, the
4090: second component is a pseudo-basis of the enlarged order and the third
4091: component is the valuation at \var{pr} of the order discriminant.
4092:
4093: \syn{rnfdedekind}{\var{nf},\var{pol},\var{pr}}.
4094:
4095: \subsecidx{rnfdet}$(\var{nf},M)$: given a pseudomatrix $M$ over the maximal
4096: order of $\var{nf}$, computes its pseudodeterminant.
4097:
4098: \syn{rnfdet}{\var{nf},M}.
4099:
4100: \subsecidx{rnfdisc}$(\var{nf},\var{pol})$: given a number field $\var{nf}$ as
4101: output by \kbd{nfinit} and a polynomial \var{pol} with coefficients in
4102: $\var{nf}$ defining a relative extension $L$ of $\var{nf}$, computes
4103: the relative
4104: discriminant of $L$. This is a two-element row vector $[D,d]$, where $D$ is
4105: the relative ideal discriminant and $d$ is the relative discriminant
4106: considered as an element of $\var{nf}^*/{\var{nf}^*}^2$. The main variable of
4107: $\var{nf}$ {\it must\/} be of lower priority than that of \var{pol}.
4108:
4109: Note: As usual, $\var{nf}$ can be a $\var{bnf}$ as output by \kbd{nfinit}.
4110:
4111: \syn{rnfdiscf}{\var{bnf},\var{pol}}.
4112:
4113: \subsecidx{rnfeltabstorel}$(\var{rnf},x)$: $\var{rnf}$ being a relative
4114: number field
4115: extension $L/K$ as output by \kbd{rnfinit} and $x$ being an element of $L$
4116: expressed as a polynomial modulo the absolute equation $\var{rnf\/}[11][1]$,
4117: computes $x$ as an element of the relative extension $L/K$ as a polmod with
4118: polmod coefficients.
4119:
4120: \syn{rnfelementabstorel}{\var{rnf},x}.
4121:
4122: \subsecidx{rnfeltdown}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
4123: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an element of
4124: $L$ expressed as a polynomial or polmod with polmod coefficients, computes
4125: $x$ as an element of $K$ as a polmod, assuming $x$ is in $K$ (otherwise an
4126: error will occur). If $x$ is given on the relative integral basis, apply
4127: \kbd{rnfbasistoalg} first, otherwise PARI will believe you are dealing with a
4128: vector.
4129:
4130: \syn{rnfelementdown}{\var{rnf},x}.
4131:
4132: \subsecidx{rnfeltreltoabs}$(\var{rnf},x)$: $\var{rnf}$ being a relative
4133: number field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an
4134: element of $L$ expressed as a polynomial or polmod with polmod
4135: coefficients, computes $x$ as an element of the absolute extension $L/\Q$ as
4136: a polynomial modulo the absolute equation $\var{rnf\/}[11][1]$. If $x$ is
4137: given on the relative integral basis, apply \kbd{rnfbasistoalg} first,
4138: otherwise PARI will believe you are dealing with a vector.
4139:
4140: \syn{rnfelementreltoabs}{\var{rnf},x}.
4141:
4142: \subsecidx{rnfeltup}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
4143: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an element of
4144: $K$ expressed as a polynomial or polmod, computes $x$ as an element of the
4145: absolute extension $L/\Q$ as a polynomial modulo the absolute equation
4146: $\var{rnf\/}[11][1]$. Note that it is unnecessary to compute $x$ as an
4147: element of the relative extension $L/K$ (its expression would be identical to
4148: itself). If $x$ is given on the integral basis of $K$, apply
4149: \kbd{nfbasistoalg} first, otherwise PARI will believe you are dealing with a
4150: vector.
4151:
4152: \syn{rnfelementup}{\var{rnf},x}.
4153:
4154: \subsecidx{rnfequation}$(\var{nf},\var{pol},\{\fl=0\})$: given a number field
4155: $\var{nf}$ as output by \kbd{nfinit} (or simply a polynomial) and a
4156: polynomial \var{pol} with
4157: coefficients in $\var{nf}$ defining a relative extension $L$ of $\var{nf}$,
4158: computes the absolute equation of $L$ over $\Q$.
4159:
4160: If $\fl$ is non-zero, outputs a 3-component row vector $[z,a,k]$, where $z$
4161: is the absolute equation of $L$ over $\Q$, as in the default behaviour,
4162: $a$ expresses as a polmod a root $\beta$ of $pol$ in terms of a root $\theta$
4163: of $z$, and $k$ is a small integer such that $\theta=\beta+k\alpha$ where
4164: $\alpha$ is a root of the polynomial defining the base field $\var{nf}$.
4165:
4166: The main variable of $\var{nf}$ {\it must\/} be of lower priority than that
4167: of \var{pol}. Note that for efficiency, this does not check whether the
4168: relative equation is irreducible over $\var{nf}$, but only if it is
4169: squarefree. If it is reducible but squarefree, the result will be the
4170: absolute equation of the \'etale algebra defined by \var{pol}. If \var{pol}
4171: is not squarefree, an error message will be issued.
4172:
4173: \syn{rnfequation0}{\var{nf},\var{pol},\fl}.
4174:
4175: \subsecidx{rnfhnfbasis}$(\var{bnf},x)$: given a big number field $\var{bnf}$
4176: as output by \kbd{bnfinit}, and either a polynomial $x$ with coefficients in
4177: $\var{bnf}$ defining a relative extension $L$ of $\var{bnf}$, or a
4178: pseudo-basis $x$ of such an extension, gives either a true $\var{bnf}$-basis
4179: of $L$ in upper triangular Hermite normal form, if it exists,
4180: zero otherwise.
4181:
4182: \syn{rnfhermitebasis}{\var{nf},x}.
4183:
4184: \subsecidx{rnf{}idealabstorel}$(\var{rnf},x)$: $\var{rnf}$ being a relative
4185: number field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an
4186: ideal of the absolute extension $L/\Q$ given in HNF\sidx{Hermite normal form}
4187: (if it is not, apply \kbd{idealhnf} first), computes the relative pseudomatrix
4188: in HNF giving the ideal $x$ considered as an ideal of the relative extension
4189: $L/K$.
4190:
4191: \syn{rnf{}idealabstorel}{\var{rnf},x}.
4192:
4193: \subsecidx{rnf{}idealdown}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
4194: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an ideal of
4195: the absolute extension $L/\Q$ given in HNF (if it is not, apply
4196: \kbd{idealhnf} first), gives the ideal of $K$ below $x$, i.e.~the
4197: intersection of $x$ with $K$. Note that, if $x$ is given as a relative ideal
4198: (i.e.~a pseudomatrix in HNF), then it is not necessary to use this function
4199: since the result is simply the first ideal of the ideal list of the
4200: pseudomatrix.
4201:
4202: \syn{rnf{}idealdown}{\var{rnf},x}.
4203:
4204: \subsecidx{rnf{}idealhnf}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
4205: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being a relative
4206: ideal (which can be, as in the absolute case, of many different types,
4207: including of course elements), computes as a 2-component row vector the
4208: relative Hermite normal form of $x$, the first component being the HNF matrix
4209: (with entries on the integral basis), and the second component the ideals.
4210:
4211: \syn{rnf{}idealhermite}{\var{rnf},x}.
4212:
4213: \subsecidx{rnfidealmul}$(\var{rnf},x,y)$: $\var{rnf}$ being a relative number
4214: field extension $L/K$ as output by \kbd{rnfinit} and $x$ and $y$ being ideals
4215: of the relative extension $L/K$ given by pseudo-matrices, outputs the ideal
4216: product, again as a relative ideal.
4217:
4218: \syn{rnf{}idealmul}{\var{rnf},x,y}.
4219:
4220: \subsecidx{rnf{}idealnormabs}$(\var{rnf},x)$: $\var{rnf}$ being a relative
4221: number field extension $L/K$ as output by \kbd{rnfinit} and $x$ being a
4222: relative ideal (which can be, as in the absolute case, of many different
4223: types, including of course elements), computes the norm of the ideal $x$
4224: considered as an ideal of the absolute extension $L/\Q$. This is identical to
4225: \kbd{idealnorm(rnfidealnormrel(\var{rnf},x))}, only faster.
4226:
4227: \syn{rnf{}idealnormabs}{\var{rnf},x}.
4228:
4229: \subsecidx{rnf{}idealnormrel}$(\var{rnf},x)$: $\var{rnf}$ being a relative
4230: number field
4231: extension $L/K$ as output by \kbd{rnfinit} and $x$ being a relative ideal
4232: (which can be, as in the absolute case, of many different types, including
4233: of course elements), computes the relative norm of $x$ as a ideal of $K$
4234: in HNF.
4235:
4236: \syn{rnf{}idealnormrel}{\var{rnf},x}.
4237:
4238: \subsecidx{rnf{}idealreltoabs}$(\var{rnf},x)$: $\var{rnf}$ being a relative
4239: number field
4240: extension $L/K$ as output by \kbd{rnfinit} and $x$ being a relative ideal
4241: (which can be, as in the absolute case, of many different types, including
4242: of course elements), computes the HNF matrix of the ideal $x$ considered
4243: as an ideal of the absolute extension $L/\Q$.
4244:
4245: \syn{rnf{}idealreltoabs}{\var{rnf},x}.
4246:
4247: \subsecidx{rnf{}idealtwoelt}$(\var{rnf},x)$: $\var{rnf}$ being a relative
4248: number field
4249: extension $L/K$ as output by \kbd{rnfinit} and $x$ being an ideal of the
4250: relative extension $L/K$ given by a pseudo-matrix, gives a vector of
4251: two generators of $x$ over $\Z_L$ expressed as polmods with polmod
4252: coefficients.
4253:
4254: \syn{rnf{}idealtwoelement}{\var{rnf},x}.
4255:
4256: \subsecidx{rnf{}idealup}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
4257: field
4258: extension $L/K$ as output by \kbd{rnfinit} and $x$ being an ideal of
4259: $K$, gives the ideal $x\Z_L$ as an absolute ideal of $L/\Q$ (the relative
4260: ideal representation is trivial: the matrix is the identity matrix, and
4261: the ideal list starts with $x$, all the other ideals being $\Z_K$).
4262:
4263: \syn{rnf{}idealup}{\var{rnf},x}.
4264:
4265: \subsecidx{rnf{}init}$(\var{nf},\var{pol})$: $\var{nf}$ being a number field in
4266: \kbd{nfinit}
4267: format considered as base field, and \var{pol} a polynomial defining a relative
4268: extension over $\var{nf}$, this computes all the necessary data to work in the
4269: relative extension. The main variable of \var{pol} must be of higher priority
4270: (i.e.~lower number) than that of $\var{nf}$, and the coefficients of \var{pol}
4271: must be in $\var{nf}$.
4272:
4273: The result is an 11-component row vector as follows (most of the components
4274: are technical), the numbering being very close to that of \kbd{nfinit}.
4275: In the following description, we let $K$ be the base field defined by
4276: $\var{nf}$,
4277: $m$ the degree of the base field, $n$ the relative degree, $L$ the large
4278: field (of relative degree $n$ or absolute degree $nm$), $r_1$ and $r_2$ the
4279: number of real and complex places of $K$.
4280:
4281: $\var{rnf\/}[1]$ contains the relative polynomial \var{pol}.
4282:
4283: $\var{rnf\/}[2]$ is a row vector with $r_1+r_2$ entries, entry $j$ being
4284: a 2-component row vector $[r_{j,1},r_{j,2}]$ where $r_{j,1}$ and $r_{j,2}$
4285: are the number of real and complex places of $L$ above the $j$-th place of
4286: $K$ so that $r_{j,1}=0$ and $r_{j,2}=n$ if $j$ is a complex place, while if
4287: $j$ is a real place we have $r_{j,1}+2r_{j,2}=n$.
4288:
4289: $\var{rnf\/}[3]$ is a two-component row vector $[\d(L/K),s]$ where $\d(L/K)$
4290: is the relative ideal discriminant of $L/K$ and $s$ is the discriminant of
4291: $L/K$ viewed as an element of $K^*/(K^*)^2$, in other words it is the output
4292: of \kbd{rnfdisc}.
4293:
4294: $\var{rnf\/}[4]$ is the ideal index $\f$, i.e.~such that
4295: $d(pol)\Z_K=\f^2\d(L/K)$.
4296:
4297: $\var{rnf\/}[5]$ is a vector \var{vm} with 7 entries useful for certain
4298: computations in the relative extension $L/K$. $\var{vm}[1]$ is a vector of
4299: $r_1+r_2$ matrices, the $j$-th matrix being an $(r_{1,j}+r_{2,j})\times n$
4300: matrix $M_j$ representing the numerical values of the conjugates of the
4301: $j$-th embedding of the elements of the integral basis, where $r_{i,j}$ is as
4302: in $\var{rnf\/}[2]$. $\var{vm}[2]$ is a vector of $r_1+r_2$ matrices, the
4303: $j$-th matrix $MC_j$ being essentially the conjugate of the matrix $M_j$
4304: except that the last $r_{2,j}$ columns are also multiplied by 2.
4305: $\var{vm}[3]$ is a vector of $r_1+r_2$ matrices $T2_j$, where $T2_j$ is
4306: an $n\times n$ matrix equal to the real part of the product $MC_j\cdot M_j$
4307: (which is a real positive definite matrix). $\var{vm}[4]$ is the $n\times n$
4308: matrix $T$ whose entries are the relative traces of $\omega_i\omega_j$
4309: expressed as polmods in $\var{nf}$, where the $\omega_i$ are the elements
4310: of the relative integral basis. Note that the $j$-th embedding of $T$ is
4311: equal to $\overline{MC_j}\cdot M_j$, and in particular will be equal to
4312: $T2_j$ if $r_{2,j}=0$. Note also that the relative ideal discriminant of
4313: $L/K$ is equal to $\det(T)$ times the square of the product of the ideals
4314: in the relative pseudo-basis (in $\var{rnf\/}[7][2]$). The last 3 entries
4315: $\var{vm}[5]$, $\var{vm}[6]$ and $\var{vm}[7]$ are linked to the different
4316: as in \kbd{nfinit}, but have not yet been implemented.
4317:
4318: $\var{rnf\/}[6]$ is a row vector with $r_1+r_2$ entries, the $j$-th entry
4319: being the
4320: row vector with $r_{1,j}+r_{2,j}$ entries of the roots of the $j$-th embedding
4321: of the relative polynomial \var{pol}.
4322:
4323: $\var{rnf\/}[7]$ is a two-component row vector, where the first component is
4324: the relative integral pseudo basis expressed as polynomials (in the variable of
4325: $pol$) with polmod coefficients in $\var{nf}$, and the second component is the
4326: ideal list of the pseudobasis in HNF.
4327:
4328: $\var{rnf\/}[8]$ is the inverse matrix of the integral basis matrix, with
4329: coefficients polmods in $\var{nf}$.
4330:
4331: $\var{rnf\/}[9]$ may be the multiplication table of the integral basis, but
4332: is not implemented at present.
4333:
4334: $\var{rnf\/}[10]$ is $\var{nf}$.
4335:
4336: $\var{rnf\/}[11]$ is a vector \var{vabs} with 5 entries describing the {\it
4337: absolute\/} extension $L/\Q$. $\var{vabs}[1]$ is an absolute equation.
4338: $\var{vabs}[2]$ expresses the generator $\alpha$ of the number field
4339: $\var{nf}$ as a polynomial modulo the absolute equation $\var{vabs}[1]$.
4340: $\var{vabs}[3]$ is a small integer $k$ such that, if $\beta$ is an abstract
4341: root of \var{pol} and $\alpha$ the generator of $\var{nf}$, the generator
4342: whose root is \var{vabs} will be $\beta + k \alpha$. Note that one must
4343: be very careful if $k\neq0$ when dealing simultaneously with absolute and
4344: relative quantities since the generator chosen for the absolute extension
4345: is not the same as for the relative one. If this happens, one can of course
4346: go on working, but we strongly advise to change the relative polynomial so
4347: that its root will be $\beta + k \alpha$. Typically, the GP instruction would
4348: be
4349:
4350: \kbd{pol = subst(pol, x, x - k*Mod(y,\var{nf}.pol))}
4351:
4352: Finally, $\var{vabs}[4]$ is the absolute integral basis of $L$ expressed in HNF
4353: (hence as would be output by \kbd{nfinit(vabs[1])}), and $\var{vabs}[5]$ the
4354: inverse matrix of the integral basis, allowing to go from polmod to integral
4355: basis representation.
4356:
4357: \syn{rnf{}initalg}{\var{nf},\var{pol},\var{prec}}.
4358:
4359: \subsecidx{rnf{}isfree}$(\var{bnf},x)$: given a big number field $\var{bnf}$ as
4360: output by \kbd{bnfinit}, and either a polynomial $x$ with coefficients in
4361: $\var{bnf}$ defining a relative extension $L$ of $\var{bnf}$, or a
4362: pseudo-basis $x$ of such an extension, returns true (1) if $L/\var{bnf}$ is
4363: free, false (0) if not.
4364:
4365: \syn{rnf{}isfree}{\var{bnf},x}, and the result is a \kbd{long}.
4366:
4367: \subsecidx{rnf{}isnorm}$(\var{bnf},\var{ext},\var{el},\{\fl=1\})$: similar to
4368: \kbd{bnfisnorm} but in the relative case. This tries to decide whether the
4369: element \var{el} in \var{bnf} is the norm of some $y$ in \var{ext}.
4370: $\var{bnf}$ is as output by \kbd{bnfinit}.
4371:
4372: $\var{ext\/}$ is a relative extension which has to be a row vector whose
4373: components are:
4374:
4375: $\var{ext}[1]$: a relative equation of the number field \var{ext} over
4376: \var{bnf}. As usual, the priority of the variable of the polynomial
4377: defining the ground field \var{bnf} (say $y$) must be lower than the
4378: main variable of $\var{ext}[1]$, say $x$.
4379:
4380: $\var{ext}[2]$: the generator $y$ of the base field as a polynomial in $x$ (as
4381: given by \kbd{rnfequation} with $\fl = 1$).
4382:
4383: $\var{ext}[3]$: is the \kbd{bnfinit} of the absolute extension $\var{ext}/\Q$.
4384:
4385: This returns a vector $[a,b]$, where $\var{el}=\var{Norm}(a)*b$. It looks for a
4386: solution which is an $S$-integer, with $S$ a list of places (of \var{bnf})
4387: containing the ramified primes, the generators of the class group of
4388: \var{ext}, as well as those primes dividing \var{el}. If $\var{ext}/\var{bnf}$
4389: is known to be \idx{Galois}, set $\fl=0$
4390: (here \var{el} is a norm iff $b=1$). If $\fl$ is non zero add to $S$ all
4391: the places above the primes which: divide $\fl$ if $\fl<0$, or are less
4392: than $\fl$ if $\fl>0$. The answer is guaranteed (i.e.~\var{el} is a norm
4393: iff $b=1$) under \idx{GRH}, if $S$ contains all primes less than
4394: $12\log^2\left|\text{disc}(\var{Ext})\right|$, where \var{Ext} is the normal
4395: closure of $\var{ext} / \var{bnf}$.
4396:
4397: \syn{rnf{}isnorm}{\var{bnf},ext,x,\fl,\var{prec}}.
4398:
4399: \subsecidx{rnfkummer}$(\var{bnr},\var{subgroup},\{deg=0\})$: \var{bnr}
4400: being as output by \kbd{bnrinit}, finds a relative equation for the
4401: class field corresponding to the module in \var{bnr} and the given
4402: congruence subgroup. If \var{deg} is positive, outputs the list of all
4403: relative equations of degree \var{deg} contained in the ray class field
4404: defined by \var{bnr}.
4405:
4406: (THIS PROGRAM IS STILL IN DEVELOPMENT STAGE)
4407:
4408: \syn{rnfkummer}{\var{bnr},\var{subgroup},\var{deg},\var{prec}},
4409: where \var{deg} is a \kbd{long}.
4410:
4411: \subsecidx{rnf{}lllgram}$(\var{nf},\var{pol},\var{order})$: given a polynomial
4412: \var{pol} with coefficients in \var{nf} and an order \var{order} as output
4413: by \kbd{rnfpseudobasis} or similar, gives $[[\var{neworder}],U]$, where
4414: \var{neworder} is a reduced order and $U$ is the unimodular transformation
4415: matrix.
4416:
4417: \syn{rnf{}lllgram}{\var{nf},\var{pol},\var{order},\var{prec}}.
4418:
4419: \subsecidx{rnfnormgroup}$(\var{bnr},\var{pol})$: \var{bnr} being a big ray
4420: class field as output by \kbd{bnrinit} and \var{pol} a relative polynomial
4421: defining an \idx{Abelian extension}, computes the norm group (alias Artin
4422: or Takagi group) corresponding to the Abelian extension of $\var{bnf}=bnr[1]$
4423: defined by \var{pol}, where the module corresponding to \var{bnr} is assumed
4424: to be a multiple of the conductor (i.e.~polrel defines a subextension of
4425: bnr). The result is the HNF defining the norm group on the given generators
4426: of $\var{bnr}[5][3]$. Note that neither the fact that \var{pol} defines an
4427: Abelian extension nor the fact that the module is a multiple of the conductor
4428: is checked. The result is undefined if the assumption is not correct.
4429:
4430: \syn{rnfnormgroup}{\var{bnr},\var{pol}}.
4431:
4432: \subsecidx{rnfpolred}$(\var{nf},\var{pol})$: relative version of \kbd{polred}.
4433: Given a monic polynomial \var{pol} with coefficients in $\var{nf}$, finds a
4434: list of relative polynomials defining some subfields, hopefully simpler and
4435: containing the original field.
4436:
4437: \syn{rnfpolred}{\var{nf},\var{pol},\var{prec}}.
4438:
4439: \subsecidx{rnfpolredabs}$(\var{nf},\var{pol},\{\fl=0\})$: relative version of
4440: \kbd{polredabs}. Given a monic polynomial \var{pol} with coefficients in
4441: $\var{nf}$, finds a simpler relative polynomial defining the same field. If
4442: $\fl=1$, returns $[P,a]$ where $P$ is the default output and $a$ is an
4443: element expressed on a root of $P$ whose characteristic polynomial is
4444: \var{pol}, if $\fl=2$, returns an absolute polynomial (same as
4445:
4446: {\tt rnfequation(\var{nf},rnfpolredabs(\var{nf},\var{pol}))}
4447:
4448: \noindent but faster).
4449:
4450: \misctitle{Remark.} In the present implementation, although this is slower
4451: than \kbd{rnfpolred}, it is much more efficient, the difference being more
4452: dramatic than in the absolute case. This is because the implementation of
4453: \kbd{rnfpolred} is based on an incomplete reduction theory of lattices over
4454: number fields (i.e.~the function \kbd{rnflllgram}) which deserves to be
4455: improved.
4456:
4457: \syn{rnfpolredabs}{\var{nf},\var{pol},\fl,\var{prec}}.
4458:
4459: \subsecidx{rnfpseudobasis}$(\var{nf},\var{pol})$: given a number field
4460: $\var{nf}$ as output by \kbd{nfinit} and a polynomial \var{pol} with
4461: coefficients in $\var{nf}$ defining a relative extension $L$ of $\var{nf}$,
4462: computes a pseudo-basis $(A,I)$ and the relative discriminant of $L$.
4463: This is output as
4464: a four-element row vector $[A,I,D,d]$, where $D$ is the relative ideal
4465: discriminant and $d$ is the relative discriminant considered as an element of
4466: $\var{nf}^*/{\var{nf}^*}^2$.
4467:
4468: Note: As usual, $\var{nf}$ can be a $\var{bnf}$ as output by \kbd{bnfinit}.
4469:
4470: \syn{rnfpseudobasis}{\var{nf},\var{pol}}.
4471:
4472: \subsecidx{rnfsteinitz}$(\var{nf},x)$: given a number field $\var{nf}$ as
4473: output by \kbd{nfinit} and either a polynomial $x$ with coefficients in
4474: $\var{nf}$ defining a relative extension $L$ of $\var{nf}$, or a pseudo-basis
4475: $x$ of such an extension as output for example by \kbd{rnfpseudobasis},
4476: computes another pseudo-basis $(A,I)$ (not in HNF in general) such that all
4477: the ideals of $I$ except perhaps the last one are equal to the ring of
4478: integers of $\var{nf}$, and outputs the four-component row vector $[A,I,D,d]$
4479: as in \kbd{rnfpseudobasis}. The name of this function comes from the fact
4480: that the ideal class of the last ideal of $I$ (which is well defined) is
4481: called the {\it Steinitz class\/} of the module $\Z_L$.
4482:
4483: Note: $\var{nf}$ can be a $\var{bnf}$ as output by \kbd{bnfinit}.
4484:
4485: \syn{rnfsteinitz}{\var{nf},x}.
4486:
4487: \subsecidx{subgrouplist}$(\var{bnr},\{\var{bound}\},\{\fl=0\})$:
4488: \var{bnr} being as output by \kbd{bnrinit} or a list of cyclic components
4489: of a finite Abelian group $G$, outputs the list of subgroups of $G$
4490: (of index bounded by \var{bound}, if not omitted). Subgroups are given
4491: as HNF\sidx{Hermite normal form} left divisors of the
4492: SNF\sidx{Smith normal form} matrix corresponding to $G$. If $\fl=0$
4493: (default) and \var{bnr} is as output by
4494: \kbd{bnrinit}, gives only the subgroups whose modulus is the conductor.
4495:
4496: \syn{subgrouplist0}{\var{bnr},\var{bound},\fl,\var{prec}}, where
4497: \var{bound}, $\fl$ and $\var{prec}$ are long integers.
4498:
4499: \subsecidx{zetak}$(\var{znf},x,\{\fl=0\})$: \var{znf} being a number
4500: field initialized by \kbd{zetakinit} ({\it not\/} by \kbd{nfinit}),
4501: computes the value of the \idx{Dedekind} zeta function of the number
4502: field at the complex number $x$. If $\fl=1$ computes Dedekind $\Lambda$
4503: function instead (i.e.~the product of the
4504: Dedekind zeta function by its gamma and exponential factors).
4505:
4506: The accuracy of the result depends in an essential way on the accuracy of
4507: both the \kbd{zetakinit} program and the current accuracy, but even so the
4508: result may be off by up to 5 or 10 decimal digits.
4509:
4510: \syn{glambdak}{\var{znf},x,\var{prec}} or
4511: $\teb{gzetak}(\var{znf},x,\var{prec})$.
4512:
4513: \subsecidx{zetakinit}$(x)$: computes a number of initialization data
4514: concerning the number field defined by the polynomial $x$ so as to be
4515: able to compute the \idx{Dedekind} zeta and lambda functions (respectively
4516: $\kbd{zetak}(x)$ and $\kbd{zetak}(x,1)$). This function calls in particular
4517: the \kbd{bnfinit} program. The result is a 9-component vector $v$ whose
4518: components are very technical and cannot really be used by the user except
4519: through the \kbd{zetak} function. The only component which can be used if it
4520: has not been computed already is $v[1][4]$ which is the result of the
4521: \kbd{bnfinit} call.
4522:
4523: This function is very inefficient and needs to computes millions of
4524: coefficients of the corresponding Dirichlet series if the precision is big.
4525: Unless the discriminant is small it will not be able to handle more than 9
4526: digits of relative precision (e.g~\kbd{zetakinit(x\pow 8 - 2)} needs 440MB of
4527: memory at default precision).
4528:
4529: \syn{initzeta}{x}.
4530:
4531: \section{Polynomials and power series}
4532:
4533: We group here all functions which are specific to polynomials or power
4534: series. Many other functions which can be applied on these objects are
4535: described in the other sections. Also, some of the functions described here
4536: can be applied to other types.
4537:
4538: \subsecidx{O}$(a$\kbd{\pow}$b)$: $p$-adic (if $a$ is an integer greater or
4539: equal to 2) or power series zero (in all other cases), with precision given
4540: by $b$.
4541:
4542: \syn{ggrandocp}{a,b}, where $b$ is a \kbd{long}.
4543:
4544: \subsecidx{deriv}$(x,\{v\})$: derivative of $x$ with respect to the main
4545: variable if $v$ is omitted, and with respect to $v$ otherwise. $x$ can be any
4546: type except polmod. The derivative of a scalar type is zero, and the
4547: derivative of a vector or matrix is done componentwise. One can use $x'$ as a
4548: shortcut if the derivative is with respect to the main variable of $x$.
4549:
4550: \syn{deriv}{x,v}, where $v$ is a \kbd{long}, and an omitted $v$ is coded as
4551: $-1$.
4552:
4553: \subsecidx{eval}$(x)$: replaces in $x$ the formal variables by the values that
4554: have been assigned to them after the creation of $x$. This is mainly useful
4555: in GP, and not in library mode. Do not confuse this with substitution (see
4556: \kbd{subst}). Applying this function to a character string yields the
4557: output from the corresponding GP command, as if directly input from the
4558: keyboard (see \secref{se:strings}).\label{se:eval}
4559:
4560: \syn{geval}{x}. The more basic functions $\teb{poleval}(q,x)$,
4561: $\teb{qfeval}(q,x)$, and $\teb{hqfeval}(q,x)$ evaluate $q$ at $x$, where $q$
4562: is respectively assumed to be a polynomial, a quadratic form (a symmetric
4563: matrix), or an Hermitian form (an Hermitian complex matrix).
4564:
4565: \subsecidx{factorpadic}$(\var{pol},p,r,\{\fl=0\})$: $p$-adic factorization
4566: of the polynomial \var{pol} to precision $r$, the result being a two-column
4567: matrix as in \kbd{factor}. $r$ must be strictly larger than the $p$-adic
4568: valuation of the discriminant of \var{pol} for the result to make any sense.
4569: The method used is \idx{Ford}-Letard's implementation of the \idx{round 4}
4570: algorithm of \idx{Zassenhaus}.
4571:
4572: If $\fl=1$, use an algorithm due to \idx{Buchmann} and \idx{Lenstra}, which is
4573: usually less efficient.
4574:
4575: \syn{factorpadic4}{\var{pol},p,r}, where $r$ is a \kbd{long} integer.
4576:
4577: \subsecidx{intformal}$(x,\{v\})$: \idx{formal integration} of $x$ with
4578: respect to the main variable if $v$ is omitted, with respect to the variable
4579: $v$ otherwise. Since PARI does not know about ``abstract'' logarithms (they
4580: are immediately evaluated, if only to a power series), logarithmic terms in
4581: the result will yield an error. $x$ can be of any type. When $x$ is a
4582: rational function, it is assumed that the base ring is an integral domain of
4583: characteristic zero.
4584:
4585: \syn{integ}{x,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded
4586: as $-1$.
4587:
4588: \subsecidx{padicappr}$(\var{pol},a)$: vector of $p$-adic roots of the
4589: polynomial
4590: $pol$ congruent to the $p$-adic number $a$ modulo $p$ (or modulo 4 if $p=2$),
4591: and with the same $p$-adic precision as $a$. The number $a$ can be an
4592: ordinary $p$-adic number (type \typ{PADIC}, i.e.~an element of $\Q_p$) or
4593: can be an element of a finite extension of $\Q_p$, in which case it is of
4594: type \typ{POLMOD}, where at least one of the coefficients of the polmod is a
4595: $p$-adic number. In this case, the result is the vector of roots belonging to
4596: the same extension of $\Q_p$ as $a$.
4597:
4598: \syn{apprgen9}{\var{pol},a}, but if $a$ is known to be simply a $p$-adic number
4599: (type \typ{PADIC}), the syntax $\teb{apprgen}(\var{pol},a)$ can be used.
4600:
4601: \subsecidx{polcoeff}$(x,s,\{v\})$: coefficient of degree $s$ of the
4602: polynomial $x$, with respect to the main variable if $v$ is omitted, with
4603: respect to $v$ otherwise.
4604:
4605: \syn{polcoeff0}{x,s,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded
4606: as $-1$. Also available is \teb{truecoeff}$(x,v)$.
4607:
4608: \subsecidx{poldegree}$(x,\{v\})$: degree of the polynomial $x$ in the main
4609: variable if $v$ is omitted, in the variable $v$ otherwise. This is to be
4610: understood as follows. When $x$ is a polynomial or a rational function, it
4611: gives the degree of $x$, the degree of $0$ being $-1$ by convention. When $x$
4612: is a non-zero scalar, it gives 0, and when $x$ is a zero scalar, it gives
4613: $-1$. Return an error otherwise.
4614:
4615: \syn{poldegree}{x,v}, where $v$ and the result are \kbd{long}s (and an
4616: omitted $v$ is coded as $-1$). Also available is \teb{degree}$(x)$, which is
4617: equivalent to \kbd{poldegree($x$,-1)}.
4618:
4619: \subsecidx{polcyclo}$(n,\{v=x\})$: $n$-th cyclotomic polynomial, in variable
4620: $v$ ($x$ by default). The integer $n$ must be positive.
4621:
4622: \syn{cyclo}{n,v}, where $n$ and $v$ are \kbd{long}
4623: integers ($v$ is a variable number, usually obtained through \kbd{varn}).
4624:
4625: \subsecidx{poldisc}$(\var{pol},\{v\})$: discriminant of the polynomial
4626: \var{pol} in the main variable is $v$ is omitted, in $v$ otherwise. The
4627: algorithm used is the \idx{subresultant algorithm}.
4628:
4629: \syn{poldisc0}{x,v}. Also available is \teb{discsr}$(x)$, equivalent
4630: to \kbd{poldisc0(x,-1)}.
4631:
4632: \subsecidx{poldiscreduced}$(f)$: reduced discriminant vector of the
4633: (integral, monic) polynomial $f$. This is the vector of elementary divisors
4634: of $\Z[\alpha]/f'(\alpha)\Z[\alpha]$, where $\alpha$ is a root of the
4635: polynomial $f$. The components of the result are all positive, and their
4636: product is equal to the absolute value of the discriminant of~$f$.
4637:
4638: \syn{reduceddiscsmith}{x}.
4639:
4640: \subsecidx{polinterpolate}$(xa,ya,\{v=x\},\{\&e\})$: given the data vectors
4641: $xa$ and $ya$ of the same length $n$ ($xa$ containing the $x$-coordinates,
4642: and $ya$ the corresponding $y$-coordinates), this function finds the
4643: \idx{interpolating polynomial} passing through these points and evaluates it
4644: at~$v$. If present, $e$ will contain an error estimate on the returned value.
4645:
4646: \syn{polint}{xa,ya,v,\&e}, where $e$ will contain an error estimate on the
4647: returned value.
4648:
4649: \subsecidx{polisirreducible}$(\var{pol})$: \var{pol} being a polynomial
4650: (univariate in the present version \vers), returns 1 if \var{pol} is
4651: non-constant and irreducible, 0 otherwise. Irreducibility is checked over
4652: the smallest base field over which \var{pol} seems to be defined.
4653:
4654: \syn{gisirreducible}{\var{pol}}.
4655:
4656: \subsecidx{pollead}$(x,\{v\})$: leading coefficient of the polynomial or
4657: power series $x$. This is computed with respect to the main variable of $x$
4658: if $v$ is omitted, with respect to the variable $v$ otherwise.
4659:
4660: \syn{pollead}{x,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded as
4661: $-1$. Also available is \teb{leadingcoeff}$(x)$.
4662:
4663: \subsecidx{pollegendre}$(n,\{v=x\})$: creates the $n^{\text{th}}$
4664: \idx{Legendre polynomial}, in variable $v$.
4665:
4666: \syn{legendre}{n}, where $x$ is a \kbd{long}.
4667:
4668: \subsecidx{polrecip}$(\var{pol})$: reciprocal polynomial of \var{pol},
4669: i.e.~the coefficients are in reverse order. \var{pol} must be a polynomial.
4670:
4671: \syn{polrecip}{x}.
4672:
4673: \subsecidx{polresultant}$(x,y,\{v\},\{\fl=0\})$: resultant of the two
4674: polynomials $x$ and $y$ with exact entries, with respect to the main
4675: variables of $x$ and $y$ if $v$ is omitted, with respect to the variable $v$
4676: otherwise. The algorithm used is the \idx{subresultant algorithm} by default.
4677:
4678: If $\fl=1$, uses the determinant of Sylvester's matrix instead (here $x$ and
4679: $y$ may have non-exact coefficients).
4680:
4681: If $\fl=2$, uses Ducos's modified subresultant algorithm. It should be much
4682: faster than the default if the coefficient ring is complicated (e.g
4683: multivariate polynomials or huge coefficients), and slightly slower
4684: otherwise.
4685:
4686: \syn{polresultant0}{x,y,v,\fl}, where $v$ is a \kbd{long} and an omitted $v$
4687: is coded as $-1$. Also available are $\teb{subres}(x,y)$ ($\fl=0$) and
4688: $\teb{resultant2}(x,y)$ ($\fl=1$).
4689:
4690: \subsecidx{polroots}$(\var{pol},\{\fl=0\})$: complex roots of the polynomial
4691: \var{pol}, given as a column vector where each root is repeated according to
4692: its multiplicity. The precision is given as for transcendental functions: under
4693: GP it is kept in the variable \kbd{realprecision} and is transparent to the
4694: user, but it must be explicitly given as a second argument in library mode.
4695:
4696: The algorithm used is a modification of A.~\idx{Sch\"onhage}'s remarkable
4697: root-finding algorithm, due to and implemented by X.~Gourdon. Barring bugs,
4698: it is guaranteed to converge and to give the roots to the required accuracy.
4699:
4700: If $\fl=1$, use a variant of the Newton-Raphson method, which is {\it not}
4701: guaranteed to converge, but is rather fast. If you get the messages ``too
4702: many iterations in roots'' or ``INTERNAL ERROR: incorrect result in roots'',
4703: use the default function (i.e.~no flag or $\fl=0$). This used to be the
4704: default root-finding function in PARI until version 1.39.06.
4705:
4706: \syn{roots}{\var{pol},\var{prec}} or $\teb{rootsold}(\var{pol},\var{prec})$.
4707:
4708: \subsecidx{polrootsmod}$(\var{pol},p,\{\fl=0\})$: row vector of roots modulo
4709: $p$ of the polynomial \var{pol}. The particular non-prime value $p=4$ is
4710: accepted, mainly for $2$-adic computations. Multiple roots are {\it not\/}
4711: repeated.
4712:
4713: If $p<100$, you may try setting $\fl=1$, which uses a naive search. In this
4714: case, multiple roots {\it are\/} repeated with their order of multiplicity.
4715:
4716: \syn{rootmod}{\var{pol},p} ($\fl=0$) or
4717: $\teb{rootmod2}(\var{pol},p)$ ($\fl=1$).
4718:
4719: \subsecidx{polrootspadic}$(\var{pol},p,r)$: row vector of $p$-adic roots of the
4720: polynomial \var{pol} with $p$-adic precision equal to $r$. Multiple roots are
4721: {\it not\/} repeated. $p$ is assumed to be a prime.
4722:
4723: \syn{rootpadic}{\var{pol},p,r}, where $r$ is a \kbd{long}.
4724:
4725: \subsecidx{polsturm}$(\var{pol},\{a\},\{b\})$: number of real roots of the real
4726: polynomial \var{pol} in the interval $]a,b]$, using Sturm's algorithm. $a$
4727: (resp.~$b$) is taken to be $-\infty$ (resp.~$+\infty$) if omitted.
4728:
4729: \syn{sturmpart}{\var{pol},a,b}. Use \kbd{NULL} to omit an argument.
4730: \kbd{\teb{sturm}(\var{pol})} is equivalent to
4731: \kbd{\key{sturmpart}(\var{pol},NULL,NULL)}.
4732: The result is a \kbd{long}.
4733:
4734: \subsecidx{polsubcyclo}$(n,d,\{v=x\})$: gives a polynomial (in variable
4735: $v$) defining the sub-Abelian extension of degree $d$ of the cyclotomic
4736: field $\Q(\zeta_n)$, where $d\mid \phi(n)$. $(\Z/n\Z)^*$ has to be cyclic
4737: (i.e.~$n=2$, $4$, $p^k$ or $2p^k$ for an odd prime $p$).
4738:
4739: \syn{subcyclo}{n,d,v}, where $v$ is a variable number.
4740:
4741: \subsecidx{polsylvestermatrix}$(x,y)$: forms the Sylvester matrix
4742: corresponding to the two polynomials $x$ and $y$, where the coefficients of
4743: the polynomials are put in the columns of the matrix (which is the natural
4744: direction for solving equations afterwards). The use of this matrix can be
4745: essential when dealing with polynomials with inexact entries, since
4746: polynomial Euclidean division doesn't make much sense in this case.
4747:
4748: \syn{sylvestermatrix}{x,y}.
4749:
4750: \subsecidx{polsym}$(x,n)$: creates the vector of the \idx{symmetric powers}
4751: of the roots of the polynomial $x$ up to power $n$, using Newton's
4752: formula.
4753:
4754: \syn{polsym}{x}.
4755:
4756: \subsecidx{poltchebi}$(n,\{v=x\})$: creates the $n^{\text{th}}$
4757: \idx{Chebyshev} polynomial, in variable $v$.
4758:
4759: \syn{tchebi}{n,v}, where $n$ and $v$ are \kbd{long}
4760: integers ($v$ is a variable number).
4761:
4762: \subsecidx{polzagier}$(n,m)$: creates Zagier's polynomial $P_{n,m}$ used in
4763: the functions \kbd{sumalt} and \kbd{sumpos} (with $\fl=1$). The exact
4764: definition can be found in a forthcoming paper. One must have $m\le n$.
4765:
4766: \syn{polzagreel}{n,m,\var{prec}} if the result is only wanted as a polynomial
4767: with real coefficients to the precision $\var{prec}$, or $\teb{polzag}(n,m)$
4768: if the result is wanted exactly, where $n$ and $m$ are \kbd{long}s.
4769:
4770: \subsecidx{serconvol}$(x,y)$: convolution (or \idx{Hadamard product}) of the
4771: two power series $x$ and $y$; in other words if $x=\sum a_k*X^k$ and $y=\sum
4772: b_k*X^k$ then $\kbd{serconvol}(x,y)=\sum a_k*b_k*X^k$.
4773:
4774: \syn{convol}{x,y}.
4775:
4776: \subsecidx{serlaplace}$(x)$: $x$ must be a power series with only
4777: non-negative exponents. If $x=\sum (a_k/k!)*X^k$ then the result is $\sum
4778: a_k*X^k$.
4779:
4780: \syn{laplace}{x}.
4781:
4782: \subsecidx{serreverse}$(x)$: reverse power series (i.e.~$x^{-1}$, not $1/x$)
4783: of $x$. $x$ must be a power series whose valuation is exactly equal to one.
4784:
4785: \syn{recip}{x}.
4786:
4787: \subsecidx{subst}$(x,y,z)$:
4788: replace the simple variable $y$ by the argument $z$ in the ``polynomial''
4789: expression $x$. Every type is allowed for $x$, but if it is not a genuine
4790: polynomial (or power series, or rational function), the substitution will be
4791: done as if the scalar components were polynomials of degree one. In
4792: particular, beware that:
4793:
4794: \bprog%
4795: ? subst(1, x, [1,2; 3,4])
4796: \%1 =
4797: [1 0]
4798: \smallskip%
4799: [0 1]
4800: \smallskip%
4801: ? subst(1, x, Mat([0,1]))
4802: \q *** forbidden substitution by a non square matrix%
4803: \eprog
4804:
4805: If $x$ is a power series, $z$ must be either a polynomial, a power series, or
4806: a rational function. $y$ must be a simple variable name.
4807:
4808: \syn{gsubst}{x,v,z}, where $v$ is the number of
4809: the variable $y$.
4810:
4811: \subsecidx{taylor}$(x,y)$: Taylor expansion around $0$ of $x$ with respect
4812: to\label{se:taylor}
4813: the simple variable $y$. $x$ can be of any reasonable type, for example a
4814: rational function. The number of terms of the expansion is transparent to the
4815: user under GP, but must be given as a second argument in library mode.
4816:
4817: \syn{tayl}{x,y,n}, where the \kbd{long} integer $n$ is the desired number of
4818: terms in the expansion.
4819:
4820: \subsecidx{thue}$(\var{tnf},a,\{\var{sol}\})$: solves the equation
4821: $P(x,y)=a$ in integers $x$ and $y$, where \var{tnf} was created with
4822: $\kbd{thueinit}(P)$. \var{sol}, if present, contains the solutions of
4823: $\text{Norm}(x)=a$ modulo units of positive norm in the number field
4824: defined by $P$ (as computed by \kbd{bnfisintnorm}). If \var{tnf} was
4825: computed without assuming \idx{GRH} ($\fl=1$ in \kbd{thueinit}), the
4826: result is unconditional.
4827:
4828: \syn{thue}{\var{tnf},a,\var{sol}}, where an omitted \var{sol} is coded
4829: as \kbd{NULL}.
4830:
4831: \subsecidx{thueinit}$(P,\{\fl=0\})$: initializes the \var{tnf} corresponding to
4832: $P$. It is meant to be used in conjunction with \tet{thue} to solve Thue
4833: equations $P(x,y) = a$, where $a$ is an integer. If $\fl$ is non-zero,
4834: certify the result unconditionnaly, Otherwise, assume \idx{GRH}, this being
4835: much faster of course.
4836:
4837: \syn{thueinit}{P,\fl,\var{prec}}.
4838:
4839: \section{Vectors, matrices, linear algebra and sets}
4840: \label{se:linear_algebra}
4841:
4842: Note that most linear algebra functions operating on subspaces defined by
4843: generating sets (such as \tet{mathnf}, \tet{qflll}, etc.) take matrices as
4844: arguments. As usual, the generating vectors are taken to be the
4845: {\it columns\/} of the given matrix.
4846:
4847: \subsecidx{algdep}$(x,k,\{\fl=0\})$:\sidx{algebraic dependence} $x$ being
4848: real or complex, finds a polynomial of degree at most $k$ having $x$ as
4849: approximate root. The algorithm used is a variant of the \idx{LLL} algorithm
4850: due to Hastad, Lagarias and Schnorr (STACS 1986). Note that the polynomial
4851: which is obtained is not necessarily the ``correct'' one (it's not even
4852: guaranteed to be irreducible!). One can check the closeness either by a
4853: polynomial evaluation or substitution, or by computing the roots of the
4854: polynomial given by algdep. If the precision is too low, the routine may
4855: enter an infinite loop.
4856:
4857: If $\fl$ is non-zero, use a standard LLL. $\fl$ then indicates a precision,
4858: which should be between $0.5$ and $1.0$ times the number of decimal digits
4859: to which $x$ was computed.
4860:
4861: \syn{algdep0}{x,k,\fl,\var{prec}}, where $k$ and $\fl$ are \kbd{long}s.
4862: Also available is $\teb{algdep}(x,k,\var{prec})$ ($\fl=0$).
4863:
4864: \subsecidx{charpoly}$(A,\{v=x\},\{\fl=0\})$: \idx{characteristic polynomial}
4865: of $A$ with respect to the variable $v$, i.e.~determinant of $v*I-A$ if $A$
4866: is a square matrix, determinant of the map ``multiplication by $A$'' if $A$
4867: is a scalar, in particular a polmod (e.g.~\kbd{charpoly(I,x)=x\pow2+1}),
4868: error if $A$ is of any other type. The value of $\fl$ is only significant
4869: for matrices.
4870:
4871: If $\fl=0$, the method used is essentially the same as for computing the
4872: adjoint matrix, i.e.~computing the traces of the powers of $A$.
4873:
4874: If $\fl=1$, uses Lagrange interpolation which is almost always slower.
4875:
4876: If $\fl=2$, uses the Hessenberg form. This is faster than the default when the
4877: coefficients are integermod a prime or real numbers, but is usually slower in
4878: other base rings.
4879:
4880: \syn{charpoly0}{A,v,\fl}, where $v$ is the variable number. Also available
4881: are the functions $\teb{caract}(A,v)$ ($\fl=1$), $\teb{carhess}(A,v)$
4882: ($\fl=2$), and $\teb{caradj}(A,v,\var{pt})$ where, in this last case,
4883: \var{pt} is a \kbd{GEN*} which, if not equal to \kbd{NULL}, will receive
4884: the address of the adjoint matrix of $A$ (see \kbd{matadjoint}), so both
4885: can be obtained at once.
4886:
4887: \subsecidx{concat}$(x,\{y\})$: concatenation of $x$ and $y$. If $x$ or $y$ is
4888: not a vector or matrix, it is considered as a one-dimensional vector. All
4889: types are allowed for $x$ and $y$, but the sizes must be compatible. Note
4890: that matrices are concatenated horizontally, i.e.~the number of rows stays
4891: the same. Using transpositions, it is easy to concatenate them vertically.
4892:
4893: To concatenate vectors sideways (i.e.~to obtain a two-row or two-column
4894: matrix), first transform the vector into a one-row or one-column matrix using
4895: the function \tet{Mat}. Concatenating a row vector to a matrix having the
4896: same number of columns will add the row to the matrix (top row if the vector
4897: is $x$, i.e.~comes first, and bottom row otherwise).
4898:
4899: The empty matrix \kbd{[;]} is considered to have a number of rows compatible
4900: with any operation, in particular concatenation. (Note that this is
4901: definitely {\it not\/} the case for empty vectors \kbd{[~]} or \kbd{[~]\til}.)
4902:
4903: If $y$ is omitted, $x$ has to be a row vector or a list, in which case its
4904: elements are concatenated, from left to right, using the above rules.
4905:
4906: \bprog%
4907: ? concat([1,2], [3,4])
4908: \%1 = [1, 2, 3, 4]
4909: ? concat([1,2]\til, [3,4]\til)
4910: \%2 = [1, 2, 3, 4]\til
4911: ? concat([1,2; 3,4], [5,6]\til)
4912: \%3 =
4913: [1, 2, 5]
4914: \smallskip%
4915: [3, 4, 6]
4916: \smallskip%
4917: ? concat([\%, [7,8]\til, [1,2,3,4]])
4918: \%4 =
4919: [1 2 5 7]
4920: \smallskip%
4921: [3 4 6 8]
4922: \smallskip%
4923: [1 2 3 4]
4924: \eprog
4925:
4926: \syn{concat}{x,y}.
4927:
4928: \subsecidx{lindep}$(x,\{\fl=0\})$:\sidx{linear dependence}$x$ being a
4929: vector with real or complex coefficients, finds a small integral linear
4930: combination among these coefficients.
4931:
4932: If $\fl=0$, uses a variant of the \idx{LLL} algorithm due to Hastad, Lagarias
4933: and Schnorr (STACS 1986).
4934:
4935: If $\fl>0$, uses the LLL algorithm. $\fl$ is a parameter which should be
4936: between one half the number of decimal digits of precision and that number
4937: (see \kbd{algdep}).
4938:
4939: If $\fl<0$, returns as soon as one relation has been found.
4940:
4941: \syn{lindep0}{x,\fl,\var{prec}}. Also available is
4942: $\teb{lindep}(x,\var{prec})$ ($\fl=0$).
4943:
4944: \subsecidx{listcreate}$(n)$: creates an empty list of maximal length $n$.
4945:
4946: This function is useless in library mode.
4947:
4948: \subsecidx{listinsert}$(\var{list},x,n)$: inserts the object $x$ at
4949: position $n$ in \var{list} (which must be of type \typ{LIST}). All the
4950: remaining elements of \var{list} (from position $n+1$ onwards) are shifted
4951: to the right. This and \kbd{listput} are the only commands which enable
4952: you to increase a list's effective length (as long as it remains under
4953: the maximal length specified at the time of the \kbd{listcreate}).
4954:
4955: This function is useless in library mode.
4956:
4957: \subsecidx{listkill}$(\var{list})$: kill \var{list}. This deletes all
4958: elements from \var{list} and sets its effective length to $0$. The maximal
4959: length is not affected.
4960:
4961: This function is useless in library mode.
4962:
4963: \subsecidx{listput}$(\var{list},x,\{n\})$: sets the $n$-th element of the list
4964: \var{list} (which must be of type \typ{LIST}) equal to $x$. If $n$ is omitted,
4965: or greater than the list current effective length, just appends $x$. This and
4966: \kbd{listinsert} are the only commands which enable you to increase a list's
4967: effective length (as long as it remains under the maximal length specified at
4968: the time of the \kbd{listcreate}).
4969:
4970: If you want to put an element into an occupied cell, i.e.~if you don't want to
4971: change the effective length, you can consider the list as a vector and use
4972: the usual \kbd{list[n] = x} construct.
4973:
4974: This function is useless in library mode.
4975:
4976: \subsecidx{listsort}$(\var{list},\{\fl=0\})$: sorts \var{list} (which must
4977: be of type \typ{LIST}) in place. If $\fl$ is non-zero, suppresses all repeated
4978: coefficients. This is much faster than the \kbd{vecsort} command since no
4979: copy has to be made.
4980:
4981: This function is useless in library mode.
4982:
4983: \subsecidx{matadjoint}$(x)$: \idx{adjoint matrix} of $x$, i.e.~the matrix $y$
4984: of cofactors of $x$, satisfying $x*y=\det(x)*\text{Id}$. $x$ must be a
4985: (non-necessarily invertible) square matrix.
4986:
4987: \syn{adj}{x}.
4988:
4989: \subsecidx{matcompanion}$(x)$: the left companion matrix to the polynomial $x$.
4990:
4991: \syn{assmat}{x}.
4992:
4993: \subsecidx{matdet}$(x,\{\fl=0\})$: determinant of $x$. $x$ must be a
4994: square matrix.
4995:
4996: If $\fl=0$, uses Gauss-Bareiss.
4997:
4998: If $\fl=1$, uses classical Gaussian elimination, which is better when the
4999: entries of the matrix are reals or integers for example, but usually much
5000: worse for more complicated entries like multivariate polynomials.
5001:
5002: \syn{det}{x} ($\fl=0$) and $\teb{det2}(x)$
5003: ($\fl=1$).
5004:
5005: \subsecidx{matdetint}$(x)$: $x$ being an $m\times n$ matrix with integer
5006: coefficients, this function computes a multiple of the determinant of the
5007: lattice generated by the columns of $x$ if it is of rank $m$, and returns
5008: zero otherwise. This function can be useful in conjunction with the function
5009: \kbd{mathnfmod} which needs to know such a multiple. Other ways to obtain
5010: this determinant (assuming the rank is maximal) is
5011: \kbd{matdet(qflll(x,4)[2]$*$x)} or more simply \kbd{matdet(mathnf(x))}.
5012: Experiment to see which is faster for your applications.
5013:
5014: \syn{detint}{x}.
5015:
5016: \subsecidx{matdiagonal}$(x)$: $x$ being a vector, creates the diagonal matrix
5017: whose diagonal entries are those of $x$.
5018:
5019: \syn{diagonal}{x}.
5020:
5021: \subsecidx{mateigen}$(x)$: gives the eigenvectors of $x$ as columns of a
5022: matrix.
5023:
5024: \syn{eigen}{x}.
5025:
5026: \subsecidx{mathess}$(x)$: Hessenberg form of the square matrix $x$.
5027:
5028: \syn{hess}{x}.
5029:
5030: \subsecidx{mathilbert}$(x)$: $x$ being a \kbd{long}, creates the \idx{Hilbert
5031: matrix} of order $x$, i.e.~the matrix whose coefficient ($i$,$j$) is $1/
5032: (i+j-1)$.
5033:
5034: \syn{mathilbert}{x}.
5035:
5036: \subsecidx{mathnf}$(x,\{\fl=0\})$: if $x$ is a (not necessarily square)
5037: matrix of maximal rank, finds the {\it upper triangular\/}
5038: \idx{Hermite normal form}
5039: of $x$. If the rank of $x$ is equal to its number of rows, the result is a
5040: square matrix. In general, the columns of the result form a basis of the
5041: lattice spanned by the columns of $x$.
5042:
5043: If $\fl=0$, uses the naive algorithm. If the $\Z$-module generated by the
5044: columns is a lattice, it is recommanded to use \kbd{mathnfmod(x,
5045: matdetint(x))} instead (much faster).
5046:
5047: If $\fl=1$, uses Batut's algorithm. Outputs a two-component row vector
5048: $[H,U]$, where $H$ is the {\it upper triangular\/} Hermite normal form
5049: of $x$ (i.e.~the default result) and $U$ is the unimodular transformation
5050: matrix such that $xU=[0|H]$. If the rank of $x$ is equal to its number of
5051: rows, $H$ is a square matrix. In general, the columns of $H$ form a basis
5052: of the lattice spanned by the columns of $x$.
5053:
5054: If $\fl=2$, uses Havas's algorithm. Outputs $[H,U,P]$, such that
5055: $H$ and $U$ are as before and $P$ is a permutation of the rows such that $P$
5056: applied to $xU$ gives $H$. This does not work very well in present version
5057: \vers.
5058:
5059: If $\fl=3$, uses Batut's algorithm, and outputs $[H,U,P]$ as in the previous
5060: case.
5061:
5062: If $\fl=4$, as in case 1 above, but uses \idx{LLL} reduction along the way.
5063:
5064: \syn{mathnf0}{x,\fl}. Also available are $\teb{hnf}(x)$ ($\fl=0$) and
5065: $\teb{hnfall}(x)$ ($\fl=1$). To reduce {\it huge} (say $400 \times 400$ and
5066: more) relation matrices (sparse with small entries), you can use the pair
5067: \kbd{hnfspec} / \kbd{hnfadd}. Since this is rather technical and the
5068: calling interface may change, they are not documented yet. Look at the code
5069: in \kbd{basemath/alglin1.c}.
5070:
5071: \subsecidx{mathnfmod}$(x,d)$: if $x$ is a (not necessarily square) matrix of
5072: maximal rank with integer entries, and $d$ is a multiple of the (non-zero)
5073: determinant of the lattice spanned by the columns of $x$, finds the
5074: {\it upper triangular\/} \idx{Hermite normal form} of $x$.
5075:
5076: If the rank of $x$ is equal to its number of rows, the result is a square
5077: matrix. In general, the columns of the result form a basis of the lattice
5078: spanned by the columns of $x$. This is much faster than \kbd{mathnf} when $d$
5079: is known.
5080:
5081: \syn{hnfmod}{x,d}.
5082:
5083: \subsecidx{mathnfmodid}$(x,d)$: outputs the (upper triangular)
5084: \idx{Hermite normal form} of $x$ concatenated with $d$ times
5085: the identity matrix.
5086:
5087: \syn{hnfmodid}{x,d}.
5088:
5089: \subsecidx{matid}$(n)$: creates the $n\times n$ identity matrix.
5090:
5091: \syn{idmat}{n} where $n$ is a \kbd{long}.
5092:
5093: Related functions are $\teb{gscalmat}(x,n)$, which creates $x$ times the
5094: identity matrix ($x$ being a \kbd{GEN} and $n$ a \kbd{long}), and
5095: $\teb{gscalsmat}(x,n)$ which is the same when $x$ is a \kbd{long}.
5096:
5097: \subsecidx{matimage}$(x,\{\fl=0\})$: gives a basis for the image of the
5098: matrix $x$ as columns of a matrix. A priori the matrix can have entries of
5099: any type. If $\fl=0$, use standard Gauss pivot. If $\fl=1$, use
5100: \kbd{matsupplement}.
5101:
5102: \syn{matimage0}{x,\fl}. Also available is $\teb{image}(x)$ ($\fl=0$).
5103:
5104: \subsecidx{matimagecompl}$(x)$: gives the vector of the column indices which
5105: are not extracted by the function \kbd{matimage}. Hence the number of
5106: components of \kbd{matimagecompl(x)} plus the number of columns of
5107: \kbd{matimage(x)} is equal to the number of columns of the matrix $x$.
5108:
5109: \syn{imagecompl}{x}.
5110:
5111: \subsecidx{matindexrank}$(x)$: $x$ being a matrix of rank $r$, gives two
5112: vectors $y$ and $z$ of length $r$ giving a list of rows and columns
5113: respectively (starting from 1) such that the extracted matrix obtained from
5114: these two vectors using $\tet{vecextract}(x,y,z)$ is invertible.
5115:
5116: \syn{indexrank}{x}.
5117:
5118: \subsecidx{matintersect}$(x,y)$: $x$ and $y$ being two matrices with the same
5119: number of rows each of whose columns are independent, finds a basis of the
5120: $\Q$-vector space equal to the intersection of the spaces spanned by the
5121: columns of $x$ and $y$ respectively. See also the function
5122: \tet{idealintersect}, which does the same for free $\Z$-modules.
5123:
5124: \syn{intersect}{x,y}.
5125:
5126: \subsecidx{matinverseimage}$(x,y)$: gives a column vector belonging to the
5127: inverse image of the column vector $y$ by the matrix $x$ if one exists, the
5128: empty vector otherwise. To get the complete inverse image, it suffices to add
5129: to the result any element of the kernel of $x$ obtained for example by
5130: \kbd{matker}.
5131:
5132: \syn{inverseimage}{x,y}.
5133:
5134: \subsecidx{matisdiagonal}$(x)$: returns true (1) if $x$ is a diagonal matrix,
5135: false (0) if not.
5136:
5137: \syn{isdiagonal}{x}, and this returns a \kbd{long}
5138: integer.
5139:
5140: \subsecidx{matker}$(x,\{\fl=0\})$: gives a basis for the kernel of the
5141: matrix $x$ as columns of a matrix. A priori the matrix can have entries of
5142: any type.
5143:
5144: If $x$ is known to have integral entries, set $\fl=1$.
5145:
5146: \noindent Note: The library function\sidx{ker\string\_mod\string\_p}
5147: $\kbd{ker\_mod\_p}(x, p)$, where $x$ has integer entries and $p$ is prime,
5148: which is equivalent to but many orders of magnitude faster than
5149: \kbd{matker(x*Mod(1,p))} and needs much less stack space. To use it under GP,
5150: type \kbd{install(ker\_mod\_p, GG)} first.
5151:
5152: \syn{matker0}{x,\fl}. Also available are $\teb{ker}(x)$ ($\fl=0$),
5153: $\teb{keri}(x)$ ($\fl=1$) and $\kbd{ker\_mod\_p}(x,p)$.
5154:
5155: \subsecidx{matkerint}$(x,\{\fl=0\})$: gives an \idx{LLL}-reduced $\Z$-basis
5156: for the lattice equal to the kernel of the matrix $x$ as columns of the
5157: matrix $x$ with integer entries (rational entries are not permitted).
5158:
5159: If $\fl=0$, uses a modified integer LLL algorithm.
5160:
5161: If $\fl=1$, uses $\kbd{matrixqz}(x,-2)$. If LLL reduction of the final result
5162: is not desired, you can save time using \kbd{matrixqz(matker(x),-2)} instead.
5163:
5164: If $\fl=2$, uses another modified LLL. In the present version \vers, only
5165: independent rows are allowed in this case.
5166:
5167: \syn{matkerint0}{x,\fl}. Also available is
5168: $\teb{kerint}(x)$ ($\fl=0$).
5169:
5170: \subsecidx{matmuldiagonal}$(x,d)$: product of the matrix $x$ by the diagonal
5171: matrix whose diagonal entries are those of the vector $d$. Equivalent to,
5172: but much faster than $x*\kbd{matdiagonal}(d)$.
5173:
5174: \syn{matmuldiagonal}{x,d}.
5175:
5176: \subsecidx{matmultodiagonal}$(x,y)$: product of the matrices $x$ and $y$
5177: knowing that the result is a diagonal matrix. Much faster than $x*y$ in
5178: that case.
5179:
5180: \syn{matmultodiagonal}{x,y}.
5181:
5182: \subsecidx{matpascal}$(x,\{q\})$: creates as a matrix the lower triangular
5183: \idx{pascal triangle} of order $x+1$ (i.e.~with binomial coefficients
5184: up to $x$). If $q$ is given, compute the $q$-Pascal triangle (i.e.~using
5185: $q$-binomial coefficients).
5186:
5187: \syn{matqpascal}{x,q}, where $x$ is a \kbd{long} and $q=\kbd{NULL}$ is used
5188: to omit $q$. Also available is \teb{matpascal}{x}.
5189:
5190: \subsecidx{matrank}$(x)$: rank of the matrix $x$.
5191:
5192: \syn{rank}{x}, and the result is a \kbd{long}.
5193:
5194: \subsecidx{matrixqz}$(x,p)$: $x$ being an $m\times n$ matrix with $m\ge n$
5195: with rational or integer entries, this function has varying behaviour
5196: depending on the sign of $p$:
5197:
5198: If $p\geq 0$, $x$ is assumed to be of maximal rank. This function returns a
5199: matrix having only integral entries, having the same image as $x$, such that
5200: the GCD of all its $n\times n$ subdeterminants is equal to 1 when $p$ is
5201: equal to 0, or not divisible by $p$ otherwise. Here $p$ must be a prime
5202: number (when it is non-zero). However, if the function is used when $p$ has
5203: no small prime factors, it will either work or give the message ``impossible
5204: inverse modulo'' and a non-trivial divisor of $p$.
5205:
5206: If $p=-1$, this function returns a matrix whose columns form a basis of the
5207: lattice equal to $\Z^n$ intersected with the lattice generated by the
5208: columns of $x$.
5209:
5210: If $p=-2$, returns a matrix whose columns form a basis of the lattice equal
5211: to $\Z^n$ intersected with the $\Q$-vector space generated by the
5212: columns of $x$.
5213:
5214: \syn{matrixqz0}{x,p}.
5215:
5216: \subsecidx{matsize}$(x)$: $x$ being a vector or matrix, returns a row vector
5217: with two components, the first being the number of rows (1 for a row vector),
5218: the second the number of columns (1 for a column vector).
5219:
5220: \syn{matsize}{x}.
5221:
5222: \subsecidx{matsnf}$(X,\{\fl=0\})$: if $X$ is a (singular or non-singular)
5223: square matrix outputs the vector of elementary divisors of $X$ (i.e.~the
5224: diagonal of the \idx{Smith normal form} of $X$).
5225:
5226: The binary digits of \fl\ mean:
5227:
5228: 1 (complete output): if set, outputs $[U,V,D]$, where $U$ and $V$ are two
5229: unimodular matrices such that $U\times X \times V$ is the diagonal matrix
5230: $D$. Otherwise output only the diagonal of $D$.
5231:
5232: 2 (generic input): if set, allows polynomial entries. Otherwise, assume
5233: that $X$ has integer coefficients.
5234:
5235: 4 (cleanup): if set, cleans up the output. This means that elementary
5236: divisors equal to $1$ will be deleted, i.e.~outputs a shortened vector $D'$
5237: instead of $D$. If complete output was required, returns $[U',V',D']$ so
5238: that $U'XV' = D'$ holds. If this flag is set, $X$ is allowed to be of the
5239: form $D$ or $[U,V,D]$ as would normally be output with the cleanup flag
5240: unset.
5241:
5242: \syn{matsnf0}{X,\fl}. Also available is $\teb{smith}(X)$ ($\fl=0$).
5243:
5244: \subsecidx{matsolve}$(x,y)$: $x$ being an invertible matrix and $y$ a column
5245: vector, finds the solution $u$ of $x*u=y$, using Gaussian elimination. This
5246: has the same effect as, but is a bit faster, than $x^{-1}*y$.
5247:
5248: \syn{gauss}{x,y}.
5249:
5250: \subsecidx{matsolvemod}$(m,d,y,\{\fl=0\})$: $m$ being any integral matrix,
5251: $d$ a vector of positive integer moduli, and $y$ an integral
5252: column vector, gives a small integer solution to the system of congruences
5253: $\sum_i m_{i,j}x_j\equiv y_i\pmod{d_i}$ if one exists, otherwise returns
5254: zero. Shorthand notation: $y$ (resp.~$d$) can be given as a single integer,
5255: in which case all the $y_i$ (resp.~$d_i$) above are taken to be equal to $y$
5256: (resp.~$d$).
5257:
5258: If $\fl=1$, all solutions are returned in the form of a two-component row
5259: vector $[x,u]$, where $x$ is a small integer solution to the system of
5260: congruences and $u$ is a matrix whose columns give a basis of the homogeneous
5261: system (so that all solutions can be obtained by adding $x$ to any linear
5262: combination of columns of $u$). If no solution exists, returns zero.
5263:
5264: \syn{matsolvemod0}{m,d,y,\fl}. Also available
5265: are $\teb{gaussmodulo}(m,d,y)$ ($\fl=0$)
5266: and $\teb{gaussmodulo2}(m,d,y)$ ($\fl=1$).
5267:
5268: \subsecidx{matsupplement}$(x)$: assuming that the columns of the matrix $x$
5269: are linearly independent (if they are not, an error message is issued), finds
5270: a square invertible matrix whose first columns are the columns of $x$,
5271: i.e.~supplement the columns of $x$ to a basis of the whole space.
5272:
5273: \syn{suppl}{x}.
5274:
5275: \subsecidx{mattranspose}$(x)$ or $x\til$: transpose of $x$.
5276: This has an effect only on vectors and matrices.
5277:
5278: \syn{gtrans}{x}.
5279:
5280: \subsecidx{qfgaussred}$(q)$: \idx{decomposition into squares} of the
5281: quadratic form represented by the symmetric matrix $q$. The result is a
5282: matrix whose diagonal entries are the coefficients of the squares, and the
5283: non-diagonal entries represent the bilinear forms. More precisely, if
5284: $(a_{ij})$ denotes the output, one has
5285: $$ q(x) = \sum_i a_{ii} (x_i + \sum_j>i a_{ij} x_j)^2 $$
5286:
5287: \syn{sqred}{x}.
5288:
5289: \subsecidx{qfjacobi}$(x)$: $x$ being a real symmetric matrix, this gives a
5290: vector having two components: the first one is the vector of eigenvalues of
5291: $x$, the second is the corresponding orthogonal matrix of eigenvectors of
5292: $x$. The method used is Jacobi's method for symmetric matrices.
5293:
5294: \syn{jacobi}{x}.
5295:
5296: \subsecidx{qf{}lll}$(x,\{\fl=0\})$: \idx{LLL} algorithm applied to the
5297: {\it columns}
5298: of the (not necessarily square) matrix $x$. The columns of $x$ must however
5299: be of maximal rank (unless specified otherwise below). The result is a square
5300: transformation matrix $T$ such that $x\cdot T$ is an LLL-reduced basis of the
5301: lattice generated by the column vectors of $x$.
5302:
5303: If $\fl=0$ (default), the computations are done with real numbers (i.e.~not
5304: with rational numbers) hence are fast but as presently programmed (version
5305: \vers) are numerically unstable.
5306:
5307: If $\fl=1$, it is assumed that the corresponding Gram matrix is integral.
5308: The computation is done entirely with integers and the algorithm is both
5309: accurate and quite fast. In this case, $x$ needs not be of maximal rank.
5310:
5311: If $\fl=2$, similar to case 1, except $x$ should be an integer matrix whose
5312: columns are linearly independent. The lattice generated by the columns of
5313: $x$ is first partially reduced before applying the LLL algorithm. [A basis
5314: is said to be {\it partially reduced} if $|v_i \pm v_j| \geq |v_i|$ for any
5315: two distinct basis vectors $v_i, \, v_j$.]
5316:
5317: This can be significantly faster than $\fl=1$ when one row is huge compared
5318: to the other rows.
5319:
5320: If $\fl=3$, all computations are done in rational numbers. This does not
5321: incur numerical instability, but is extremely slow. This function is
5322: essentially superseded by case 1, so will soon disappear.
5323:
5324: If $\fl=4$, $x$ is assumed to have integral entries, but needs not be of
5325: maximal rank. The result is a two-component vector of matrices, the columns
5326: of the first matrix representing a basis of the integer kernel of $x$ (not
5327: necessarily LLL-reduced) and the columns of the second matrix being an
5328: LLL-reduced $\Z$-basis of the image of the matrix $x$.
5329:
5330: If $\fl=5$, case as case $4$, but $x$ may have polynomial coefficients.
5331:
5332: If $\fl=7$, uses an older version of case $0$ above.
5333:
5334: If $\fl=8$, same as case $0$, where $x$ may have polynomial coefficients.
5335:
5336: If $\fl=9$, variation on case $1$, using content.
5337:
5338: \syn{qf{}lll0}{x,\fl,\var{prec}}. Also available are
5339: $\teb{lll}(x,\var{prec})$ ($\fl=0$), $\teb{lllint}(x)$ ($\fl=1$), and
5340: $\teb{lllkerim}(x)$ ($\fl=4$).
5341:
5342: \subsecidx{qf{}lllgram}$(x,\{\fl=0\})$: same as \kbd{qflll} except that the
5343: matrix $x$ which must now be a square symmetric real matrix is the Gram
5344: matrix of the lattice vectors, and not the coordinates of the vectors
5345: themselves. The result is again the transformation matrix $T$ which gives (as
5346: columns) the coefficients with respect to the initial basis vectors. The
5347: flags have more or less the same meaning, but some are missing. In brief:
5348:
5349: $\fl=0$: numerically unstable in the present version \vers.
5350:
5351: $\fl=1$: $x$ has integer entries, the computations are all done in integers.
5352:
5353: $\fl=4$: $x$ has integer entries, gives the kernel and reduced image.
5354:
5355: $\fl=5$: same as $4$ for generic $x$.
5356:
5357: $\fl=7$: an older version of case $0$.
5358:
5359: \syn{qf{}lllgram0}{x,\fl,\var{prec}}. Also available are
5360: $\teb{lllgram}(x,\var{prec})$ ($\fl=0$), $\teb{lllgramint}(x)$ ($\fl=1$), and
5361: $\teb{lllgramkerim}(x)$ ($\fl=4$).
5362:
5363: \subsecidx{qfminim}$(x,b,m,\{\fl=0\})$: $x$ being a square and symmetric
5364: matrix representing a positive definite quadratic form, this function
5365: deals with the minimal vectors of $x$, depending on $\fl$.
5366:
5367: If $\fl=0$ (default), seeks vectors of square norm less than or equal to $b$
5368: (for the norm defined by $x$), and at most $2m$ of these vectors. The result
5369: is a three-component vector, the first component being the number of vectors,
5370: the second being the maximum norm found, and the last vector is a matrix
5371: whose columns are the vectors found, only one being given for each
5372: pair $\pm v$ (at most $m$ such pairs).
5373:
5374: If $\fl=1$, ignores $m$ and returns the first vector whose norm is less than
5375: $b$.
5376:
5377: In both these cases, $x$ {\it is assumed to have integral entries}, and the
5378: function searches for the minimal non-zero vectors whenever $b=0$.
5379:
5380: If $\fl=2$, $x$ can have non integral real entries, but $b=0$ is now
5381: meaningless (uses Fincke-Pohst algorithm).
5382:
5383: \syn{minim}{x,b,m} ($\fl=0$), $\teb{minim2}(x,b,m)$
5384: ($\fl=1$), or finally $\key{fincke\_pohst}(x,b,m,\var{prec})$
5385: ($\fl=2$).\sidx{fincke\string\_pohst}
5386:
5387: \subsecidx{qfperfection}$(x)$: $x$ being a square and symmetric matrix with
5388: integer entries representing a positive definite quadratic form, outputs the
5389: perfection rank of the form. That is, gives the rank of the family of the $s$
5390: symmetric matrices $v_iv_i^t$, where $s$ is half the number of minimal
5391: vectors and the $v_i$ ($1\le i\le s$) are the minimal vectors.
5392:
5393: As a side note to old-timers, this used to fail bluntly when $x$ had more
5394: than $5000$ minimal vectors. Beware that the computations can now be very
5395: lengthy when $x$ has many minimal vectors.
5396:
5397: \syn{perf}{x}.
5398:
5399: \subsecidx{qfsign}$(x)$: signature of the quadratic form represented by the
5400: symmetric matrix $x$. The result is a two-component vector.
5401:
5402: \syn{signat}{x}.
5403:
5404: \subsecidx{setintersect}$(x,y)$: intersection of the two sets $x$ and $y$.
5405:
5406: \syn{setintersect}{x,y}.
5407:
5408: \subsecidx{setisset}$(x)$: returns true (1) if $x$ is a set, false (0) if
5409: not. In PARI, a set is simply a row vector whose entries are strictly
5410: increasing. To convert any vector (and other objects) into a set, use the
5411: function \kbd{Set}.
5412:
5413: \syn{setisset}{x}, and this returns a \kbd{long}.
5414:
5415: \subsecidx{setminus}$(x,y)$: difference of the two sets $x$ and $y$,
5416: i.e.~set of elements of $x$ which do not belong to $y$.
5417:
5418: \syn{setminus}{x,y}.
5419:
5420: \subsecidx{setsearch}$(x,y,\{\fl=0\})$: searches if $y$ belongs to the set
5421: $x$. If it does and $\fl$ is zero or omitted, returns the index $j$ such that
5422: $x[j]=y$, otherwise returns 0. If $\fl$ is non-zero returns the index $j$
5423: where $y$ should be inserted, and $0$ if it already belongs to $x$ (this is
5424: meant to be used in conjunction with \kbd{listinsert}).
5425:
5426: This function works also if $x$ is a {\it sorted\/} list (see \kbd{listsort}).
5427:
5428: \syn{setsearch}{x,y,\fl} which returns a \kbd{long}
5429: integer.
5430:
5431: \subsecidx{setunion}$(x,y)$: union of the two sets $x$ and $y$.
5432:
5433: \syn{setunion}{x,y}.
5434:
5435: \subsecidx{trace}$(x)$: this applies to quite general $x$. If $x$ is not a
5436: matrix, it is equal to the sum of $x$ and its conjugate, except for polmods
5437: where it is the trace as an algebraic number.
5438:
5439: For $x$ a square matrix, it is the ordinary trace. If $x$ is a
5440: non-square matrix (but not a vector), an error occurs.
5441:
5442: \syn{gtrace}{x}.
5443:
5444: \subsecidx{vecextract}$(x,y,\{z\})$: extraction of components of the
5445: vector or matrix $x$ according to $y$. In case $x$ is a matrix, its
5446: components are as usual the {\it columns} of $x$. The parameter $y$ is a
5447: component specifier, which is either an integer, a string describing a
5448: range, or a vector.
5449:
5450: If $y$ is an integer, it is considered as a mask: the binary bits of $y$ are
5451: read from right to left, but correspond to taking the components from left to
5452: right. For example, if $y=13=(1101)_2$ then the components 1,3 and 4 are
5453: extracted.
5454:
5455: If $y$ is a vector, which must have integer entries, these entries correspond
5456: to the component numbers to be extracted, in the order specified.
5457:
5458: If $y$ is a string, it can be
5459:
5460: $\bullet$ a single (non-zero) index giving a component number (a negative
5461: index means we start counting from the end).
5462:
5463: $\bullet$ a range of the form \kbd{"$a$..$b$"}, where $a$ and $b$ are
5464: indexes as above. Any of $a$ and $b$ can be omitted; in this case, we take
5465: as default values $a = 1$ and $b = -1$, i.e.~ the first and last components
5466: respectively. We then extract all components in the interval $[a,b]$, in
5467: reverse order if $b < a$.
5468:
5469: In addition, if the first character in the string is \kbd{\pow}, the
5470: complement of the given set of indices is taken.
5471:
5472: If $z$ is not omitted, $x$ must be a matrix. $y$ is then the {\it line}
5473: specifier, and $z$ the {\it column} specifier, where the component specifier
5474: is as explained above.
5475:
5476: \bprog%
5477: ? v = [a, b, c, d, e];
5478: ? vecextract(v, 5) \bs\bs~mask
5479: \%1 = [a, c]
5480: ? vecextract(v, [4, 2, 1]) \bs\bs~component list
5481: \%2 = [d, b, a]
5482: ? vecextract(v, "2..4") \bs\bs~interval
5483: \%3 = [b, c, d]
5484: ? vecextract(v, "-1..-3") \bs\bs~interval + reverse order
5485: \%4 = [e, d, c]
5486: ? vecextract([1,2,3], "\pow2") \bs\bs~complement
5487: \%5 = [1, 3]
5488: ? vecextract(matid(3), "2..", "..")
5489: \%6 =
5490: [0 1 0]
5491: \smallskip%
5492: [0 0 1]
5493: \eprog
5494:
5495: \syn{extract}{x,y} or $\teb{matextract}(x,y,z)$.
5496:
5497: \subsecidx{vecsort}$(x,\{k\},\{\fl=0\})$: sorts the vector $x$ in ascending
5498: order, using the heapsort method. $x$ must be a vector, and its components
5499: integers, reals, or fractions.
5500:
5501: If $k$ is present and is an integer, sorts according to the value of the
5502: $k$-th subcomponents of the components of~$x$. $k$ can also be a vector,
5503: in which case the
5504: sorting is done lexicographically according to the components listed in the
5505: vector $k$. For example, if $k=[2,1,3]$, sorting will be done with respect
5506: to the second component, and when these are equal, with respect to the
5507: first, and when these are equal, with respect to the third.
5508:
5509: \noindent The binary digits of \fl\ mean:
5510:
5511: $\bullet$ 1: indirect sorting of the vector $x$, i.e.~if $x$ is an
5512: $n$-component vector, returns a permutation of $[1,2,\dots,n]$ which
5513: applied to the components of $x$ sorts $x$ in increasing order.
5514: For example, \kbd{vecextract(x, vecsort(x,,1))} is equivalent to
5515: \kbd{vecsort(x)}.
5516:
5517: $\bullet$ 2: sorts $x$ by ascending lexicographic order (as per the
5518: \kbd{lex} comparison function).
5519:
5520: \syn{vecsort0}{x,k,flag}. To omit $k$, use \kbd{NULL} instead. You can also
5521: use the simpler functions
5522:
5523: $\teb{sort}(x)$ (= $\kbd{vecsort0}(x,\text{NULL},0)$).
5524:
5525: $\teb{indexsort}(x)$ (= $\kbd{vecsort0}(x,\text{NULL},1)$).
5526:
5527: $\teb{lexsort}(x)$ (= $\kbd{vecsort0}(x,\text{NULL},2)$).
5528:
5529: Also available are \teb{sindexsort} and \teb{sindexlexsort} which return a
5530: vector (type \typ{VEC}) of C-long integers $v$, where $v[1]\dots v[n]$
5531: contain the indices. Note that the resulting $v$ is {\it not\/} a valid PARI
5532: object, but is in general easier to use in C programs!
5533:
5534: \section{Sums, products, integrals and similar functions}
5535:
5536: Although the GP calculator is programmable, it is useful to have
5537: preprogrammed a number of loops, including sums, products, and a certain
5538: number of recursions. Also, a number of functions from numerical analysis
5539: like numerical integration and summation of series will be described here.
5540:
5541: One of the parameters in these loops must be the control variable, hence a
5542: simple variable name. The last parameter can be any legal PARI expression,
5543: including of course expressions using loops. Since it is much easier to
5544: program directly the loops in library mode, these functions are mainly
5545: useful for GP programming. The use of these functions in library mode is a
5546: little tricky and its explanation will be mostly omitted, although the
5547: reader can try and figure it out by himself by checking the example given
5548: for the \tet{sum} function. In this section we only give the library
5549: syntax, with no semantic explanation.
5550:
5551: The letter $X$ will always denote any simple variable name, and represents
5552: the formal parameter used in the function.
5553:
5554: \misctitle{(numerical) integration}:\sidx{numerical integration} A number
5555: of Romberg-like integration methods are implemented (see \kbd{intnum} as
5556: opposed to \kbd{intformal} which we already described). The user should not
5557: require too much accuracy: 18 or 28 decimal digits is OK, but not much more.
5558: In addition, analytical cleanup of the integral must have been done: there
5559: must be no singularities in the interval or at the boundaries. In practice
5560: this can be accomplished with a simple change of variable. Furthermore, for
5561: improper integrals, where one or both of the limits of integration are plus
5562: or minus infinity, the function must decrease sufficiently rapidly at
5563: infinity. This can often be accomplished through integration by parts.
5564:
5565: Note that \idx{infinity} can be represented with essentially no loss of
5566: accuracy by 1e4000. However beware of real underflow when dealing with
5567: rapidly decreasing functions. For example, if one wants to compute the
5568: $\int_0^\infty e^{-x^2}\,dx$ to 28 decimal digits, then one should set
5569: infinity equal to 10 for example, and certainly not to 1e4000.
5570:
5571: The integrand may have values belonging to a vector space over the real
5572: numbers; in particular, it can be complex-valued or vector-valued.
5573:
5574: See also the discrete summation methods below (sharing the prefix \kbd{sum}).
5575:
5576: \subsecidx{intnum}$(X=a,b,\var{expr},\{\fl=0\})$: numerical integration of
5577: \var{expr} (smooth in $]a,b[$), with respect to $X$.
5578:
5579: Set $\fl=0$ (or omit it altogether) when $a$ and $b$ are not too large, the
5580: function is smooth, and can be evaluated exactly everywhere on the interval
5581: $[a,b]$.
5582:
5583: If $\fl=1$, uses a general driver routine for doing numerical integration,
5584: making no particular assumption (slow).
5585:
5586: $\fl=2$ is tailored for being used when $a$ or $b$ are infinite. One
5587: {\it must\/} have $ab>0$, and in fact if for example $b=+\infty$, then it is
5588: preferable to have $a$ as large as possible, at least $a\ge1$.
5589:
5590: If $\fl=3$, the function is allowed to be undefined (but continuous) at $a$
5591: or $b$, for example the function $\sin(x)/x$ at $x=0$.
5592:
5593: \synt{intnum0}{entree$\,$*e,GEN a,GEN b,char$\,$*expr,long \fl,long prec}.
5594:
5595: \subsecidx{matrix}$(m,n,\{X\},\{Y\},\{\var{expr}=0\})$: creation of the
5596: $m\times n$ matrix whose coefficients are given by the expression
5597: \var{expr}. There are two formal parameters in \var{expr}, the first one
5598: ($X$) corresponding to the rows, the second ($Y$) to the columns, and $X$
5599: goes from 1 to $m$, $Y$ goes from 1 to $n$. If one of the last 3 parameters
5600: is omitted, fill the matrix with zeroes.
5601:
5602: \synt{matrice}{GEN nlig,GEN ncol,entree *e1,entree *e2,char *expr}.
5603:
5604: \subsecidx{prod}$(X=a,b,\var{expr},\{x=1\})$: product of expression \var{expr},
5605: initialized at $x$, the formal parameter $X$ going from $a$ to $b$. As for
5606: \kbd{sum}, the main purpose of the initialization parameter $x$ is to force
5607: the type of the operations being performed. For example if it is set equal to
5608: the integer 1, operations will start being done exactly. If it is set equal
5609: to the real $1.$, they will be done using real numbers having the default
5610: precision. If it is set equal to the power series $1+O(X^k)$ for a certain
5611: $k$, they will be done using power series of precision at most $k$. These
5612: are the three most common initializations.
5613:
5614: \noindent As an extreme example, compare
5615:
5616: \bprog%
5617: ? prod(i=1, 100, 1-X\pow i); \bs\bs\ this has degree $5050$~!!
5618: \smallskip%
5619: time = 3,335 ms.
5620: \smallskip%
5621: ? prod(i=1, 100, 1-X\pow i, 1+O(X\pow 101))
5622: \smallskip%
5623: time = 43 ms.
5624: \smallskip%
5625: \%2 = 1 - X - X\pow 2 + X\pow 5 + X\pow 7 - X\pow 12 - X\pow 15 + X\pow 22 + X\pow 26 - X\pow 35 - X\pow 40 + X\pow 51
5626: + X\pow 57 - X\pow 70 - X\pow 77 + X\pow 92 + X\pow 100 + O(X\pow 101)%
5627: \eprog
5628:
5629: \synt{produit}{entree *ep, GEN a, GEN b, char *expr, GEN x}.
5630:
5631: \subsecidx{prodeuler}$(X=a,b,\var{expr})$: product of expression \var{expr},
5632: initialized at 1. (i.e.~to a {\it real\/} number equal to 1 to the current
5633: \kbd{realprecision}), the formal parameter $X$ ranging over the prime numbers
5634: between $a$ and $b$.\sidx{Euler product}
5635:
5636: \synt{prodeuler}{entree *ep, GEN a, GEN b, char *expr, long prec}.
5637:
5638: \subsecidx{prodinf}$(X=a,\var{expr},\{\fl=0\})$: \idx{infinite product} of
5639: expression \var{expr}, the formal parameter $X$ starting at $a$. The evaluation
5640: stops when the relative error of the expression minus 1 is less than the
5641: default precision. The expressions must always evaluate to an element of
5642: $\C$.
5643:
5644: If $\fl=1$, do the product of the ($1+\var{expr}$) instead.
5645:
5646: \synt{prodinf}{entree *ep, GEN a, char *expr, long prec} ($\fl=0$), or
5647: \teb{prodinf1} with the same arguments ($\fl=1$).
5648:
5649: \subsecidx{solve}$(X=a,b,\var{expr})$: find a real root of expression
5650: \var{expr} between $a$ and $b$, under the condition
5651: $\var{expr}(X=a)*\var{expr}(X=b)\le0$. This
5652: routine uses Brent's method. This can fail miserably if \var{expr} is not
5653: defined in the whole of $[a,b]$ (try \kbd{solve(x=1, 2, tan(x)}).
5654:
5655: \synt{zbrent}{entree *ep, GEN a, GEN b, char *expr, long prec}.
5656:
5657: \subsecidx{sum}$(X=a,b,\var{expr},\{x=0\})$: sum of expression \var{expr},
5658: initialized at $x$, the formal parameter going from $a$ to $b$. As for
5659: \kbd{prod}, the initialization parameter $x$ may be given to force the type
5660: of the operations being performed.
5661:
5662: \noindent As an extreme example, compare
5663:
5664: \bprog%
5665: ? sum(i=1, 5000, 1/i); \bs\bs rational number: denominator has $2166$ digits.
5666: \smallskip%
5667: time = 1,241 ms.
5668: \smallskip%
5669: ? sum(i=1, 5000, 1/i, 0.)
5670: \smallskip%
5671: time = 158 ms.
5672: \smallskip%
5673: \%2 = 9.094508852984436967261245533%
5674: \eprog
5675:
5676: \synt{somme}{entree *ep, GEN a, GEN b, char *expr, GEN x}. This is to be
5677: used as follows: \kbd{ep} represents the dummy variable used in the
5678: expression \kbd{expr}
5679: \bprog%
5680: /* compute a\pow 2 + \dots + b\pow 2 */
5681: \obr
5682: \q /* define the dummy variable "i" */
5683: \q entree *ep = gp\_variable("i");
5684: \q /* sum for a <= i <= b */
5685: \q return somme(ep, a, b, "i\pow2", gzero);
5686: \cbr
5687: \eprog
5688:
5689: \subsecidx{sumalt}$(X=a,\var{expr},\{\fl=0\})$: numerical summation of the
5690: series \var{expr}, which should be an \idx{alternating series}, the formal
5691: variable $X$ starting at $a$.
5692:
5693: If $\fl=0$, use an algorithm of F.~Villegas as modified by D.~Zagier. This
5694: is much better than \idx{Euler}-Van Wijngaarden's method which was used
5695: formerly.
5696: Beware that the stopping criterion is that the term gets small enough, hence
5697: terms which are equal to 0 will create problems and should be removed.
5698:
5699: If $\fl=1$, use a variant with slightly different polynomials. Sometimes
5700: faster.
5701:
5702: Divergent alternating series can sometimes be summed by this method, as well
5703: as series which are not exactly alternating (see for example
5704: \secref{se:user_defined}).
5705:
5706: \misctitle{Important hint:} a significant speed gain can be obtained by
5707: writing the $(-1)^X$ which may occur in the expression as
5708: \kbd{(1.~- X\%2*2)}.
5709:
5710: \synt{sumalt}{entree *ep, GEN a, char *expr, long \fl, long prec}.
5711:
5712: \subsecidx{sumdiv}$(n,X,\var{expr})$: sum of expression \var{expr} over
5713: the positive divisors of $n$.
5714:
5715: In the present version \vers, $n$ is restricted to being less than $2^{31}$.
5716:
5717: \synt{divsum}{entree *ep, GEN num, char *expr}.
5718:
5719: \subsecidx{suminf}$(X=a,\var{expr})$: \idx{infinite sum} of expression
5720: \var{expr}, the formal parameter $X$ starting at $a$. The evaluation stops
5721: when the relative error of the expression is less than the default precision.
5722: The expressions must always evaluate to a complex number.
5723:
5724: \synt{suminf}{entree *ep, GEN a, char *expr, long prec}.
5725:
5726: \subsecidx{sumpos}$(X=a,\var{expr},\{\fl=0\})$: numerical summation of the
5727: series \var{expr}, which must be a series of terms having the same sign,
5728: the formal
5729: variable $X$ starting at $a$. The algorithm used is Van Wijngaarden's trick
5730: for converting such a series into an alternating one, and is quite slow.
5731: Beware that the stopping criterion is that the term gets small enough, hence
5732: terms which are equal to 0 will create problems and should be removed.
5733:
5734: If $\fl=1$, use slightly different polynomials. Sometimes faster.
5735:
5736: \synt{sumpos}{entree *ep, GEN a, char *expr, long \fl, long prec}.
5737:
5738: \subsecidx{vector}$(n,\{X\},\{\var{expr}=0\})$: creates a row vector (type
5739: \typ{VEC}) with $n$ components whose components are the expression
5740: \var{expr} evaluated at the integer points between 1 and $n$. If one of the
5741: last two arguments is omitted, fill the vector with zeroes.
5742:
5743: \synt{vecteur}{GEN nmax, entree *ep, char *expr}.
5744:
5745: \subsecidx{vectorv}$(n,X,\var{expr})$: as \teb{vector}, but returns a
5746: column vector (type \typ{COL}).
5747:
5748: \synt{vvecteur}{GEN nmax, entree *ep, char *expr}.
5749:
5750: \section{Plotting functions}
5751:
5752: Although plotting is not even a side purpose of PARI, a number of plotting
5753: functions are provided. Moreover, a lot of people felt like suggesting
5754: ideas or submitting huge patches for this section of the code. Among these,
5755: special thanks go to Klaus-Peter Nischke who suggested the recursive plotting
5756: and the forking/resizing stuff under X11, and Ilya Zakharevich who
5757: undertook a complete rewrite of the graphic code, so that most of it is now
5758: platform-independent and should be relatively easy to port or expand.
5759:
5760: These graphic functions are either
5761:
5762: $\bullet$ high-level plotting functions (all the functions starting with
5763: \kbd{ploth}) in which the user has little to do but explain what type of plot
5764: he wants, and whose syntax is similar to the one used in the preceding
5765: section (with somewhat more complicated flags).
5766:
5767: $\bullet$ low-level plotting functions, where every drawing primitive (point,
5768: line, box, etc.) must be specified by the user. These low-level functions
5769: (called {\it rectplot} functions, sharing the prefix \kbd{plot}) work as
5770: follows. You have at your disposal 16 virtual windows which are filled
5771: independently, and can then be physically ORed on a single window at
5772: user-defined positions. These windows are numbered from 0 to 15, and must be
5773: initialized before being used by the function \kbd{plotinit}, which specifies
5774: the height and width of the virtual window (called a {\it rectwindow} in the
5775: sequel). At all times, a virtual cursor (initialized at $[0,0]$) is
5776: associated to the window, and its current value can be obtained using the
5777: function \kbd{plotcursor}.
5778:
5779: A number of primitive graphic objects (called {\it rect} objects) can then
5780: be drawn in these windows, using a default color associated to that window
5781: (which can be changed under X11, using the \kbd{plotcolor} function, black
5782: otherwise) and only the part of the object which is inside the window will be
5783: drawn, with the exception of polygons and strings which are drawn entirely
5784: (but the virtual cursor can move outside of the window). The ones sharing the
5785: prefix \kbd{plotr} draw relatively to the current position of the virtual
5786: cursor, the others use absolute coordinates. Those having the prefix
5787: \kbd{plotrecth} put in the rectwindow a large batch of rect objects
5788: corresponding to the output of the related \kbd{ploth} function.
5789:
5790: Finally, the actual physical drawing is done using the function
5791: \kbd{plotdraw}. Note that the windows are preserved so that further drawings
5792: using the same windows at different positions or different windows can be
5793: done without extra work. If you want to erase a window (and free the
5794: corresponding memory), use the function \kbd{plotkill}. It is not possible to
5795: partially erase a window. Erase it completely, initialize it again and then
5796: fill it with the graphic objects that you want to keep.
5797:
5798: In addition to initializing the window, you may want to have a scaled
5799: window to avoid unnecessary conversions. For this, use the function
5800: \kbd{plotscale} below. As long as this function is not called, the scaling is
5801: simply the number of pixels, the origin being at the upper left and the
5802: $y$-coordinates going downwards.
5803:
5804: Note that in the present version \vers{} all these plotting functions
5805: (both low and high level) have been written for the X11-window system (hence
5806: also for GUI's based on X11 such as Openwindows and Motif), and for
5807: Sunview/Suntools only, though very little code remains which is actually
5808: platform-dependent. A Macintosh, and an Atari/Gem port were provided for
5809: previous versions. These {\it may} be adapted in future releases.
5810:
5811: Under X11/Suntools, the physical window (opened by \kbd{plotdraw} or any
5812: of the \kbd{ploth*} functions) is completely separated from GP (technically,
5813: a \kbd{fork} is done, and the non-graphical memory is immediately freed in
5814: the child process), which means you can go on working in the current GP
5815: session, without having to kill the window first. Under X11, this window can
5816: be closed, enlarged or reduced using the standard window manager functions.
5817: No zooming procedure is implemented though (yet).
5818:
5819: $\bullet$ Finally, note that in the same way that \kbd{printtex} allows you
5820: to have a \TeX{} output corresponding to printed results, the functions
5821: starting with \kbd{ps} allow you to have \tet{PostScript} output of the
5822: plots. This will not be absolutely identical with the screen output, but will
5823: be sufficiently close. Note that you can use PostScript output even if you do
5824: not have the plotting routines enabled. The PostScript output is written in a
5825: file whose name is derived from the \tet{psfile} default (\kbd{./pari.ps} if
5826: you did not tamper with it). Each time a new PostScript output is asked for,
5827: the PostScript output is appended to that file. Hence the user must remove
5828: this file, or change the value of \kbd{psfile}, first if he does not want
5829: unnecessary drawings from preceding sessions to appear. On the other hand, in
5830: this manner as many plots as desired can be kept in a single file. \smallskip
5831:
5832: {\it None of the graphic functions are available within the PARI library, you
5833: must be under GP to use them}. The reason for that is that you really should
5834: not use PARI for heavy-duty graphical work, there are much better specialized
5835: alternatives around. This whole set of routines was only meant as a
5836: convenient, but simple-minded, visual aid. If you really insist on using
5837: these in your program (we warned you), the source (\kbd{plot*.c}) should be
5838: readable enough for you to achieve something.
5839:
5840: \subsecidx{plot}$(X=a,b,\var{expr})$: crude (ASCII) plot of the function
5841: represented by expression \var{expr} from $a$ to $b$.
5842:
5843: \subsecidx{plotbox}$(w,x2,y2)$: let $(x1,y1)$ be the current position of the
5844: virtual cursor. Draw in the rectwindow $w$ the outline of the rectangle which
5845: is such that the points $(x1,y1)$ and $(x2,y2)$ are opposite corners. Only
5846: the part of the rectangle which is in $w$ is drawn. The virtual cursor does
5847: {\it not\/} move.
5848:
5849: \subsecidx{plotclip}$(w)$: `clips' the content of rectwindow $w$, i.e
5850: remove all parts of the drawing that would not be visible on the screen.
5851: Together with \tet{plotcopy} this function enables you to draw on a
5852: scratchpad before commiting the part you're interested in to the final
5853: picture.
5854:
5855: \subsecidx{plotcolor}$(w,c)$: set default color to $c$ in rectwindow $w$.
5856: In present version \vers, this is only implemented for X11 window system,
5857: and you only have the following palette to choose from:
5858:
5859: 1=black, 2=blue, 3=sienna, 4=red, 5=cornsilk, 6=grey, 7=gainsborough.
5860:
5861: Note that it should be fairly easy for you to hardwire some more colors by
5862: tweaking the files \kbd{rect.h} and \kbd{plotX.c}. User-defined
5863: colormaps would be nice, and {\it may\/} be available in future versions.
5864:
5865: \subsecidx{plotcopy}$(w1,w2,dx,dy)$: copy the contents of rectwindow
5866: $w1$ to rectwindow $w2$, with offset $(dx,dy)$.
5867:
5868: \subsecidx{plotcursor}$(w)$: give as a 2-component vector the current
5869: (scaled) position of the virtual cursor corresponding to the rectwindow $w$.
5870:
5871: \subsecidx{plotdraw}$(list)$: physically draw the rectwindows given in $list$
5872: which must be a vector whose number of components is divisible by 3. If
5873: $list=[w1,x1,y1,w2,x2,y2,\dots]$, the windows $w1$, $w2$, etc.~are
5874: physically placed with their upper left corner at physical position
5875: $(x1,y1)$, $(x2,y2)$,\dots\ respectively, and are then drawn together.
5876: Overlapping regions will thus be drawn twice, and the windows are considered
5877: transparent. Then display the whole drawing in a special window on your
5878: screen.
5879:
5880: \subsecidx{plotfile}$(s)$: set the output file for plotting output. Special
5881: filename \kbd{-} redirects to the same place as PARI output.
5882:
5883: \subsecidx{ploth}$(X=a,b,\var{expr},\{\fl=0\},\{n=0\})$: high precision
5884: plot of the function $y=f(x)$ represented by the expression \var{expr}, $x$
5885: going from $a$ to $b$. This opens a specific window (which is killed
5886: whenever you click on it), and returns a four-component vector giving the
5887: coordinates of the bounding box in the form
5888: $[\var{xmin},\var{xmax},\var{ymin},\var{ymax}]$.
5889:
5890: \misctitle{Important note}: Since this may involve a lot of function calls,
5891: it is advised to keep the current precision to a minimum (e.g.~9) before
5892: calling this function.
5893:
5894: $n$ specifies the number of reference point on the graph (0 means use the
5895: hardwired default values, that is: 1000 for general plot, 1500 for
5896: parametric plot, and 15 for recursive plot).
5897:
5898: If no $\fl$ is given, \var{expr} is either a scalar expression $f(X)$, in which
5899: case the plane curve $y=f(X)$ will be drawn, or a vector
5900: $[f_1(X),\dots,f_k(X)]$, and then all the curves $y=f_i(X)$ will be drawn in
5901: the same window.
5902:
5903: \noindent The binary digits of $\fl$ mean:
5904:
5905: $\bullet$ 1: {\it \idx{parametric plot}}. Here \var{expr} must be a vector with
5906: an even number of components. Successive pairs are then understood as the
5907: parametric coordinates of a plane curve. Each of these are then drawn.
5908:
5909: For instance:
5910:
5911: \kbd{ploth(X=0,2*Pi,[sin(X),cos(X)],1)} will draw a circle.
5912:
5913: \kbd{ploth(X=0,2*Pi,[sin(X),cos(X)])} will draw two entwined sinusoidal
5914: curves.
5915:
5916: \kbd{ploth(X=0,2*Pi,[X,X,sin(X),cos(X)],1)} will draw a circle and the line
5917: $y=x$.
5918:
5919:
5920: $\bullet$ 2: {\it \idx{recursive plot}}. If this flag is set, only {\it
5921: one\/} curve can be drawn at time, i.e.~\var{expr} must be either a
5922: two-component vector (for a single parametric curve, and the parametric flag
5923: {\it has\/} to be set), or a scalar function. The idea is to choose pairs of
5924: successive reference points, and if their middle point is not too far away
5925: from the segment joining them, draw this as a local approximation to the
5926: curve. Otherwise, add the middle point to the reference points. This is very
5927: fast, and usually more precise than usual plot. Compare the results of
5928: $$\kbd{ploth(X=-1,1,sin(1/X),2)}\quad
5929: \text{and}\quad\kbd{ploth(X=-1,1,sin(1/X))}$$
5930: for instance. But beware that if you are extremely unlucky, or choose too few
5931: reference points, you may draw some nice polygon bearing little resemblance
5932: to the original curve. For instance you should {\it never\/} plot recursively
5933: an odd function in a symmetric interval around 0. Try
5934: \bprog%
5935: ploth(x = -20, 20, sin(x), 2)
5936: \eprog
5937: \noindent to see why. Hence, it's usually a good idea to try and plot the same
5938: curve with slightly different parameters.
5939:
5940: $\bullet$ 8: do not print the $x$-axis.
5941:
5942: $\bullet$ 16: do not print the $y$-axis.
5943:
5944: $\bullet$ 32: do not print frame.
5945:
5946: $\bullet$ 64: only plot reference points, do not join them.
5947:
5948: \subsecidx{plothraw}$(\var{listx},\var{listy},\{\fl=0\})$: given
5949: \var{listx} and \var{listy} two vectors of equal length, plots (in high
5950: precision) the points whose $(x,y)$-coordinates are given in \var{listx}
5951: and \var{listy}. Automatic positioning and scaling is done, but with the
5952: same scaling factor on $x$ and $y$. If $\fl$ is non-zero, join points.
5953:
5954: \subsecidx{plothsizes}$()$: return data corresponding to the output window
5955: in the form of a 6-component vector: window width and height, sizes for ticks
5956: in horizontal and vertical directions (this is intended for the \kbd{gnuplot}
5957: interface and is currently not significant), width and height of characters.
5958:
5959: \subsecidx{plotinit}$(w,x,y)$: initialize the rectwindow $w$ to width $x$ and
5960: height $y$, and position the virtual cursor at $(0,0)$. This destroys any rect
5961: objects you may have already drawn in $w$.
5962:
5963: The plotting device imposes an upper bound for $x$ and $y$, for instance the
5964: number of pixels for screen output. These bounds are available through the
5965: \tet{plothsizes} function. The following sequence initializes in a portable way
5966: (i.e independant of the output device) a window of maximal size, accessed through
5967: coordinates in the $[0,1000] \times [0,1000]$ range~:
5968:
5969: \bprog%
5970: s = plothsizes();
5971: plotinit(0, s[1]-1, s[2]-1);
5972: plotscale(0, 0,1000, 0,1000);
5973: \eprog
5974:
5975: \subsecidx{plotkill}$(w)$: erase rectwindow $w$ and free the corresponding
5976: memory. Note that if you want to use the rectwindow $w$ again, you have to
5977: use \kbd{initrect} first to specify the new size. So it's better in this case
5978: to use \kbd{initrect} directly as this throws away any previous work in the
5979: given rectwindow.
5980:
5981: \subsecidx{plotlines}$(w,X,Y,\{\fl=0\})$: draw on the rectwindow $w$
5982: the polygon such that the (x,y)-coordinates of the vertices are in the
5983: vectors of equal length $X$ and $Y$. For simplicity, the whole
5984: polygon is drawn, not only the part of the polygon which is inside the
5985: rectwindow. If $\fl$ is non-zero, close the polygon. In any case, the
5986: virtual cursor does not move.
5987:
5988: $X$ and $Y$ are allowed to be scalars (in this case, both have to).
5989: There, a single segment will be drawn, between the virtual cursor current
5990: position and the point $(X,Y)$. And only the part thereof which
5991: actually lies within the boundary of $w$. Then {\it move} the virtual cursor
5992: to $(X,Y)$, even if it is outside the window. If you want to draw a
5993: line from $(x1,y1)$ to $(x2,y2)$ where $(x1,y1)$ is not necessarily the
5994: position of the virtual cursor, use \kbd{plotmove(w,x1,y1)} before using this
5995: function.
5996:
5997: \subsecidx{plotlinetype}$(w,\var{type})$: this is intended for the
5998: \kbd{gnuplot} interface and is currently not significant.
5999:
6000: \subsecidx{plotmove}$(w,x,y)$: move the virtual cursor of the rectwindow $w$
6001: to position $(x,y)$.
6002:
6003: \subsecidx{plotpoints}$(w,X,Y)$: draw on the rectwindow $w$ the
6004: points whose $(x,y)$-coordinates are in the vectors of equal length $X$ and
6005: $Y$ and which are inside $w$. The virtual cursor does {\it not\/} move. This
6006: is basically the same function as \kbd{plothraw}, but either with no scaling
6007: factor or with a scale chosen using the function \kbd{plotscale}.
6008:
6009: As was the case with the \kbd{plotlines} function, $X$ and $Y$ are allowed to
6010: be (simultaneously) scalar. In this case, draw the single point $(X,Y)$ on
6011: the rectwindow $w$ (if it is actually inside $w$), and in any case
6012: {\it move\/} the virtual cursor to position $(x,y)$.
6013:
6014: \subsecidx{plotpointsize}$(w,size)$: changes the ``size'' of following
6015: points in rectwindow $w$. If $w = -1$, change it in all rectwindows.
6016: This only works in the \kbd{gnuplot} interface.
6017:
6018: \subsecidx{plotpointtype}$(w,\var{type})$: this is intended for the
6019: \kbd{gnuplot} interface and is currently not significant.
6020:
6021: \subsecidx{plotrbox}$(w,dx,dy)$: draw in the rectwindow $w$ the outline of
6022: the rectangle which is such that the points $(x1,y1)$ and $(x1+dx,y1+dy)$ are
6023: opposite corners, where $(x1,y1)$ is the current position of the cursor.
6024: Only the part of the rectangle which is in $w$ is drawn. The virtual cursor
6025: does {\it not\/} move.
6026:
6027: \subsecidx{plotrecth}$(w,X=a,b,\var{expr},\{\fl=0\},\{n=0\})$: writes to
6028: rectwindow $w$ the curve output of \kbd{ploth}$(w,X=a,b,\var{expr},\fl,n)$.
6029:
6030: \subsecidx{plotrecthraw}$(w,\var{data},\{\fl=0\})$: plot graph(s) for
6031: \var{data} in rectwindow $w$. $\fl$ has the same significance here as in
6032: \kbd{ploth}, though recursive plot is no more significant.
6033:
6034: \var{data} is a vector of vectors, each corresponding to a list a coordinates.
6035: If parametric plot is set, there must be an even number of vectors, each
6036: successive pair corresponding to a curve. Otherwise, the first one containe
6037: the $x$ coordinates, and the other ones contain the $y$-coordinates
6038: of curves to plot.
6039:
6040: \subsecidx{plotrline}$(w,dx,dy)$: draw in the rectwindow $w$ the part of the
6041: segment $(x1,y1)-(x1+dx,y1+dy)$ which is inside $w$, where $(x1,y1)$ is the
6042: current position of the virtual cursor, and move the virtual cursor to
6043: $(x1+dx,y1+dy)$ (even if it is outside the window).
6044:
6045: \subsecidx{plotrmove}$(w,dx,dy)$: move the virtual cursor of the rectwindow
6046: $w$ to position $(x1+dx,y1+dy)$, where $(x1,y1)$ is the initial position of
6047: the cursor (i.e.~to position $(dx,dy)$ relative to the initial cursor).
6048:
6049: \subsecidx{plotrpoint}$(w,dx,dy)$: draw the point $(x1+dx,y1+dy)$ on the
6050: rectwindow $w$ (if it is inside $w$), where $(x1,y1)$ is the current position
6051: of the cursor, and in any case move the virtual cursor to position
6052: $(x1+dx,y1+dy)$.
6053:
6054: \subsecidx{plotscale}$(w,x1,x2,y1,y2)$: scale the local coordinates of the
6055: rectwindow $w$ so that $x$ goes from $x1$ to $x2$ and $y$ goes from $y1$ to
6056: $y2$ ($x2<x1$ and $y2<y1$ being allowed). Initially, after the initialization
6057: of the rectwindow $w$ using the function \kbd{plotinit}, the default scaling
6058: is the graphic pixel count, and in particular the $y$ axis is oriented
6059: downwards since the origin is at the upper left. The function \kbd{plotscale}
6060: allows to change all these defaults and should be used whenever functions are
6061: graphed.
6062:
6063: \subsecidx{plotstring}$(w,x)$: draw on the rectwindow $w$ the String $x$ (see
6064: Section 2.4), at the current position of the cursor.
6065:
6066: \subsecidx{plotterm}$(\var{type})$: this is intended for the \kbd{gnuplot}
6067: interface and is currently not significant.
6068:
6069: \subsecidx{psdraw}$(\var{list})$: same as \kbd{plotdraw}, except that the
6070: output is a PostScript program appended to the \kbd{psfile}.
6071:
6072: \subsecidx{psploth}$(X=a,b,\var{expr})$: same as \kbd{ploth}, except that the
6073: output is a PostScript program appended to the \kbd{psfile}.
6074:
6075: \subsecidx{psplothraw}$(\var{listx},\var{listy})$: same as \kbd{plothraw},
6076: except that the output is a PostScript program appended to the \kbd{psfile}.
6077:
6078: \section{Programming under GP}
6079: \sidx{programming}\label{se:programming}
6080: \subsecidx{Control statements}.
6081:
6082: A number of control statements are available under GP. They are simpler and
6083: have a syntax slightly different from their C counterparts, but are quite
6084: powerful enough to write any kind of program. Some of them are specific to
6085: GP, since they are made for number theorists. As usual, $X$ will denote any
6086: simple variable name, and \var{seq} will always denote a sequence of
6087: expressions, including the empty sequence.
6088:
6089: \subsubsecidx{break}$(\{n=1\})$: interrupts execution of current \var{seq}, and
6090: immediately exits from the $n$ innermost enclosing loops, within the
6091: current function call (or the top level loop). $n$ must be bigger than 1.
6092: If $n$ is greater than the number of enclosing loops, all enclosing loops
6093: are exited.
6094:
6095: \subsubsecidx{for}$(X=a,b,\var{seq})$: the formal variable $X$ going from
6096: $a$ to $b$, the \var{seq} is evaluated. Nothing is done if $a>b$.
6097: $a$ and $b$ must be in $\R$.
6098:
6099: \subsubsecidx{fordiv}$(n,X,\var{seq})$: the formal variable $X$ ranging
6100: through the positive divisors of $n$, the sequence \var{seq} is evaluated.
6101: $n$ must be of type integer.
6102:
6103: \subsubsecidx{forprime}$(X=a,b,\var{seq})$: the formal variable $X$
6104: ranging over the prime numbers between $a$ to $b$ (including $a$ and $b$
6105: if they are prime), the \var{seq} is evaluated. Nothing is done if $a>b$.
6106: Note that $a$ and $b$ must be in $\R$.
6107:
6108: \subsubsecidx{forstep}$(X=a,b,s,\var{seq})$: the formal variable $X$
6109: going from $a$ to $b$, in increments of $s$, the \var{seq} is evaluated.
6110: Nothing is done if $s>0$ and $a>b$ or if $s<0$ and $a<b$. $s$ must be in
6111: $\R^*$ or a vector of steps $[s_1,\dots,s_n]$. In the latter case, the
6112: successive steps are used in the order they appear in $s$.
6113:
6114: \bprog%
6115: ? forstep(x=5, 20, [2,4], print(x))
6116: 5
6117: 7
6118: 11
6119: 13
6120: 17
6121: 19
6122: \eprog
6123:
6124: \subsubsecidx{forsubgroup}$(H=G,\{B\},\var{seq})$: executes \var{seq} for
6125: each subgroup $H$ of the {\it abelian} group $G$ (given in
6126: SNF\sidx{Smith normal form} form or as a vector of elementary divisors),
6127: whose index is bounded by bound. The subgroups are not ordered in any
6128: obvious way, unless $G$ is a $p$-group in which case Birkhoff's algorithm
6129: produces them by decreasing index. A \idx{subgroup} is given as a matrix
6130: whose columns give its generators on the implicit generators of $G$. For
6131: example, the following prints all subgroups of index less than 2 in $G =
6132: \Z/2\Z g_1 \times \Z/2\Z g_2$~:
6133:
6134: \bprog%
6135: ? G = [2,2]; forsubgroup(H=G, 2, print(H))
6136: [1; 1]
6137: [1; 2]
6138: [2; 1]
6139: [1, 0; 1, 1]
6140: \eprog
6141: The last one, for instance is generated by $(g_1, g_1 + g_2)$. This
6142: routine is intended to treat huge groups, when \teb{subgrouplist} is not an
6143: option due to the sheer size of the output.
6144:
6145: For maximal speed the subgroups have been left as produced by the algorithm.
6146: To print them in canonical form (as left divisors of $G$ in
6147: HNF\sidx{Hermite normal form} form), one can for instance use
6148: \bprog%
6149: ? G = matdiagonal([2,2]); forsubgroup(H=G, 2, print(mathnf(concat(G,H))))
6150: [2, 1; 0, 1]
6151: [1, 0; 0, 2]
6152: [2, 0; 0, 1]
6153: [1, 0; 0, 1]
6154: \eprog
6155: Note that in this last representation, the index $[G:H]$ is given by the
6156: determinant.
6157:
6158: \subsubsecidx{forvec}$(X=v,\var{seq},\{\fl=0\})$: $v$ being an $n$-component
6159: vector (where $n$ is arbitrary) of two-component vectors $[a_i,b_i]$
6160: for $1\le i\le n$, the \var{seq} is evaluated with the formal variable
6161: $X[1]$ going from $a_1$ to $b_1$,\dots,$X[n]$ going from $a_n$ to $b_n$.
6162: The formal variable with the highest index moves the fastest. If $\fl=1$,
6163: generate only nondecreasing vectors $X$, and if $\fl=2$, generate only
6164: strictly increasing vectors $X$.
6165:
6166: \subsubsecidx{if}$(a,\{\var{seq1}\},\{\var{seq2}\})$: if $a$ is non-zero,
6167: the expression sequence \var{seq1} is evaluated, otherwise the expression
6168: \var{seq2} is evaluated. Of course, \var{seq1} or \var{seq2} may be empty,
6169: so \kbd{if ($a$,\var{seq})} evaluates \var{seq} if $a$ is not equal to zero
6170: (you don't have to write the second comma), and does nothing otherwise,
6171: whereas \kbd{if ($a$,,\var{seq})} evaluates \var{seq} if $a$ is equal to
6172: zero, and does nothing otherwise. You could get the same result using
6173: the \kbd{!} (\kbd{not}) operator: \kbd{if (!$a$,\var{seq})}.
6174:
6175: Note that the boolean operators \kbd{\&\&} and \kbd{||} are evaluated
6176: according to operator precedence as explained in \secref{se:operators}, but
6177: that, contrary to other operators, the evaluation of the arguments is
6178: stopped as soon as the final truth value has been determined. For instance
6179: \bprog%
6180: if (reallydoit \&\& longcomplicatedfunction(), $\dots$)%
6181: \eprog
6182: \noindent is a perfectly safe statement.
6183:
6184: Recall that functions such as \kbd{break} and \kbd{next} operate on
6185: {\it loops\/} (such as \kbd{for$xxx$}, \kbd{while}, \kbd{until}). The \kbd{if}
6186: statement is {\it not\/} a loop (obviously!).
6187:
6188: \subsubsecidx{next}$(\{n=1\})$: interrupts execution of current $seq$,
6189: resume the next iteration of the innermost enclosing loop, within the
6190: current fonction call (or top level loop). If $n$ is specified, resume at
6191: the $n$-th enclosing loop. If $n$ is bigger than the number of enclosing
6192: loops, all enclosing loops are exited.
6193:
6194: \subsubsecidx{return}$(\{x=0\})$: returns from current subroutine, with
6195: result $x$.
6196:
6197: \subsubsecidx{until}$(a,\var{seq})$: evaluates expression sequence \var{seq}
6198: until $a$ is not equal to 0 (i.e.~until $a$ is true). If $a$ is initially
6199: not equal to 0, \var{seq} is evaluated once (more generally, the condition
6200: on $a$ is tested {\it after\/} execution of the \var{seq}, not before as in
6201: \kbd{while}).
6202:
6203: \subsubsecidx{while}$(a,\var{seq})$: while $a$ is non-zero evaluate the
6204: expression sequence \var{seq}. The test is made {\it before\/} evaluating
6205: the $seq$, hence in particular if $a$ is initially equal to zero the
6206: \var{seq} will not be evaluated at all.\smallskip
6207:
6208: \subsec{Specific functions used in GP programming}.
6209: \label{se:gp_program}
6210:
6211: In addition to the general PARI functions, it is necessary to have some
6212: functions which will be of use specifically for GP, though a few of these can
6213: be accessed under library mode. Before we start describing these, we recall
6214: the difference between {\it strings\/} and {\it keywords\/} (see
6215: \secref{se:strings}): the latter don't get expanded at all, and you can type
6216: them without any enclosing quotes. The former are dynamic objects, where
6217: everything outside quotes gets immediately expanded.
6218:
6219: We need an additional notation for this chapter. An argument between braces,
6220: followed by a star, like $\{\var{str}\}*$, means that any number of such
6221: arguments (possibly none) can be given.
6222:
6223: \subsubsecidx{addhelp}$(S,\var{str})$:\label{se:addhelp} changes the help
6224: message for the symbol $S$. The string \var{str} is expanded on the spot
6225: and stored as the online help for $S$. If $S$ is a function {\it you\/} have
6226: defined, its definition will still be printed before the message \var{str}.
6227: It is recommended that you document global variables and user functions in
6228: this way. Of course GP won't protest if you don't do it.
6229:
6230: There's nothing to prevent you from modifying the help of built-in PARI
6231: functions (but if you do, we'd like to hear why you needed to do it!).
6232:
6233: \subsubsecidx{alias}$(\var{newkey},\var{key})$: defines the keyword
6234: \var{newkey} as an alias for keyword \var{key}. \var{key} must correspond
6235: to an existing {\it function\/} name.
6236: This is different from the general user macros in that alias expansion takes
6237: place immediately upon execution, without having to look up any function
6238: code, and is thus much faster. A sample alias file \kbd{misc/gpalias} is
6239: provided with the standard distribution. Alias commands are meant to be read
6240: upon startup from the \kbd{.gprc} file, to cope with function names you are
6241: dissatisfied with, and should be useless in interactive usage.
6242:
6243: \subsubsecidx{allocatemem}$(\{x=0\})$: this is a very special operation which
6244: allows the user to change the stack size {\it after\/} initialization. $x$
6245: must be a non-negative integer. If $x!=0$, a new stack of size $16*\lceil
6246: x/16\rceil$ bytes will be allocated, all the PARI data on the old stack will
6247: be moved to the new one, and the old stack will be discarded. If $x=0$, the
6248: size of the new stack will be twice the size of the old one.
6249:
6250: Although it is a function, this must be the {\it last\/} instruction in any GP
6251: sequence. The technical reason is that this routine usually moves the stack,
6252: so objects from the current sequence might not be correct anymore. Hence, to
6253: prevent such problems, this routine terminates by a \kbd{longjmp} (just as an
6254: error would) and not by a return.
6255:
6256: \syn{allocatemoremem}{x}, where $x$ is an unsigned long, and the return type
6257: is void. GP uses a variant which ends by a \kbd{longjmp}.
6258:
6259: \subsubsecidx{default}$(\{\var{key}\},\{\var{val}\},\{\fl\})$: sets the default
6260: corresponding to keyword \var{key} to value \var{val}. \var{val} is a string
6261: (which of course accepts numeric arguments without adverse effects, due to the
6262: expansion mechanism). See \secref{se:defaults} for a list of available
6263: defaults, and \secref{se:meta} for some shortcut alternatives.
6264: \label{se:default}
6265:
6266: If \var{val} is omitted, prints the current value of default \var{key}.
6267: If \var{key} is omitted, prints the current values of all the defaults.
6268: If $\fl$ is set, returns the result instead of printing it.
6269:
6270: \subsubsecidx{error}$(\{\var{str}\}*)$: outputs its argument list (each of them
6271: interpreted as a string), then interrupts the running GP program, returning to
6272: the input prompt.
6273:
6274: Example: \kbd{error("n = ", n, " is not squarefree !")}.
6275:
6276: Note that, due to the automatic concatenation of strings, you could in fact
6277: use only one argument, just by suppressing the commas.
6278:
6279: \subsubsecidxunix{extern}$(\var{str})$: the string \var{str} is the name
6280: of an external command (i.e.~one you would type from your UNIX shell prompt).
6281: This command is immediately run and its input fed into GP, just as if read
6282: from a file.
6283:
6284: \subsubsecidx{getheap}$()$: returns a two-component row vector giving the
6285: number of objects on the heap and the amount of memory they occupy in long
6286: words. Useful mainly for debugging purposes.
6287:
6288: \syn{getheap}{}.
6289:
6290: \subsubsecidx{getrand}$()$: returns the current value of the random number
6291: seed. Useful mainly for debugging purposes.
6292:
6293: \syn{getrand}{}, returns a C long.
6294:
6295: \subsubsecidx{getstack}$()$: returns the current value of
6296: \kbd{top${}-{}$avma},
6297: i.e.~the number of bytes used up to now on the stack. Should be equal to 0
6298: in between commands. Useful mainly for debugging purposes.
6299:
6300: \syn{getstack}{}, returns a C long.
6301:
6302: \subsubsecidx{gettime}$()$: returns the time (in milliseconds) elapsed since
6303: either the last call to \kbd{gettime}, or to the beginning of the containing
6304: GP instruction (if inside GP), whichever came last.
6305:
6306: \syn{gettime}{}, returns a C long.
6307:
6308: \subsubsecidx{global}$(\{\hbox{\it list of variables}\})$: \label{se:global}
6309: declares the corresponding variables to be global. From now on, you will be
6310: forbidden to use them as formal parameters for function definitions or as
6311: loop indexes. This is especially useful when patching together various
6312: scripts, possibly written with different naming conventions. For instance the
6313: following situation is dangerous:
6314: %
6315: \bprog%
6316: p = 3 \bs\bs~fix characteristic
6317: ...
6318: forprime(p = 2, N, ...)
6319: f(p) = ...
6320: \eprog
6321: since within the loop or within the function's body, the true global value of
6322: \kbd{p} will be hidden. If the statement \kbd{global(p = 3)} appears at the
6323: beginning of the script, then both expressions will trigger syntax errors.
6324:
6325: Calling \kbd{global} without arguments prints the list of global variables in
6326: use. In particular, \kbd{eval(global)} will output the values of all local
6327: variables.
6328:
6329: \subsubsecidx{input}$()$: reads a string, interpreted as a GP expression,
6330: from the input file, usually standard input (i.e.~the keyboard). If a
6331: sequence of expressions is given, the result is the result of the last
6332: expression of the sequence. When using this instruction, it is useful to
6333: prompt for the string by using the \kbd{print1} function. Note that in the
6334: present version 2.19 of \kbd{pari.el}, when using GP under GNU Emacs (see
6335: \secref{se:emacs}) one {\it must\/} prompt for the string, with a string
6336: which ends with the same prompt as any of the previous ones (a \kbd{"? "}
6337: will do for instance).
6338:
6339: \subsubsecidxunix{install}$(\var{name},\var{code},\{\var{gpname}\},\{\var{lib}\})$:
6340: loads from dynamic library \var{lib} the function \var{name}. Assigns to it
6341: the name \var{gpname} in this GP session, with argument code \var{code} (see
6342: \secref{se:gp.interface} for an explanation of those). If \var{lib} is
6343: omitted, uses \kbd{libpari.so}. If \var{gpname} is omitted, uses
6344: \var{name}.\label{se:install}
6345:
6346: This function is useful for adding custom functions to the GP interpreter.
6347: But it also gives you access to all (non static) functions defined in the
6348: PARI library. For instance, the function \kbd{GEN addii(GEN x, GEN y)} adds
6349: two PARI integers, and is not directly accessible under GP (it's eventually
6350: called by the \kbd{+} operator of course):
6351:
6352: \bprog%
6353: ? install("addii", "GG")
6354: ? addii(1, 2)
6355: \%1 = 3%
6356: \eprog
6357:
6358: \misctitle{Caution:} This function may not work on all systems, especially
6359: when GP has been compiled statically. In that case, the first use of an
6360: installed function will provoke a Segmentation Fault, i.e.~a major internal
6361: blunder (this should never happen with a dynamically linked executable). This
6362: {\it used\/} to be the fate of statically linked gp on \kbd{Linux} and
6363: \kbd{OSF1} up to and including version 2.0.3.
6364:
6365: Hence, if you intend to use this function, please check first on some
6366: harmless example such as the one above that it works properly on your
6367: machine.
6368:
6369: \subsubsecidx{kill}$(x)$:\label{se:kill} kills the present value of the
6370: variable, alias or user-defined function $x$ (you can only kill your own
6371: functions). The corresponding identifier can now be used to name any GP
6372: object (variable or function). This is the only way to replace a variable by
6373: a function having the same name (or the other way round), as in the following
6374: example:
6375:
6376: \bprog%
6377: ? f = 1
6378: \%1 = 1
6379: ? f(x) = 0
6380: \ \ ***\ \ \ unused characters:~f(x)=0
6381: \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \pow----
6382: ? kill(f)
6383: ? f(x) = 0
6384: ? f()
6385: \%2 = 0%
6386: \eprog
6387:
6388: When you kill a variable, all objects that used it become invalid. You
6389: can still display them, even though the killed variable will be printed in a
6390: funny way (following the same convention as used by the library function
6391: \kbd{fetch\_var}, see~\secref{se:vars}). For example:
6392:
6393: \bprog%
6394: ? a\pow 2 + 1
6395: \%1 = a\pow2 + 1
6396: ? kill(a)
6397: ? \%1
6398: \%2 = \#<1>\pow2 + 1%
6399: \eprog
6400:
6401: If you simply want to restore a variable to its original value (monomial of
6402: degree one), use the \idx{quote} operator: \kbd{x = 'x}.
6403:
6404: \subsubsecidx{print}$(\{\var{str}\}*)$: outputs its (string) arguments in raw
6405: format, ending with a newline.
6406:
6407: \subsubsecidx{print1}$(\{\var{str}\}*)$: outputs its (string) arguments in raw
6408: format, without ending with a newline (note that you can still embed newlines
6409: within your strings, using the \b{n} notation~!).
6410:
6411: \subsubsecidx{printp}$(\{\var{str}\}*)$: outputs its (string) arguments in
6412: prettyprint (beautified) format, ending with a newline.
6413:
6414: \subsubsecidx{printp1}$(\{\var{str}\}*)$: outputs its (string) arguments in
6415: prettyprint (beautified) format, without ending with a newline.
6416:
6417: \subsubsecidx{printtex}$(\{\var{str}\}*)$: outputs its (string) arguments in
6418: \TeX{} format. This output can then be used in a \TeX{} manuscript.
6419: The printing is done on the standard output. If you want to print it to a
6420: file you should use \kbd{writetex} (see there).
6421:
6422: Another possibility is to enable the \tet{log} default
6423: (see~\secref{se:defaults}).
6424: You could for instance do:\sidx{logfile}
6425: %
6426: \bprog%
6427: default(logfile, "new.tex");
6428: default(log, 1);
6429: printtex(result);%
6430: \eprog
6431: \noindent
6432: (You can use the automatic string expansion/concatenation process to have
6433: dynamic file names if you wish).
6434:
6435: \subsubsecidx{quit}$()$: exits GP.\label{se:quit}
6436:
6437: \subsubsecidx{read}$(\{\var{str}\})$: reads in the file whose name results
6438: from the expansion of the string \var{str}. If \var{str} is omitted,
6439: re-reads the last file that was fed into GP. The return value is the result of
6440: the last expression evaluated.\label{se:read}
6441:
6442: \subsubsecidx{reorder}$(\{x=[\,]\})$: $x$ must be a vector. If $x$ is the
6443: empty vector, this gives the vector whose components are the existing
6444: variables in increasing order (i.e.~in decreasing importance). Killed
6445: variables (see \kbd{kill}) will be shown as \kbd{0}. If $x$ is
6446: non-empty, it must be a permutation of variable names, and this permutation
6447: gives a new order of importance of the variables, {\it for output only}. For
6448: example, if the existing order is \kbd{[x,y,z]}, then after
6449: \kbd{reorder([z,x])} the order of importance of the variables, with respect
6450: to output, will be \kbd{[z,y,x]}. The internal representation is unaffected.
6451: \label{se:reorder}
6452:
6453: \subsubsecidx{setrand}$(n)$: reseeds the random number generator to the value
6454: $n$. The initial seed is $n=1$.
6455:
6456: \syn{setrand}{n}, where $n$ is a \kbd{long}. Returns $n$.
6457:
6458: \subsubsecidxunix{system}$(\var{str})$: \var{str} is a string representing
6459: a system command. This command is executed, its output written to the
6460: standard output (this won't get into your logfile), and control returns
6461: to the PARI system. This simply calls the C \kbd{system} command.
6462:
6463: \subsubsecidx{type}$(x,\{t\})$: this is useful only under GP. If $t$ is
6464: not present, returns the internal type number of the PARI object $x$.
6465: Otherwise, makes a copy of $x$ and sets its type equal to type $t$, which
6466: can be either a number or, preferably since internal codes may eventually
6467: change, a symbolic name such as \typ{FRACN} (you can skip the \typ{}
6468: part here, so that \kbd{FRACN} by itself would also be all right). Check out
6469: existing type names with the metacommand \b{t}.\label{se:gptype}
6470:
6471: Type changes must be used with extreme caution, or disasters may
6472: occur (\kbd{SIGSEGV} or \kbd{SIGBUS} being one's best bet), but one instance
6473: where it can be useful is \kbd{type(x,RFRACN)} when \kbd{x} is a rational
6474: function (type \typ{RFRAC}). In this case, the created object, as well as
6475: the objects created from it, will not be reduced automatically, making the
6476: operations much faster. In fact this function is the {\it only\/} way to create
6477: reducible rationals (type \typ{FRACN}) or rational functions (type
6478: \typ{RFRACN}) in GP.
6479:
6480: There is no equivalent library syntax, since the internal functions \kbd{typ}
6481: and \kbd{settyp} are available. Note that \kbd{settyp} does {\it not\/} create
6482: a copy of \kbd{x}, contrary to most PARI functions. It just changes the type in
6483: place (and returns nothing). \kbd{typ} returns a C long integer. Note also
6484: the different spellings of the internal functions (\kbd{set})\kbd{typ} and of
6485: the GP function \kbd{type}\footnote{*}{This is due to the fact that
6486: \kbd{type} is a reserved identifier for some C compilers.}.
6487:
6488: \subsubsecidx{whatnow}$(\var{key})$: if keyword \var{key} is the name
6489: of a function that was present in GP version 1.39.15 or lower, outputs
6490: the new function name and syntax, if it changed at all ($387$ out of $560$
6491: did).\label{se:whatnow}
6492:
6493: \subsubsecidx{write}$(\var{filename},\{\var{str}*\})$: writes (appends)
6494: to \var{filename} the remaining arguments, and appends a newline (same output
6495: as \kbd{print}).\label{se:write}
6496:
6497: \subsubsecidx{write1}$(\var{filename},\{\var{str}*\})$: writes (appends) to
6498: \var{filename} the remaining arguments without a trailing newline
6499: (same output as \kbd{print1}).
6500:
6501: \subsubsecidx{writetex}$(\var{filename},\{\var{str}*\})$: as \kbd{write},
6502: in \TeX\ format.\label{se:writetex}
6503:
6504: \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 / doc