Annotation of OpenXM_contrib/pari-2.2/doc/usersch3.tex, Revision 1.2
1.2 ! noro 1: % $Id: usersch3.tex,v 1.213 2002/09/10 14:27:48 karim Exp $
1.1 noro 2: % Copyright (c) 2000 The PARI Group
3: %
4: % This file is part of the PARI/GP documentation
5: %
6: % Permission is granted to copy, distribute and/or modify this document
7: % under the terms of the GNU Free Documentation License
8: \chapter{Functions and Operations Available in PARI and GP}
9: \label{se:functions}
10:
11: The functions and operators available in PARI and in the GP/PARI calculator
12: are numerous and everexpanding. Here is a description of the ones available
13: in version \vers. It should be noted that many of these functions accept
14: quite different types as arguments, but others are more restricted. The list
15: of acceptable types will be given for each function or class of functions.
16: Except when stated otherwise, it is understood that a function or operation
17: which should make natural sense is legal. In this chapter, we will describe
18: the functions according to a rough classification. The general entry looks
19: something like:
20:
21: \key{foo}$(x,\{\fl=0\})$: short description.
22:
23: \syn{foo}{x,\fl}.
24:
25: \noindent
26: This means that the GP function \kbd{foo} has one mandatory argument $x$, and
27: an optional one, $\fl$, whose default value is 0 (the $\{\}$ should never be
28: typed, it is just a convenient notation we will use throughout to denote
29: optional arguments). That is, you can type \kbd{foo(x,2)}, or \kbd{foo(x)},
30: which is then understood to mean \kbd{foo(x,0)}. As well, a comma or closing
31: parenthesis, where an optional argument should have been, signals to GP it
32: should use the default. Thus, the syntax \kbd{foo(x,)} is also accepted as a
33: synonym for our last expression. When a function has more than one optional
34: argument, the argument list is filled with user supplied values, in order.
35: And when none are left, the defaults are used instead. Thus, assuming that
36: \kbd{foo}'s prototype had been
37: $$\hbox{%
38: \key{foo}$(\{x=1\},\{y=2\},\{z=3\})$,%
39: }$$
40: typing in \kbd{foo(6,4)} would give
41: you \kbd{foo(6,4,3)}. In the rare case when you want to set some far away
1.2 ! noro 42: argument, and leave the defaults in between as they stand, you can use the
1.1 noro 43: ``empty arg'' trick alluded to above: \kbd{foo(6,,1)} would yield
44: \kbd{foo(6,2,1)}. By the way, \kbd{foo()} by itself yields
45: \kbd{foo(1,2,3)} as was to be expected. In this rather special case of a
46: function having no mandatory argument, you can even omit the $()$: a
47: standalone \kbd{foo} would be enough (though we don't really recommend it for
48: your scripts, for the sake of clarity). In defining GP syntax, we strove
49: to put optional arguments at the end of the argument list (of course, since
50: they would not make sense otherwise), and in order of decreasing usefulness
51: so that, most of the time, you will be able to ignore them.
52:
1.2 ! noro 53: \misctitle{Flags}. A \tev{flag} is an argument which, rather than conveying
! 54: actual information to the routine, intructs it to change its default
! 55: behaviour, e.g.~return more or less information. All such
! 56: flags are optional, and will be called \fl\ in the function descriptions to
! 57: follow. There are two different kind of flags
! 58:
! 59: $\bullet$ generic: all valid values for the flag are individually
! 60: described (``If \fl\ is equal to $1$, then\dots'').
! 61:
! 62: $\bullet$ binary:\sidx{binary flag} use customary binary notation as a
! 63: compact way to represent many toggles with just one number. Letting
! 64: $(p_0,\dots,p_n)$ be a list of switches (i.e.~of properties which take either
! 65: the value $0$ or~$1$), the number $2^3 + 2^5 = 40$ means that $p_3$ and $p_5$
1.1 noro 66: have been set (that is, set to $1$), and none of the others were (that is,
1.2 ! noro 67: they were set to $0$). This is announced as ``The binary digits of $\fl$ mean
! 68: 1: $p_0$, 2: $p_1$, 4: $p_2$'', and so on, using the available consecutive
! 69: powers of~$2$.
! 70:
! 71: \misctitle{Mnemonics for flags}. Numeric flags as mentionned above are
! 72: obscure, error-prone, and quite rigid: should the authors
! 73: want to adopt a new flag numbering scheme (for instance when noticing
! 74: flags with the same meaning but different numeric values), it would break
! 75: backward compatibility. The only advantage of explicit numeric values is that
! 76: they are fast to type, so their use is only advised when using the calculator
! 77: GP.
! 78:
! 79: As an alternative, one can replace a numeric flag by a character string
! 80: containing symbolic identifiers. For a generic flag, the mnemonic
! 81: corresponding to the numeric identifier is given after it as in (taken from
! 82: description of $\tet{log}(x,\{\fl=0\})$):
! 83:
! 84: \centerline{If \fl\ is equal to $1 = \kbd{AGM}$, use an agm formula\dots}
! 85:
! 86: \noindent which means that one can use indifferently \kbd{log($x$, 1)} or
! 87: \kbd{log($x$, AGM)}.
! 88:
! 89: For a binary flag, mnemonics corresponding to the various toggles are given
! 90: after each of them. They can be negated by prepending \kbd{no\_} to the
! 91: mnemonic, or by removing such a prefix. These toggles are grouped together
! 92: using any punctuation character (such as ',' or ';'). For instance (taken
! 93: from description of $\tet{ploth}(X=a,b,\var{expr},\{\fl=0\},\{n=0\})$)
! 94:
! 95: \centerline{Binary digits of flags mean: $1=\kbd{Parametric}$,
! 96: $2=\kbd{Recursive}$, \dots}
! 97:
! 98: \noindent so that, instead of $1$, one could use the mnemonic
! 99: \kbd{"Parametric; no\_Recursive"}, or simply \kbd{"Parametric"} since
! 100: \kbd{Recursive} is unset by default (default value of $\fl$ is $0$,
! 101: i.e.~everything unset).
1.1 noro 102:
103: \misctitle{Pointers}.\sidx{pointer} If a parameter in the function
104: prototype is prefixed with a \& sign, as in
105:
106: \key{foo}$(x,\&e)$
107:
108: \noindent it means that, besides the normal return value, the variable named
109: $e$ may be set as a side effect. When passing the argument, the \& sign has
110: to be typed in explicitly. As of version \vers, this \tet{pointer} argument
111: is optional for all documented functions, hence the \& will always appear
112: between brackets as in \kbd{issquare}$(x,\{\&e\})$.
113:
1.2 ! noro 114: \misctitle{About library programming}.
! 115: the \var{library} function \kbd{foo}, as defined
! 116: at the beginning of this section, is seen to have two mandatory arguments,
! 117: $x$ and \fl: no PARI mathematical function has been implemented so as to
! 118: accept a variable number of arguments, so all arguments are mandatory when
! 119: programming with the library (often, variants are provided corresponding to
! 120: the various flag values). When not mentioned otherwise, the result and
! 121: arguments of a function are assumed implicitly to be of type \kbd{GEN}. Most
! 122: other functions return an object of type \kbd{long} integer in C (see
! 123: Chapter~4). The variable or parameter names \var{prec} and \fl\ always denote
! 124: \kbd{long} integers.
1.1 noro 125:
126: The \tet{entree} type is used by the library to implement iterators (loops,
127: sums, integrals, etc.) when a formal variable has to successively assume a
128: number of values in a given set. When programming with the library, it is
129: easier and much more efficient to code loops and the like directly. Hence
130: this type is not documented, although it does appear in a few library
131: function prototypes below. See \secref{se:sums} for more details.
132:
133: \section{Standard monadic or dyadic operators}
134:
135: \subseckbd{+$/$-}: The expressions \kbd{+}$x$ and \kbd{-}$x$ refer
136: to monadic operators (the first does nothing, the second negates $x$).
137:
138: \syn{gneg}{x} for \kbd{-}$x$.
139:
140: \subseckbd{+}, \kbd{-}: The expression $x$ \kbd{+} $y$ is the \idx{sum} and
141: $x$ \kbd{-} $y$ is the \idx{difference} of $x$ and $y$. Among the prominent
142: impossibilities are addition/subtraction between a scalar type and a vector
143: or a matrix, between vector/matrices of incompatible sizes and between an
144: integermod and a real number.
145:
146: \syn{gadd}{x,y} $x$ \kbd{+} $y$, $\teb{gsub}(x,y)$ for $x$ \kbd{-} $y$.
147:
148: \subseckbd{*}: The expression $x$ \kbd{*} $y$ is the \idx{product} of $x$
149: and $y$. Among the prominent impossibilities are multiplication between
150: vector/matrices of incompatible sizes, between an integermod and a real
151: number. Note that because of vector and matrix operations, \kbd{*} is not
152: necessarily commutative. Note also that since multiplication between two
153: column or two row vectors is not allowed, to obtain the \idx{scalar product}
154: of two vectors of the same length, you must multiply a line vector by a
155: column vector, if necessary by transposing one of the vectors (using
156: the operator \kbd{\til} or the function \kbd{mattranspose}, see
157: \secref{se:linear_algebra}).
158:
159: If $x$ and $y$ are binary quadratic forms, compose them. See also
160: \kbd{qfbnucomp} and \kbd{qfbnupow}.
161:
162: \syn{gmul}{x,y} for $x$ \kbd{*} $y$. Also available is
163: $\teb{gsqr}(x)$ for $x$ \kbd{*} $x$ (faster of course!).
164:
165: \subseckbd{/}: The expression $x$ \kbd{/} $y$ is the \idx{quotient} of $x$
166: and $y$. In addition to the impossibilities for multiplication, note that if
167: the divisor is a matrix, it must be an invertible square matrix, and in that
168: case the result is $x*y^{-1}$. Furthermore note that the result is as exact
169: as possible: in particular, division of two integers always gives a rational
170: number (which may be an integer if the quotient is exact) and \var{not} the
171: Euclidean quotient (see $x$ \kbd{\bs} $y$ for that), and similarly the
172: quotient of two polynomials is a rational function in general. To obtain the
173: approximate real value of the quotient of two integers, add \kbd{0.} to the
174: result; to obtain the approximate $p$-adic value of the quotient of two
175: integers, add \kbd{O(p\pow k)} to the result; finally, to obtain the
176: \idx{Taylor series} expansion of the quotient of two polynomials, add
177: \kbd{O(X\pow k)} to the result or use the \kbd{taylor} function
178: (see \secref{se:taylor}). \label{se:gdiv}
179:
180: \syn{gdiv}{x,y} for $x$ \kbd{/} $y$.
181:
1.2 ! noro 182: \subseckbd{\bs}: The expression \kbd{$x$ \bs\ $y$} is the \idx{Euclidean
! 183: quotient} of $x$ and $y$. If $y$ is a real scalar, this is defined as
! 184: \kbd{floor($x$/$y$)} if $y > 0$, and \kbd{ceil($x$/$y$)} if $y < 0$ and
! 185: the division is not exact. Hence the remainder \kbd{$x$ - ($x$\bs$y$)*$y$}
! 186: is in $[0, |y|[$.
! 187:
! 188: Note that when $y$ is an integer and $x$ a polynomial, $y$ is first promoted
! 189: to a polynomial of degree $0$. When $x$ is a vector or matrix, the operator
! 190: is applied componentwise.
1.1 noro 191:
192: \syn{gdivent}{x,y} for $x$ \kbd{\bs} $y$.
193:
1.2 ! noro 194: \subseckbd{\bs/}: The expression $x$ \b{/} $y$ evaluates to the rounded
! 195: \idx{Euclidean quotient} of $x$ and $y$. This is the same as \kbd{$x$ \bs\ $y$}
! 196: except for scalar division: the quotient is such that the corresponding
! 197: remainder is smallest in absolute value and in case of a tie the quotient
! 198: closest to $+\infty$ is chosen (hence the remainder would belong to
! 199: $]-|y|/2, |y|/2]$).
! 200:
! 201: When $x$ is a vector or matrix, the operator is applied componentwise.
1.1 noro 202:
203: \syn{gdivround}{x,y} for $x$ \b{/} $y$.
204:
1.2 ! noro 205: \subseckbd{\%}: The expression \kbd{$x$ \% $y$} evaluates to the modular
! 206: \idx{Euclidean remainder} of $x$ and $y$, which we now define. If $y$ is an
! 207: integer, this is the smallest non-negative integer congruent to $x$ modulo
! 208: $y$. If $y$ is a polynomial, this is the polynomial of smallest degree
! 209: congruent to $x$ modulo $y$. When $y$ is a non-integral real number,
! 210: \kbd{$x$\%$y$} is defined as \kbd{$x$ - ($x$\bs$y$)*$y$}. This
! 211: coincides with the definition for $y$ integer if and only if $x$ is an
! 212: integer, but still belongs to $[0, |y|[$. For instance:
! 213: \bprog
! 214: ? (1/2) % 3
! 215: %1 = 2
! 216: ? 0.5 % 3
! 217: *** forbidden division t_REAL % t_INT.
! 218: ? (1/2) % 3.0
! 219: %2 = 1/2
! 220: @eprog
! 221: Note that when $y$ is an integer and $x$ a polynomial, $y$ is first promoted
! 222: to a polynomial of degree $0$. When $x$ is a vector or matrix, the operator
! 223: is applied componentwise.
1.1 noro 224:
225: \syn{gmod}{x,y} for $x$ \kbd{\%} $y$.
226:
1.2 ! noro 227: \subsecidx{divrem}$(x,y,\{v\})$: creates a column vector with two components,
! 228: the first being the Euclidean quotient (\kbd{$x$ \bs\ $y$}), the second the
! 229: Euclidean remainder (\kbd{$x$ - ($x$\bs$y$)*$y$}), of the division of $x$ by
! 230: $y$. This avoids the need to do two divisions if one needs both the quotient
! 231: and the remainder. If $v$ is present, and $x$, $y$ are multivariate
! 232: polynomials, divide with respect to the variable $v$.
! 233:
! 234: Beware that \kbd{divrem($x$,$y$)[2]} is in general not the same as
! 235: \kbd{$x$ \% $y$}; there is no operator to obtain it in GP:
! 236: \bprog
! 237: ? divrem(1/2, 3)[2]
! 238: %1 = 1/2
! 239: ? (1/2) % 3
! 240: %2 = 2
! 241: ? divrem(Mod(2,9), 3)[2]
! 242: *** forbidden division t_INTMOD \ t_INT.
! 243: ? Mod(2,9) % 6
! 244: %3 = Mod(2,3)
! 245: @eprog
1.1 noro 246:
1.2 ! noro 247: \syn{divrem}{x,y,v},where $v$ is a \kbd{long}. Also available as
! 248: $\teb{gdiventres}(x,y)$ when $v$ is not needed.
1.1 noro 249:
250: \subseckbd{\pow}: The expression $x\hbox{\kbd{\pow}}n$ is \idx{powering}.
251: If the exponent is an integer, then exact operations are performed using
252: binary (left-shift) powering techniques. In particular, in this case $x$
253: cannot be a vector or matrix unless it is a square matrix (and moreover
254: invertible if the exponent is negative). If $x$ is a $p$-adic number, its
255: precision will increase if $v_p(n) > 0$. PARI is able to rewrite the
256: multiplication $x * x$ of two {\it identical} objects as $x^2$, or
257: $\kbd{sqr}(x)$ (here, identical means the operands are two different labels
258: referencing the same chunk of memory; no equality test is performed). This
259: is no longer true when more than two arguments are involved.
260:
261: If the exponent is not of type integer, this is treated as a transcendental
262: function (see \secref{se:trans}), and in particular has the effect of
263: componentwise powering on vector or matrices.
264:
265: As an exception, if the exponent is a rational number $p/q$ and $x$ an
266: integer modulo a prime, return a solution $y$ of $y^q=x^p$ if it
267: exists. Currently, $q$ must not have large prime factors.
268:
269: Beware that
270:
271: \bprog
272: ? Mod(7,19)^(1/2)
273: %1 = Mod(11, 19)/*is any square root*/
274: ? sqrt(Mod(7,19))
275: %2 = Mod(8, 19)/*is the smallest square root*/
276: ? Mod(7,19)^(3/5)
277: %3 = Mod(1, 19)
278: ? %3^(5/3)
279: %4 = Mod(1, 19)/*Mod(7,19) is just another cubic root*/
280: @eprog\noindent
281:
282: \syn{gpow}{x,n,\var{prec}} for $x\hbox{\kbd{\pow}}n$.
283:
1.2 ! noro 284: \subsecidx{shift}$(x,n,\{\fl=0\})$ or $x$ \kbd{<<} $n$ (= $x$ \kbd{>>} $(-n)$):
! 285: shifts $x$ componentwise left by $n$ bits if $n\ge0$ and right by $|n|$ bits
! 286: if $n<0$. A left shift by $n$ corresponds to multiplication by $2^n$. A right
! 287: shift of an integer $x$ by $|n|$ corresponds to a Euclidean division of $x$
! 288: by $2^{|n|}$ with a remainder of the same sign as $x$, hence is not the same
! 289: (when $x < 0$) as $x \kbd{\bs} 2^{|n|}$. If $\fl$ is non-zero, this behaviour
! 290: is modified and right shift of a negative $x$ \var{is} the same as $x
! 291: \kbd{\bs} 2^{|n|}$ (which is consistent with $2$-complement semantic of
! 292: negative numbers).
1.1 noro 293:
1.2 ! noro 294: \syn{gshift3}{x,n,\fl} where $n$ is a \kbd{long}. Also available is
! 295: $\teb{gshift}(x,n)$ for the case $\fl=0$.
1.1 noro 296:
297: \subsecidx{shiftmul}$(x,n)$: multiplies $x$ by $2^n$. The difference with
298: \kbd{shift} is that when $n<0$, ordinary division takes place, hence for
299: example if $x$ is an integer the result may be a fraction, while for
300: \kbd{shift} Euclidean division takes place when $n<0$ hence if $x$ is an
301: integer the result is still an integer.
302:
303: \syn{gmul2n}{x,n} where $n$ is a \kbd{long}.
304:
305: \subsec{Comparison and boolean operators}.\sidx{boolean operators}
306: The six standard \idx{comparison operators} \kbd{<=}, \kbd{<}, \kbd{>=},
307: \kbd{>}, \kbd{==}, \kbd{!=} are available in GP, and in library mode under
308: the names \tet{gle}, \tet{glt}, \tet{gge}, \tet{ggt}, \tet{geq}, \tet{gne}
309: respectively. The library syntax is $\var{co}(x,y)$, where \var{co} is the
310: comparison operator. The result is 1 (as a \kbd{GEN}) if the comparison is
311: true, 0 (as a \kbd{GEN}) if it is false.
312:
313: The standard boolean functions \kbd{||} (\idx{inclusive or}), \kbd{\&\&}
314: (\idx{and})\sidx{or} and \kbd{!} (\idx{not}) are also available, and the
315: library syntax is $\teb{gor}(x,y)$, $\teb{gand}(x,y)$ and $\teb{gnot}(x)$
316: respectively.
317:
318: In library mode, it is in fact usually preferable to use the two basic
319: functions which are $\teb{gcmp}(x,y)$ which gives the sign (1, 0, or -1) of
320: $x-y$, where $x$ and $y$ must be in $\R$, and $\teb{gegal}(x,y)$ which
321: can be applied to any two PARI objects $x$ and $y$ and gives 1 (i.e.~true) if
322: they are equal (but not necessarily identical), 0 (i.e.~false) otherwise.
323: Particular cases of \teb{gegal} which should be used are $\teb{gcmp0}(x)$
324: ($x==0$ ?), $\teb{gcmp1}(x)$ ($x==1$ ?), and
325: $\teb{gcmp_1}(x)$ ($x==-1$ ?).
326:
327: Note that $\teb{gcmp0}(x)$ tests whether $x$ is equal to zero, even if $x$ is
328: not an exact object. To test whether $x$ is an exact object which is equal to
329: zero, one must use $\tet{isexactzero}$.
330:
331: Also note that the \kbd{gcmp} and \kbd{gegal} functions return a C-integer,
332: and \var{not} a \kbd{GEN} like \kbd{gle} etc.
333:
334: \smallskip
335: GP accepts the following synonyms for some of the above functions: since we
336: thought it might easily lead to confusion, we don't use the customary C
337: operators for bitwise \kbd{and} or bitwise \kbd{or} (use \tet{bitand} or
338: \tet{bitor}), hence \kbd{|} and \kbd{\&} are accepted as\sidx{bitwise
339: and}\sidx{bitwise or} synonyms of \kbd{||} and \kbd{\&\&} respectively.
340: Also, \kbd{<>} is accepted as a synonym for \kbd{!=}. On the other hand,
341: \kbd{=} is definitely \var{not} a synonym for \kbd{==} since it is the
342: assignment statement.
343:
344: \subsecidx{lex}$(x,y)$: gives the result of a lexicographic comparison
1.2 ! noro 345: between $x$ and $y$ (as $-1$, $0$ or $1$). This is to be interpreted in quite
! 346: a wide sense: It is admissible to compare objects of different types
! 347: (scalars, vectors, matrices), provided the scalars can be compared, as well
! 348: as vectors/matrices of different lengths. The comparison is recursive.
! 349:
! 350: In case all components are equal up to the smallest length of the operands,
! 351: the more complex is considered to be larger. More precisely, the longest is
! 352: the largest; when lengths are equal, we have matrix $>$ vector $>$ scalar.
! 353: For example:
! 354: \bprog
! 355: ? lex([1,3], [1,2,5])
! 356: %1 = 1
! 357: ? lex([1,3], [1,3,-1])
! 358: %2 = -1
! 359: ? lex([1], [[1]])
! 360: %3 = -1
! 361: ? lex([1], [1]~)
! 362: %4 = 0
! 363: @eprog
1.1 noro 364:
365: \syn{lexcmp}{x,y}.
366:
367: \subsecidx{sign}$(x)$: \idx{sign} ($0$, $1$ or $-1$) of $x$, which must be of
368: type integer, real or fraction.
369:
370: \syn{gsigne}{x}. The result is a \kbd{long}.
371:
372: \subsecidx{max}$(x,y)$ and \teb{min}$(x,y)$: creates the
373: maximum and minimum of $x$ and $y$ when they can be compared.
374:
375: \syn{gmax}{x,y} and $\teb{gmin}(x,y)$.
376:
377: \subsecidx{vecmax}$(x)$: if $x$ is a vector or a matrix, returns the maximum
378: of the elements of $x$, otherwise returns a copy of $x$. Returns $-\infty$
379: in the form of $-(2^{31}-1)$ (or $-(2^{63}-1)$ for 64-bit machines) if $x$ is
380: empty.
381:
382: \syn{vecmax}{x}.
383:
384: \subsecidx{vecmin}$(x)$: if $x$ is a vector or a matrix, returns the minimum
385: of the elements of $x$, otherwise returns a copy of $x$. Returns $+\infty$
386: in the form of $2^{31}-1$ (or $2^{63}-1$ for 64-bit machines) if $x$ is empty.
387:
388: \syn{vecmin}{x}.
389:
390: \section{Conversions and similar elementary functions or commands}
391: \label{se:conversion}
392:
393: \noindent
394: Many of the conversion functions are rounding or truncating operations. In
395: this case, if the argument is a rational function, the result is the
396: Euclidean quotient of the numerator by the denominator, and if the argument
397: is a vector or a matrix, the operation is done componentwise. This will not
398: be restated for every function.
399:
400: \subsecidx{List}$({x=[\,]})$: transforms a (row or column) vector $x$
401: into a list. The only other way to create a \typ{LIST} is to use the
402: function \kbd{listcreate}.
403:
404: This is useless in library mode.
405:
406: \subsecidx{Mat}$({x=[\,]})$: transforms the object $x$ into a matrix.
407: If $x$ is not a vector or a matrix, this creates a $1\times 1$ matrix.
408: If $x$ is a row (resp. column) vector, this creates a 1-row (resp.
409: 1-column) matrix. If $x$ is already a matrix, a copy of $x$ is created.
410:
411: This function can be useful in connection with the function \kbd{concat}
412: (see there).
413:
414: \syn{gtomat}{x}.
415:
416: \subsecidx{Mod}$(x,y,\{\fl=0\})$:\label{se:Mod} creates the PARI object
417: $(x \mod y)$, i.e.~an integermod or a polmod. $y$ must be an integer or a
418: polynomial. If $y$ is an integer, $x$ must be an integer, a rational
419: number, or a $p$-adic number compatible with the modulus $y$. If $y$ is a
420: polynomial, $x$ must be a scalar (which is not a polmod), a polynomial, a
421: rational function, or a power series.
422:
423: This function is not the same as $x$ \kbd{\%} $y$, the result of which is an
424: integer or a polynomial.
425:
426: If $\fl$ is equal to $1$, the modulus of the created result is put on the
427: heap and not on the stack, and hence becomes a permanent copy which cannot be
428: erased later by garbage collecting (see \secref{se:garbage}). Functions
429: will operate faster on such objects and memory consumption will be lower.
430: On the other hand, care should be taken to avoid creating too many such
431: objects.
432:
433: Under GP, the same effect can be obtained by assigning the object to a GP
434: variable (the value of which is a permanent object for the duration of the
435: relevant library function call, and is treated as such). This value is
436: subject to garbage collection, since it will be deleted when the value
437: changes. This is preferable and the above flag is only retained for
438: compatibility reasons (it can still be useful in library mode).
439:
440: \syn{Mod0}{x,y,\fl}. Also available are
441:
442: $\bullet$ for $\fl=1$: $\teb{gmodulo}(x,y)$.
443:
444: $\bullet$ for $\fl=0$: $\teb{gmodulcp}(x,y)$.
445:
446: \subsecidx{Pol}$(x,\{v=x\})$: transforms the object $x$ into a polynomial with
447: main variable $v$. If $x$ is a scalar, this gives a constant polynomial. If
448: $x$ is a power series, the effect is identical to \kbd{truncate} (see there),
449: i.e.~it chops off the $O(X^k)$. If $x$ is a vector, this function creates
450: the polynomial whose coefficients are given in $x$, with $x[1]$ being the
451: leading coefficient (which can be zero).
452:
1.2 ! noro 453: \misctitle{Warning:} this is \var{not} a substitution function. It is
! 454: intended to be quick and dirty. So if you try \kbd{Pol(a,y)} on the
! 455: polynomial \kbd{a = x+y}, you will get \kbd{y+y}, which is not a valid PARI
! 456: object.
1.1 noro 457:
458: \syn{gtopoly}{x,v}, where $v$ is a variable number.
459:
460: \subsecidx{Polrev}$(x,\{v=x\})$: transform the object $x$ into a polynomial
461: with main variable $v$. If $x$ is a scalar, this gives a constant polynomial.
462: If $x$ is a power series, the effect is identical to \kbd{truncate} (see
463: there), i.e.~it chops off the $O(X^k)$. If $x$ is a vector, this function
464: creates the polynomial whose coefficients are given in $x$, with $x[1]$ being
465: the constant term. Note that this is the reverse of \kbd{Pol} if $x$ is a
466: vector, otherwise it is identical to \kbd{Pol}.
467:
468: \syn{gtopolyrev}{x,v}, where $v$ is a variable number.
469:
470: \subsecidx{Qfb}$(a,b,c,\{D=0.\})$: creates the binary quadratic form
471: $ax^2+bxy+cy^2$. If $b^2-4ac>0$, initialize \idx{Shanks}' distance
472: function to $D$.
473:
474: \syn{Qfb0}{a,b,c,D,\var{prec}}. Also available are
475: $\teb{qfi}(a,b,c)$ (when $b^2-4ac<0$), and
476: $\teb{qfr}(a,b,c,d)$ (when $b^2-4ac>0$).\sidx{binary quadratic form}
477:
478: \subsecidx{Ser}$(x,\{v=x\})$: transforms the object $x$ into a power series
479: with main variable $v$ ($x$ by default). If $x$ is a scalar, this gives a
480: constant power series with precision given by the default \kbd{serieslength}
481: (corresponding to the C global variable \kbd{precdl}). If $x$ is a
482: polynomial, the precision is the greatest of \kbd{precdl} and the degree of
483: the polynomial. If $x$ is a vector, the precision is similarly given, and the
484: coefficients of the vector are understood to be the coefficients of the power
485: series starting from the constant term (i.e.~the reverse of the function
486: \kbd{Pol}).
487:
488: The warning given for \kbd{Pol} applies here: this is not a substitution
489: function.
490:
491: \syn{gtoser}{x,v}, where $v$ is a variable number (i.e.~a C integer).
492:
493: \subsecidx{Set}$(\{x=[\,]\})$: converts $x$ into a set, i.e.~into a row vector
494: with strictly increasing entries. $x$ can be of any type, but is most useful
495: when $x$ is already a vector. The components of $x$ are put in canonical form
496: (type \typ{STR}) so as to be easily sorted. To recover an ordinary \kbd{GEN}
497: from such an element, you can apply \tet{eval} to it.
498:
499: \syn{gtoset}{x}.
500:
501: \subsecidx{Str}$(\{x=\hbox{\kbd{""}}\},\{\fl=0\})$: converts $x$ into a
502: character string (type \typ{STR}, the empty string if $x$ is omitted). To
503: recover an ordinary \kbd{GEN} from a string, apply \kbd{eval} to it. The
504: arguments of \kbd{Str} are evaluated in string context (see
505: \secref{se:strings}). If \fl\ is set, treat $x$ as a filename and perform
506: \idx{environment expansion} on the string. This feature can be used to read
507: \idx{environment variable} values.
508:
509: \bprog
510: ? i = 1; Str("x" i)
511: %1 = "x1"
512: ? eval(%)
513: %2 = x1;
514: ? Str("$HOME", 1)
515: %3 = "/home/pari"
516: @eprog
517:
518: \syn{strtoGENstr}{x,\fl}. This function is mostly useless in library mode. Use
519: the pair \tet{strtoGEN}/\tet{GENtostr} to convert between \kbd{char*} and
520: \kbd{GEN}.
521:
522: \subsecidx{Vec}$({x=[\,]})$: transforms the object $x$ into a row vector.
523: The vector will be with one component only, except when $x$ is a
524: vector/matrix or a quadratic form (in which case the resulting vector is
525: simply the initial object considered as a row vector), a character string
526: (a vector of individual characters is returned), but more importantly when
527: $x$ is a polynomial or a power series. In the case of a polynomial, the
528: coefficients of the vector start with the leading coefficient of the
529: polynomial, while for power series only the significant coefficients are
530: taken into account, but this time by increasing order of degree.
531:
532: \syn{gtovec}{x}.
533:
534: \subsecidx{Vecsmall}$({x=[\,]})$: transforms the object $x$ into a row
535: vector of type \typ{VECSMALL}. This acts as \kbd{Vec}, but only on a
536: limited set of objects (the result must be representable as a vector of small
537: integers). In particular, polynomials and power series are forbidden.
538:
539: \syn{gtovecsmall}{x}.
540:
541: \subsecidx{binary}$(x)$: outputs the vector of the binary digits of $|x|$.
542: Here $x$ can be an integer, a real number (in which case the result has two
543: components, one for the integer part, one for the fractional part) or a
544: vector/matrix.
545:
546: \syn{binaire}{x}.
547:
548: \subsecidx{bitand}$(x,y)$: bitwise \tet{and}\sidx{bitwise and} of two
549: integers $x$ and $y$, that is the integer
550: $$\sum (x_i~\kbd{and}~y_i) 2^i$$
551:
552: Negative numbers behave as if modulo a huge power of $2$.
553:
554: \syn{gbitand}{x,y}.
555:
556: \subsecidx{bitneg}$(x,\{n=-1\})$: \idx{bitwise negation} of an integer $x$,
557: truncated to $n$ bits, that is the integer
558: $$\sum_{i=0}^n \kbd{not}(x_i) 2^i$$
559: The special case $n=-1$ means no truncation: an infinite sequence of
560: leading $1$ is then represented as a negative number.
561:
562: Negative numbers behave as if modulo a huge power of $2$.
563:
564: \syn{gbitneg}{x}.
565:
566: \subsecidx{bitnegimply}$(x,y)$: bitwise negated imply of two integers $x$
567: and $y$ (or \kbd{not} $(x \Rightarrow y)$), that is the integer
568: $$\sum (x_i~\kbd{and not}(y_i)) 2^i$$
569:
570: Negative numbers behave as if modulo a huge power of $2$.
571:
572: \syn{gbitnegimply}{x,y}.
573:
1.2 ! noro 574: \subsecidx{bitor}$(x,y)$: \sidx{bitwise inclusive or}bitwise (inclusive)
! 575: \tet{or} of two integers $x$ and $y$, that is the integer
1.1 noro 576: $$\sum (x_i~\kbd{or}~y_i) 2^i$$
577:
578: Negative numbers behave as if modulo a huge power of $2$.
579:
580: \syn{gbitor}{x,y}.
581:
1.2 ! noro 582: \subsecidx{bittest}$(x,n,\{c=1\})$: extracts $|c|$ bits starting from
! 583: number $n$ from the right in the development of $|x|$ (i.e.~the coefficient
! 584: of $2^n$ in the binary expansion of $x$), returning the bits as an integer
! 585: bitmap. That is, if $x = \sum x_i 2^i$ with the $x_i$ in $\{0,1\}$, this
! 586: routine returns the integer
! 587: $$ \sum_{0\leq i < |c|} x_{n + i} 2^i $$
! 588: Bits at negative offsets are 0. A negative value of $c$ means that negative
! 589: values of $x$ are treated in the spirit of $2$-complement arithmetic (i.e
! 590: modulo a big power of $2$). To extract several bits (or groups of bits if
! 591: $|c|>1$) separately at once as a vector, pass a vector for $n$.
! 592:
! 593: \syn{gbittest3}{x,n,c}. Also available are $\teb{gbittest}(x,n)$
! 594: (default case $c=1$) and for simple cases $\teb{bittest}(x,n)$, where $n$
! 595: and the result are \kbd{long}s.
1.1 noro 596:
597: \subsecidx{bitxor}$(x,y)$: bitwise (exclusive) \tet{or}\sidx{bitwise
598: exclusive or} of two integers $x$ and $y$, that is the integer
599: $$\sum (x_i~\kbd{xor}~y_i) 2^i$$
600: Negative numbers behave as if modulo a huge power of $2$.
601:
602: \syn{gbitxor}{x,y}.
603:
604: \subsecidx{ceil}$(x)$: ceiling of $x$. When $x$ is in $\R$,
605: the result is the smallest integer greater than or equal to $x$. Applied to a
606: rational function, $\kbd{ceil}(x)$ returns the euclidian quotient of the
607: numerator by the denominator.
608:
609: \syn{gceil}{x}.
610:
611: \subsecidx{centerlift}$(x,\{v\})$: lifts an element $x=a \bmod n$ of $\Z/n\Z$
612: to $a$ in $\Z$, and similarly lifts a polmod to a polynomial. This is the
613: same as \tet{lift} except that in the particular case of elements of
614: $\Z/n\Z$, the lift $y$ is such that $-n/2<y\le n/2$. If $x$ is of type
615: fraction, complex, quadratic, polynomial, power series, rational function,
616: vector or matrix, the lift is done for each coefficient. Reals are forbidden.
617:
618: \syn{centerlift0}{x,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded
619: as $-1$. Also available is \teb{centerlift}$(x)$ = \kbd{centerlift0($x$,-1)}.
620:
621: \subsecidx{changevar}$(x,y)$: creates a copy of the object $x$ where its
622: variables are modified according to the permutation specified by the vector
623: $y$. For example, assume that the variables have been introduced in the
624: order \kbd{x}, \kbd{a}, \kbd{b}, \kbd{c}. Then, if $y$ is the vector
625: \kbd{[x,c,a,b]}, the variable \kbd{a} will be replaced by \kbd{c}, \kbd{b} by
626: \kbd{a}, and \kbd{c} by \kbd{b}, \kbd{x} being unchanged. Note that the
627: permutation must be completely specified, e.g.~\kbd{[c,a,b]} would not work,
628: since this would replace \kbd{x} by \kbd{c}, and leave \kbd{a} and \kbd{b}
629: unchanged (as well as \kbd{c} which is the fourth variable of the initial
630: list). In particular, the new variable names must be distinct.
631:
632: \syn{changevar}{x,y}.
633:
634: \subsec{components of a PARI object}:
635:
636: There are essentially three ways to extract the \idx{components} from a PARI
637: object.
638:
639: The first and most general, is the function $\teb{component}(x,n)$ which
640: extracts the $n^{\text{th}}$-component of $x$. This is to be understood as
641: follows: every PARI type has one or two initial \idx{code words}. The
642: components are counted, starting at 1, after these code words. In particular
643: if $x$ is a vector, this is indeed the $n^{\text{th}}$-component of $x$, if
644: $x$ is a matrix, the $n^{\text{th}}$ column, if $x$ is a polynomial, the
645: $n^{\text{th}}$ coefficient (i.e.~of degree $n-1$), and for power series, the
646: $n^{\text{th}}$ significant coefficient. The use of the function
647: \kbd{component} implies the knowledge of the structure of the different PARI
648: types, which can be recalled by typing \b{t} under GP.
649:
650: \syn{compo}{x,n}, where $n$ is a \kbd{long}.
651:
652: The two other methods are more natural but more restricted. The function
653: \funs{polcoeff}{x,n} gives the coefficient of degree $n$ of the polynomial
654: or power series $x$, with respect to the main variable of $x$ (to check
655: variable ordering, or to change it, use the function \tet{reorder}, see
656: \secref{se:reorder}). In particular if $n$ is less than the valuation of
657: $x$ or in the case of a polynomial, greater than the degree, the result is
658: zero (contrary to \kbd{compo} which would send an error message). If $x$ is
659: a power series and $n$ is greater than the largest significant degree, then
660: an error message is issued.
661:
662: For greater flexibility, vector or matrix types are also accepted for $x$,
663: and the meaning is then identical with that of \kbd{compo}.
664:
665: Finally note that a scalar type is considered by \kbd{polcoeff} as a
666: polynomial of degree zero.
667:
668: \syn{truecoeff}{x,n}.
669:
670: The third method is specific to vectors or matrices under GP. If $x$ is a
671: (row or column) vector, then \tet{x[n]} represents the $n^{\text{th}}$
672: component of $x$, i.e.~\kbd{compo(x,n)}. It is more natural and shorter to
673: write. If $x$ is a matrix, \tet{x[m,n]} represents the coefficient of
674: row \kbd{m} and column \kbd{n} of the matrix, \tet{x[m,]} represents
675: the $m^{\text{th}}$ \var{row} of $x$, and \tet{x[,n]} represents
676: the $n^{\text{th}}$ \var{column} of $x$.
677:
678: Finally note that in library mode, the macros \teb{coeff} and \teb{mael}
679: are available to deal with the non-recursivity of the \kbd{GEN} type from the
680: compiler's point of view. See the discussion on typecasts in Chapter 4.
681:
682: \subsecidx{conj}$(x)$: conjugate of $x$. The meaning of this
683: is clear, except that for real quadratic numbers, it means conjugation in the
684: real quadratic field. This function has no effect on integers, reals,
685: integermods, fractions or $p$-adics. The only forbidden type is polmod
686: (see \kbd{conjvec} for this).
687:
688: \syn{gconj}{x}.
689:
690: \subsecidx{conjvec}$(x)$: conjugate vector representation of $x$. If $x$ is a
691: polmod, equal to \kbd{Mod}$(a,q)$, this gives a vector of length
692: $\text{degree}(q)$ containing the complex embeddings of the polmod if $q$ has
693: integral or rational coefficients, and the conjugates of the polmod if $q$
694: has some integermod coefficients. The order is the same as that of the
695: \kbd{polroots} functions. If $x$ is an integer or a rational number, the
696: result is~$x$. If $x$ is a (row or column) vector, the result is a matrix
697: whose columns are the conjugate vectors of the individual elements of $x$.
698:
699: \syn{conjvec}{x,\var{prec}}.
700:
701: \subsecidx{denominator}$(x)$: lowest denominator of $x$. The meaning of this
702: is clear when $x$ is a rational number or function. When $x$ is an integer
703: or a polynomial, the result is equal to $1$. When $x$ is a vector or a matrix,
704: the lowest common denominator of the components of $x$ is computed. All other
705: types are forbidden.
706:
707: \syn{denom}{x}.
708:
709: \subsecidx{floor}$(x)$: floor of $x$. When $x$ is in $\R$, the result is the
710: largest integer smaller than or equal to $x$. Applied to a rational function,
711: $\kbd{floor}(x)$ returns the euclidian quotient of the numerator by the
712: denominator.
713:
714: \syn{gfloor}{x}.
715:
716: \subsecidx{frac}$(x)$: fractional part of $x$. Identical to
717: $x-\text{floor}(x)$. If $x$ is real, the result is in $[0,1[$.
718:
719: \syn{gfrac}{x}.
720:
721: \subsecidx{imag}$(x)$: imaginary part of $x$. When
722: $x$ is a quadratic number, this is the coefficient of $\omega$ in
723: the ``canonical'' integral basis $(1,\omega)$.
724:
725: \syn{gimag}{x}.
726:
727: \subsecidx{length}$(x)$: number of non-code words in $x$ really used (i.e.~the
728: effective length minus 2 for integers and polynomials). In particular,
729: the degree of a polynomial is equal to its length minus 1. If $x$ has type
730: \typ{STR}, output number of letters.
731:
732: \syn{glength}{x} and the result is a C long.
733:
734: \subsecidx{lift}$(x,\{v\})$: lifts an element $x=a \bmod n$ of $\Z/n\Z$ to
735: $a$ in $\Z$, and similarly lifts a polmod to a polynomial if $v$ is omitted.
1.2 ! noro 736: Otherwise, lifts only polmods whose modulus has main variable $v$ (if $v$
! 737: does not occur in $x$, lifts only intmods). If $x$ is of recursive (non
! 738: modular) type, the lift is done coefficientwise. For $p$-adics, this routine
! 739: acts as \tet{truncate}. It is not allowed to have $x$ of type \typ{REAL}.
! 740:
! 741: \bprog
! 742: ? lift(Mod(5,3))
! 743: %1 = 2
! 744: ? lift(3 + O(3^9))
! 745: %2 = 3
! 746: ? lift(Mod(x,x^2+1))
! 747: %3 = x
! 748: ? lift(x * Mod(1,3) + Mod(2,3))
! 749: %4 = x + 2
! 750: ? lift(x * Mod(y,y^2+1) + Mod(2,3))
! 751: %5 = y*x + Mod(2, 3) \\@com do you understand this one ?
! 752: ? lift(x * Mod(y,y^2+1) + Mod(2,3), x)
! 753: %6 = Mod(y, y^2+1) * x + Mod(2, y^2+1)
! 754: @eprog
1.1 noro 755:
756: \syn{lift0}{x,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded as
757: $-1$. Also available is \teb{lift}$(x)$ = \kbd{lift0($x$,-1)}.
758:
759: \subsecidx{norm}$(x)$: algebraic norm of $x$, i.e.~the product of $x$ with
760: its conjugate (no square roots are taken), or conjugates for polmods. For
761: vectors and matrices, the norm is taken componentwise and hence is not the
762: $L^2$-norm (see \kbd{norml2}). Note that the norm of an element of
763: $\R$ is its square, so as to be compatible with the complex norm.
764:
765: \syn{gnorm}{x}.
766:
767: \subsecidx{norml2}$(x)$: square of the $L^2$-norm of $x$. $x$ must
768: be a (row or column) vector.
769:
770: \syn{gnorml2}{x}.
771:
772: \subsecidx{numerator}$(x)$: numerator of $x$. When $x$ is a rational number
773: or function, the meaning is clear. When $x$ is an integer or a polynomial,
774: the result is $x$ itself. When $x$ is a vector or a matrix, then
775: \kbd{numerator(x)} is defined to be \kbd{denominator(x)*x}. All other types
776: are forbidden.
777:
778: \syn{numer}{x}.
779:
780: \subsecidx{numtoperm}$(n,k)$: generates the $k$-th permutation (as a
781: row vector of length $n$) of the numbers $1$ to $n$. The number $k$ is taken
782: modulo $n!\,$, i.e.~inverse function of \tet{permtonum}.
783:
784: \syn{numtoperm}{n,k}, where $n$ is a \kbd{long}.
785:
786: \subsecidx{padicprec}$(x,p)$: absolute $p$-adic precision of the object $x$.
787: This is the minimum precision of the components of $x$. The result is
788: \kbd{VERYBIGINT} ($2^{31}-1$ for 32-bit machines or $2^{63}-1$ for 64-bit
789: machines) if $x$ is an exact object.
790:
791: \syn{padicprec}{x,p} and the result is a \kbd{long}
792: integer.
793:
794: \subsecidx{permtonum}$(x)$: given a permutation $x$ on $n$ elements,
795: gives the number $k$ such that $x=\kbd{numtoperm(n,k)}$, i.e.~inverse
796: function of \tet{numtoperm}.
797:
798: \syn{permtonum}{x}.
799:
800: \subsecidx{precision}$(x,\{n\})$: gives the precision in decimal digits of the
801: PARI object $x$. If $x$ is an exact object, the largest single precision
802: integer is returned. If $n$ is not omitted, creates a new object equal to $x$
803: with a new precision $n$. This is to be understood as follows:
804:
805: For exact types, no change. For $x$ a vector or a matrix, the operation
806: is done componentwise.
807:
808: For real $x$, $n$ is the number of desired significant \var{decimal} digits.
809: If $n$ is smaller than the precision of $x$, $x$ is truncated, otherwise $x$
810: is extended with zeros.
811:
812: For $x$ a $p$-adic or a power series, $n$ is the desired number of
813: significant $p$-adic or $X$-adic digits, where $X$ is the main variable of
814: $x$.
815:
816: Note that the function \kbd{precision} never changes the type of the result.
817: In particular it is not possible to use it to obtain a polynomial from a
818: power series. For that, see \kbd{truncate}.
819:
820: \syn{precision0}{x,n}, where $n$ is a \kbd{long}. Also available are
821: $\teb{ggprecision}(x)$ (result is a \kbd{GEN}) and $\teb{gprec}(x,n)$, where
822: $n$ is a \kbd{long}.
823:
824: \subsecidx{random}$(\{N=2^{31}\})$: gives a random integer between 0 and
825: $N-1$. $N$ can be arbitrary large. This is an internal PARI function and does
826: not depend on the system's random number generator. Note that the resulting
827: integer is obtained by means of linear congruences and will not be well
828: distributed in arithmetic progressions.
829:
830: \syn{genrand}{N}.
831:
832: \subsecidx{real}$(x)$: real part of $x$. In the case where $x$ is a quadratic
833: number, this is the coefficient of $1$ in the ``canonical'' integral basis
834: $(1,\omega)$.
835:
836: \syn{greal}{x}.
837:
838: \subsecidx{round}$(x,\{\&e\})$: If $x$ is in $\R$, rounds $x$ to the nearest
839: integer and sets $e$ to the number of error bits, that is the binary exponent
840: of the difference between the original and the rounded value (the
841: ``fractional part''). If the exponent of $x$ is too large compared to its
842: precision (i.e.~$e>0$), the result is undefined and an error occurs if $e$
843: was not given.
844:
845: \misctitle{Important remark:} note that, contrary to the other truncation
846: functions, this function operates on every coefficient at every level of a
847: PARI object. For example
848: $$\text{truncate}\left(\dfrac{2.4*X^2-1.7}{X}\right)=2.4*X,$$ whereas
849: $$\text{round}\left(\dfrac{2.4*X^2-1.7}{X}\right)=\dfrac{2*X^2-2}{X}.$$
850: An important use of \kbd{round} is to get exact results after a long
851: approximate computation, when theory tells you that the coefficients
852: must be integers.
853:
854: \syn{grndtoi}{x,\&e}, where $e$ is a \kbd{long} integer. Also available is
855: $\teb{ground}(x)$.
856:
857: \subsecidx{simplify}$(x)$: this function tries to simplify the object $x$ as
858: much as it can. The simplifications do not concern rational functions (which
859: PARI automatically tries to simplify), but type changes. Specifically, a
860: complex or quadratic number whose imaginary part is exactly equal to 0
861: (i.e.~not a real zero) is converted to its real part, and a polynomial of
862: degree zero is converted to its constant term. For all types, this of course
863: occurs recursively. This function is useful in any case, but in particular
864: before the use of arithmetic functions which expect integer arguments, and
865: not for example a complex number of 0 imaginary part and integer real part
866: (which is however printed as an integer).
867:
868: \syn{simplify}{x}.
869:
870: \subsecidx{sizebyte}$(x)$: outputs the total number of bytes occupied by the
871: tree representing the PARI object $x$.
872:
873: \syn{taille2}{x} which returns a \kbd{long}. The
874: function \teb{taille} returns the number of \var{words} instead.
875:
876: \subsecidx{sizedigit}$(x)$: outputs a quick bound for the number of decimal
877: digits of (the components of) $x$, off by at most $1$. If you want the
878: exact value, you can use \kbd{length(Str(x))}, which is much slower.
879:
880: \syn{sizedigit}{x} which returns a \kbd{long}.
881:
882: \subsecidx{truncate}$(x,\{\&e\})$: truncates $x$ and sets $e$ to the number of
883: error bits. When $x$ is in $\R$, this means that the part after the decimal
884: point is chopped away, $e$ is the binary exponent of the difference between
885: the original and the truncated value (the ``fractional part''). If the
886: exponent of $x$ is too large compared to its precision (i.e.~$e>0$), the
887: result is undefined and an error occurs if $e$ was not given. The function
888: applies componentwise on vector / matrices; $e$ is then the maximal number of
889: error bits. If $x$ is a rational function, the result is the ``integer part''
890: (Euclidean quotient of numerator by denominator) and $e$ is not set.
891:
892: Note a very special use of \kbd{truncate}: when applied to a power series, it
893: transforms it into a polynomial or a rational function with denominator
894: a power of $X$, by chopping away the $O(X^k)$. Similarly, when applied to
895: a $p$-adic number, it transforms it into an integer or a rational number
896: by chopping away the $O(p^k)$.
897:
898: \syn{gcvtoi}{x,\&e}, where $e$ is a \kbd{long} integer. Also available is
899: \teb{gtrunc}$(x)$.
900:
901: \subsecidx{valuation}$(x,p)$:\label{se:valuation} computes the highest
902: exponent of $p$ dividing $x$. If $p$ is of type integer, $x$ must be an
903: integer, an integermod whose modulus is divisible by $p$, a fraction, a
904: $q$-adic number with $q=p$, or a polynomial or power series in which case the
905: valuation is the minimum of the valuation of the coefficients.
906:
907: If $p$ is of type polynomial, $x$ must be of type polynomial or rational
908: function, and also a power series if $x$ is a monomial. Finally, the
909: valuation of a vector, complex or quadratic number is the minimum of the
910: component valuations.
911:
912: If $x=0$, the result is \kbd{VERYBIGINT} ($2^{31}-1$ for 32-bit machines or
913: $2^{63}-1$ for 64-bit machines) if $x$ is an exact object. If $x$ is a
914: $p$-adic numbers or power series, the result is the exponent of the zero.
915: Any other type combinations gives an error.
916:
917: \syn{ggval}{x,p}, and the result is a \kbd{long}.
918:
919: \subsecidx{variable}$(x)$: gives the main variable of the object $x$, and
920: $p$ if $x$ is a $p$-adic number. Gives an error if $x$ has no variable
921: associated to it. Note that this function is useful only in GP, since in
922: library mode the function \kbd{gvar} is more appropriate.
923:
924: \syn{gpolvar}{x}. However, in library mode, this function should not be used.
925: Instead, test whether $x$ is a $p$-adic (type \typ{PADIC}), in which case $p$
926: is in $x[2]$, or call the function $\key{gvar}(x)$ which returns the variable
927: \var{number} of $x$ if it exists, \kbd{BIGINT} otherwise.
928:
929: \section{Transcendental functions}\label{se:trans}
930:
931: As a general rule, which of course in some cases may have exceptions,
932: transcendental functions operate in the following way:
933:
934: $\bullet$ If the argument is either an integer, a real, a rational, a complex
935: or a quadratic number, it is, if necessary, first converted to a real (or
936: complex) number using the current \idx{precision} held in the default
937: \kbd{realprecision}. Note that only exact arguments are converted, while
938: inexact arguments such as reals are not.
939:
940: Under GP this is transparent to the user, but when programming in library
941: mode, care must be taken to supply a meaningful parameter \var{prec} as the
942: last argument of the function if the first argument is an exact object.
943: This parameter is ignored if the argument is inexact.
944:
945: Note that in library mode the precision argument \var{prec} is a word
946: count including codewords, i.e.~represents the length in words of a real
947: number, while under GP the precision (which is changed by the metacommand
948: \b{p} or using \kbd{default(realprecision,...)}) is the number of significant
949: decimal digits.
950:
951: Note that some accuracies attainable on 32-bit machines cannot be attained
952: on 64-bit machines for parity reasons. For example the default GP accuracy
953: is 28 decimal digits on 32-bit machines, corresponding to \var{prec} having
954: the value 5, but this cannot be attained on 64-bit machines.\smallskip
955:
956: After possible conversion, the function is computed. Note that even if the
957: argument is real, the result may be complex (e.g.~$\text{acos}(2.0)$ or
958: $\text{acosh}(0.0)$). Note also that the principal branch is always chosen.
959:
960: $\bullet$ If the argument is an integermod or a $p$-adic, at present only a
961: few functions like \kbd{sqrt} (square root), \kbd{sqr} (square), \kbd{log},
962: \kbd{exp}, powering, \kbd{teichmuller} (Teichm\"uller character) and
963: \kbd{agm} (arithmetic-geometric mean) are implemented.
964:
965: Note that in the case of a $2$-adic number, $\kbd{sqr}(x)$ may not be
966: identical to $x*x$: for example if $x = 1+O(2^5)$ and $y = 1+O(2^5)$ then
967: $x*y = 1+O(2^5)$ while $\kbd{sqr}(x) = 1+O(2^6)$. Here, $x * x$ yields the
968: same result as $\kbd{sqr}(x)$ since the two operands are known to be {\it
969: identical}. The same statement holds true for $p$-adics raised to the power
970: $n$, where $v_p(n) > 0$.
971:
972: \misctitle{Remark:} note that if we wanted to be strictly consistent with
973: the PARI philosophy, we should have $x*y = (4 \mod 8)$ and $\kbd{sqr}(x) =
974: (4 \mod 32)$ when both $x$ and $y$ are congruent to $2$ modulo $4$.
975: However, since integermod is an exact object, PARI assumes that the modulus
976: must not change, and the result is hence $(0\, \mod\, 4)$ in both cases. On
977: the other hand, $p$-adics are not exact objects, hence are treated
978: differently.
979:
980: $\bullet$ If the argument is a polynomial, power series or rational function,
981: it is, if necessary, first converted to a power series using the current
982: precision held in the variable \tet{precdl}. Under GP this again is
983: transparent to the user. When programming in library mode, however, the
984: global variable \kbd{precdl} must be set before calling the function if the
985: argument has an exact type (i.e.~not a power series). Here \kbd{precdl} is
986: not an argument of the function, but a global variable.
987:
988: Then the Taylor series expansion of the function around $X=0$ (where $X$ is
989: the main variable) is computed to a number of terms depending on the number
990: of terms of the argument and the function being computed.
991:
992: $\bullet$ If the argument is a vector or a matrix, the result is the
993: componentwise evaluation of the function. In particular, transcendental
994: functions on square matrices, which are not implemented in the present
995: version \vers\ (see Appendix~B however), will have a slightly different name
996: if they are implemented some day.
997:
998: \subseckbd{\pow}: If $y$ is not of type integer, \kbd{x\pow y} has the same
999: effect as \kbd{exp(y*ln(x))}. It can be applied to $p$-adic numbers as
1000: well as to the more usual types.\sidx{powering}
1001:
1002: \syn{gpow}{x,y,\var{prec}}.
1003:
1004: \subsecidx{Euler}: Euler's constant $0.57721\cdots$. Note that \kbd{Euler}
1005: is one of the few special reserved names which cannot be used for variables
1006: (the others are \kbd{I} and \kbd{Pi}, as well as all function names).
1007: \label{se:euler}
1008:
1009: \syn{mpeuler}{\var{prec}} where $\var{prec}$ \var{must} be given. Note that
1010: this creates $\gamma$ on the PARI stack, but a copy is also created on the
1011: heap for quicker computations next time the function is called.
1012:
1013: \subsecidx{I}: the complex number $\sqrt{-1}$.
1014:
1015: The library syntax is the global variable \kbd{gi} (of type \kbd{GEN}).
1016:
1017: \subsecidx{Pi}: the constant $\pi$ ($3.14159\cdots$).\label{se:pi}
1018:
1019: \syn{mppi}{\var{prec}} where $\var{prec}$ \var{must} be given. Note that this
1020: creates $\pi$ on the PARI stack, but a copy is also created on the heap for
1021: quicker computations next time the function is called.
1022:
1023: \subsecidx{abs}$(x)$: absolute value of $x$ (modulus if $x$ is complex).
1024: Power series and rational functions are not allowed. Contrary to most
1025: transcendental functions, an exact argument is \var{not} converted to a real
1026: number before applying \kbd{abs} and an exact result is returned if possible.
1027: \bprog
1028: ? abs(-1)
1029: %1 = 1
1030: ? abs(3/7 + 4/7*I)
1031: %2 = 5/7
1032: ? abs(1 + I)
1033: %3 = 1.414213562373095048801688724
1034: @eprog
1035: \noindent If $x$ is a polynomial, returns $-x$ if the leading coefficient is
1036: real and negative else returns $x$. For a power series, the constant
1037: coefficient is considered instead.
1038:
1039: \syn{gabs}{x,\var{prec}}.
1040:
1041: \subsecidx{acos}$(x)$: principal branch of $\text{cos}^{-1}(x)$,
1042: i.e.~such that $\text{Re(acos}(x))\in [0,\pi]$. If
1043: $x\in \R$ and $|x|>1$, then $\text{acos}(x)$ is complex.
1044:
1045: \syn{gacos}{x,\var{prec}}.
1046:
1047: \subsecidx{acosh}$(x)$: principal branch of $\text{cosh}^{-1}(x)$,
1048: i.e.~such that $\text{Im(acosh}(x))\in [0,\pi]$. If
1049: $x\in \R$ and $x<1$, then $\text{acosh}(x)$ is complex.
1050:
1051: \syn{gach}{x,\var{prec}}.
1052:
1053: \subsecidx{agm}$(x,y)$: arithmetic-geometric mean of $x$ and $y$. In the
1054: case of complex or negative numbers, the principal square root is always
1055: chosen. $p$-adic or power series arguments are also allowed. Note that
1056: a $p$-adic agm exists only if $x/y$ is congruent to 1 modulo $p$ (modulo
1057: 16 for $p=2$). $x$ and $y$ cannot both be vectors or matrices.
1058:
1059: \syn{agm}{x,y,\var{prec}}.
1060:
1061: \subsecidx{arg}$(x)$: argument of the complex number $x$, such that
1062: $-\pi<\text{arg}(x)\le\pi$.
1063:
1064: \syn{garg}{x,\var{prec}}.
1065:
1066: \subsecidx{asin}$(x)$: principal branch of $\text{sin}^{-1}(x)$, i.e.~such
1067: that $\text{Re(asin}(x))\in [-\pi/2,\pi/2]$. If $x\in \R$ and $|x|>1$ then
1068: $\text{asin}(x)$ is complex.
1069:
1070: \syn{gasin}{x,\var{prec}}.
1071:
1072: \subsecidx{asinh}$(x)$: principal branch of $\text{sinh}^{-1}(x)$, i.e.~such
1073: that $\text{Im(asinh}(x))\in [-\pi/2,\pi/2]$.
1074:
1075: \syn{gash}{x,\var{prec}}.
1076:
1077: \subsecidx{atan}$(x)$: principal branch of $\text{tan}^{-1}(x)$, i.e.~such
1078: that $\text{Re(atan}(x))\in{} ]-\pi/2,\pi/2[$.
1079:
1080: \syn{gatan}{x,\var{prec}}.
1081:
1082: \subsecidx{atanh}$(x)$: principal branch of $\text{tanh}^{-1}(x)$, i.e.~such
1083: that $\text{Im(atanh}(x))\in{} ]-\pi/2,\pi/2]$. If $x\in \R$ and $|x|>1$ then
1084: $\text{atanh}(x)$ is complex.
1085:
1086: \syn{gath}{x,\var{prec}}.
1087:
1088: \subsecidx{bernfrac}$(x)$: Bernoulli number\sidx{Bernoulli numbers} $B_x$,
1089: where $B_0=1$, $B_1=-1/2$, $B_2=1/6$,\dots, expressed as a rational number.
1090: The argument $x$ should be of type integer.
1091:
1092: \syn{bernfrac}{x}.
1093:
1094: \subsecidx{bernreal}$(x)$: Bernoulli number\sidx{Bernoulli numbers}
1095: $B_x$, as \kbd{bernfrac}, but $B_x$ is returned as a real number
1096: (with the current precision).
1097:
1098: \syn{bernreal}{x,\var{prec}}.
1099:
1100: \subsecidx{bernvec}$(x)$: creates a vector containing, as rational numbers,
1101: the \idx{Bernoulli numbers} $B_0$, $B_2$,\dots, $B_{2x}$. These Bernoulli
1102: numbers can then be used as follows. Assume that this vector has been put
1103: into a variable, say \kbd{bernint}. Then you can define under GP:
1104: \bprog
1105: bern(x) =
1106: {
1107: if (x == 1, return(-1/2));
1108: if (x < 0 || x % 2, return(0));
1109: bernint[x/2+1]
1110: }
1111: @eprog
1112: \noindent and then \kbd{bern(k)} gives the Bernoulli number of index $k$ as a
1113: rational number, exactly as \kbd{bernreal(k)} gives it as a real number. If
1114: you need only a few values, calling \kbd{bernfrac(k)} each time will be much
1115: more efficient than computing the huge vector above.
1116:
1117: \syn{bernvec}{x}.
1118:
1119: \subsecidx{besseljh}$(n,x)$: $J$-Bessel function of half integral index.
1120: More precisely, $\kbd{besseljh}(n,x)$ computes $J_{n+1/2}(x)$ where $n$
1121: must be of type integer, and $x$ is any element of $\C$. In the
1122: present version \vers, this function is not very accurate when $x$ is
1123: small.
1124:
1125: \syn{jbesselh}{n,x,\var{prec}}.
1126:
1127: \subsecidx{besselk}$(\var{nu},x,\{\fl=0\})$: $K$-Bessel function of index
1128: \var{nu} (which can be complex) and argument $x$. Only real and positive
1.2 ! noro 1129: arguments $x$ are allowed in the present version \vers. If $\fl$ is equal to
! 1130: 1, uses another implementation of this function which is often faster. In the
! 1131: present version \vers, this function is not very accurate when $x$ is small.
1.1 noro 1132:
1133: \syn{kbessel}{\var{nu},x,\var{prec}} and
1134: $\teb{kbessel2}(\var{nu},x,\var{prec})$ respectively.
1135:
1136: \subsecidx{cos}$(x)$: cosine of $x$.
1137:
1138: \syn{gcos}{x,\var{prec}}.
1139:
1140: \subsecidx{cosh}$(x)$: hyperbolic cosine of $x$.
1141:
1142: \syn{gch}{x,\var{prec}}.
1143:
1144: \subsecidx{cotan}$(x)$: cotangent of $x$.
1145:
1146: \syn{gcotan}{x,\var{prec}}.
1147:
1148: \subsecidx{dilog}$(x)$: principal branch of the dilogarithm of $x$,
1149: i.e.~analytic continuation of the power series $\log_2(x)=\sum_{n\ge1}x^n/n^2$.
1150:
1151: \syn{dilog}{x,\var{prec}}.
1152:
1153: \subsecidx{eint1}$(x,\{n\})$: exponential integral
1154: $\int_x^\infty \dfrac{e^{-t}}{t}\,dt$ ($x\in\R$)
1155:
1156: If $n$ is present, outputs the $n$-dimensional vector
1157: $[\kbd{eint1}(x),\dots,\kbd{eint1}(nx)]$ ($x \geq 0$). This is faster than
1158: repeatedly calling \kbd{eint1($i$ * x)}.
1159:
1160: \syn{veceint1}{x,n,\var{prec}}. Also available is
1161: $\teb{eint1}(x,\var{prec})$.
1162:
1163: \subsecidx{erfc}$(x)$: complementary error function
1.2 ! noro 1164: $(2/\sqrt\pi)\int_x^\infty e^{-t^2}\,dt$ ($x\in\R$).
1.1 noro 1165:
1166: \syn{erfc}{x,\var{prec}}.
1167:
1168: \subsecidx{eta}$(x,\{\fl=0\})$: \idx{Dedekind}'s $\eta$ function, without the
1169: $q^{1/24}$. This means the following: if $x$ is a complex number with positive
1170: imaginary part, the result is $\prod_{n=1}^\infty(1-q^n)$, where
1171: $q=e^{2i\pi x}$. If $x$ is a power series (or can be converted to a power
1172: series) with positive valuation, the result is $\prod_{n=1}^\infty(1-x^n)$.
1173:
1174: If $\fl=1$ and $x$ can be converted to a complex number (i.e.~is not a power
1175: series), computes the true $\eta$ function, including the leading $q^{1/24}$.
1176:
1177: \syn{eta}{x,\var{prec}}.
1178:
1179: \subsecidx{exp}$(x)$: exponential of $x$.
1180: $p$-adic arguments with positive valuation are accepted.
1181:
1182: \syn{gexp}{x,\var{prec}}.
1183:
1184: \subsecidx{gammah}$(x)$: gamma function evaluated at the argument
1185: $x+1/2$. When $x$ is an integer, this is much faster than using
1186: $\kbd{gamma}(x+1/2)$.
1187:
1188: \syn{ggamd}{x,\var{prec}}.
1189:
1190: \subsecidx{gamma}$(x)$: gamma function of $x$. In the present version
1191: \vers\ the $p$-adic gamma function is not implemented.
1192:
1193: \syn{ggamma}{x,\var{prec}}.
1194:
1195: \subsecidx{hyperu}$(a,b,x)$: $U$-confluent hypergeometric function with
1196: parameters $a$ and $b$. The parameters $a$ and $b$ can be complex but
1197: the present implementation requires $x$ to be positive.
1198:
1199: \syn{hyperu}{a,b,x,\var{prec}}.
1200:
1201: \subsecidx{incgam}$(s,x,{y})$: incomplete gamma function.
1202:
1203: $x$ must be positive and $s$ real. The result returned is $\int_x^\infty
1204: e^{-t}t^{s-1}\,dt$. When $y$ is given, assume (of course without checking!)
1205: that $y=\Gamma(s)$. For small $x$, this will tremendously speed up the
1206: computation.
1207:
1208: \syn{incgam}{s,x,\var{prec}} and $\teb{incgam4}(s,x,y,\var{prec})$,
1209: respectively. There exist also the functions \teb{incgam1} and
1210: \teb{incgam2} which are used for internal purposes.
1211:
1212: \subsecidx{incgamc}$(s,x)$: complementary incomplete gamma function.
1213:
1214: The arguments $s$ and $x$ must be positive. The result returned is
1215: $\int_0^x e^{-t}t^{s-1}\,dt$, when $x$ is not too large.
1216:
1217: \syn{incgam3}{s,x,\var{prec}}.
1218:
1219: \subsecidx{log}$(x,\{\fl=0\})$: principal branch of the natural logarithm of
1220: $x$, i.e.~such that $\text{Im(ln}(x))\in{} ]-\pi,\pi]$. The result is complex
1221: (with imaginary part equal to $\pi$) if $x\in \R$ and $x<0$.
1222:
1223: $p$-adic arguments are also accepted for $x$, with the convention that
1224: $\ln(p)=0$. Hence in particular $\exp(\ln(x))/x$ will not in general be
1225: equal to 1 but to a $(p-1)$-th root of unity (or $\pm1$ if $p=2$)
1226: times a power of $p$.
1227:
1.2 ! noro 1228: If $\fl$ is equal to $1 = \kbd{AGM}$, use an agm formula suggested by Mestre,
! 1229: when $x$ is real, otherwise identical to \kbd{log}.
1.1 noro 1230:
1231: \syn{glog}{x,\var{prec}} or $\teb{glogagm}(x,\var{prec})$.
1232:
1233: \subsecidx{lngamma}$(x)$: principal branch of the logarithm of the gamma
1234: function of $x$. Can have much larger arguments than \kbd{gamma} itself.
1235: In the present version \vers, the $p$-adic \kbd{lngamma} function is not
1236: implemented.
1237:
1238: \syn{glngamma}{x,\var{prec}}.
1239:
1240: \subsecidx{polylog}$(m,x,{\fl=0})$: one of the different polylogarithms,
1241: depending on \fl:
1242:
1243: If $\fl=0$ or is omitted: $m^\text{th}$ polylogarithm of $x$, i.e.~analytic
1244: continuation of the power series $\text{Li}_m(x)=\sum_{n\ge1}x^n/n^m$. The
1245: program uses the power series when $|x|^2\le1/2$, and the power series
1246: expansion in $\log(x)$ otherwise. It is valid in a large domain (at least
1247: $|x|<230$), but should not be used too far away from the unit circle since it
1248: is then better to use the functional equation linking the value at $x$ to the
1249: value at $1/x$, which takes a trivial form for the variant below. Power
1250: series, polynomial, rational and vector/matrix arguments are allowed.
1251:
1252: For the variants to follow we need a notation: let $\Re_m$
1253: denotes $\Re$ or $\Im$ depending whether $m$ is odd or even.
1254:
1255: If $\fl=1$: modified $m^\text{th}$ polylogarithm of $x$, called
1256: $\tilde D_m(x)$ in Zagier, defined for $|x|\le1$ by
1257: $$\Re_m\left(\sum_{k=0}^{m-1} \dfrac{(-\log|x|)^k}{k!}\text{Li}_{m-k}(x)
1258: +\dfrac{(-\log|x|)^{m-1}}{m!}\log|1-x|\right).$$
1259:
1260: If $\fl=2$: modified $m^\text{th}$ polylogarithm of $x$,
1261: called $D_m(x)$ in Zagier, defined for $|x|\le1$ by
1262: $$\Re_m\left(\sum_{k=0}^{m-1}\dfrac{(-\log|x|)^k}{k!}\text{Li}_{m-k}(x)
1263: -\dfrac{1}{2}\dfrac{(-\log|x|)^m}{m!}\right).$$
1264:
1265: If $\fl=3$: another modified $m^\text{th}$
1266: polylogarithm of $x$, called $P_m(x)$ in Zagier, defined for $|x|\le1$ by
1267: $$\Re_m\left(\sum_{k=0}^{m-1}\dfrac{2^kB_k}{k!}(\log|x|)^k\text{Li}_{m-k}(x)
1268: -\dfrac{2^{m-1}B_m}{m!}(\log|x|)^m\right).$$
1269:
1270: These three functions satisfy the functional equation
1271: $f_m(1/x)=(-1)^{m-1}f_m(x)$.
1272:
1273: \syn{polylog0}{m,x,\fl,\var{prec}}.
1274:
1275: \subsecidx{psi}$(x)$: the $\psi$-function of $x$, i.e.~the
1276: logarithmic derivative $\Gamma'(x)/\Gamma(x)$.
1277:
1278: \syn{gpsi}{x,\var{prec}}.
1279:
1280: \subsecidx{sin}$(x)$: sine of $x$.
1281:
1282: \syn{gsin}{x,\var{prec}}.
1283:
1284: \subsecidx{sinh}$(x)$: hyperbolic sine of $x$.
1285:
1286: \syn{gsh}{x,\var{prec}}.
1287:
1288: \subsecidx{sqr}$(x)$: square of $x$. This operation is not completely
1289: straightforward, i.e.~identical to $x * x$, since it can usually be
1290: computed more efficiently (roughly one-half of the elementary
1291: multiplications can be saved). Also, squaring a $2$-adic number increases
1292: its precision. For example,
1293: \bprog
1294: ? (1 + O(2^4))^2
1295: %1 = 1 + O(2^5)
1296: ? (1 + O(2^4)) * (1 + O(2^4))
1297: %2 = 1 + O(2^4)
1298: @eprog\noindent
1299: Note that this function is also called whenever one multiplies two objects
1300: which are known to be {\it identical}, e.g.~they are the value of the same
1301: variable, or we are computing a power.
1302: \bprog
1303: ? x = (1 + O(2^4)); x * x
1304: %3 = 1 + O(2^5)
1305: ? (1 + O(2^4))^4
1306: %4 = 1 + O(2^6)
1307: @eprog
1308: \noindent(note the difference between \kbd{\%2} and \kbd{\%3} above).
1309:
1310: \syn{gsqr}{x}.
1311:
1312: \subsecidx{sqrt}$(x)$: principal branch of the square root of $x$,
1313: i.e.~such that $\text{Arg}(\text{sqrt}(x))\in{} ]-\pi/2, \pi/2]$, or in other
1314: words such that $\Re(\text{sqrt}(x))>0$ or $\Re(\text{sqrt}(x))=0$ and
1315: $\Im(\text{sqrt}(x))\ge 0$. If $x\in \R$ and $x<0$, then the result is
1316: complex with positive imaginary part.
1317:
1318: Integermod a prime and $p$-adics are allowed as arguments. In that case,
1319: the square root (if it exists) which is returned is the one whose
1320: first $p$-adic digit (or its unique $p$-adic digit in the case of
1321: integermods) is in the interval $[0,p/2]$. When the argument is an
1322: integermod a non-prime (or a non-prime-adic), the result is undefined.
1323:
1324: \syn{gsqrt}{x,\var{prec}}.
1325:
1326: \subsecidx{sqrtn}$(x,n,\{\&z\})$: principal branch of the $n$th root of $x$,
1327: i.e.~such that $\text{Arg}(\text{sqrt}(x))\in{} ]-\pi/n, \pi/n]$.
1328:
1329: Integermod a prime and $p$-adics are allowed as arguments.
1330:
1331: If $z$ is present, it is set to a suitable root of unity allowing to
1332: recover all the other roots. If it was not possible, z is
1333: set to zero.
1334:
1335: The following script computes all roots in all possible cases:
1336:
1337: \bprog
1338: sqrtnall(x,n)=
1339: {
1340: local(V,r,z,r2);
1341: r = sqrtn(x,n, &z);
1342: if (!z, error("Impossible case in sqrtn"));
1343: if (type(x) == "t_INTMOD" || type(x)=="t_PADIC" ,
1344: r2 = r*z; n = 1;
1345: while (r2!=r, r2*=z;n++));
1346: V = vector(n); V[1] = r;
1347: for(i=2, n, V[i] = V[i-1]*z);
1348: V
1349: }
1350: addhelp(sqrtnall,"sqrtnall(x,n):compute the vector of nth-roots of x");
1351: @eprog\noindent
1352:
1353: \syn{gsqrtn}{x,n,\&z,\var{prec}}.
1354:
1355: \subsecidx{tan}$(x)$: tangent of $x$.
1356:
1357: \syn{gtan}{x,\var{prec}}.
1358:
1359: \subsecidx{tanh}$(x)$: hyperbolic tangent of $x$.
1360:
1361: \syn{gth}{x,\var{prec}}.
1362:
1363: \subsecidx{teichmuller}$(x)$: Teichm\"uller character of the $p$-adic number
1364: $x$.
1365:
1366: \syn{teich}{x}.
1367:
1368: \subsecidx{theta}$(q,z)$: Jacobi sine theta-function.
1369:
1370: \syn{theta}{q,z,\var{prec}}.
1371:
1372: \subsecidx{thetanullk}$(q,k)$: $k$-th derivative at $z=0$ of
1373: $\kbd{theta}(q,z)$.
1374:
1375: \syn{thetanullk}{q,k,\var{prec}}, where $k$ is a \kbd{long}.
1376:
1377: \subsecidx{weber}$(x,\{\fl=0\})$: one of Weber's three $f$ functions.
1378: If $\fl=0$, returns
1379: $$f(x)=\exp(-i\pi/24)\cdot\eta((x+1)/2)\,/\,\eta(x) \quad\hbox{such that}\quad
1380: j=(f^{24}-16)^3/f^{24}\,,$$
1381: where $j$ is the elliptic $j$-invariant (see the function \kbd{ellj}).
1382: If $\fl=1$, returns
1383: $$f_1(x)=\eta(x/2)\,/\,\eta(x)\quad\hbox{such that}\quad
1384: j=(f_1^{24}+16)^3/f_1^{24}\,.$$
1385: Finally, if $\fl=2$, returns
1386: $$f_2(x)=\sqrt{2}\eta(2x)\,/\,\eta(x)\quad\hbox{such that}\quad
1387: j=(f_2^{24}+16)^3/f_2^{24}.$$
1388: Note the identities $f^8=f_1^8+f_2^8$ and $ff_1f_2=\sqrt2$.
1389:
1390: \syn{weber0}{x,\fl,\var{prec}}, or
1391: $\teb{wf}(x,\var{prec})$, $\teb{wf1}(x,\var{prec})$ or
1392: $\teb{wf2}(x,\var{prec})$.
1393:
1394: \subsecidx{zeta}$(s)$: Riemann's zeta function\sidx{Riemann zeta-function}
1395: $\zeta(s)=\sum_{n\ge1}n^{-s}$, computed using the \idx{Euler-Maclaurin}
1396: summation formula, except when $s$ is of type integer, in which case it
1397: is computed using Bernoulli numbers\sidx{Bernoulli numbers} for
1398: $s\le0$ or $s>0$ and even, and using modular forms for $s>0$ and odd.
1399:
1400: \syn{gzeta}{s,\var{prec}}.
1401:
1402: \section{Arithmetic functions}\label{se:arithmetic}
1403:
1404: These functions are by definition functions whose natural domain of
1405: definition is either $\Z$ (or $\Z_{>0}$), or sometimes polynomials
1406: over a base ring. Functions which concern polynomials exclusively will be
1407: explained in the next section. The way these functions are used is
1408: completely different from transcendental functions: in general only the types
1409: integer and polynomial are accepted as arguments. If a vector or matrix type
1410: is given, the function will be applied on each coefficient independently.
1411:
1412: In the present version \vers, all arithmetic functions in the narrow sense
1413: of the word~--- Euler's totient\sidx{Euler totient function} function, the
1414: \idx{Moebius} function, the sums over divisors or powers of divisors
1415: etc.--- call, after trial division by small primes, the same versatile
1416: factoring machinery described under \kbd{factorint}. It includes
1417: \idx{Shanks SQUFOF}, \idx{Pollard Rho}, \idx{ECM} and \idx{MPQS} stages, and
1418: has an early exit option for the functions \teb{moebius} and (the integer
1419: function underlying) \teb{issquarefree}. Note that it relies on a (fairly
1420: strong) probabilistic primality test: numbers found to be strong
1421: pseudo-primes after 10 successful trials of the \idx{Rabin-Miller} test are
1422: declared primes.
1423:
1424: \bigskip
1425: \subsecidx{addprimes}$(\{x=[\,]\})$: adds the ``primes'' contained in the
1426: vector $x$ (or the single integer $x$) to the table computed upon GP
1427: initialization (by \kbd{pari\_init} in library mode), and returns a row
1428: vector entries contain all such user primes. Whenever \kbd{factor} or
1429: \kbd{smallfact} is subsequently called, first the primes in the table
1430: computed by \kbd{pari\_init} will be checked, and then the additional
1431: primes in this table. If $x$ is empty or omitted, just returns the current
1432: list of extra primes.
1433:
1434: The entries in $x$ are not checked for primality. They need only be positive
1435: integers not divisible by any of the pre-computed primes. It's in fact a nice
1436: trick to add composite numbers, which for example the function
1437: $\kbd{factor}(x,0)$ was not able to factor. In case the message
1438: ``impossible inverse modulo $\langle$\var{some INTMOD}$\rangle$'' shows up
1439: afterwards, you have just stumbled over a non-trivial factor. Note that the
1440: arithmetic functions in the narrow sense, like \teb{eulerphi}, do \var{not}
1441: use this extra table.
1442:
1443: To remove primes from the list use \kbd{removeprimes}.
1444:
1445: \syn{addprimes}{x}.
1446:
1447: \subsecidx{bestappr}$(x,A,\{B\})$: if $B$ is omitted, finds the best rational
1448: approximation to $x\in\R$ (or $\R[X]$, or $\R^n$, \dots) with denominator at
1449: most equal to $A$ using continued fractions.
1450:
1451: If $B$ is present, $x$ is assumed to be of type \typ{INTMOD} modulo $M$ (or a
1452: recursive combination of those), and the routine returns the unique fraction
1453: $a/b$ in coprime integers $a\leq A$ and $b\leq B$ which is congruent to $x$
1454: modulo $M$. If $M \leq 2AB$, uniqueness is not guaranteed and the function
1455: fails with an error message. If rational reconstruction is not possible
1456: (no such $a/b$ exists for at least one component of $x$), returns $-1$.
1457:
1458: \syn{bestappr0}{x,A,B}. Also available is $\teb{bestappr}(x,A)$ corresponding
1459: to an omitted $B$.
1460:
1461: \subsecidx{bezout}$(x,y)$: finds $u$ and $v$ minimal in a
1462: natural sense such that $x*u+y*v=\text{gcd}(x,y)$. The arguments
1463: must be both integers or both polynomials, and the result is a
1464: row vector with three components $u$, $v$, and $\text{gcd}(x,y)$.
1465:
1466: \syn{vecbezout}{x,y} to get the vector, or $\teb{gbezout}(x,y, \&u, \&v)$
1467: which gives as result the address of the created gcd, and puts
1468: the addresses of the corresponding created objects into $u$ and $v$.
1469:
1470: \subsecidx{bezoutres}$(x,y)$: as \kbd{bezout}, with the resultant of $x$ and
1471: $y$ replacing the gcd.
1472:
1473: \syn{vecbezoutres}{x,y} to get the vector, or $\teb{subresext}(x,y, \&u,
1474: \&v)$ which gives as result the address of the created gcd, and puts the
1475: addresses of the corresponding created objects into $u$ and $v$.
1476:
1477: \subsecidx{bigomega}$(x)$: number of prime divisors of $|x|$ counted with
1478: multiplicity. $x$ must be an integer.
1479:
1480: \syn{bigomega}{x}, the result is a \kbd{long}.
1481:
1482: \subsecidx{binomial}$(x,y)$: \idx{binomial coefficient} $\binom x y$.
1483: Here $y$ must be an integer, but $x$ can be any PARI object.
1484:
1485: \syn{binome}{x,y}, where $y$ must be a \kbd{long}.
1486:
1.2 ! noro 1487: \subsecidx{chinese}$(x,\{y\})$: if $x$ and $y$ are both integermods or both
1.1 noro 1488: polmods, creates (with the same type) a $z$ in the same residue class
1489: as $x$ and in the same residue class as $y$, if it is possible.
1490:
1491: This function also allows vector and matrix arguments, in which case the
1492: operation is recursively applied to each component of the vector or matrix.
1.2 ! noro 1493: For polynomial arguments, it is applied to each coefficient.
! 1494:
! 1495: If $y$ is omitted, and $x$ is a vector, \kbd{chinese} is applied recursively
! 1496: to the components of $x$, yielding a residue belonging to the same class as all
! 1497: components of $x$.
! 1498:
! 1499: Finally $\kbd{chinese}(x,x) = x$ regardless of the type of $x$; this allows
! 1500: vector arguments to contain other data, so long as they are identical in both
1.1 noro 1501: vectors.
1502:
1503: \syn{chinois}{x,y}.
1504:
1505: \subsecidx{content}$(x)$: computes the gcd of all the coefficients of $x$,
1.2 ! noro 1506: when this gcd makes sense. If $x$ is a scalar, this simply returns the
! 1507: absolute value of $x$ if $x$ is rationnal (\typ{INT}, \typ{FRAC} or
! 1508: \typ{FRACN}), and $x$ otherwise. If $x$ is a polynomial (and by extension a
! 1509: power series), it gives the usual content of $x$. If $x$ is a rational
! 1510: function, it gives the ratio of the contents of the numerator and the
! 1511: denominator. Finally, if $x$ is a vector or a matrix, it gives the gcd of all
! 1512: the entries.
1.1 noro 1513:
1514: \syn{content}{x}.
1515:
1.2 ! noro 1516: \subsecidx{contfrac}$(x,\{b\},\{nmax\})$: creates the row vector whose
1.1 noro 1517: components are the partial quotients of the \idx{continued fraction}
1.2 ! noro 1518: expansion of $x$. That is a result $[a_0,\dots,a_n]$ means that
! 1519: $x \approx a_0+1/(a_1+\dots+1/a_n)\dots)$. The output is normalized so that
! 1520: $a_n \neq 1$ (unless we also have $n = 0$).
! 1521:
! 1522: The number of partial quotients $n$ is limited to $nmax$. If $x$ is a real
! 1523: number, the expansion stops at the last significant partial quotient if $nmax$
! 1524: is omitted. $x$ can also be a rational function or a power series.
1.1 noro 1525:
1526: If a vector $b$ is supplied, the numerators will be equal to the coefficients
1.2 ! noro 1527: of $b$ (instead of all equal to $1$ as above). The length of the result is
! 1528: then equal to the length of $b$, unless a partial remainder is encountered
! 1529: which is equal to zero, in which case the expansion stops. In the case of real
! 1530: numbers, the stopping criterion is thus different from the one mentioned above
! 1531: since, if $b$ is too long, some partial quotients may not be significant.
1.1 noro 1532:
1.2 ! noro 1533: If $b$ is an integer, the command is understood as \kbd{contfrac($x,nmax$)}.
1.1 noro 1534:
1.2 ! noro 1535: \syn{contfrac0}{x,b,nmax}. Also available are
! 1536: $\teb{gboundcf}(x,nmax)$, $\teb{gcf}(x)$, or $\teb{gcf2}(b,x)$, where $nmax$
1.1 noro 1537: is a C integer.
1538:
1539: \subsecidx{contfracpnqn}$(x)$: when $x$ is a vector or a one-row matrix, $x$
1540: is considered as the list of partial quotients $[a_0,a_1,\dots,a_n]$ of a
1541: rational number, and the result is the 2 by 2 matrix
1542: $[p_n,p_{n-1};q_n,q_{n-1}]$ in the standard notation of continued fractions,
1543: so $p_n/q_n=a_0+1/(a_1+\dots+1/a_n)\dots)$. If $x$ is a matrix with two rows
1544: $[b_0,b_1,\dots,b_n]$ and $[a_0,a_1,\dots,a_n]$, this is then considered as a
1545: generalized continued fraction and we have similarly
1546: $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
1547: usually has $b_0=1$.
1548:
1549: \syn{pnqn}{x}.
1550:
1551: \subsecidx{core}$(n,\{\fl=0\})$: if $n$ is a non-zero integer written as
1552: $n=df^2$ with $d$ squarefree, returns $d$. If $\fl$ is non-zero,
1553: returns the two-element row vector $[d,f]$.
1554:
1555: \syn{core0}{n,\fl}.
1556: Also available are
1557: $\teb{core}(n)$ (= \teb{core}$(n,0)$) and
1558: $\teb{core2}(n)$ (= \teb{core}$(n,1)$).
1559:
1560: \subsecidx{coredisc}$(n,\{\fl\})$: if $n$ is a non-zero integer written as
1561: $n=df^2$ with $d$ fundamental discriminant (including 1), returns $d$. If
1562: $\fl$ is non-zero, returns the two-element row vector $[d,f]$. Note that if
1563: $n$ is not congruent to 0 or 1 modulo 4, $f$ will be a half integer and not
1564: an integer.
1565:
1566: \syn{coredisc0}{n,\fl}.
1567: Also available are
1568: $\teb{coredisc}(n)$ (= \teb{coredisc}$(n,0)$) and
1569: $\teb{coredisc2}(n)$ (= \teb{coredisc}$(n,1)$).
1570:
1571: \subsecidx{dirdiv}$(x,y)$: $x$ and $y$ being vectors of perhaps different
1572: lengths but with $y[1]\neq 0$ considered as \idx{Dirichlet series}, computes
1573: the quotient of $x$ by $y$, again as a vector.
1574:
1575: \syn{dirdiv}{x,y}.
1576:
1577: \subsecidx{direuler}$(p=a,b,\var{expr},\{c\})$: computes the
1578: \idx{Dirichlet series} to $b$ terms of the \idx{Euler product} of
1579: expression \var{expr} as $p$ ranges through the primes from $a$ to $b$.
1580: \var{expr} must be a polynomial or rational function in another variable
1581: than $p$ (say $X$) and $\var{expr}(X)$ is understood as the Dirichlet
1582: series (or more precisely the local factor) $\var{expr}(p^{-s})$. If $c$ is
1583: present, output only the first $c$ coefficients in the series.
1584:
1585: \synt{direuler}{entree *ep, GEN a, GEN b, char *expr}
1586:
1587: \subsecidx{dirmul}$(x,y)$: $x$ and $y$ being vectors of perhaps different
1588: lengths considered as \idx{Dirichlet series}, computes the product of
1589: $x$ by $y$, again as a vector.
1590:
1591: \syn{dirmul}{x,y}.
1592:
1593: \subsecidx{divisors}$(x)$: creates a row vector whose components are the
1594: positive divisors of the integer $x$ in increasing order. The factorization
1595: of $x$ (as output by \tet{factor}) can be used instead.
1596:
1597: \syn{divisors}{x}.
1598:
1599: \subsecidx{eulerphi}$(x)$: Euler's $\phi$
1600: (totient)\sidx{Euler totient function} function of $|x|$, in other words
1601: $|(\Z/x\Z)^*|$. $x$ must be of type integer.
1602:
1603: \syn{phi}{x}.
1604:
1605: \subsecidx{factor}$(x,\{\var{lim}=-1\})$: general factorization function.
1606: If $x$ is of type integer, rational, polynomial or rational function, the
1607: result is a two-column matrix, the first column being the irreducibles
1608: dividing $x$ (prime numbers or polynomials), and the second the exponents.
1609: If $x$ is a vector or a matrix, the factoring is done componentwise (hence
1610: the result is a vector or matrix of two-column matrices). By definition,
1611: $0$ is factored as $0^1$.
1612:
1613: If $x$ is of type integer or rational, an argument \var{lim} can be
1614: added, meaning that we look only for factors up to \var{lim}, or to
1615: \kbd{primelimit}, whichever is lowest (except when $\var{lim}=0$ where the
1616: effect is identical to setting $\var{lim}=\kbd{primelimit}$). Hence in this
1617: case, the remaining part is not necessarily prime. See \tet{factorint} for
1618: more information about the algorithms used.
1619:
1620: The polynomials or rational functions to be factored must have scalar
1621: coefficients. In particular PARI does \var{not} know how to factor
1622: multivariate polynomials.
1623:
1624: Note that PARI tries to guess in a sensible way over which ring you want
1625: to factor. Note also that factorization of polynomials is done up to
1626: multiplication by a constant. In particular, the factors of rational
1627: polynomials will have integer coefficients, and the content of a polynomial
1628: or rational function is discarded and not included in the factorization. If
1629: you need it, you can always ask for the content explicitly:
1630:
1631: \bprog
1632: ? factor(t^2 + 5/2*t + 1)
1633: %1 =
1634: [2*t + 1 1]
1635:
1636: [t + 2 1]
1637:
1638: ? content(t^2 + 5/2*t + 1)
1639: %2 = 1/2
1640: @eprog
1641:
1642: \noindent See also \tet{factornf}.
1643:
1644: \syn{factor0}{x,\var{lim}}, where \var{lim} is a C integer.
1645: Also available are
1646: $\teb{factor}(x)$ (= $\teb{factor0}(x,-1)$),
1647: $\teb{smallfact}(x)$ (= $\teb{factor0}(x,0)$).
1648:
1.2 ! noro 1649: \subsecidx{factorback}$(f,\{e\},\{nf\})$: gives back the factored object
! 1650: corresponding to a factorization. If the last argument is of number field
! 1651: type (e.g.~created by \kbd{nfinit} or \kbd{bnfinit}), assume we are dealing
! 1652: with an ideal factorization in the number field. The resulting ideal product is
! 1653: given in HNF\sidx{Hermite normal form} form.
! 1654:
! 1655: If $e$ is present, $e$ and $f$ must be vectors of the same length ($e$ being
! 1656: integral), and the corresponding factorization is the product of the
! 1657: $f[i]^{e[i]}$.
! 1658:
! 1659: If not, and $f$ is vector, it is understood as in the preceding case with
! 1660: $e$ a vector of 1 (the product of the $f[i]$ is returned). Finally,
! 1661: $f$ can be a regular factorization, as produced with any \kbd{factor}
! 1662: command. A few examples:
! 1663: \bprog
! 1664: ? factorback([2,2; 3,1])
! 1665: %1 = 12
! 1666: ? factorback([2,2], [3,1])
! 1667: %2 = 12
! 1668: ? factorback([5,2,3])
! 1669: %3 = 30
! 1670: ? factorback([2,2], [3,1], nfinit(x^3+2))
! 1671: %4 =
! 1672: [16 0 0]
! 1673:
! 1674: [0 16 0]
! 1675:
! 1676: [0 0 16]
! 1677: ? nf = nfinit(x^2+1); fa = idealfactor(nf, 10)
! 1678: %5 =
! 1679: [[2, [1, 1]~, 2, 1, [1, 1]~] 2]
! 1680:
! 1681: [[5, [-2, 1]~, 1, 1, [2, 1]~] 1]
! 1682:
! 1683: [[5, [2, 1]~, 1, 1, [-2, 1]~] 1]
! 1684: ? factorback(fa)
! 1685: *** forbidden multiplication t_VEC * t_VEC.
! 1686: ? factorback(fa, nf)
! 1687: %6 =
! 1688: [10 0]
! 1689:
! 1690: [0 10]
1.1 noro 1691:
1.2 ! noro 1692: @eprog
! 1693: In the fourth example, $2$ and $3$ are interpreted as principal ideals in a
! 1694: cubic field. In the fifth one, \kbd{factorback(fa)} is meaningless since we
! 1695: forgot to indicate the number field, and the entries in the first column of
! 1696: \kbd{fa} can't be multiplied.
! 1697:
! 1698: \syn{factorback0}{f,e,\var{nf}}, where an omitted
! 1699: $\var{nf}$ or $e$ is entered as \kbd{NULL}. Also available is
! 1700: \tet{factorback}$(f,\var{nf})$ (case $e = \kbd{NULL}$) where an omitted
1.1 noro 1701: $\var{nf}$ is entered as \kbd{NULL}.
1702:
1703: \subsecidx{factorcantor}$(x,p)$: factors the polynomial $x$ modulo the
1704: prime $p$, using distinct degree plus
1705: \idx{Cantor-Zassenhaus}\sidx{Zassenhaus}. The coefficients of $x$ must be
1706: operation-compatible with $\Z/p\Z$. The result is a two-column matrix, the
1707: first column being the irreducible polynomials dividing $x$, and the second
1708: the exponents. If you want only the \var{degrees} of the irreducible
1709: polynomials (for example for computing an $L$-function), use
1710: $\kbd{factormod}(x,p,1)$. Note that the \kbd{factormod} algorithm is
1711: usually faster than \kbd{factorcantor}.
1712:
1713: \syn{factcantor}{x,p}.
1714:
1715: \subsecidx{factorff}$(x,p,a)$: factors the polynomial $x$ in the field
1716: $\F_q$ defined by the irreducible polynomial $a$ over $\F_p$. The
1717: coefficients of $x$ must be operation-compatible with $\Z/p\Z$. The result
1718: is a two-column matrix, the first column being the irreducible polynomials
1719: dividing $x$, and the second the exponents. It is recommended to use for
1720: the variable of $a$ (which will be used as variable of a polmod) a name
1721: distinct from the other variables used, so that a \kbd{lift()} of the
1722: result will be legible. If all the coefficients of $x$ are in $\F_p$, a much faster algorithm is applied, using the computation of isomorphisms between finite fields.
1723:
1724: \syn{factmod9}{x,p,a}.
1725:
1726: \subsecidx{factorial}$(x)$ or $x!$: factorial of $x$. The expression $x!$
1727: gives a result which is an integer, while $\kbd{factorial}(x)$ gives a real
1728: number.
1729:
1730: \syn{mpfact}{x} for $x!$ and
1731: $\teb{mpfactr}(x,\var{prec})$ for $\kbd{factorial}(x)$. $x$ must be a \kbd{long}
1732: integer and not a PARI integer.
1733:
1734: \subsecidx{factorint}$(n,\{\fl=0\})$: factors the integer n using a
1735: combination of the \idx{Shanks SQUFOF} and \idx{Pollard Rho} method (with
1736: modifications due to Brent), \idx{Lenstra}'s \idx{ECM} (with modifications by
1737: Montgomery), and \idx{MPQS} (the latter adapted from the \idx{LiDIA} code
1738: with the kind permission of the LiDIA maintainers), as well as a search for
1739: pure powers with exponents$\le 10$. The output is a two-column matrix as for
1740: \kbd{factor}.
1741:
1742: This gives direct access to the integer factoring engine called by most
1743: arithmetical functions. \fl\ is optional; its binary digits mean 1: avoid
1744: MPQS, 2: skip first stage ECM (we may still fall back to it later), 4: avoid
1745: Rho and SQUFOF, 8: don't run final ECM (as a result, a huge composite may be
1746: declared to be prime). Note that a (strong) probabilistic primality test is
1747: used; thus composites might (very rarely) not be detected.
1748:
1749: The machinery underlying this function is still in a somewhat experimental
1750: state, but should be much faster on average than pure ECM as used by all
1751: PARI versions up to 2.0.8, at the expense of heavier memory use. You are
1752: invited to play with the flag settings and watch the internals at work by
1753: using GP's \tet{debuglevel} default parameter (level 3 shows just the
1754: outline, 4 turns on time keeping, 5 and above show an increasing amount
1755: of internal details). If you see anything funny happening, please let
1756: us know.
1757:
1758: \syn{factorint}{n,\fl}.
1759:
1760: \subsecidx{factormod}$(x,p,\{\fl=0\})$: factors the polynomial $x$ modulo
1761: the prime integer $p$, using \idx{Berlekamp}. The coefficients of $x$ must be
1762: operation-compatible with $\Z/p\Z$. The result is a two-column matrix, the
1763: first column being the irreducible polynomials dividing $x$, and the second
1764: the exponents. If $\fl$ is non-zero, outputs only the \var{degrees} of the
1765: irreducible polynomials (for example, for computing an $L$-function). A
1766: different algorithm for computing the mod $p$ factorization is
1767: \kbd{factorcantor} which is sometimes faster.
1768:
1769: \syn{factormod}{x,p,\fl}. Also available are
1770: $\teb{factmod}(x,p)$ (which is equivalent to $\teb{factormod}(x,p,0)$) and
1771: $\teb{simplefactmod}(x,p)$ (= $\teb{factormod}(x,p,1)$).
1772:
1773: \subsecidx{fibonacci}$(x)$: $x^{\text{th}}$ Fibonacci number.
1774:
1775: \syn{fibo}{x}. $x$ must be a \kbd{long}.
1776:
1777: \subsecidx{ffinit}$(p,n,\{v=x\})$: computes a monic polynomial of degree
1778: $n$ which is irreducible over $\F_p$. For instance if
1779: \kbd{P = ffinit(3,2,y)}, you can represent elements in $\F_{3^2}$ as polmods
1.2 ! noro 1780: modulo \kbd{P}. Starting with version 2.2.3 this function use a fast variant
! 1781: of Adleman--Lenstra algorithm, and is much faster than in earlier versions.
1.1 noro 1782:
1783: \syn{ffinit}{p,n,v}, where $v$ is a variable number.
1784:
1.2 ! noro 1785: \subsecidx{gcd}$(x,\{y\},\{\fl=0\})$: creates the greatest common divisor of $x$
1.1 noro 1786: and $y$. $x$ and $y$ can be of quite general types, for instance both
1787: rational numbers. Vector/matrix types are also accepted, in which case
1788: the GCD is taken recursively on each component. Note that for these
1.2 ! noro 1789: types, \kbd{gcd} is not commutative. \fl\ is obsolete and should not be used.
! 1790:
! 1791: If $y$ is omitted and $x$ is a vector, return the $\text{gcd}$ of all
! 1792: components of $x$. The algorithm used is a naive \idx{Euclid} except for the
! 1793: following inputs:
1.1 noro 1794:
1.2 ! noro 1795: $\bullet$ integers: use modified right-shift binary (``plus-minus''
! 1796: variant).
1.1 noro 1797:
1.2 ! noro 1798: $\bullet$ univariate polynomials with coeffients in the same number
! 1799: field (in particular rational): use modular gcd algorithm.
1.1 noro 1800:
1.2 ! noro 1801: $\bullet$ general polynomials: use the \idx{subresultant algorithm} if
! 1802: coefficient explosion is likely (exact, non modular, coefficients).
1.1 noro 1803:
1.2 ! noro 1804: \syn{ggcd}{x,y}. For general polynomial inputs, $\teb{srgcd}(x,y)$ is also
! 1805: available. For univariate {\it rational} polynomials, one also has
! 1806: $\teb{modulargcd}(x,y)$.
1.1 noro 1807:
1808: \subsecidx{hilbert}$(x,y,\{p\})$: \idx{Hilbert symbol} of $x$ and $y$ modulo
1809: $p$. If $x$ and $y$ are of type integer or fraction, an explicit third
1810: parameter $p$ must be supplied, $p=0$ meaning the place at infinity.
1811: Otherwise, $p$ needs not be given, and $x$ and $y$ can be of compatible types
1.2 ! noro 1812: integer, fraction, real, integermod a prime (result is undefined if the
! 1813: modulus is not prime), or $p$-adic.
1.1 noro 1814:
1815: \syn{hil}{x,y,p}.
1816:
1817: \subsecidx{isfundamental}$(x)$: true (1) if $x$ is equal to 1 or to the
1818: discriminant of a quadratic field, false (0) otherwise.
1819:
1820: \syn{gisfundamental}{x}, but the
1821: simpler function $\teb{isfundamental}(x)$ which returns a \kbd{long}
1822: should be used if $x$ is known to be of type integer.
1823:
1.2 ! noro 1824: \subsecidx{isprime}$(x,\{\fl=0\})$: true (1) if $x$ is a (proven) prime
! 1825: number, false (0) otherwise. This can be very slow when $x$ is indeed
! 1826: prime and has more than $1000$ digits, say. Use \tet{ispseudoprime} to
! 1827: quickly check for pseudo primality.
! 1828:
! 1829: If $\fl=0$, use a combination of Baillie-PSW pseudo primality test (see
! 1830: \tet{ispseudoprime}), Selfridge ``$p-1$'' test if $x-1$ is smooth enough, and
! 1831: Adleman-Pomerance-Rumely-Cohen-Lenstra (APRCL) for general $x$.
! 1832:
! 1833: If $\fl=1$, use Selfridge-Pocklington-Lehmer ``$p-1$'' test and output a
! 1834: primality certificate as follows: return 0 if $x$ is composite, 1 if $x$ is
! 1835: small enough that passing Baillie-PSW test guarantees its primality
! 1836: (currently $x < 10^{13}$), $2$ if $x$ is a large prime whose primality could
! 1837: only sensibly be proven (given the algorithms implemented in PARI) using the
! 1838: APRCL test. Otherwise ($x$ is large and $x-1$ is smooth) output a three
! 1839: column matrix as a primality certificate. The first column contains the prime
! 1840: factors $p$ of $x-1$, the second the corresponding elements $a_p$ as in
! 1841: Proposition~8.3.1 in GTM~138, and the third the output of isprime(p,1). The
! 1842: algorithm fails if one of the pseudo-prime factors is not prime, which is
! 1843: exceedingly unlikely (and well worth a bug report).
1.1 noro 1844:
1.2 ! noro 1845: If $\fl=2$, use APRCL.
1.1 noro 1846:
1847: \syn{gisprime}{x,\fl}, but the simpler function $\teb{isprime}(x)$
1848: which returns a \kbd{long} should be used if $x$ is known to be of
1849: type integer.
1850:
1851:
1.2 ! noro 1852: \subsecidx{ispseudoprime}$(x,\{\fl\})$: true (1) if $x$ is a strong pseudo
! 1853: prime (see below), false (0) otherwise. If this function returns false, $x$
! 1854: is not prime; if, on the other hand it returns true, it is only highly likely
! 1855: that $x$ is a prime number. Use \tet{isprime} (which is of course much
! 1856: slower) to prove that $x$ is indeed prime.
! 1857:
! 1858: If $\fl = 0$, checks whether $x$ is a Baillie-Pomerance-Selfridge-Wagstaff
! 1859: pseudo prime (strong Rabin-Miller pseudo prime for base $2$, with
! 1860: end-matching to catch square roots of $-1$, followed by strong Lucas test for
! 1861: the sequence $(P,-1)$, $P$ smallest positive integer such that $P^2 - 4$ is
! 1862: not a square mod $x$).
! 1863:
! 1864: There are no known composite numbers passing this test, although it is
! 1865: expected that infinitely such numbers exist.
! 1866:
! 1867: If $\fl > 0$, checks whether $x$ is a strong Miller-Rabin pseudo prime (with
! 1868: end-matching) for $\fl$ randomly chosen bases.
1.1 noro 1869:
1.2 ! noro 1870: \syn{gispseudoprime}{x,\fl}, but the simpler function $\teb{ispseudoprime}(x)$
! 1871: which returns a \kbd{long} should be used if $x$ is known to be of type
! 1872: integer.
1.1 noro 1873:
1874: \subsecidx{issquare}$(x,\{\&n\})$: true (1) if $x$ is square, false (0) if
1875: not. $x$ can be of any type. If $n$ is given and an exact square root had to
1876: be computed in the checking process, puts that square root in $n$. This is in
1877: particular the case when $x$ is an integer or a polynomial. This is \var{not}
1878: the case for intmods (use quadratic reciprocity) or series (only check the
1879: leading coefficient).
1880:
1881: \syn{gcarrecomplet}{x,\&n}. Also available is $\teb{gcarreparfait}(x)$.
1882:
1883: \subsecidx{issquarefree}$(x)$: true (1) if $x$ is squarefree, false (0) if not.
1884: Here $x$ can be an integer or a polynomial.
1885:
1886: \syn{gissquarefree}{x}, but the simpler function $\teb{issquarefree}(x)$
1887: which returns a \kbd{long} should be used if $x$ is known to be of type
1888: integer. This \teb{issquarefree} is just the square of the
1889: \idx{Moebius} function, and is computed as a multiplicative
1890: arithmetic function much like the latter.
1891:
1892: \subsecidx{kronecker}$(x,y)$:
1893: Kronecker\sidx{Kronecker symbol}\sidx{Legendre symbol}
1894: (i.e.~generalized Legendre) symbol $\left(\dfrac{x}{y}\right)$. $x$ and $y$
1895: must be of type integer.
1896:
1897: \syn{kronecker}{x,y}, the result ($0$ or $\pm 1$) is a \kbd{long}.
1898:
1.2 ! noro 1899: \subsecidx{lcm}$(x,\{y\})$: least common multiple of $x$ and $y$, i.e.~such
1.1 noro 1900: that $\text{lcm}(x,y)*\text{gcd}(x,y)=\text{abs}(x*y)$.
1901:
1.2 ! noro 1902: If $y$ is omitted and $x$ is a vector, return the $\text{lcm}$ of all
! 1903: components of $x$.
! 1904:
1.1 noro 1905: \syn{glcm}{x,y}.
1906:
1907: \subsecidx{moebius}$(x)$: \idx{Moebius} $\mu$-function of $|x|$. $x$ must
1908: be of type integer.
1909:
1910: \syn{mu}{x}, the result ($0$ or $\pm 1$) is a \kbd{long}.
1911:
1912: \subsecidx{nextprime}$(x)$: finds the smallest prime greater than or
1913: equal to $x$. $x$ can be of any real type. Note that if $x$ is a prime,
1914: this function returns $x$ and not the smallest prime strictly larger than $x$.
1915:
1916: \syn{nextprime}{x}.
1917:
1918: \subsecidx{numdiv}$(x)$: number of divisors of $|x|$. $x$ must be of type
1.2 ! noro 1919: integer.
1.1 noro 1920:
1921: \syn{numbdiv}{x}.
1922:
1923: \subsecidx{omega}$(x)$: number of distinct prime divisors of $|x|$. $x$
1924: must be of type integer.
1925:
1926: \syn{omega}{x}, the result is a \kbd{long}.
1927:
1928: \subsecidx{precprime}$(x)$: finds the largest prime less than or equal to
1929: $x$. $x$ can be of any real type. Returns 0 if $x\le1$.
1930: Note that if $x$ is a prime, this function returns $x$ and not the largest
1931: prime strictly smaller than $x$.
1932:
1933: \syn{precprime}{x}.
1934:
1935: \subsecidx{prime}$(x)$: the $x^{\text{th}}$ prime number, which must be among
1936: the precalculated primes.
1937:
1938: \syn{prime}{x}. $x$ must be a \kbd{long}.
1939:
1940: \subsecidx{primes}$(x)$: creates a row vector whose components
1941: are the first $x$ prime numbers, which must be among the precalculated primes.
1942:
1943: \syn{primes}{x}. $x$ must be a \kbd{long}.
1944:
1.2 ! noro 1945: \subsecidx{qfbclassno}$(D,\{\fl=0\})$: ordinary class number of the quadratic
! 1946: order of discriminant $D$. In the present version \vers, a $O(D^{1/2})$
! 1947: algorithm is used for $D > 0$ (using Euler product and the functional
! 1948: equation) so $D$ should not be too large, say $D < 10^8$, for the time to be
! 1949: reasonable. On the other hand, for $D < 0$ one can reasonably compute
! 1950: \kbd{qfbclassno($D$)} for $|D|<10^{25}$, since the routine uses
! 1951: \idx{Shanks}'method which is in $O(|D|^{1/4})$. For larger values of $|D|$,
! 1952: see \kbd{quadclassunit}, which unfortunately works reliably only for
! 1953: fundamental discriminants.
1.1 noro 1954:
1955: If $\fl=1$, compute the class number using \idx{Euler product}s and the
1.2 ! noro 1956: functional equation. However, it is in $O(|D|^{1/2})$.
1.1 noro 1957:
1.2 ! noro 1958: \misctitle{Important warning.} For $D < 0$, this function often gives
1.1 noro 1959: incorrect results when the class group is non-cyclic, because the authors
1960: were too lazy to implement \idx{Shanks}' method completely. It is therefore
1.2 ! noro 1961: strongly recommended to use either the version with $\fl = 1$, the function
! 1962: $\kbd{qfbhclassno}(-D)$ if $D$ is known to be a fundamental discriminant, or
1.1 noro 1963: the function \kbd{quadclassunit}.
1964:
1.2 ! noro 1965: \misctitle{Warning.} contrary to what its name implies, this routine does not
! 1966: compute the number of classes of binary primitive forms of discriminant $D$,
! 1967: which is equal to the \var{narrow} class number. The two notions are the same
! 1968: when $D < 0$ or the fundamental unit $\varepsilon$ has negative norm; when $D
! 1969: > 0$ and $N\varepsilon > 0$, the number of classes of forms is twice the
! 1970: ordinary class number. This is a problem which we cannot fix for backward
! 1971: compatibility reasons. Use the following routine if you are only interested
! 1972: in the number of classes of form:
! 1973: \bprog
! 1974: QFBclassno(D) =
! 1975: qfbclassno(D) * if (D < 0 || norm(quadunit(D)) < 0, 1, 2)
! 1976: @eprog
! 1977: \noindent Here are a few examples, including an erroneous answer:
! 1978: \bprog
! 1979: ? qfbclassno(400000028)
! 1980: time = 3,140 ms.
! 1981: %1 = 1
! 1982: ? quadclassunit(400000028).no
! 1983: time = 20 ms. \\@com{ much faster}
! 1984: %2 = 1
! 1985: ? qfbclassno(-400000028)
! 1986: time = 0 ms.
! 1987: %3 = 7253 \\@com{ correct, and fast enough}
! 1988: ? quadclassunit(-400000028).no
! 1989: *** Warning: not a fundamental discriminant in quadclassunit.
! 1990: time = 0 ms.
! 1991: %4 = 7253
! 1992: ? qfbclassno(-2878367)
! 1993: time = 0 ms.
! 1994: %6 = 1056 \\@com{ This is wrong! Correct answer is $1152$}
! 1995: (14:40) gp > quadclassunit(-2878367)
! 1996: time = 10 ms.
! 1997: %7 = [1152, [48, 24], [Qfb(647, 189, 1126), Qfb(2, 1, 359796)], 1, 1.000250]
! 1998: @eprog
! 1999:
! 2000: \syn{qfbclassno0}{D,\fl}. Also available:
! 2001: $\teb{classno}(D)$ (= $\teb{qfbclassno}(D)$),
! 2002: $\teb{classno2}(D)$ (= $\teb{qfbclassno}(D,1)$), and finally
! 2003: there exists the function $\teb{hclassno}(D)$ which computes the class
! 2004: number of an imaginary quadratic field by counting reduced forms, an $O(|D|)$
1.1 noro 2005: algorithm. See also \kbd{qfbhclassno}.
2006:
2007: \subsecidx{qfbcompraw}$(x,y)$ \idx{composition} of the binary quadratic forms
2008: $x$ and $y$, without \idx{reduction} of the result. This is useful e.g.~to
2009: compute a generating element of an ideal.
2010:
2011: \syn{compraw}{x,y}.
2012:
2013: \subsecidx{qfbhclassno}$(x)$: \idx{Hurwitz class number} of $x$, where $x$ is
2014: non-negative and congruent to 0 or 3 modulo 4. See also \kbd{qfbclassno}.
2015:
2016: \syn{hclassno}{x}.
2017:
2018: \subsecidx{qfbnucomp}$(x,y,l)$: \idx{composition} of the primitive positive
2019: definite binary quadratic forms $x$ and $y$ using the NUCOMP and NUDUPL
2020: algorithms of \idx{Shanks} (\`a la Atkin). $l$ is any positive constant,
2021: but for optimal speed, one should take $l=|D|^{1/4}$, where $D$ is the common
1.2 ! noro 2022: discriminant of $x$ and $y$. When $x$ and $y$ do not have the same
! 2023: discriminant, the result is undefined.
1.1 noro 2024:
2025: \syn{nucomp}{x,y,l}. The auxiliary function
2026: $\teb{nudupl}(x,l)$ should be used instead for speed when $x=y$.
2027:
2028: \subsecidx{qfbnupow}$(x,n)$: $n$-th power of the primitive positive definite
2029: binary quadratic form $x$ using the NUCOMP and NUDUPL algorithms (see
2030: \kbd{qfbnucomp}).
2031:
2032: \syn{nupow}{x,n}.
2033:
2034: \subsecidx{qfbpowraw}$(x,n)$: $n$-th power of the binary quadratic form
2035: $x$, computed without doing any \idx{reduction} (i.e.~using \kbd{qfbcompraw}).
2036: Here $n$ must be non-negative and $n<2^{31}$.
2037:
2038: \syn{powraw}{x,n} where $n$ must be a \kbd{long}
2039: integer.
2040:
2041: \subsecidx{qfbprimeform}$(x,p)$: prime binary quadratic form of discriminant
2042: $x$ whose first coefficient is the prime number $p$. By abuse of notation,
2043: $p = 1$ is a valid special case which returns the unit form. Returns an
2044: error if $x$ is not a quadratic residue mod $p$. In the case where $x>0$,
2045: the ``distance'' component of the form is set equal to zero according to
2046: the current precision.
2047:
2048: \syn{primeform}{x,p,\var{prec}}, where the third variable $\var{prec}$ is a
2049: \kbd{long}, but is only taken into account when $x>0$.
2050:
2051: \subsecidx{qfbred}$(x,\{\fl=0\},\{D\},\{\var{isqrtD}\},\{\var{sqrtD}\})$:
2052: reduces the binary quadratic form $x$ (updating Shanks's distance function
2053: if $x$ is indefinite). The binary digits of $\fl$ are toggles meaning
2054:
2055: \quad 1: perform a single \idx{reduction} step
2056:
2057: \quad 2: don't update \idx{Shanks}'s distance
2058:
2059: $D$, \var{isqrtD}, \var{sqrtD}, if present, supply the values of the
2060: discriminant, $\lfloor \sqrt{D}\rfloor$, and $\sqrt{D}$ respectively
2061: (no checking is done of these facts). If $D<0$ these values are useless,
2062: and all references to Shanks's distance are irrelevant.
2063:
2064: \syn{qfbred0}{x,\fl,D,\var{isqrtD},\var{sqrtD}}. Use \kbd{NULL}
2065: to omit any of $D$, \var{isqrtD}, \var{sqrtD}.
2066:
2067: \noindent Also available are
2068:
2069: $\teb{redimag}(x)$ (= $\teb{qfbred}(x)$ where $x$ is definite),
2070:
2071: \noindent and for indefinite forms:
2072:
2073: $\teb{redreal}(x)$ (= $\teb{qfbred}(x)$),
2074:
2075: $\teb{rhoreal}(x)$ (= $\teb{qfbred}(x,1)$),
2076:
2077: $\teb{redrealnod}(x,sq)$ (= $\teb{qfbred}(x,2,,isqrtD)$),
2078:
2079: $\teb{rhorealnod}(x,sq)$ (= $\teb{qfbred}(x,3,,isqrtD)$).
2080:
2081: \subsecidx{quadclassunit}$(D,\{\fl=0\},\{\var{tech}=[]\})$:
2082: \idx{Buchmann-McCurley}'s sub-exponential algorithm for computing the class
2083: group of a quadratic field of discriminant $D$. If $D$ is not fundamental,
2084: the function may or may not be defined, but usually is, and often gives the
2085: right answer (a warning is issued). The more general function \tet{bnrinit}
2086: should be used to compute the class group of an order.
2087:
2088: This function should be used instead of \kbd{qfbclassno} or \kbd{quadregula}
2089: when $D<-10^{25}$, $D>10^{10}$, or when the \var{structure} is wanted.
2090:
2091: If $\fl$ is non-zero \var{and} $D>0$, computes the narrow class group and
2092: regulator, instead of the ordinary (or wide) ones. In the current version
2093: \vers, this doesn't work at all~: use the general function \tet{bnfnarrow}.
2094:
2095: Optional parameter \var{tech} is a row vector of the form
2096: $[c_1,c_2]$, where $c_1$ and $c_2$ are positive real numbers which
2097: control the execution time and the stack size. To get maximum speed,
2098: set $c_2=c$. To get a rigorous result (under \idx{GRH}) you must take
2099: $c_2=6$. Reasonable values for $c$ are between $0.1$ and $2$.
2100:
2101: The result of this function is a vector $v$ with 4 components if $D<0$, and
2102: $5$ otherwise. The correspond respectively to
2103:
2104: $\bullet$ $v[1]$~: the class number
2105:
2106: $\bullet$ $v[2]$~: a vector giving the structure of the class group as a
2107: product of cyclic groups;
2108:
2109: $\bullet$ $v[3]$~: a vector giving generators of those cyclic groups (as
2110: binary quadratic forms).
2111:
2112: $\bullet$ $v[4]$~: (omitted if $D < 0$) the regulator, computed to an
2113: accuracy which is the maximum of an internal accuracy determined by the
2114: program and the current default (note that once the regulator is known to a
2115: small accuracy it is trivial to compute it to very high accuracy, see the
2116: tutorial).
2117:
2118: $\bullet$ $v[5]$~: a measure of the correctness of the result. If it is
2119: close to 1, the result is correct (under \idx{GRH}). If it is close to a
2120: larger integer, this shows that the class number is off by a factor equal
2121: to this integer, and you must start again with a larger value for $c_1$ or
2122: a different random seed. In this case, a warning message is printed.
2123:
2124: \syn{quadclassunit0}{D,\fl,tech}. Also available are
2125: $\teb{buchimag}(D,c_1,c_2)$ and $\teb{buchreal}(D,\fl,c_1,c_2)$.
2126:
2127: \subsecidx{quaddisc}$(x)$: discriminant of the quadratic field
2128: $\Q(\sqrt{x})$, where $x\in\Q$.
2129:
2130: \syn{quaddisc}{x}.
2131:
2132: \subsecidx{quadhilbert}$(D,\{\fl=0\})$: relative equation defining the
2133: \idx{Hilbert class field} of the quadratic field of discriminant $D$.
2134: If $\fl$ is non-zero
2135: and $D<0$, outputs $[\var{form},\var{root}(\var{form})]$ (to be used for
2136: constructing subfields). If $\fl$ is non-zero and $D>0$, try hard to
2137: get the best modulus.
2138: Uses complex multiplication in the imaginary case and \idx{Stark units}
2139: in the real case.
2140:
2141: \syn{quadhilbert}{D,\fl,\var{prec}}.
2142:
2143: \subsecidx{quadgen}$(x)$: creates the quadratic number\sidx{omega}
2144: $\omega=(a+\sqrt{x})/2$ where $a=0$ if $x\equiv0\mod4$,
2145: $a=1$ if $x\equiv1\mod4$, so that $(1,\omega)$ is an integral basis for
2146: the quadratic order of discriminant $x$. $x$ must be an integer congruent to
2147: 0 or 1 modulo 4.
2148:
2149: \syn{quadgen}{x}.
2150:
2151: \subsecidx{quadpoly}$(D,\{v=x\})$: creates the ``canonical'' quadratic
2152: polynomial (in the variable $v$) corresponding to the discriminant $D$,
2153: i.e.~the minimal polynomial of $\kbd{quadgen}(x)$. $D$ must be an integer
2154: congruent to 0 or 1 modulo 4.
2155:
2156: \syn{quadpoly0}{x,v}.
2157:
2158: \subsecidx{quadray}$(D,f,\{\fl=0\})$: relative equation for the ray class
2159: field of conductor $f$ for the quadratic field of discriminant $D$ (which
2160: can also be a \kbd{bnf}), using analytic methods.
2161:
2162: For $D<0$, uses the $\sigma$ function. $\fl$ has the following meaning: if
2163: it's an odd integer, outputs instead the vector of $[\var{ideal},
2164: \var{corresponding root}]$. It can also be a two-component vector
2165: $[\lambda,\fl]$, where \fl\ is as above and $\lambda$ is the technical
2166: element of \kbd{bnf} necessary for Schertz's method. In that case, returns
2167: 0 if $\lambda$ is not suitable.
2168:
2169: For $D>0$, uses Stark's conjecture. If $\fl$ is non-zero, try hard to
2170: get the best modulus. The function may fail with the following message
2171: \bprog
2172: "Cannot find a suitable modulus in FindModulus"
2173: @eprog
2174: See \tet{bnrstark} for more details about the real case.
2175:
2176: \syn{quadray}{D,f,\fl}.
2177:
2178: \subsecidx{quadregulator}$(x)$: regulator of the quadratic field of
2179: positive discriminant $x$. Returns an error if $x$ is not a discriminant
2180: (fundamental or not) or if $x$ is a square. See also \kbd{quadclassunit} if
2181: $x$ is large.
2182:
2183: \syn{regula}{x,\var{prec}}.
2184:
2185: \subsecidx{quadunit}$(x)$: fundamental unit\sidx{fundamental units} of the
2186: real quadratic field $\Q(\sqrt x)$ where $x$ is the positive discriminant
2187: of the field. If $x$ is not a fundamental discriminant, this probably gives
2188: the fundamental unit of the corresponding order. $x$ must be of type
2189: integer, and the result is a quadratic number.
2190:
2191: \syn{fundunit}{x}.
2192:
2193: \subsecidx{removeprimes}$(\{x=[\,]\})$: removes the primes listed in $x$ from
2194: the prime number table. In particular \kbd{removeprimes(addprimes)} empties
2195: the extra prime table. $x$ can also be a single integer. List the current
2196: extra primes if $x$ is omitted.
2197:
2198: \syn{removeprimes}{x}.
2199:
2200: \subsecidx{sigma}$(x,\{k=1\})$: sum of the $k^{\text{th}}$ powers of the
2201: positive divisors of $|x|$. $x$ must be of type integer.
2202:
2203: \syn{sumdiv}{x} (= $\teb{sigma}(x)$) or $\teb{gsumdivk}(x,k)$ (=
2204: $\teb{sigma}(x,k)$), where $k$ is a C long integer.
2205:
2206: \subsecidx{sqrtint}$(x)$: integer square root of $x$, which must be of PARI
2207: type integer. The result is non-negative and rounded towards zero. A
2208: negative $x$ is allowed, and the result in that case is \kbd{I*sqrtint(-x)}.
2209:
2210: \syn{racine}{x}.
2211:
2212: \subsecidx{znlog}$(x,g)$: $g$ must be a primitive root mod a prime $p$, and
2213: the result is the discrete log of $x$ in the multiplicative group
2214: $(\Z/p\Z)^*$. This function uses a simple-minded combination of
2215: Pohlig-Hellman algorithm and Shanks baby-step/giant-step which requires
2216: $O(\sqrt{q})$ storage, where $q$ is the largest prime factor of $p-1$. Hence
2217: it cannot be used when the largest prime divisor of $p-1$ is greater than
2218: about $10^{13}$.
2219:
2220: \syn{znlog}{x,g}.
2221:
2222: \subsecidx{znorder}$(x)$: $x$ must be an integer mod $n$, and the result is the
2223: order of $x$ in the multiplicative group $(\Z/n\Z)^*$. Returns an error if $x$
2224: is not invertible.
2225:
2226: \syn{order}{x}.
2227:
2228: \subsecidx{znprimroot}$(n)$: returns a primitive root (generator) of
2229: $(\Z/n\Z)^*$, whenever this latter group is cyclic ($n = 4$ or $n = 2p^k$ or
2230: $n = p^k$, where $p$ is an odd prime and $k \geq 0$).
2231:
2232: \syn{gener}{x}.
2233:
2234: \subsecidx{znstar}$(n)$: gives the structure of the multiplicative group
2235: $(\Z/n\Z)^*$ as a 3-component row vector $v$, where $v[1]=\phi(n)$ is the
2236: order of that group, $v[2]$ is a $k$-component row-vector $d$ of integers
2237: $d[i]$ such that $d[i]>1$ and $d[i]\mid d[i-1]$ for $i \ge 2$ and
2238: $(\Z/n\Z)^* \simeq \prod_{i=1}^k(\Z/d[i]\Z)$, and $v[3]$ is a $k$-component row
2239: vector giving generators of the image of the cyclic groups $\Z/d[i]\Z$.
2240:
2241: \syn{znstar}{n}.
2242:
2243: \section{Functions related to elliptic curves}
2244:
2245: We have implemented a number of functions which are useful for number
2246: theorists working on elliptic curves. We always use \idx{Tate}'s notations.
2247: The functions assume that the curve is given by a general Weierstrass
2248: model\sidx{Weierstrass equation}
2249: $$
2250: y^2+a_1xy+a_3y=x^3+a_2x^2+a_4x+a_6,
2251: $$
2252: where a priori the $a_i$ can be of any scalar type. This curve can be
2253: considered as a five-component vector \kbd{E=[a1,a2,a3,a4,a6]}. Points on
2254: \kbd{E} are represented as two-component vectors \kbd{[x,y]}, except for the
2255: point at infinity, i.e.~the identity element of the group law, represented by
2256: the one-component vector \kbd{[0]}.
2257:
2258: It is useful to have at one's disposal more information. This is given by
2259: the function \tet{ellinit} (see there), which usually gives a 19 component
2260: vector (which we will call a long vector in this section). If a specific flag
2261: is added, a vector with only 13 component will be output (which we will call
2262: a medium vector). A medium vector just gives the first 13 components of the
2263: long vector corresponding to the same curve, but is of course faster to
2264: compute. The following \idx{member functions} are available to deal with the
2265: output of \kbd{ellinit}:
2266: \settabs\+xxxxxxxxxxxxxxxxxx&: &\cr
2267:
2268: \+ \kbd{a1}--\kbd{a6}, \kbd{b2}--\kbd{b8}, \kbd{c4}--\kbd{c6} &: &
2269: coefficients of the elliptic curve.\cr
2270:
2271: \+ \tet{area} &: & volume of the complex lattice defining $E$.\cr
2272:
2273: \+ \tet{disc} &: & discriminant of the curve.\cr
2274:
2275: \+ \tet{j} &: & $j$-invariant of the curve.\cr
2276:
2277: \+ \tet{omega}&: & $[\omega_1,\omega_2]$, periods forming a basis of
2278: the complex lattice defining $E$ ($\omega_1$ is the\cr
2279:
2280: \+ & & real period, and $\omega_2/\omega_1$ belongs to
2281: Poincar\'e's half-plane).\cr
2282:
2283: \+ \tet{eta} &: & quasi-periods $[\eta_1, \eta_2]$, such that
2284: $\eta_1\omega_2-\eta_2\omega_1=i\pi$.\cr
2285:
2286: \+ \tet{roots}&: & roots of the associated Weierstrass equation.\cr
2287:
2288: \+ \tet{tate} &: & $[u^2,u,v]$ in the notation of Tate.\cr
2289:
2290: \+ \tet{w} &: & Mestre's $w$ (this is technical).\cr
2291:
2292: Their use is best described by an example: assume that $E$ was output by
2293: \kbd{ellinit}, then typing \kbd{$E$.disc} will retrieve the curve's
2294: discriminant. The member functions \kbd{area}, \kbd{eta} and \kbd{omega} are
2295: only available for curves over $\Q$. Conversely, \kbd{tate} and \kbd{w} are
2296: only available for curves defined over $\Q_p$.\smallskip
2297:
2298: Some functions, in particular those relative to height computations (see
2299: \kbd{ellheight}) require also that the curve be in minimal Weierstrass
1.2 ! noro 2300: form. This is achieved by the function \kbd{ellminimalmodel}.
1.1 noro 2301:
2302: All functions related to elliptic curves share the prefix \kbd{ell}, and the
2303: precise curve we are interested in is always the first argument, in either
2304: one of the three formats discussed above, unless otherwise specified. For
2305: instance, in functions which do not use the extra information given by long
2306: vectors, the curve can be given either as a five-component vector, or by one
2307: of the longer vectors computed by \kbd{ellinit}.
2308:
2309: \subsecidx{elladd}$(E,z1,z2)$: sum of the points $z1$ and $z2$ on the
2310: elliptic curve corresponding to the vector $E$.
2311:
2312: \syn{addell}{E,z1,z2}.
2313:
2314: \subsecidx{ellak}$(E,n)$: computes the coefficient $a_n$ of the
2315: $L$-function of the elliptic curve $E$, i.e.~in principle coefficients of a
2316: newform of weight 2 assuming \idx{Taniyama-Weil conjecture} (which is now
2317: known to hold in full generality thanks to the work of \idx{Breuil},
2318: \idx{Conrad}, \idx{Diamond}, \idx{Taylor} and \idx{Wiles}). $E$ must be a
2319: medium or long vector of the type given by \kbd{ellinit}. For this function
2320: to work for every $n$ and not just those prime to the conductor, $E$ must
2321: be a minimal Weierstrass equation. If this is not the case, use the
1.2 ! noro 2322: function \kbd{ellminimalmodel} first before using \kbd{ellak}.
1.1 noro 2323:
2324: \syn{akell}{E,n}.
2325:
2326: \subsecidx{ellan}$(E,n)$: computes the vector of the first $n$ $a_k$
2327: corresponding to the elliptic curve $E$. All comments in \kbd{ellak}
2328: description remain valid.
2329:
2330: \syn{anell}{E,n}, where $n$ is a C integer.
2331:
2332: \subsecidx{ellap}$(E,p,\{\fl=0\})$: computes the $a_p$ corresponding to the
2333: elliptic curve $E$ and the prime number $p$. These are defined by the
2334: equation $\#E(\F_p) = p+1 - a_p$, where $\#E(\F_p)$ stands for the number
2335: of points of the curve $E$ over the finite field $\F_p$. When $\fl$ is $0$,
2336: this uses the baby-step giant-step method and a trick due to Mestre. This
2337: runs in time $O(p^{1/4})$ and requires $O(p^{1/4})$ storage, hence becomes
2338: unreasonable when $p$ has about 30 digits.
2339:
2340: If $\fl$ is $1$, computes the $a_p$ as a sum of Legendre symbols. This is
2341: slower than the previous method as soon as $p$ is greater than 100, say.
2342:
2343: No checking is done that $p$ is indeed prime. $E$ must be a medium or long
2344: vector of the type given by \kbd{ellinit}, defined over $\Q$, $\F_p$ or
2345: $\Q_p$. $E$ must be given by a Weierstrass equation minimal at $p$.
2346:
2347: \syn{ellap0}{E,p,\fl}. Also available are $\teb{apell}(E,p)$, corresponding
2348: to $\fl=0$, and $\teb{apell2}(E,p)$ ($\fl=1$).
2349:
2350: \subsecidx{ellbil}$(E,z1,z2)$: if $z1$ and $z2$ are points on the elliptic
2351: curve $E$, this function computes the value of the canonical bilinear form on
2352: $z1$, $z2$:
2353: $$
2354: \kbd{ellheight}(E,z1\kbd{+}z2) - \kbd{ellheight}(E,z1) - \kbd{ellheight}(E,z2)
2355: $$
2356: where \kbd{+} denotes of course addition on $E$. In addition, $z1$ or $z2$
2357: (but not both) can be vectors or matrices. Note that this is equal to twice
2358: some normalizations. $E$ is assumed to be integral, given by a minimal model.
2359:
2360: \syn{bilhell}{E,z1,z2,\var{prec}}.
2361:
2362: \subsecidx{ellchangecurve}$(E,v)$: changes the data for the elliptic curve $E$
2363: by changing the coordinates using the vector \kbd{v=[u,r,s,t]}, i.e.~if $x'$
2364: and $y'$ are the new coordinates, then $x=u^2x'+r$, $y=u^3y'+su^2x'+t$.
2365: The vector $E$ must be a medium or long vector of the type given by
2366: \kbd{ellinit}.
2367:
2368: \syn{coordch}{E,v}.
2369:
2370: \subsecidx{ellchangepoint}$(x,v)$: changes the coordinates of the point or
2371: vector of points $x$ using the vector \kbd{v=[u,r,s,t]}, i.e.~if $x'$ and
2372: $y'$ are the new coordinates, then $x=u^2x'+r$, $y=u^3y'+su^2x'+t$ (see also
2373: \kbd{ellchangecurve}).
2374:
2375: \syn{pointch}{x,v}.
2376:
2377: \subsecidx{elleisnum}$(E,k,\{\fl=0\})$: $E$ being an elliptic curve as
2378: output by \kbd{ellinit} (or, alternatively, given by a 2-component vector
2379: $[\omega_1,\omega_2]$), and $k$ being an even positive integer, computes
2380: the numerical value of the Eisenstein series of weight $k$ at $E$. When
2381: \fl\ is non-zero and $k=4$ or 6, returns $g_2$ or $g_3$ with the correct
2382: normalization.
2383:
2384: \syn{elleisnum}{E,k,\fl}.
2385:
2386: \subsecidx{elleta}$(om)$: returns the two-component row vector
2387: $[\eta_1,\eta_2]$ of quasi-periods associated to $\kbd{om} = [\omega_1,
2388: \omega_2]$
2389:
2390: \syn{elleta}{om, \var{prec}}
2391:
2392: \subsecidx{ellglobalred}$(E)$: calculates the arithmetic conductor, the global
2393: minimal model of $E$ and the global \idx{Tamagawa number} $c$. Here $E$ is an
2394: elliptic curve given by a medium or long vector of the type given by
2395: \kbd{ellinit}, {\it and is supposed to have all its coefficients $a_i$ in}
2396: $\Q$. The result is a 3 component vector $[N,v,c]$. $N$ is the arithmetic
1.2 ! noro 2397: conductor of the curve. $v$ gives the coordinate change for $E$ over $\Q$ to
! 2398: the minimal integral model (see \tet{ellminimalmodel}). Finally $c$ is the
! 2399: product of the local Tamagawa numbers $c_p$, a quantity which enters in the
! 2400: \idx{Birch and Swinnerton-Dyer conjecture}.\sidx{minimal model}
1.1 noro 2401:
2402: \syn{globalreduction}{E}.
2403:
2404: \subsecidx{ellheight}$(E,z,\{\fl=0\})$: global \idx{N\'eron-Tate height} of
2405: the point $z$ on the elliptic curve $E$. The vector $E$ must be a long vector
2406: of the type given by \kbd{ellinit}, with $\fl=1$. If $\fl=0$, this
2407: computation is done using sigma and theta-functions and a trick due to J.
2408: Silverman. If $\fl=1$, use Tate's $4^n$ algorithm, which is much slower.
2409: $E$ is assumed to be integral, given by a minimal model.
2410:
2411: \syn{ellheight0}{E,z,\fl,\var{prec}}. The Archimedean
2412: contribution alone is given by the library function
2413: $\teb{hell}(E,z,\var{prec})$.
2414: Also available are $\teb{ghell}(E,z,\var{prec})$ ($\fl=0$) and
2415: $\teb{ghell2}(E,z,\var{prec})$ ($\fl=1$).
2416:
2417: \subsecidx{ellheightmatrix}$(E,x)$: $x$ being a vector of points, this
2418: function outputs the Gram matrix of $x$ with respect to the N\'eron-Tate
2419: height, in other words, the $(i,j)$ component of the matrix is equal to
2420: \kbd{ellbil($E$,x[$i$],x[$j$])}. The rank of this matrix, at least in some
2421: approximate sense, gives the rank of the set of points, and if $x$ is a
2422: basis of the \idx{Mordell-Weil group} of $E$, its determinant is equal to
2423: the regulator of $E$. Note that this matrix should be divided by 2 to be in
2424: accordance with certain normalizations. $E$ is assumed to be integral,
2425: given by a minimal model.
2426:
2427: \syn{mathell}{E,x,\var{prec}}.
2428:
2429: \subsecidx{ellinit}$(E,\{\fl=0\})$: computes some fixed data concerning the
2430: elliptic curve given by the five-component vector $E$, which will be
2431: essential for most further computations on the curve. The result is a
2432: 19-component vector E (called a long vector in this section), shortened
2433: to 13 components (medium vector) if $\fl=1$. Both contain the
2434: following information in the first 13 components:
2435: %
2436: $$ a_1,a_2,a_3,a_4,a_6,b_2,b_4,b_6,b_8,c_4,c_6,\Delta,j.$$
2437: %
2438: In particular, the discriminant is $E[12]$ (or \kbd{$E$.disc}), and the
2439: $j$-invariant is $E[13]$ (or \kbd{$E$.j}).
2440:
2441: The other six components are only present if $\fl$ is $0$ (or omitted!).
2442: Their content depends on whether the curve is defined over $\R$ or not:
2443: \smallskip
2444: $\bullet$ When $E$ is defined over $\R$, $E[14]$ (\kbd{$E$.roots}) is a
2445: vector whose three components contain the roots of the associated Weierstrass
2446: equation. If the roots are all real, then they are ordered by decreasing
2447: value. If only one is real, it is the first component of $E[14]$.
2448:
2449: $E[15]$ (\kbd{$E$.omega[1]}) is the real period of $E$ (integral of
2450: $dx/(2y+a_1x+a_3)$ over the connected component of the identity element of
2451: the real points of the curve), and $E[16]$ (\kbd{$E$.omega[2]}) is a complex
2452: period. In other words, $\omega_1=E[15]$ and $\omega_2=E[16]$ form a basis of
2453: the complex lattice defining $E$ (\kbd{$E$.omega}), with
2454: $\tau=\dfrac{\omega_2}{\omega_1}$ having positive imaginary part.
2455:
2456: $E[17]$ and $E[18]$ are the corresponding values $\eta_1$ and $\eta_2$ such
2457: that $\eta_1\omega_2-\eta_2\omega_1=i\pi$, and both can be retrieved by
2458: typing \kbd{$E$.eta} (as a row vector whose components are the $\eta_i$).
2459:
2460: Finally, $E[19]$ (\kbd{$E$.area}) is the volume of the complex lattice defining
2461: $E$.\smallskip
2462:
2463: $\bullet$ When $E$ is defined over $\Q_p$, the $p$-adic valuation of $j$
2464: must be negative. Then $E[14]$ (\kbd{$E$.roots}) is the vector with a single
2465: component equal to the $p$-adic root of the associated Weierstrass equation
2466: corresponding to $-1$ under the Tate parametrization.
2467:
2468: $E[15]$ is equal to the square of the $u$-value, in the notation of Tate.
2469:
2470: $E[16]$ is the $u$-value itself, if it belongs to $\Q_p$, otherwise zero.
2471:
2472: $E[17]$ is the value of Tate's $q$ for the curve $E$.
2473:
2474: \kbd{$E$.tate} will yield the three-component vector $[u^2,u,q]$.
2475:
2476: $E[18]$ (\kbd{$E$.w}) is the value of Mestre's $w$ (this is technical), and
2477: $E[19]$ is arbitrarily set equal to zero.
2478: \smallskip
2479: For all other base fields or rings, the last six components are arbitrarily
2480: set equal to zero (see also the description of member functions related to
2481: elliptic curves at the beginning of this section).
2482:
2483: \syn{ellinit0}{E,\fl,\var{prec}}. Also available are
2484: $\teb{initell}(E,\var{prec})$ ($\fl=0$) and
2485: $\teb{smallinitell}(E,\var{prec})$ ($\fl=1$).
2486:
2487: \subsecidx{ellisoncurve}$(E,z)$: gives 1 (i.e.~true) if the point $z$ is on
2488: the elliptic curve $E$, 0 otherwise. If $E$ or $z$ have imprecise coefficients,
2489: an attempt is made to take this into account, i.e.~an imprecise equality is
2490: checked, not a precise one.
2491:
2492: \syn{oncurve}{E,z}, and the result is a \kbd{long}.
2493:
2494: \subsecidx{ellj}$(x)$: elliptic $j$-invariant. $x$ must be a complex number
2495: with positive imaginary part, or convertible into a power series or a
2496: $p$-adic number with positive valuation.
2497:
2498: \syn{jell}{x,\var{prec}}.
2499:
2500: \subsecidx{elllocalred}$(E,p)$: calculates the \idx{Kodaira} type of the
2501: local fiber of the elliptic curve $E$ at the prime $p$.
2502: $E$ must be given by a medium or
2503: long vector of the type given by \kbd{ellinit}, and is assumed to have all
2504: its coefficients $a_i$ in $\Z$. The result is a 4-component vector
2505: $[f,kod,v,c]$. Here $f$ is the exponent of $p$ in the arithmetic conductor of
2506: $E$, and $kod$ is the Kodaira type which is coded as follows:
2507:
2508: 1 means good reduction (type I$_0$), 2, 3 and 4 mean types II, III and IV
2509: respectively, $4+\nu$ with $\nu>0$ means type I$_\nu$;
2510: finally the opposite values $-1$, $-2$, etc.~refer to the starred types
2511: I$_0^*$, II$^*$, etc. The third component $v$ is itself a vector $[u,r,s,t]$
2512: giving the coordinate changes done during the local reduction. Normally, this
2513: has no use if $u$ is 1, that is, if the given equation was already minimal.
2514: Finally, the last component $c$ is the local \idx{Tamagawa number} $c_p$.
2515:
2516: \syn{localreduction}{E,p}.
2517:
2518: \subsecidx{elllseries}$(E,s,\{A=1\})$: $E$ being a medium or long vector
2519: given by \kbd{ellinit}, this computes the value of the L-series of $E$ at
2520: $s$. It is assumed that $E$ is a minimal model over $\Z$ and that the curve
2521: is a modular elliptic curve. The optional parameter $A$ is a cutoff point for
2522: the integral, which must be chosen close to 1 for best speed. The result
2523: must be independent of $A$, so this allows some internal checking of the
2524: function.
2525:
2526: Note that if the conductor of the curve is large, say greater than $10^{12}$,
2527: this function will take an unreasonable amount of time since it uses an
2528: $O(N^{1/2})$ algorithm.
2529:
2530: \syn{lseriesell}{E,s,A,\var{prec}} where $\var{prec}$ is a \kbd{long} and an
2531: omitted $A$ is coded as \kbd{NULL}.
2532:
1.2 ! noro 2533: \subsecidx{ellminimalmodel}$(E,\{\&v\})$: return the standard minimal
! 2534: integral model of the rational elliptic curve $E$. If present, sets $v$ to the
! 2535: corresponding change of variables, which is a vector $[u,r,s,t]$ with
! 2536: rational components. The return value is identical to that of
! 2537: \kbd{ellchangecurve(E, v)}.
! 2538:
! 2539: The resulting model has integral coefficients, is everywhere minimal, $a_1$
! 2540: is 0 or 1, $a_2$ is 0, 1 or $-1$ and $a_3$ is 0 or 1. Such a model is unique,
! 2541: and the vector $v$ is unique if we specify that $u$ is positive, which we do.
! 2542: \sidx{minimal model}
! 2543:
! 2544: \syn{ellminimalmodel}{E,\&v}, where an omitted $v$ is coded as \kbd{NULL}.
! 2545:
1.1 noro 2546: \subsecidx{ellorder}$(E,z)$: gives the order of the point $z$ on the elliptic
2547: curve $E$ if it is a torsion point, zero otherwise. In the present version
2548: \vers, this is implemented only for elliptic curves defined over $\Q$.
2549:
2550: \syn{orderell}{E,z}.
2551:
2552: \subsecidx{ellordinate}$(E,x)$: gives a 0, 1 or 2-component vector containing
2553: the $y$-coordinates of the points of the curve $E$ having $x$ as
2554: $x$-coordinate.
2555:
2556: \syn{ordell}{E,x}.
2557:
2558: \subsecidx{ellpointtoz}$(E,z)$: if $E$ is an elliptic curve with coefficients
2559: in $\R$, this computes a complex number $t$ (modulo the lattice defining
2560: $E$) corresponding to the point $z$, i.e.~such that, in the standard
2561: Weierstrass model, $\wp(t)=z[1],\wp'(t)=z[2]$. In other words, this is the
2562: inverse function of \kbd{ellztopoint}.
2563:
2564: If $E$ has coefficients in $\Q_p$, then either Tate's $u$ is in $\Q_p$, in
2565: which case the output is a $p$-adic number $t$ corresponding to the point $z$
2566: under the Tate parametrization, or only its square is, in which case the
2567: output is $t+1/t$. $E$ must be a long vector output by \kbd{ellinit}.
2568:
2569: \syn{zell}{E,z,\var{prec}}.
2570:
2571: \subsecidx{ellpow}$(E,z,n)$: computes $n$ times the point $z$ for the
2572: group law on the elliptic curve $E$. Here, $n$ can be in $\Z$, or $n$
2573: can be a complex quadratic integer if the curve $E$ has complex multiplication
2574: by $n$ (if not, an error message is issued).
2575:
2576: \syn{powell}{E,z,n}.
2577:
2578: \subsecidx{ellrootno}$(E,\{p=1\})$: $E$ being a medium or long vector given
2579: by \kbd{ellinit}, this computes the local (if $p\neq 1$) or global (if $p=1$)
2580: root number of the L-series of the elliptic curve $E$. Note that the global
2581: root number is the sign of the functional equation and conjecturally is the
2582: parity of the rank of the \idx{Mordell-Weil group}.
2583: The equation for $E$ must have
2584: coefficients in $\Q$ but need \var{not} be minimal.
2585:
2586: \syn{ellrootno}{E,p} and the result (equal to $\pm1$) is a \kbd{long}.
2587:
2588: \subsecidx{ellsigma}$(E,z,\{\fl=0\})$: value of the Weierstrass $\sigma$
2589: function of the lattice associated to $E$ as given by \kbd{ellinit}
2590: (alternatively, $E$ can be given as a lattice $[\omega_1,\omega_2]$).
2591:
2592: If $\fl=1$, computes an (arbitrary) determination of $\log(\sigma(z))$.
2593:
2594: If $\fl=2,3$, same using the product expansion instead of theta series.
2595: \syn{ellsigma}{E,z,\fl}
2596:
2597: \subsecidx{ellsub}$(E,z1,z2)$: difference of the points $z1$ and $z2$ on the
2598: elliptic curve corresponding to the vector $E$.
2599:
2600: \syn{subell}{E,z1,z2}.
2601:
2602: \subsecidx{elltaniyama}$(E)$: computes the modular parametrization of the
2603: elliptic curve $E$, where $E$ is given in the (long or medium) format output
2604: by \kbd{ellinit}, in the form of a two-component vector $[u,v]$ of power
2605: series, given to the current default series precision. This vector is
2606: characterized by the following two properties. First the point $(x,y)=(u,v)$
2607: satisfies the equation of the elliptic curve. Second, the differential
2608: $du/(2v+a_1u+a_3)$ is equal to $f(z)dz$, a differential form on
2609: $H/\Gamma_0(N)$ where $N$ is the conductor of the curve. The variable used in
2610: the power series for $u$ and $v$ is $x$, which is implicitly understood to be
2611: equal to $\exp(2i\pi z)$. It is assumed that the curve is a \var{strong}
2612: \idx{Weil curve}, and the Manin constant is equal to 1. The equation of
1.2 ! noro 2613: the curve $E$ must be minimal (use \kbd{ellminimalmodel} to get a minimal
1.1 noro 2614: equation).
2615:
2616: \syn{taniyama}{E}, and the precision of the result is determined by the
2617: global variable \kbd{precdl}.
2618:
2619: \subsecidx{elltors}$(E,\{\fl=0\})$: if $E$ is an elliptic curve {\it defined
2620: over $\Q$}, outputs the torsion subgroup of $E$ as a 3-component vector
2621: \kbd{[t,v1,v2]}, where \kbd{t} is the order of the torsion group, \kbd{v1}
2622: gives the structure of the torsion group as a product of cyclic groups
2623: (sorted by decreasing order), and \kbd{v2} gives generators for these cyclic
2624: groups. $E$ must be a long vector as output by \kbd{ellinit}.
2625:
2626: \bprog
2627: ? E = ellinit([0,0,0,-1,0]);
2628: ? elltors(E)
2629: %1 = [4, [2, 2], [[0, 0], [1, 0]]]
2630: @eprog
2631: Here, the torsion subgroup is isomorphic to $\Z/2\Z \times \Z/2\Z$, with
2632: generators $[0,0]$ and $[1,0]$.
2633:
2634: If $\fl = 0$, use Doud's algorithm~: bound torsion by computing $\#E(\F_p)$
2635: for small primes of good reduction, then look for torsion points using
2636: Weierstrass parametrization (and Mazur's classification).
2637:
2638: If $\fl = 1$, use Lutz--Nagell (\var{much} slower), $E$ is allowed to be a
2639: medium vector.
2640:
2641: \syn{elltors0}{E,flag}.
2642:
2643: \subsecidx{ellwp}$(E,\{z=x\},\{\fl=0\})$:
2644:
2645: Computes the value at $z$ of the Weierstrass $\wp$ function attached to the
2646: elliptic curve $E$ as given by \kbd{ellinit} (alternatively, $E$ can be
2647: given as a lattice $[\omega_1,\omega_2]$).
2648:
2649: If $z$ is omitted or is a simple variable, computes the \var{power series}
2650: expansion in $z$ (starting $z^{-2}+O(z^2)$). The number of terms to an
2651: \var{even} power in the expansion is the default serieslength in GP, and the
2652: second argument (C long integer) in library mode.
2653:
2654: Optional \fl\ is (for now) only taken into account when $z$ is numeric, and
2655: means 0: compute only $\wp(z)$, 1: compute $[\wp(z),\wp'(z)]$.
2656:
2657: \syn{ellwp0}{E,z,\fl,\var{prec},\var{precdl}}. Also available is
2658: \teb{weipell}$(E,\var{precdl})$ for the power series (in
2659: $x=\kbd{polx[0]}$).
2660:
2661: \subsecidx{ellzeta}$(E,z)$: value of the Weierstrass $\zeta$ function of the
2662: lattice associated to $E$ as given by \kbd{ellinit} (alternatively, $E$ can
2663: be given as a lattice $[\omega_1,\omega_2]$).
2664:
2665: \syn{ellzeta}{E,z}.
2666:
2667: \subsecidx{ellztopoint}$(E,z)$: $E$ being a long vector, computes the
2668: coordinates $[x,y]$ on the curve $E$ corresponding to the complex number $z$.
2669: Hence this is the inverse function of \kbd{ellpointtoz}. In other words, if
2670: the curve is put in Weierstrass form, $[x,y]$ represents the
2671: \idx{Weierstrass $\wp$-function} and its derivative.
2672: If $z$ is in the lattice defining $E$ over
2673: $\C$, the result is the point at infinity $[0]$.
2674:
2675: \syn{pointell}{E,z,\var{prec}}.
2676:
2677: \section{Functions related to general number fields}
2678:
2679: In this section can be found functions which are used almost exclusively for
2680: working in general number fields. Other less specific functions can be found
2681: in the next section on polynomials. Functions related to quadratic number
2682: fields can be found in the section \secref{se:arithmetic} (Arithmetic
2683: functions).
2684:
2685: \noindent We shall use the following conventions:
2686:
2687: $\bullet$ $\tev{nf}$ denotes a number field, i.e.~a 9-component vector
2688: in the format output by \tet{nfinit}. This contains the basic arithmetic data
2689: associated to the number field: signature, maximal order, discriminant, etc.
2690:
2691: $\bullet$ $\tev{bnf}$ denotes a big number field, i.e.~a 10-component
2692: vector in the format output by \tet{bnfinit}. This contains $\var{nf}$ and
2693: the deeper invariants of the field: units, class groups, as well as a lot of
1.2 ! noro 2694: technical data necessary for some complex functions like \kbd{bnfisprincipal}.
1.1 noro 2695:
2696: $\bullet$ $\tev{bnr}$ denotes a big ``ray number field'', i.e.~some data
2697: structure output by \kbd{bnrinit}, even more complicated than $\var{bnf}$,
2698: corresponding to the ray class group structure of the field, for some
2699: modulus.
2700:
2701: $\bullet$ $\tev{rnf}$ denotes a relative number field (see below).
2702: \smallskip
2703:
2704: $\bullet$ $\tev{ideal}$ can mean any of the following:
2705:
2706: \quad -- a $\Z$-basis, in \idx{Hermite normal form}
2707: (HNF) or not. In this case $x$ is a square matrix.
2708:
2709: \quad -- an \tev{idele}, i.e.~a 2-component vector, the first being an
2710: ideal given as a $\Z$--basis, the second being a $r_1+r_2$-component row
2711: vector giving the complex logarithmic Archimedean information.
2712:
2713: \quad -- a $\Z_K$-generating system for an ideal.
2714:
2715: \quad -- a \var{column} vector $x$ expressing an element of the number field
2716: on the integral basis, in which case the ideal is treated as being the
2717: principal idele (or ideal) generated by $x$.
2718:
2719: \quad -- a prime ideal, i.e.~a 5-component vector in the format output by
2720: \kbd{idealprimedec}.
2721:
2722: \quad -- a polmod $x$, i.e.~an algebraic integer, in which case the ideal
2723: is treated as being the principal idele generated by $x$.
2724:
2725: \quad -- an integer or a rational number, also treated as a principal idele.
2726:
2727: $\bullet$ a \var{{character}} on the Abelian group
2728: $\bigoplus (\Z/N_i\Z) g_i$
2729: is given by a row vector $\chi = [a_1,\ldots,a_n]$ such that
2730: $\chi(\prod g_i^{n_i}) = exp(2i\pi\sum a_i n_i / N_i)$.
2731:
2732:
2733: \misctitle{Warnings:}
2734:
2735: 1) An element in $\var{nf}$ can be expressed either as a polmod or as a
2736: vector of components on the integral basis \kbd{\var{nf}.zk}. It is absolutely
2737: essential that all such vectors be \var{column} vectors.
2738:
2739: 2) When giving an ideal by a $\Z_K$ generating system to a function expecting
2740: an ideal, it must be ensured that the function understands that it is a
2741: $\Z_K$-generating system and not a $\Z$-generating system. When the number of
2742: generators is strictly less than the degree of the field, there is no
2743: ambiguity and the program assumes that one is giving a $\Z_K$-generating set.
2744: When the number of generators is greater than or equal to the degree of the
2745: field, however, the program assumes on the contrary that you are giving a
2746: $\Z$-generating set. If this is not the case, you \var{must} absolutely
2747: change it into a $\Z$-generating set, the simplest manner being to use
2748: \kbd{idealhnf(\var{nf},$x$)}.
2749:
2750: Concerning relative extensions, some additional definitions are necessary.
2751:
2752: $\bullet$ A \var{{relative matrix}} will be a matrix whose entries are
2753: elements of a (given) number field $\var{nf}$, always expressed as column
2754: vectors on the integral basis \kbd{\var{nf}.zk}. Hence it is a matrix of
2755: vectors.
2756:
2757: $\bullet$ An \tev{ideal list} will be a row vector of (fractional)
2758: ideals of the number field $\var{nf}$.
2759:
2760: $\bullet$ A \tev{pseudo-matrix} will be a pair $(A,I)$ where $A$ is a
2761: relative matrix and $I$ an ideal list whose length is the same as the number
2762: of columns of $A$. This pair will be represented by a 2-component row vector.
2763:
2764: $\bullet$ The \tev{module} generated by a pseudo-matrix $(A,I)$ is
2765: the sum $\sum_i{\Bbb a}_jA_j$ where the ${\Bbb a}_j$ are the ideals of $I$
2766: and $A_j$ is the $j$-th column of $A$.
2767:
2768: $\bullet$ A pseudo-matrix $(A,I)$ is a \tev{pseudo-basis} of the module
2769: it generates if $A$ is a square matrix with non-zero determinant and all the
2770: ideals of $I$ are non-zero. We say that it is in Hermite Normal
2771: Form\sidx{Hermite normal form} (HNF) if it is upper triangular and all the
2772: elements of the diagonal are equal to 1.
2773:
2774: $\bullet$ The \var{determinant} of a pseudo-basis $(A,I)$ is the ideal
2775: equal to the product of the determinant of $A$ by all the ideals of $I$. The
2776: determinant of a pseudo-matrix is the determinant of any pseudo-basis of the
2777: module it generates.
2778:
2779: Finally, when defining a relative extension, the base field should be
1.2 ! noro 2780: defined by a variable having a lower priority (i.e.~a higher number, see
! 2781: \secref{se:priority}) than the variable defining the extension. For example,
! 2782: under GP you can use the variable name $y$ (or $t$) to define the base field,
! 2783: and the variable name $x$ to define the relative extension.
1.1 noro 2784:
2785: Now a last set of definitions concerning the way big ray number fields
2786: (or \var{bnr}) are input, using class field theory.
2787: These are defined by a triple
2788: $a1$, $a2$, $a3$, where the defining set $[a1,a2,a3]$ can have any of the
2789: following forms: $[\var{bnr}]$, $[\var{bnr},\var{subgroup}]$,
2790: $[\var{bnf},\var{module}]$, $[\var{bnf},\var{module},\var{subgroup}]$, where:
2791:
2792: $\bullet$ $\var{bnf}$ is as output by \kbd{bnfclassunit} or \kbd{bnfinit},
2793: where units are mandatory unless the ideal is trivial; \var{bnr} by
2794: \kbd{bnrclass} (with $\fl>0$) or \kbd{bnrinit}. This is the ground field.
2795:
2796: $\bullet$ \var{module} is either an ideal in any form (see above) or a
2797: two-component row vector containing an ideal and an $r_1$-component row
2798: vector of flags indicating which real Archimedean embeddings to take in the
2799: module.
2800:
2801: $\bullet$ \var{subgroup} is the HNF matrix of a subgroup of the ray class group
2802: of the ground field for the modulus \var{module}. This is input as a square
2803: matrix expressing generators of a subgroup of the ray class group
2804: \kbd{\var{bnr}.clgp} on the given generators.
2805:
2806: The corresponding \var{bnr} is then the subfield of the ray class field of the
2807: ground field for the given modulus, associated to the given subgroup.
2808:
2809: All the functions which are specific to relative extensions, number fields,
2810: big number fields, big number rays, share the prefix \kbd{rnf}, \kbd{nf},
2811: \kbd{bnf}, \kbd{bnr} respectively. They are meant to take as first argument a
2812: number field of that precise type, respectively output by \kbd{rnfinit},
2813: \kbd{nfinit}, \kbd{bnfinit}, and \kbd{bnrinit}.
2814:
2815: However, and even though it may not be specified in the descriptions of the
2816: functions below, it is permissible, if the function expects a $\var{nf}$, to
2817: use a $\var{bnf}$ instead (which contains much more information). The program
2818: will make the effort of converting to what it needs. On the other hand, if
2819: the program requires a big number field, the program will \var{not} launch
2820: \kbd{bnfinit} for you, which can be a costly operation. Instead, it will give
2821: you a specific error message.
2822:
2823: The data types corresponding to the structures described above are rather
2824: complicated. Thus, as we already have seen it with elliptic curves, GP
2825: provides you with some ``member functions'' to retrieve the data you need
2826: from these structures (once they have been initialized of course). The
2827: relevant types of number fields are indicated between parentheses:
2828: \smallskip
2829:
2830: \sidx{member functions}
2831: \settabs\+xxxxxxx&(\var{bnr},x&\var{bnf},x&nf\hskip2pt&)x&: &\cr
2832:
2833: \+\tet{bnf} &(\var{bnr},& \var{bnf}&&)&: & big number field.\cr
2834:
2835: \+\tet{clgp} &(\var{bnr},& \var{bnf}&&)&: & classgroup. This one admits the
2836: following three subclasses:\cr
2837:
2838: \+ \quad \tet{cyc} &&&&&: & \quad cyclic decomposition
2839: (SNF)\sidx{Smith normal form}.\cr
2840:
2841: \+ \quad \kbd{gen}\sidx{gen (member function)} &&&&&: &
2842: \quad generators.\cr
2843:
2844: \+ \quad \tet{no} &&&&&: & \quad number of elements.\cr
2845:
2846: \+\tet{diff} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & the different ideal.\cr
2847:
2848: \+\tet{codiff}&(\var{bnr},& \var{bnf},& \var{nf}&)&: & the codifferent
2849: (inverse of the different in the ideal group).\cr
2850:
2851: \+\tet{disc} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & discriminant.\cr
2852:
2853: \+\tet{fu} &(\var{bnr},& \var{bnf},& \var{nf}&)&: &
2854: \idx{fundamental units}.\cr
2855:
2856: \+\tet{futu} &(\var{bnr},& \var{bnf}&&)&: & $[u,w]$, $u$ is a vector of
2857: fundamental units, $w$ generates the torsion.\cr
2858:
2859: \+\tet{nf} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & number field.\cr
2860:
2861: \+\tet{reg} &(\var{bnr},& \var{bnf},&&)&: & regulator.\cr
2862:
2863: \+\tet{roots}&(\var{bnr},& \var{bnf},& \var{nf}&)&: & roots of the
1.2 ! noro 2864: polynomial generating the field.\cr
1.1 noro 2865:
2866: \+\tet{sign} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & $[r_1,r_2]$ the
2867: signature of the field. This means that the field has $r_1$ real \cr
2868: \+ &&&&&& embeddings, $2r_2$ complex ones.\cr
2869:
2870: \+\tet{t2} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & the T2 matrix (see
2871: \kbd{nfinit}).\cr
2872:
2873: \+\tet{tu} &(\var{bnr},& \var{bnf},&&)&: & a generator for the torsion
2874: units.\cr
2875:
2876: \+\tet{tufu} &(\var{bnr},& \var{bnf},&&)&: & as \kbd{futu}, but outputs
2877: $[w,u]$.\cr
2878:
2879: \+\tet{zk} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & integral basis, i.e.~a
2880: $\Z$-basis of the maximal order.\cr
2881:
2882: \+\tet{zkst} &(\var{bnr}& & &)&: & structure of $(\Z_K/m)^*$ (can be
2883: extracted also from an \var{idealstar}).\cr
2884:
2885: For instance, assume that $\var{bnf} = \kbd{bnfinit}(\var{pol})$, for some
2886: polynomial. Then \kbd{\var{bnf}.clgp} retrieves the class group, and
2887: \kbd{\var{bnf}.clgp.no} the class number. If we had set $\var{bnf} =
2888: \kbd{nfinit}(\var{pol})$, both would have output an error message. All these
2889: functions are completely recursive, thus for instance
2890: \kbd{\var{bnr}.bnf.nf.zk} will yield the maximal order of \var{bnr} (which
2891: you could get directly with a simple \kbd{\var{bnr}.zk} of course).
2892:
2893: \medskip
2894: The following functions, starting with \kbd{buch} in library mode, and with
2895: \kbd{bnf} under GP, are implementations of the sub-exponential algorithms for
2896: finding class and unit groups under \idx{GRH}, due to Hafner-McCurley,
2897: \idx{Buchmann} and Cohen-Diaz-Olivier.
2898:
2899: The general call to the functions concerning class groups of general number
2900: fields (i.e.~excluding \kbd{quadclassunit}) involves a polynomial $P$ and a
2901: technical vector
1.2 ! noro 2902: $$\var{tech} = [c,c2,\var{nrel},\var{small\_norm},\var{nrpid},\var{minsfb}],$$
1.1 noro 2903: where the parameters are to be understood as follows:
2904:
2905: $P$ is the defining polynomial for the number field, which must be in
2906: $\Z[X]$, irreducible and, preferably, monic. In fact, if you supply a
2907: non-monic polynomial at this point, GP will issue a warning, then
2908: \var{transform your polynomial} so that it becomes monic. Instead of the
2909: normal result, say \kbd{res}, you then get a vector \kbd{[res,Mod(a,Q)]},
2910: where \kbd{Mod(a,Q)=Mod(X,P)} gives the change of variables.
2911:
2912: The numbers $c$ and $c2$ are positive real numbers which control the
2913: execution time and the stack size. To get maximum speed, set $c2=c$. To get a
2914: rigorous result (under \idx{GRH}) you must take $c2=12$ (or $c2=6$ in the
2915: quadratic case, but then you should use the much faster function
2916: \kbd{quadclassunit}). Reasonable values for $c$ are between $0.1$ and
2917: $2$. (The defaults are $c=c2=0.3$).
2918:
1.2 ! noro 2919: $\var{nrel}$ is the number of initial extra relations requested in computing
! 2920: the relation matrix. Reasonable values are between 5 and 20. (The default is
! 2921: 5).
! 2922:
! 2923: $\var{small\_norm}$ is a toggle used to disable the search for small norm
! 2924: relations. If this parameter is set equal to $0$, the program does not search
! 2925: for small norm relations (default value is $1$). {\sl This is obsolete and
! 2926: should not be used. Set $\var{nrpid} = 0$ instead}.
1.1 noro 2927:
2928: $\var{nrpid}$ is the maximal number of small norm relations associated to each
1.2 ! noro 2929: ideal in the factor base. Irrelevant when $\var{small\_norm}=0$. Otherwise,
1.1 noro 2930: reasonable values are between 4 and 20. (The default is 4).
2931:
2932: $\var{minsfb}$ is the minimal number of elements in the ``sub-factorbase''.
1.2 ! noro 2933: If the program does not seem to succeed in finding a full rank matrix (which
! 2934: you can see in GP by typing \kbd{\bs g 2}), increase this number. Reasonable
! 2935: values are between 2 and 5. (The default is 3).
1.1 noro 2936:
2937: \misctitle{Remarks.}
2938:
2939: Apart from the polynomial $P$, you don't need to supply any of the technical
2940: parameters (under the library you still need to send at least an empty
2941: vector, \kbd{cgetg(1,t\_VEC)}). However, should you choose to set some of
2942: them, they \var{must} be given in the requested order. For example, if you
2943: want to specify a given value of $nrel$, you must give some values as well
2944: for $c$ and $c2$, and provide a vector $[c,c2,nrel]$.
2945:
2946: Note also that you can use an $\var{nf}$ instead of $P$, which avoids
2947: recomputing the integral basis and analogous quantities.
2948:
2949: \smallskip
2950: \subsecidx{bnfcertify}$(\var{bnf})$: $\var{bnf}$ being a big number field
2951: as output by \kbd{bnfinit} or \kbd{bnfclassunit}, checks whether the result
2952: is correct, i.e.~whether it is possible to remove the assumption of the
2953: Generalized Riemann Hypothesis\sidx{GRH}. If it is correct, the answer is 1.
2954: If not, the program may output some error message, but more probably will loop
2955: indefinitely. In \var{no} occasion can the program give a wrong answer
2956: (barring bugs of course): if the program answers 1, the answer is certified.
2957:
2958: \syn{certifybuchall}{\var{bnf}}, and the result is a C long.
2959:
2960: \subsecidx{bnfclassunit}$(P,\{\fl=0\},\{\var{tech}=[\,]\})$: \idx{Buchmann}'s
2961: sub-exponential algorithm for computing the class group, the regulator and a
2962: system of \idx{fundamental units} of the general algebraic number field $K$
2963: defined by the irreducible polynomial $P$ with integer coefficients.
2964:
2965: The result of this function is a vector $v$ with 10 components (it is
2966: \var{not} a $\var{bnf}$, you need \kbd{bnfinit} for that), which for ease of
2967: presentation is in fact output as a one column matrix. First we describe the
2968: default behaviour ($\fl=0$):
2969:
2970: $v[1]$ is equal to the polynomial $P$. Note that for optimum performance,
2971: $P$ should have gone through \kbd{polred} or $\kbd{nfinit}(x,2)$.
2972:
2973: $v[2]$ is the 2-component vector $[r1,r2]$, where $r1$ and $r2$ are as usual
2974: the number of real and half the number of complex embeddings of the number
2975: field $K$.
2976:
2977: $v[3]$ is the 2-component vector containing the field discriminant and the
2978: index.
2979:
2980: $v[4]$ is an integral basis in Hermite normal form.
2981:
2982: $v[5]$ (\kbd{$v$.clgp}) is a 3-component vector containing the class number
2983: (\kbd{$v$.clgp.no}), the structure of the class group as a product of cyclic
2984: groups of order $n_i$ (\kbd{$v$.clgp.cyc}), and the corresponding generators
2985: of the class group of respective orders $n_i$ (\kbd{$v$.clgp.gen}).
2986:
2987: $v[6]$ (\kbd{$v$.reg}) is the regulator computed to an accuracy which is the
2988: maximum of an internally determined accuracy and of the default.
2989:
2990: $v[7]$ is a measure of the correctness of the result. If it is close to 1,
2991: the results are correct (under \idx{GRH}). If it is close to a larger integer,
2992: this shows that the product of the class number by the regulator is off by a
2993: factor equal to this integer, and you must start again with a larger value
2994: for $c$ or a different random seed, i.e.~use the function \kbd{setrand}.
2995: (Since the computation involves a random process, starting again with exactly
2996: the same parameters may give the correct result.) In this case a warning
2997: message is printed.
2998:
2999: $v[8]$ (\kbd{$v$.tu}) a vector with 2 components, the first being the number
3000: $w$ of roots of unity in $K$ and the second a primitive $w$-th root of unity
3001: expressed as a polynomial.
3002:
3003: $v[9]$ (\kbd{$v$.fu}) is a system of fundamental units also expressed as
3004: polynomials.
3005:
3006: $v[10]$ gives a measure of the correctness of the computations of the
3007: fundamental units (not of the regulator), expressed as a number of bits. If
3008: this number is greater than $20$, say, everything is OK. If $v[10]\le0$,
3009: then we have lost all accuracy in computing the units (usually an error
3010: message will be printed and the units not given). In the intermediate cases,
3011: one must proceed with caution (for example by increasing the current
3012: precision).
3013:
3014: If $\fl=1$, and the precision happens to be insufficient for obtaining the
3015: fundamental units exactly, the internal precision is doubled and the
3016: computation redone, until the exact results are obtained. The user should be
3017: warned that this can take a very long time when the coefficients of the
3018: fundamental units on the integral basis are very large, for example in the
3019: case of large real quadratic fields. In that case, there are alternate
3020: methods for representing algebraic numbers which are not implemented in PARI.
3021:
3022: If $\fl=2$, the fundamental units and roots of unity are not computed.
3023: Hence the result has only 7 components, the first seven ones.
3024:
3025: $\var{tech}$ is a technical vector (empty by default) containing $c$, $c2$,
3026: \var{nrel}, \var{borne}, \var{nbpid}, \var{minsfb}, in this order (see
3027: the beginning of the section or the keyword \kbd{bnf}).
3028: You can supply any number of these {\it provided you give an actual value to
3029: each of them} (the ``empty arg'' trick won't work here). Careful use of these
3030: parameters may speed up your computations considerably.
3031:
3032: \syn{bnfclassunit0}{P,\fl,\var{tech},\var{prec}}.
3033:
3034: \subsecidx{bnfclgp}$(P,\{\var{tech}=[\,]\})$: as \kbd{bnfclassunit}, but only
3035: outputs $v[5]$, i.e.~the class group.
3036:
3037: \syn{bnfclassgrouponly}{P,\var{tech},\var{prec}}, where \var{tech}
3038: is as described under \kbd{bnfclassunit}.
3039:
3040: \subsecidx{bnfdecodemodule}$(\var{nf},m)$: if $m$ is a module as output in the
3041: first component of an extension given by \kbd{bnrdisclist}, outputs the
3042: true module.
3043:
3044: \syn{decodemodule}{\var{nf},m}.
3045:
3046: \subsecidx{bnfinit}$(P,\{\fl=0\},\{\var{tech}=[\,]\})$: essentially identical
3047: to \kbd{bnfclassunit} except that the output contains a lot of technical data,
3048: and should not be printed out explicitly in general. The result of
3049: \kbd{bnfinit} is used in programs such as \kbd{bnfisprincipal},
3050: \kbd{bnfisunit} or \kbd{bnfnarrow}. The result is a 10-component vector
3051: $\var{bnf}$.
3052:
3053: \noindent $\bullet$ The first 6 and last 2 components are technical and in
3054: principle are not used by the casual user. However, for the sake of
3055: completeness, their description is as follows. We use the notations explained
3056: in the book by H. Cohen, {\it A Course in Computational Algebraic Number
3057: Theory}, Graduate Texts in Maths \key{138}, Springer-Verlag, 1993, Section
3058: 6.5, and subsection 6.5.5 in particular.
3059:
3060: $\var{bnf}[1]$ contains the matrix $W$, i.e.~the matrix in Hermite normal
3061: form giving relations for the class group on prime ideal generators
1.2 ! noro 3062: $(\wp_i)_{1\le i\le r}$.
1.1 noro 3063:
3064: $\var{bnf}[2]$ contains the matrix $B$, i.e.~the matrix containing the
1.2 ! noro 3065: expressions of the prime ideal factorbase in terms of the $\wp_i$. It is an
1.1 noro 3066: $r\times c$ matrix.
3067:
3068: $\var{bnf}[3]$ contains the complex logarithmic embeddings of the system of
3069: fundamental units which has been found. It is an $(r_1+r_2)\times(r_1+r_2-1)$
3070: matrix.
3071:
3072: $\var{bnf}[4]$ contains the matrix $M''_C$ of Archimedean components of the
3073: relations of the matrix $(W|B)$.
3074:
3075: $\var{bnf}[5]$ contains the prime factor base, i.e.~the list of prime
3076: ideals used in finding the relations.
3077:
1.2 ! noro 3078: $\var{bnf}[6]$ used to contain a permutation of the prime factor base, but
! 3079: has been obsoleted. It contains a dummy $0$.
1.1 noro 3080:
3081: $\var{bnf}[9]$ is a 3-element row vector used in \tet{bnfisprincipal} only
3082: and obtained as follows. Let $D = U W V$ obtained by applying the
3083: \idx{Smith normal form} algorithm to the matrix $W$ (= $\var{bnf}[1]$) and
3084: let $U_r$ be the reduction of $U$ modulo $D$. The first elements of the
3085: factorbase are given (in terms of \kbd{bnf.gen}) by the columns of $U_r$,
1.2 ! noro 3086: with Archimedean component $g_a$; let also $GD_a$ be the Archimedean
1.1 noro 3087: components of the generators of the (principal) ideals defined by the
3088: \kbd{bnf.gen[i]\pow bnf.cyc[i]}. Then $\var{bnf}[9]=[U_r, g_a, GD_a]$.
3089:
3090: Finally, $\var{bnf}[10]$ is by default unused and set equal to 0. This
3091: field is used to store further information about the field as it becomes
3092: available (which is rarely needed, hence would be too expensive to compute
3093: during the initial \kbd{bnfinit} call). For instance, the generators of the
3094: principal ideals \kbd{bnf.gen[i]\pow bnf.cyc[i]} (during a call to
3095: \tet{bnrisprincipal}), or those corresponding to the relations in $W$ and
3096: $B$ (when the \kbd{bnf} internal precision needs to be increased).
3097: \smallskip
3098:
3099: \noindent$\bullet$ The less technical components are as follows:
3100:
3101: $\var{bnf}[7]$ or \kbd{\var{bnf}.nf} is equal to the number field data
3102: $\var{nf}$ as would be given by \kbd{nfinit}.
3103:
3104: $\var{bnf}[8]$ is a vector containing the last 6 components of
3105: \kbd{bnfclassunit[,1]}, i.e.~the classgroup \kbd{\var{bnf}.clgp}, the
3106: regulator \kbd{\var{bnf}.reg}, the general ``check'' number which should be
3107: close to 1, the number of roots of unity and a generator \kbd{\var{bnf}.tu},
3108: the fundamental units \kbd{\var{bnf}.fu}, and finally the check on their
3109: computation. If the precision becomes insufficient, GP outputs a warning
3110: (\kbd{fundamental units too large, not given}) and does not strive to
3111: compute the units by default ($\fl=0$).
3112:
3113: When $\fl=1$, GP insists on finding the fundamental units exactly, the
3114: internal precision being doubled and the computation redone, until the exact
3115: results are obtained. The user should be warned that this can take a very
3116: long time when the coefficients of the fundamental units on the integral
3117: basis are very large.
3118:
3119: When $\fl=2$, on the contrary, it is initially agreed that GP
3120: will not compute units.
3121:
3122: When $\fl=3$, computes a very small version of \kbd{bnfinit}, a ``small big
3123: number field'' (or \var{sbnf} for short) which contains enough information
3124: to recover the full $\var{bnf}$ vector very rapidly, but which is much
3125: smaller and hence easy to store and print. It is supposed to be used in
3126: conjunction with \kbd{bnfmake}. The output is a 12 component vector $v$, as
3127: follows. Let $\var{bnf}$ be the result of a full \kbd{bnfinit}, complete with
3128: units. Then $v[1]$ is the polynomial $P$, $v[2]$ is the number of real
3129: embeddings $r_1$, $v[3]$ is the field discriminant, $v[4]$ is the integral
3130: basis, $v[5]$ is the list of roots as in the sixth component of \kbd{nfinit},
3131: $v[6]$ is the matrix $MD$ of \kbd{nfinit} giving a $\Z$-basis of the
3132: different, $v[7]$ is the matrix $\kbd{W} = \var{bnf}[1]$, $v[8]$ is the
3133: matrix $\kbd{matalpha}=\var{bnf}[2]$, $v[9]$ is the prime ideal factor base
3134: $\var{bnf}[5]$ coded in a compact way, and ordered according to the
3135: permutation $\var{bnf}[6]$, $v[10]$ is the 2-component vector giving the
3136: number of roots of unity and a generator, expressed on the integral basis,
3137: $v[11]$ is the list of fundamental units, expressed on the integral basis,
3138: $v[12]$ is a vector containing the algebraic numbers alpha corresponding to
3139: the columns of the matrix \kbd{matalpha}, expressed on the integral basis.
3140:
3141: Note that all the components are exact (integral or rational), except for
3142: the roots in $v[5]$. In practice, this is the only component which a user
3143: is allowed to modify, by recomputing the roots to a higher accuracy if
3144: desired. Note also that the member functions will \var{not} work on
3145: \var{sbnf}, you have to use \kbd{bnfmake} explicitly first.
3146:
3147: \syn{bnfinit0}{P,\fl,\var{tech},\var{prec}}.
3148:
3149: \subsecidx{bnfisintnorm}$(\var{bnf},x)$: computes a complete system of
3150: solutions (modulo units of positive norm) of the absolute norm equation
3151: $\text{Norm}(a)=x$,
3152: where $a$ is an integer in $\var{bnf}$. If $\var{bnf}$ has not been certified,
3153: the correctness of the result depends on the validity of \idx{GRH}.
3154:
3155: \syn{bnfisintnorm}{\var{bnf},x}.
3156:
3157: \subsecidx{bnfisnorm}$(\var{bnf},x,\{\fl=1\})$: tries to tell whether the
3158: rational number $x$ is the norm of some element y in $\var{bnf}$. Returns a
3159: vector $[a,b]$ where $x=Norm(a)*b$. Looks for a solution which is an $S$-unit,
3160: with $S$ a certain set of prime ideals containing (among others) all primes
3161: dividing $x$. If $\var{bnf}$ is known to be \idx{Galois}, set $\fl=0$ (in
3162: this case,
3163: $x$ is a norm iff $b=1$). If $\fl$ is non zero the program adds to $S$ the
3164: following prime ideals, depending on the sign of $\fl$. If $\fl>0$, the
3165: ideals of norm less than $\fl$. And if $\fl<0$ the ideals dividing $\fl$.
3166:
3167: If you are willing to assume \idx{GRH}, the answer is guaranteed
3168: (i.e.~$x$ is a norm iff $b=1$), if $S$ contains all primes less than
3169: $12\log(\var{disc}(\var{Bnf}))^2$,
3170: where $\var{Bnf}$ is the Galois closure of $\var{bnf}$.
3171:
3172: \syn{bnfisnorm}{\var{bnf},x,\fl,\var{prec}}, where $\fl$ and
3173: $\var{prec}$ are \kbd{long}s.
3174:
3175: \subsecidx{bnfissunit}$(\var{bnf},\var{sfu},x)$: $\var{bnf}$ being output by
3176: \kbd{bnfinit}, \var{sfu} by \kbd{bnfsunit}, gives the column vector of
3177: exponents of $x$ on the fundamental $S$-units and the roots of unity.
3178: If $x$ is not a unit, outputs an empty vector.
3179:
3180: \syn{bnfissunit}{\var{bnf},\var{sfu},x}.
3181:
3182: \subsecidx{bnfisprincipal}$(\var{bnf},x,\{\fl=1\})$: $\var{bnf}$ being the
3183: number field data output by \kbd{bnfinit}, and $x$ being either a $\Z$-basis
3184: of an ideal in the number field (not necessarily in HNF) or a prime ideal in
3185: the format output by the function \kbd{idealprimedec}, this function tests
3186: whether the ideal is principal or not. The result is more complete than a
3187: simple true/false answer: it gives a row vector $[v_1,v_2,check]$, where
3188:
3189: $v_1$ is the vector of components $c_i$ of the class of the ideal $x$ in the
3190: class group, expressed on the generators $g_i$ given by \kbd{bnfinit}
1.2 ! noro 3191: (specifically \kbd{\var{bnf}.gen}). The $c_i$ are chosen so that $0\le c_i<n_i$
! 3192: where $n_i$ is the order of $g_i$ (the vector of $n_i$ being \kbd{\var{bnf}.cyc}).
1.1 noro 3193:
3194: $v_2$ gives on the integral basis the components of $\alpha$ such that
3195: $x=\alpha\prod_ig_i^{c_i}$. In particular, $x$ is principal if and only if
1.2 ! noro 3196: $v_1$ is equal to the zero vector. In the latter case, $x = \alpha\Z_K$ where
1.1 noro 3197: $\alpha$ is given by $v_2$. Note that if $\alpha$ is too large to be given, a
3198: warning message will be printed and $v_2$ will be set equal to the empty
3199: vector.
3200:
3201: Finally the third component \var{check} is analogous to the last component of
3202: \kbd{bnfclassunit}: it gives a check on the accuracy of the result, in bits.
3203: \var{check} should be at least $10$, and preferably much more. In any case, the
3204: result is checked for correctness.
3205:
3206: If $\fl=0$, outputs only $v_1$, which is much easier to compute.
3207:
3208: If $\fl=2$, does as if $\fl$ were $0$, but doubles the precision until a
3209: result is obtained.
3210:
3211: If $\fl=3$, as in the default behaviour ($\fl=1$), but doubles the precision
3212: until a result is obtained.
3213:
3214: The user is warned that these two last setting may induce \var{very} lengthy
3215: computations.
3216:
3217: \syn{isprincipalall}{\var{bnf},x,\fl}.
3218:
3219: \subsecidx{bnfisunit}$(\var{bnf},x)$: $\var{bnf}$ being the number field data
3220: output by
3221: \kbd{bnfinit} and $x$ being an algebraic number (type integer, rational or
3222: polmod), this outputs the decomposition of $x$ on the fundamental units and
3223: the roots of unity if $x$ is a unit, the empty vector otherwise. More
3224: precisely, if $u_1$,\dots,$u_r$ are the fundamental units, and $\zeta$ is
3225: the generator of the group of roots of unity (found by \kbd{bnfclassunit} or
3226: \kbd{bnfinit}), the output is a vector $[x_1,\dots,x_r,x_{r+1}]$ such that
3227: $x=u_1^{x_1}\cdots u_r^{x_r}\cdot\zeta^{x_{r+1}}$. The $x_i$ are integers for
3228: $i\le r$ and is an integer modulo the order of $\zeta$ for $i=r+1$.
3229:
3230: \syn{isunit}{\var{bnf},x}.
3231:
3232: \subsecidx{bnfmake}$(\var{sbnf})$: \var{sbnf} being a ``small $\var{bnf}$''
3233: as output by \kbd{bnfinit}$(x,3)$, computes the complete \kbd{bnfinit}
3234: information. The result is \var{not} identical to what \kbd{bnfinit} would
3235: yield, but is functionally identical. The execution time is very small
3236: compared to a complete \kbd{bnfinit}. Note that if the default precision in
3237: GP (or $\var{prec}$ in library mode) is greater than the precision of the
3238: roots $\var{sbnf}[5]$, these are recomputed so as to get a result with
3239: greater accuracy.
3240:
3241: Note that the member functions are \var{not} available for \var{sbnf}, you
3242: have to use \kbd{bnfmake} explicitly first.
3243:
3244: \syn{makebigbnf}{\var{sbnf},\var{prec}}, where $\var{prec}$ is a
3245: C long integer.
3246:
3247: \subsecidx{bnfnarrow}$(\var{bnf})$: $\var{bnf}$ being a big number field as
3248: output by \kbd{bnfinit}, computes the narrow class group of $\var{bnf}$. The
3249: output is a 3-component row vector $v$ analogous to the corresponding
3250: class group component \kbd{\var{bnf}.clgp} (\kbd{\var{bnf}[8][1]}): the
3251: first component is the narrow class number \kbd{$v$.no}, the second component
3252: is a vector containing the SNF\sidx{Smith normal form} cyclic components
3253: \kbd{$v$.cyc} of the narrow
3254: class group, and the third is a vector giving the generators of the
3255: corresponding \kbd{$v$.gen} cyclic groups. Note that this function is a
3256: special case of \kbd{bnrclass}.
3257:
3258: \syn{buchnarrow}{\var{bnf}}.
3259:
3260: \subsecidx{bnfsignunit}$(\var{bnf})$: $\var{bnf}$ being a big number field
3261: output by \kbd{bnfinit}, this computes an $r_1\times(r_1+r_2-1)$ matrix
3262: having $\pm1$ components, giving the signs of the real embeddings of the
1.2 ! noro 3263: fundamental units. The following functions compute generators for the totally
! 3264: positive units:
! 3265:
! 3266: \bprog
! 3267: /* exponents of totally positive units generators on bnf.tufu */
! 3268: tpuexpo(bnf)=
! 3269: { local(S,d,K);
! 3270:
! 3271: S = bnfsignunit(bnf); d = matsize(S);
! 3272: S = matrix(d[1],d[2], i,j, if (S[i,j] < 0, 1,0));
! 3273: S = concat(S, vectorv(d[1],i,1)); \\ sign(-1)
! 3274: K = lift(matker(S * Mod(1,2)));
! 3275: if (K, mathnfmodid(K, 2), 2*matid(d[1]))
! 3276: }
! 3277:
! 3278: /* totally positive units */
! 3279: tpu(bnf)=
! 3280: { local(vu, ex = tpuexpo(bnf));
! 3281:
! 3282: vu = nfbasistoalg(bnf, bnf.tufu);
! 3283: vector(length(ex)-1, i, factorback([vu, ex[,i+1]])) \\ ex[,1] is 1
! 3284: }
! 3285: @eprog
1.1 noro 3286:
3287: \syn{signunits}{\var{bnf}}.
3288:
3289: \subsecidx{bnfreg}$(\var{bnf})$: $\var{bnf}$ being a big number field
3290: output by \kbd{bnfinit}, computes its regulator.
3291:
3292: \syn{regulator}{\var{bnf},\var{tech},\var{prec}}, where \var{tech} is as in
3293: \kbd{bnfclassunit}.
3294:
3295: \subsecidx{bnfsunit}$(\var{bnf},S)$: computes the fundamental $S$-units of the
3296: number field $\var{bnf}$ (output by \kbd{bnfinit}), where $S$ is a list of
3297: prime ideals (output by \kbd{idealprimedec}). The output is a vector $v$ with
3298: 6 components.
3299:
3300: $v[1]$ gives a minimal system of (integral) generators of the $S$-unit group
3301: modulo the unit group.
3302:
3303: $v[2]$ contains technical data needed by \kbd{bnfissunit}.
3304:
3305: $v[3]$ is an empty vector (used to give the logarithmic embeddings of the
3306: generators in $v[1]$ in version 2.0.16).
3307:
3308: $v[4]$ is the $S$-regulator (this is the product of the regulator, the
3309: determinant of $v[2]$ and the natural logarithms of the norms of the ideals
3310: in $S$).
3311:
3312: $v[5]$ gives the $S$-class group structure, in the usual format
3313: (a row vector whose three components give in order the $S$-class number,
3314: the cyclic components and the generators).
3315:
3316: $v[6]$ is a copy of $S$.
3317:
3318: \syn{bnfsunit}{\var{bnf},S,\var{prec}}.
3319:
3320: \subsecidx{bnfunit}$(\var{bnf})$: $\var{bnf}$ being a big number field as
1.2 ! noro 3321: output by \kbd{bnfinit}, outputs a two-component row vector giving in the
! 3322: first component the vector of fundamental units of the number field, and in
! 3323: the second component the number of bit of accuracy which remained in the
1.1 noro 3324: computation (which is always correct, otherwise an error message is printed).
3325: This function is mainly for people who used the wrong flag in \kbd{bnfinit}
3326: and would like to skip part of a lengthy \kbd{bnfinit} computation.
3327:
3328: \syn{buchfu}{\var{bnf}}.
3329:
1.2 ! noro 3330: \subsecidx{bnrL1}$(\var{bnr},\{\var{subgroup}\},\{\fl=0\})$:
1.1 noro 3331: \var{bnr} being the number field data which is output by
3332: \kbd{bnrinit(,,1)} and \var{subgroup} being a square matrix defining a
3333: congruence subgroup of the ray class group corresponding to \var{bnr}
1.2 ! noro 3334: (the trivial congruence subgroup if omitted), returns for each
1.1 noro 3335: \idx{character} $\chi$ of the ray class group which is trivial on this
3336: subgroup, the value at $s = 1$ (or $s = 0$) of the abelian
3337: $L$-function associated to $\chi$. For the value at $s = 0$, the
3338: function returns in fact for each character $\chi$ a vector $[r_\chi ,
3339: c_\chi]$ where $r_\chi$ is the order of $L(s, \chi)$ at $s = 0$ and
3340: $c_\chi$ the first non-zero term in the expansion of $L(s,
3341: \chi)$ at $s = 0$; in other words
3342: %
3343: $$L(s, \chi) = c_\chi \cdot s^{r_\chi} + O(s^{r_\chi + 1})$$
3344: %
3345: \noindent near $0$. \fl\ is optional, default value is 0; its binary digits
3346: mean 1: compute at $s = 1$ if set to 1 or $s = 0$ if set to 0, 2: compute
3347: the primitive $L$-functions associated to $\chi$ if set to 0 or the
3348: $L$-function with Euler factors at prime ideals dividing the modulus of
3349: \var{bnr} removed if set to 1 (this is the so-called $L_S(s, \chi)$
3350: function where $S$ is the set of infinite places of the number field
3351: together with the finite prime ideals dividing the modulus of \var{bnr},
3352: see the example below), 3: returns also the character.
3353:
3354: Example:
3355: \bprog
3356: bnf = bnfinit(x^2 - 229);
3357: bnr = bnrinit(bnf,1,1);
1.2 ! noro 3358: bnrL1(bnr)
1.1 noro 3359: @eprog\noindent
3360: returns the order and the first non-zero term of the abelian
3361: $L$-functions $L(s, \chi)$ at $s = 0$ where $\chi$ runs through the
3362: characters of the class group of $\Q(\sqrt{229})$. Then
3363: \bprog
3364: bnr2 = bnrinit(bnf,2,1);
1.2 ! noro 3365: bnrL1(bnr2,,2)
1.1 noro 3366: @eprog\noindent
3367: returns the order and the first non-zero terms of the abelian
3368: $L$-functions $L_S(s, \chi)$ at $s = 0$ where $\chi$ runs through the
3369: characters of the class group of $\Q(\sqrt{229})$ and $S$ is the set
3370: of infinite places of $\Q(\sqrt{229})$ together with the finite prime
3371: $2$ (note that the ray class group modulo $2$ is in fact the class
3372: group, so \kbd{bnrL1(bnr2,0)} returns exactly the same answer as
3373: \kbd{bnrL1(bnr,0)}!).
3374:
1.2 ! noro 3375: \syn{bnrL1}{\var{bnr},\var{subgroup},\fl,\var{prec}}, where an omitted
! 3376: \var{subgroup} is coded as \kbd{NULL}.
1.1 noro 3377:
3378: \subsecidx{bnrclass}$(\var{bnf},\var{ideal},\{\fl=0\})$:
3379: $\var{bnf}$ being a big number field
3380: as output by \kbd{bnfinit} (the units are mandatory unless the ideal is
3381: trivial), and \var{ideal} being either an ideal in any form or a two-component
3382: row vector containing an ideal and an $r_1$-component row vector of flags
3383: indicating which real Archimedean embeddings to take in the module, computes
3384: the ray class group of the number field for the module \var{ideal}, as a
3385: 3-component vector as all other finite Abelian groups (cardinality, vector of
3386: cyclic components, corresponding generators).
3387:
3388: If $\fl=2$, the output is different. It is a 6-component vector $w$. $w[1]$
3389: is $\var{bnf}$. $w[2]$ is the result of applying
3390: $\kbd{idealstar}(\var{bnf},I,2)$. $w[3]$, $w[4]$ and $w[6]$ are technical
3391: components used only by the function \kbd{bnrisprincipal}. $w[5]$ is the
3392: structure of the ray class group as would have been output with $\fl=0$.
3393:
3394: If $\fl=1$, as above, except that the generators of the ray class group are
3395: not computed, which saves time.
3396:
3397: \syn{bnrclass0}{\var{bnf},\var{ideal},\fl}.
3398:
3399: \subsecidx{bnrclassno}$(\var{bnf},I)$: $\var{bnf}$ being a big number field
3400: as output
3401: by \kbd{bnfinit} (units are mandatory unless the ideal is trivial), and $I$
3402: being either an ideal in any form or a two-component row vector containing an
3403: ideal and an $r_1$-component row vector of flags indicating which real
3404: Archimedean embeddings to take in the modulus, computes the ray class number
3405: of the number field for the modulus $I$. This is faster than \kbd{bnrclass}
3406: and should be used if only the ray class number is desired.
3407:
3408: \syn{rayclassno}{\var{bnf},I}.
3409:
3410: \subsecidx{bnrclassnolist}$(\var{bnf},\var{list})$: $\var{bnf}$ being a
3411: big number field as output by \kbd{bnfinit} (units are mandatory unless
3412: the ideal is trivial), and \var{list} being a list of modules as output
3413: by \kbd{ideallist} of \kbd{ideallistarch},
3414: outputs the list of the class numbers of the corresponding ray class groups.
3415:
3416: \syn{rayclassnolist}{\var{bnf},\var{list}}.
3417:
3418: \subsecidx{bnrconductor}$(a_1,\{a_2\},\{a_3\}, \{\fl=0\})$: conductor of the
3419: subfield of a ray class field as defined by $[a_1,a_2,a_3]$ (see \kbd{bnr}
3420: at the beginning of this section).
3421:
3422: \syn{bnrconductor}{a_1,a_2,a_3,\fl}, where an omitted argument
3423: among the $a_i$ is input as \kbd{gzero}, and $\fl$ is a C long.
3424:
3425: \subsecidx{bnrconductorofchar}$(\var{bnr},\var{chi})$: \var{bnr} being a
3426: big ray number field
3427: as output by \kbd{bnrclass}, and \var{chi} being a row vector representing a
3428: \idx{character} as expressed on the generators of the ray class group, gives
3429: the conductor of this character as a modulus.
3430:
3431: \syn{bnrconductorofchar}{\var{bnr},\var{chi}}.
3432:
3433: \subsecidx{bnrdisc}$(a1,\{a2\},\{a3\},\{\fl=0\})$: $a1$, $a2$, $a3$
1.2 ! noro 3434: defining a big ray number field $L$ over a ground field $K$ (see \kbd{bnr}
1.1 noro 3435: at the beginning of this section for the
3436: meaning of $a1$, $a2$, $a3$), outputs a 3-component row vector $[N,R_1,D]$,
3437: where $N$ is the (absolute) degree of $L$, $R_1$ the number of real places of
3438: $L$, and $D$ the discriminant of $L/\Q$, including sign (if $\fl=0$).
3439:
3440: If $\fl=1$, as above but outputs relative data. $N$ is now the degree of
3441: $L/K$, $R_1$ is the number of real places of $K$ unramified in $L$ (so that
3442: the number of real places of $L$ is equal to $R_1$ times the relative degree
3443: $N$), and $D$ is the relative discriminant ideal of $L/K$.
3444:
3445: If $\fl=2$, does as in case 0, except that if the modulus is not the exact
3446: conductor corresponding to the $L$, no data is computed and the result is $0$
3447: (\kbd{gzero}).
3448:
3449: If $\fl=3$, as case 2, outputting relative data.
3450:
3451: \syn{bnrdisc0}{a1,a2,a3,\fl}.
3452:
3453: \subsecidx{bnrdisclist}$(\var{bnf},\var{bound},\{\var{arch}\},\{\fl=0\})$:
3454: $\var{bnf}$ being a big
3455: number field as output by \kbd{bnfinit} (the units are mandatory), computes a
3456: list of discriminants of Abelian extensions of the number field by increasing
3457: modulus norm up to bound \var{bound}, where the ramified Archimedean places are
3458: given by \var{arch} (unramified at infinity if \var{arch} is void or
3459: omitted). If
3460: \fl\ is non-zero, give \var{arch} all the possible values. (See \kbd{bnr}
3461: at the beginning of this section for the meaning of $a1$, $a2$, $a3$.)
3462:
3463: The alternative syntax $\kbd{bnrdisclist}(\var{bnf},\var{list})$
3464: is supported, where \var{list} is as output by \kbd{ideallist} or
3465: \kbd{ideallistarch} (with units).
3466:
3467: The output format is as follows. The output $v$ is a row vector of row
3468: vectors, allowing the bound to be greater than $2^{16}$ for 32-bit machines,
3469: and $v[i][j]$ is understood to be in fact $V[2^{15}(i-1)+j]$ of a unique big
3470: vector $V$ (note that $2^{15}$ is hardwired and can be increased in the
3471: source code only on 64-bit machines and higher).
3472:
3473: Such a component $V[k]$ is itself a vector $W$ (maybe of length 0) whose
3474: components correspond to each possible ideal of norm $k$. Each component
3475: $W[i]$ corresponds to an Abelian extension $L$ of $\var{bnf}$ whose modulus is
3476: an ideal of norm $k$ and no Archimedean components (hence the extension is
3477: unramified at infinity). The extension $W[i]$ is represented by a 4-component
3478: row vector $[m,d,r,D]$ with the following meaning. $m$ is the prime ideal
3479: factorization of the modulus, $d=[L:\Q]$ is the absolute degree of $L$,
3480: $r$ is the number of real places of $L$, and $D$ is the factorization of the
3481: absolute discriminant. Each prime ideal $pr=[p,\alpha,e,f,\beta]$ in the
3482: prime factorization $m$ is coded as $p\cdot n^2+(f-1)\cdot n+(j-1)$, where
3483: $n$ is the degree of the base field and $j$ is such that
3484:
3485: \kbd{pr = idealprimedec(\var{nf},p)[j]}.
3486:
3487: $m$ can be decoded using \kbd{bnfdecodemodule}.
3488:
3489: \syn{bnrdisclist0}{a1,a2,a3,\var{bound},\var{arch},\fl}.
3490:
3491: \subsecidx{bnrinit}$(\var{bnf},\var{ideal},\{\fl=0\})$: $\var{bnf}$ is as
3492: output by \kbd{bnfinit}, \var{ideal} is a valid ideal (or a module),
3493: initializes data linked
3494: to the ray class group structure corresponding to this module. This is the
3495: same as $\kbd{bnrclass}(\var{bnf},\var{ideal},\fl+1)$.
3496:
3497: \syn{bnrinit0}{\var{bnf},\var{ideal},\fl}.
3498:
3499: \subsecidx{bnrisconductor}$(a1,\{a2\},\{a3\})$: $a1$, $a2$, $a3$ represent
3500: an extension of the base field, given by class field theory for some modulus
3501: encoded in the parameters. Outputs 1 if this modulus is the conductor, and 0
3502: otherwise. This is slightly faster than \kbd{bnrconductor}.
3503:
3504: \syn{bnrisconductor}{a1,a2,a3} and the result is a \kbd{long}.
3505:
3506: \subsecidx{bnrisprincipal}$(\var{bnr},x,\{\fl=1\})$: \var{bnr} being the
3507: number field data which is output by \kbd{bnrinit}$(,,1)$ and $x$ being an
3508: ideal in any form, outputs the components of $x$ on the ray class group
3509: generators in a way similar to \kbd{bnfisprincipal}. That is a 3-component
3510: vector $v$ where $v[1]$ is the vector of components of $x$ on the ray class
3511: group generators, $v[2]$ gives on the integral basis an element $\alpha$ such
3512: that $x=\alpha\prod_ig_i^{x_i}$. Finally $v[3]$ indicates the number of bits
3513: of accuracy left in the result. In any case the result is checked for
3514: correctness, but $v[3]$ is included to see if it is necessary to increase the
3515: accuracy in other computations.
3516:
3517: If $\fl=0$, outputs only $v_1$. In that case, \var{bnr} need not contain the
3518: ray class group generators, i.e.~it may be created with \kbd{bnrinit}$(,,0)$
3519:
3520: \syn{isprincipalrayall}{\var{bnr},x,\fl}.
3521:
3522: \subsecidx{bnrrootnumber}$(\var{bnr},\var{chi},\{\fl=0\})$:
3523: if $\chi=\var{chi}$ is a (not necessarily primitive)
3524: \idx{character} over \var{bnr}, let
3525: $L(s,\chi) = \sum_{id} \chi(id) N(id)^{-s}$ be the associated
3526: \idx{Artin L-function}. Returns the so-called \idx{Artin root number}, i.e.~the
3527: complex number $W(\chi)$ of modulus 1 such that
3528: %
3529: $$\Lambda(1-s,\chi) = W(\chi) \Lambda(s,\overline{\chi})$$
3530: %
3531: \noindent where $\Lambda(s,\chi) = A(\chi)^{s/2}\gamma_\chi(s) L(s,\chi)$ is
3532: the enlarged L-function associated to $L$.
3533:
3534: The generators of the ray class group are needed, and you can set $\fl=1$ if
3535: the character is known to be primitive. Example:
3536:
3537: \bprog
3538: bnf = bnfinit(x^2 - 145);
3539: bnr = bnrinit(bnf,7,1);
3540: bnrrootnumber(bnr, [5])
3541: @eprog\noindent
3542: returns the root number of the character $\chi$ of $Cl_7(\Q(\sqrt{145}))$
3543: such that $\chi(g) = \zeta^5$, where $g$ is the generator of the ray-class
3544: field and $\zeta = e^{2i\pi/N}$ where $N$ is the order of $g$ ($N=12$ as
3545: \kbd{bnr.cyc} readily tells us).
3546:
3547: \syn{bnrrootnumber}{\var{bnf},\var{chi},\fl}
3548:
1.2 ! noro 3549: \subsecidx{bnrstark}${(\var{bnr},\{\var{subgroup}\},\{\fl=0\})}$: \var{bnr}
1.1 noro 3550: being as output by \kbd{bnrinit(,,1)}, finds a relative equation for the
3551: class field corresponding to the modulus in \var{bnr} and the given
1.2 ! noro 3552: congruence subgroup using \idx{Stark units} (omit $\var{subgroup}=0$ if you
1.1 noro 3553: want the whole ray class group). The main variable of \var{bnr} must not be
1.2 ! noro 3554: $x$, and the ground field and the class field must be totally real. When the
! 3555: base field is $\Q$, the vastly simpler \tet{galoissubcyclo} is used instead.
1.1 noro 3556:
1.2 ! noro 3557: \fl\ is optional and may be set to 0 (default) to obtain a reduced relative
! 3558: polynomial, 1 to be satisfied with any relative polynomial, 2 to obtain an
! 3559: absolute polynomial and 3 to obtain the irreducible relative polynomial of
! 3560: the Stark unit. Example:
1.1 noro 3561: \bprog
3562: bnf = bnfinit(y^2 - 3);
3563: bnr = bnrinit(bnf, 5, 1);
3564: bnrstark(bnr, 0)
3565: @eprog\noindent
3566: returns the ray class field of $\Q(\sqrt{3})$ modulo $5$.
3567:
3568: \misctitle{Remark.} The result of the computation depends on the choice of
3569: a modulus verifying special conditions. By default the function will try
3570: few moduli, choosing the one giving the smallest result. In some cases
3571: where the result is however very large, you can tell the function to
3572: try more moduli by adding $4$ to the value of flag. Whether this flag is
3573: set or not, the function may fail in some extreme cases, returning the
3574: error message
3575:
3576: \kbd{"Cannot find a suitable modulus in FindModule"}.
3577:
3578: In this case, the corresponding congruence group is a product of cyclic
3579: groups and, for the time being, the class field has to be obtained by
3580: splitting this group into its cyclic components.
3581:
1.2 ! noro 3582: \syn{bnrstark}{\var{bnr},\var{subgroup},\fl}, where an omitted \var{subgroup}
! 3583: is coded by \kbd{NULL}.
1.1 noro 3584:
3585: \subsecidx{dirzetak}$(\var{nf},b)$: gives as a vector the first $b$
3586: coefficients of the \idx{Dedekind} zeta function of the number field $\var{nf}$
3587: considered as a \idx{Dirichlet series}.
3588:
3589: \syn{dirzetak}{\var{nf},b}.
3590:
3591: \subsecidx{factornf}$(x,t)$: factorization of the univariate polynomial $x$
3592: over the number field defined by the (univariate) polynomial $t$. $x$ may
3593: have coefficients in $\Q$ or in the number field. The main variable of
1.2 ! noro 3594: $t$ must be of \var{lower} priority than that of $x$ (see
! 3595: \secref{se:priority}). However if
1.1 noro 3596: the coefficients of the number field occur explicitly (as polmods) as
3597: coefficients of $x$, the variable of these polmods \var{must} be the same as
3598: the main variable of $t$. For example
3599: \bprog
3600: ? factornf(x^2 + Mod(y, y^2+1), y^2+1);
3601: ? factornf(x^2 + 1, y^2+1); \\@com these two are OK
3602: ? factornf(x^2 + Mod(z,z^2+1), y^2+1)
3603: *** incorrect type in gmulsg
3604: @eprog
3605:
3606: \syn{polfnf}{x,t}.
3607:
3608: \subsecidx{galoisfixedfield}$(\var{gal},\var{perm},\{fl=0\},\{v=y\}))$:
3609: \var{gal} being be a Galois field as output by \tet{galoisinit} and
3610: \var{perm} an element of $\var{gal}.group$ or a vector of such elements,
3611: computes the fixed field of \var{gal} by the automorphism defined by the
3612: permutations \var{perm} of the roots $\var{gal}.roots$. $P$ is guaranteed to
3613: be squarefree modulo $\var{gal}.p$.
3614:
3615: If no flags or $\fl=0$, output format is the same as for \tet{nfsubfield},
3616: returning $[P,x]$ such that $P$ is a polynomial defining the fixed field, and
3617: $x$ is a root of $P$ expressed as a polmod in $\var{gal}.pol$.
3618:
3619: If $\fl=1$ return only the polynomial $P$.
3620:
3621: If $\fl=2$ return $[P,x,F]$ where $P$ and $x$ are as above and $F$ is the
3622: factorization of $\var{gal}.pol$ over the field defined by $P$, where
3623: variable $v$ ($y$ by default) stands for a root of $P$. The priority of $v$
1.2 ! noro 3624: must be less than the priority of the variable of $\var{gal}.pol$ (see
! 3625: \secref{se:priority}). Example:
1.1 noro 3626:
3627: \bprog
3628: G = galoisinit(x^4+1);
3629: galoisfixedfield(G,G.group[2],2)
3630: [x^2 + 2, Mod(x^3 + x, x^4 + 1), [x^2 - y*x - 1, x^2 + y*x - 1]]
3631: @eprog
3632: computes the factorization $x^4+1=(x^2-\sqrt{-2}x-1)(x^2+\sqrt{-2}x-1)$
3633:
3634: \syn{galoisfixedfield}{\var{gal},\var{perm},p}.
3635:
3636: \subsecidx{galoisinit}$(\var{pol},\{den\})$: computes the Galois group
1.2 ! noro 3637: and all necessary information for computing the fixed fields of the
1.1 noro 3638: Galois extension $K/\Q$ where $K$ is the number field defined by
3639: $\var{pol}$ (monic irreducible polynomial in $\Z[X]$ or
3640: a number field as output by \tet{nfinit}). The extension $K/\Q$ must be
3641: Galois with Galois group ``weakly'' super-solvable (see \tet{nfgaloisconj})
3642:
3643: \misctitle{Warning:} The interface of this function is experimental,
3644: so the described output can be subject to important changes in the
3645: near future. However the function itself should work as described. For any
3646: remarks about this interface, please mail \kbd{allomber@math.u-bordeaux.fr}.
3647:
3648: The output is an 8-component vector \var{gal}.
3649:
3650: $\var{gal}[1]$ contains the polynomial \var{pol}
3651: (\kbd{\var{gal}.pol}).
3652:
3653: $\var{gal}[2]$ is a three--components vector $[p,e,q]$ where $p$ is a
3654: prime number (\kbd{\var{gal}.p}) such that \var{pol} totally split
3655: modulo $p$ , $e$ is an integer and $q=p^e$ (\kbd{\var{gal}.mod}) is the
3656: modulus of the roots in \kbd{\var{gal}.roots}.
3657:
3658: $\var{gal}[3]$ is a vector $L$ containing the $p$-adic roots of
3659: \var{pol} as integers implicitly modulo \kbd{\var{gal}.mod}.
3660: (\kbd{\var{gal}.roots}).
3661:
3662: $\var{gal}[4]$ is the inverse of the Van der Monde matrix of the
3663: $p$-adic roots of \var{pol}, multiplied by $\var{gal}[5]$.
3664:
3665: $\var{gal}[5]$ is a multiple of the least common denominator of the
3666: automorphisms expressed as polynomial in a root of \var{pol}.
3667:
3668: $\var{gal}[6]$ is the Galois group $G$ expressed as a vector of
3669: permutations of $L$ (\kbd{\var{gal}.group}).
3670:
3671: $\var{gal}[7]$ is a generating subset $S=[s_1,\ldots,s_g]$ of $G$
3672: expressed as a vector of permutations of $L$ (\kbd{\var{gal}.gen}).
3673:
3674: $\var{gal}[8]$ contains the relative orders $[o_1,\ldots,o_g]$ of
3675: the generators of $S$ (\kbd{\var{gal}.orders}).
3676:
3677: Let $H$ be the maximal normal supersolvable subgroup of $G$, we have the
3678: following properties:
3679:
3680: \quad$\bullet$ if $G/H\simeq A_4$ then $[o_1,\ldots,o_g]$ ends by
3681: $[2,2,3]$.
3682:
3683: \quad$\bullet$ if $G/H\simeq S_4$ then $[o_1,\ldots,o_g]$ ends by
3684: $[2,2,3,2]$.
3685:
3686: \quad$\bullet$ else $G$ is super-solvable.
3687:
3688: \quad$\bullet$ for $1\leq i \leq g$ the subgroup of $G$ generated by
3689: $[s_1,\ldots,s_g]$ is normal, with the exception of $i=g-2$ in the
3690: second case and of $i=g-3$ in the third.
3691:
3692: \quad$\bullet$ the relative order $o_i$ of $s_i$ is its order in the
3693: quotient group $G/\langle s_1,\ldots,s_{i-1}\rangle$, with the same
3694: exceptions.
3695:
3696: \quad$\bullet$ for any $x\in G$ there exists a unique family
3697: $[e_1,\ldots,e_g]$ such that (no exceptions):
3698:
3699: -- for $1\leq i \leq g$ we have $0\leq e_i<o_i$
3700:
3701: -- $x=g_1^{e_1}g_2^{e_2}\ldots g_n^{e_n}$
3702:
3703: If present $den$ must be a suitable value for $\var{gal}[5]$.
3704:
3705: \syn{galoisinit}{\var{gal},\var{den}}.
3706:
1.2 ! noro 3707: \subsecidx{galoisisabelian}$(\var{gal},{fl=0})$: \var{gal} being as output by \kbd{galoisinit}, return $0$ if
! 3708: \var{gal} is not an abelian group, and the HNF matrix of \var{gal} over \kbd{gal.gen} if $fl=0$, $1$ if
! 3709: $fl=1$.
! 3710:
! 3711: \syn{galoisisabelian}{\var{gal},\var{fl}} where \var{fl} is a C long integer.
! 3712:
1.1 noro 3713: \subsecidx{galoispermtopol}$(\var{gal},\var{perm})$: \var{gal} being a
3714: Galois field as output by \kbd{galoisinit} and \var{perm} a element of
3715: $\var{gal}.group$, return the polynomial defining the Galois
3716: automorphism, as output by \kbd{nfgaloisconj}, associated with the
3717: permutation \var{perm} of the roots $\var{gal}.roots$. \var{perm} can
3718: also be a vector or matrix, in this case, \kbd{galoispermtopol} is
3719: applied to all components recursively.
3720:
3721: \noindent Note that
3722: \bprog
3723: G = galoisinit(pol);
3724: galoispermtopol(G, G[6])~
3725: @eprog
3726: \noindent is equivalent to \kbd{nfgaloisconj(pol)}, if degree of \var{pol}
3727: is greater or equal to $2$.
3728:
3729: \syn{galoispermtopol}{\var{gal},\var{perm}}.
3730:
1.2 ! noro 3731: \subsecidx{galoissubcyclo}$(N,H,\{fl=0\},\{v\})$: computes the subextension
! 3732: of $\Q(\zeta_n)$ fixed by the subgroup $H \subset (\Z/n\Z)^*$. By the
! 3733: Kronecker-Weber theorem, all abelian number fields can be generated in this
! 3734: way (uniquely if $n$ is taken to be minimal).
! 3735:
! 3736: \noindent The pair $(n, H)$ is deduced from the parameters $(N, H)$ as follows
! 3737:
! 3738: $\bullet$ $N$ an integer: then $n = N$; $H$ is a generator, i.e. an
! 3739: integer or an integer modulo $n$; or a vector of generators.
! 3740:
! 3741: $\bullet$ $N$ the output of \kbd{znstar($n$)}. $H$ as in the first case
! 3742: above, or a matrix, taken to be a HNF left divisor of the SNF for $(\Z/n\Z)^*$
! 3743: (of type \kbd{$N$.cyc}), giving the generators of $H$ in terms of \kbd{$N$.gen}.
! 3744:
! 3745: $\bullet$ $N$ the output of \kbd{bnrinit(bnfinit(y), $m$, 1)} where $m$ is a
! 3746: module. $H$ as in the first case, or a matrix taken to be a HNF left
! 3747: divisor of the SNF for the ray class group modulo $m$
! 3748: (of type \kbd{$N$.cyc}), giving the generators of $H$ in terms of \kbd{$N$.gen}.
1.1 noro 3749:
1.2 ! noro 3750: In this last case, beware that $H$ is understood relatively to $N$; in
! 3751: particular, if the infinite place does not divide the module, e.g if $m$ is
! 3752: an integer, then it is not a subgroup of $(\Z/n\Z)^*$, but of its quotient by
! 3753: $\{\pm 1\}$.
1.1 noro 3754:
1.2 ! noro 3755: If $fl=0$, compute a polynomial (in the variable \var{v}) defining the
! 3756: the subfield of $\Q(\zeta_n)$ fixed by the subgroup \var{H} of $(\Z/n\Z)^*$.
! 3757:
! 3758: If $fl=1$, compute only the conductor of the abelian extension, as a module.
! 3759:
! 3760: If $fl=2$, output $[pol, N]$, where $pol$ is the polynomial as output when
! 3761: $fl=0$ and $N$ the conductor as output when $fl=1$.
1.1 noro 3762:
3763: The following function can be used to compute all subfields of
1.2 ! noro 3764: $\Q(\zeta_n)$ (of exact degree \kbd{d}, if \kbd{d} is set):
1.1 noro 3765: \bprog
3766: subcyclo(n, d = -1)=
3767: {
1.2 ! noro 3768: local(bnr,L,IndexBound);
! 3769: IndexBound = if (d < 0, n, [d]);
! 3770: bnr = bnrinit(bnfinit(y), [n,[1]], 1);
! 3771: L = subgrouplist(bnr, IndexBound, 1);
! 3772: vector(#L,i, galoissubcyclo(bnr,L[i]));
1.1 noro 3773: }
1.2 ! noro 3774: @eprog\noindent
! 3775: Setting \kbd{L = subgrouplist(bnr, [d])} would produce subfields of exact
! 3776: conductor $n\infty$.
! 3777:
! 3778: \syn{galoissubcyclo}{N,H,fl,v} where \var{fl} is a C long integer, and
! 3779: \var{v} a variable number.
1.1 noro 3780:
1.2 ! noro 3781: \subsecidx{galoissubfields}$(G,\{fl=0\},\{v\})$: Output all the subfields of the Galois group \var{G},
! 3782: as a vector.
! 3783: This works by applying \kbd{galoisfixedfield} to all subgroups. The meaning of the flag \var{fl} is
! 3784: the same as for \kbd{galoisfixedfield}.
! 3785:
! 3786: \syn{galoissubfields}{\var{G},fl,v}, where \var{fl} is a long and \var{v} a variable number.
! 3787:
! 3788: \subsecidx{galoissubgroups}$(G)$: Output all the subgroups of the Galois group \kbd{G}.
! 3789: A subgroup is a vector $[gen, orders]$, with the same meaning as for $\var{gal}.gen$
! 3790: and $\var{gal}.orders$. Hence \var{gen} is a vector of permutations generating the
! 3791: subgroup, and \var{orders} is the relatives orders of the generators. The cardinal
! 3792: of a subgroup is the product of the relative orders.
1.1 noro 3793:
1.2 ! noro 3794: \syn{galoissubgroups}{\var{G}}.
1.1 noro 3795:
3796: \subsecidx{idealadd}$(\var{nf},x,y)$: sum of the two ideals $x$ and $y$ in the
3797: number field $\var{nf}$. When $x$ and $y$ are given by $\Z$-bases, this does
3798: not depend on $\var{nf}$ and can be used to compute the sum of any two
3799: $\Z$-modules. The result is given in HNF.
3800:
3801: \syn{idealadd}{\var{nf},x,y}.
3802:
3803: \subsecidx{idealaddtoone}$(\var{nf},x,\{y\})$: $x$ and $y$ being two co-prime
3804: integral ideals (given in any form), this gives a two-component row vector
3805: $[a,b]$ such that $a\in x$, $b\in y$ and $a+b=1$.
3806:
3807: The alternative syntax $\kbd{idealaddtoone}(\var{nf},v)$, is supported, where
3808: $v$ is a $k$-component vector of ideals (given in any form) which sum to
3809: $\Z_K$. This outputs a $k$-component vector $e$ such that $e[i]\in x[i]$ for
3810: $1\le i\le k$ and $\sum_{1\le i\le k}e[i]=1$.
3811:
3812: \syn{idealaddtoone0}{\var{nf},x,y}, where an omitted $y$ is coded as
3813: \kbd{NULL}.
3814:
3815: \subsecidx{idealappr}$(\var{nf},x,\{\fl=0\})$: if $x$ is a fractional ideal
3816: (given in any form), gives an element $\alpha$ in $\var{nf}$ such that for
1.2 ! noro 3817: all prime ideals $\wp$ such that the valuation of $x$ at $\wp$ is non-zero, we
! 3818: have $v_{\wp}(\alpha)=v_{\wp}(x)$, and. $v_{\wp}(\alpha)\ge0$ for all other
! 3819: ${\wp}$.
1.1 noro 3820:
3821: If $\fl$ is non-zero, $x$ must be given as a prime ideal factorization, as
3822: output by \kbd{idealfactor}, but possibly with zero or negative exponents.
1.2 ! noro 3823: This yields an element $\alpha$ such that for all prime ideals $\wp$ occurring
! 3824: in $x$, $v_{\wp}(\alpha)$ is equal to the exponent of $\wp$ in $x$, and for all
! 3825: other prime ideals, $v_{\wp}(\alpha)\ge0$. This generalizes
1.1 noro 3826: $\kbd{idealappr}(\var{nf},x,0)$ since zero exponents are allowed. Note that
3827: the algorithm used is slightly different, so that
3828: \kbd{idealappr(\var{nf},idealfactor(\var{nf},x))} may not be the same as
3829: \kbd{idealappr(\var{nf},x,1)}.
3830:
3831: \syn{idealappr0}{\var{nf},x,\fl}.
3832:
3833: \subsecidx{idealchinese}$(\var{nf},x,y)$: $x$ being a prime ideal factorization
3834: (i.e.~a 2 by 2 matrix whose first column contain prime ideals, and the second
3835: column integral exponents), $y$ a vector of elements in $\var{nf}$ indexed by
3836: the ideals in $x$, computes an element $b$ such that
3837:
1.2 ! noro 3838: $v_\wp(b - y_\wp) \geq v_\wp(x)$ for all prime ideals in $x$ and $v_\wp(b)\geq 0$
! 3839: for all other $\wp$.
1.1 noro 3840:
3841: \syn{idealchinese}{\var{nf},x,y}.
3842:
3843: \subsecidx{idealcoprime}$(\var{nf},x,y)$: given two integral ideals $x$ and $y$
3844: in the number field $\var{nf}$, finds a $\beta$ in the field, expressed on the
1.2 ! noro 3845: integral basis $\var{nf}[7]$, such that $\beta\cdot x$ is an integral ideal
! 3846: coprime to $y$.
1.1 noro 3847:
1.2 ! noro 3848: \syn{idealcoprime}{\var{nf},x,y}.
1.1 noro 3849:
3850: \subsecidx{idealdiv}$(\var{nf},x,y,\{\fl=0\})$: quotient $x\cdot y^{-1}$ of the
3851: two ideals $x$ and $y$ in the number field $\var{nf}$. The result is given in
3852: HNF.
3853:
3854: If $\fl$ is non-zero, the quotient $x \cdot y^{-1}$ is assumed to be an
3855: integral ideal. This can be much faster when the norm of the quotient is
3856: small even though the norms of $x$ and $y$ are large.
3857:
3858: \syn{idealdiv0}{\var{nf},x,y,\fl}. Also available
3859: are $\teb{idealdiv}(\var{nf},x,y)$ ($\fl=0$) and
3860: $\teb{idealdivexact}(\var{nf},x,y)$ ($\fl=1$).
3861:
3862: \subsecidx{idealfactor}$(\var{nf},x)$: factors into prime ideal powers the
3863: ideal $x$ in the number field $\var{nf}$. The output format is similar to the
3864: \kbd{factor} function, and the prime ideals are represented in the form
3865: output by the \kbd{idealprimedec} function, i.e.~as 5-element vectors.
3866:
3867: \syn{idealfactor}{\var{nf},x}.
3868:
3869: \subsecidx{idealhnf}$(\var{nf},a,\{b\})$: gives the \idx{Hermite normal form}
3870: matrix of the ideal $a$. The ideal can be given in any form whatsoever
3871: (typically by an algebraic number if it is principal, by a $\Z_K$-system of
3872: generators, as a prime ideal as given by \kbd{idealprimedec}, or by a
3873: $\Z$-basis).
3874:
3875: If $b$ is not omitted, assume the ideal given was $a\Z_K+b\Z_K$, where $a$
3876: and $b$ are elements of $K$ given either as vectors on the integral basis
3877: $\var{nf}[7]$ or as algebraic numbers.
3878:
3879: \syn{idealhnf0}{\var{nf},a,b} where an omitted $b$ is coded as \kbd{NULL}.
3880: Also available is $\teb{idealhermite}(\var{nf},a)$ ($b$ omitted).
3881:
3882: \subsecidx{idealintersect}$(\var{nf},x,y)$: intersection of the two ideals
3883: $x$ and $y$ in the number field $\var{nf}$. When $x$ and $y$ are given by
3884: $\Z$-bases, this does not depend on $\var{nf}$ and can be used to compute the
3885: intersection of any two $\Z$-modules. The result is given in HNF.
3886:
3887: \syn{idealintersect}{\var{nf},x,y}.
3888:
3889: \subsecidx{idealinv}$(\var{nf},x)$: inverse of the ideal $x$ in the
3890: number field $\var{nf}$. The result is the Hermite normal form of the inverse
3891: of the ideal, together with the opposite of the Archimedean information if it
3892: is given.
3893:
3894: \syn{idealinv}{\var{nf},x}.
3895:
3896: \subsecidx{ideallist}$(\var{nf},\var{bound},\{\fl=4\})$: computes the list
3897: of all ideals of norm less or equal to \var{bound} in the number field
3898: \var{nf}. The result is a row vector with exactly \var{bound} components.
3899: Each component is itself a row vector containing the information about
3900: ideals of a given norm, in no specific order. This information can be
3901: either the HNF of the ideal or the \kbd{idealstar} with possibly some
3902: additional information.
3903:
3904: If $\fl$ is present, its binary digits are toggles meaning
3905:
3906: \quad 1: give also the generators in the \kbd{idealstar}.
3907:
3908: \quad 2: output $[L,U]$, where $L$ is as before and $U$ is a vector of
3909: \kbd{zinternallog}s of the units.
3910:
3911: \quad 4: give only the ideals and not the \kbd{idealstar} or the \kbd{ideallog}
3912: of the units.
3913:
3914: \syn{ideallist0}{\var{nf},\var{bound},\fl}, where \var{bound} must
3915: be a C long integer. Also available is $\teb{ideallist}(\var{nf},\var{bound})$,
3916: corresponding to the case $\fl=0$.
3917:
3918: \subsecidx{ideallistarch}$(\var{nf},\var{list},\{\var{arch}=[\,]\},\{\fl=0\})$:
3919: vector of vectors of all \kbd{idealstarinit} (see \kbd{idealstar}) of all
3920: modules in \var{list}, with Archimedean part \var{arch} added (void if
3921: omitted). \var{list} is a vector of big ideals, as output by
3922: \kbd{ideallist}$(\ldots, \fl)$ for instance. $\fl$ is optional; its binary
3923: digits are toggles meaning: 1: give generators as well, 2: list format is
3924: $[L,U]$ (see \kbd{ideallist}).
3925:
3926: \syn{ideallistarch0}{\var{nf},\var{list},\var{arch},\fl}, where an omitted
3927: \var{arch} is coded as \kbd{NULL}.
3928:
3929: \subsecidx{ideallog}$(\var{nf},x,\var{bid})$: $\var{nf}$ being a number field,
3930: \var{bid} being a ``big ideal'' as output by \kbd{idealstar} and $x$ being a
3931: non-necessarily integral element of \var{nf} which must have valuation
3932: equal to 0 at all prime ideals dividing $I=\var{bid}[1]$, computes the
3933: ``discrete logarithm'' of $x$ on the generators given in $\var{bid}[2]$.
3934: In other words, if $g_i$ are these generators, of orders $d_i$ respectively,
3935: the result is a column vector of integers $(x_i)$ such that $0\le x_i<d_i$ and
3936: $$x\equiv\prod_ig_i^{x_i}\pmod{\ ^*I}\enspace.$$
3937: Note that when $I$ is a module, this implies also sign conditions on the
3938: embeddings.
3939:
3940: \syn{zideallog}{\var{nf},x,\var{bid}}.
3941:
3942: \subsecidx{idealmin}$(\var{nf},x,\{\var{vdir}\})$: computes a minimum of
3943: the ideal $x$ in the direction \var{vdir} in the number field \var{nf}.
3944:
3945: \syn{minideal}{\var{nf},x,\var{vdir},\var{prec}}, where an omitted
3946: \var{vdir} is coded as \kbd{NULL}.
3947:
3948: \subsecidx{idealmul}$(\var{nf},x,y,\{\fl=0\})$: ideal multiplication of the
3949: ideals $x$ and $y$ in the number field \var{nf}. The result is a generating
3950: set for the ideal product with at most $n$ elements, and is in Hermite normal
3951: form if either $x$ or $y$ is in HNF or is a prime ideal as output by
3952: \kbd{idealprimedec}, and this is given together with the sum of the
3953: Archimedean information in $x$ and $y$ if both are given.
3954:
3955: If $\fl$ is non-zero, reduce the result using \kbd{idealred}.
3956:
3957: \syn{idealmul}{\var{nf},x,y} ($\fl=0$) or
3958: $\teb{idealmulred}(\var{nf},x,y,\var{prec})$ ($\fl\neq0$), where as usual,
3959: $\var{prec}$ is a C long integer representing the precision.
3960:
3961: \subsecidx{idealnorm}$(\var{nf},x)$: computes the norm of the ideal~$x$
3962: in the number field~$\var{nf}$.
3963:
3964: \syn{idealnorm}{\var{nf}, x}.
3965:
3966: \subsecidx{idealpow}$(\var{nf},x,k,\{\fl=0\})$: computes the $k$-th power of
3967: the ideal $x$ in the number field $\var{nf}$. $k$ can be positive, negative
3968: or zero. The result is NOT reduced, it is really the $k$-th ideal power, and
3969: is given in HNF.
3970:
3971: If $\fl$ is non-zero, reduce the result using \kbd{idealred}. Note however
3972: that this is NOT the same as as $\kbd{idealpow}(\var{nf},x,k)$ followed by
3973: reduction, since the reduction is performed throughout the powering process.
3974:
3975: The library syntax corresponding to $\fl=0$ is
3976: $\teb{idealpow}(\var{nf},x,k)$. If $k$ is a \kbd{long}, you can use
3977: $\teb{idealpows}(\var{nf},x,k)$. Corresponding to $\fl=1$ is
3978: $\teb{idealpowred}(\var{nf},vp,k,\var{prec})$, where $\var{prec}$ is a
3979: \kbd{long}.
3980:
3981: \subsecidx{idealprimedec}$(\var{nf},p)$: computes the prime ideal
3982: decomposition of the prime number $p$ in the number field $\var{nf}$. $p$
3983: must be a (positive) prime number. Note that the fact that $p$ is prime is
3984: not checked, so if a non-prime number $p$ is given it may lead to
3985: unpredictable results.
3986:
3987: The result is a vector of 5-component vectors, each representing one of the
3988: prime ideals above $p$ in the number field $\var{nf}$. The representation
3989: $vp=[p,a,e,f,b]$ of a prime ideal means the following. The prime ideal is
3990: equal to $p\Z_K+\alpha\Z_K$ where $\Z_K$ is the ring of integers of the field
3991: and $\alpha=\sum_i a_i\omega_i$ where the $\omega_i$ form the integral basis
3992: \kbd{\var{nf}.zk}, $e$ is the ramification index, $f$ is the residual index,
3993: and $b$ is an $n$-component column vector representing a $\beta\in\Z_K$ such
3994: that $vp^{-1}=\Z_K+\beta/p\Z_K$ which will be useful for computing
3995: valuations, but which the user can ignore. The number $\alpha$ is guaranteed
3996: to have a valuation equal to 1 at the prime ideal (this is automatic if
3997: $e>1$).
3998:
3999: \syn{idealprimedec}{\var{nf},p}.
4000:
4001: \subsecidx{idealprincipal}$(\var{nf},x)$: creates the principal ideal
4002: generated by the algebraic number $x$ (which must be of type integer,
4003: rational or polmod) in the number field $\var{nf}$. The result is a
4004: one-column matrix.
4005:
4006: \syn{principalideal}{\var{nf},x}.
4007:
4008: \subsecidx{idealred}$(\var{nf},I,\{\var{vdir}=0\})$: \idx{LLL} reduction of
4009: the ideal $I$ in the number field \var{nf}, along the direction \var{vdir}.
4010: If \var{vdir} is present, it must be an $r1+r2$-component vector ($r1$ and
4011: $r2$ number of real and complex places of \var{nf} as usual).
4012:
4013: This function finds a ``small'' $a$ in $I$ (it is an LLL pseudo-minimum
4014: along direction \var{vdir}). The result is the \idx{Hermite normal form} of
4015: the LLL-reduced ideal $r I/a$, where $r$ is a rational number such that the
4016: resulting ideal is integral and primitive. This is often, but not always, a
4017: reduced ideal in the sense of \idx{Buchmann}. If $I$ is an idele, the
4018: logarithmic embeddings of $a$ are subtracted to the Archimedean part.
4019:
4020: More often than not, a \idx{principal ideal} will yield the identity
4021: matrix. This is a quick and dirty way to check if ideals are principal
4022: without computing a full \kbd{bnf} structure, but it's not a necessary
4023: condition; hence, a non-trivial result doesn't prove the ideal is
4024: non-trivial in the class group.
4025:
4026: Note that this is \var{not} the same as the LLL reduction of the lattice
4027: $I$ since ideal operations are involved.
4028:
4029: \syn{ideallllred}{\var{nf},x,\var{vdir},\var{prec}}, where an omitted
4030: \var{vdir} is coded as \kbd{NULL}.
4031:
4032: \subsecidx{idealstar}$(\var{nf},I,\{\fl=1\})$: \var{nf} being a number
4033: field, and $I$
4034: either and ideal in any form, or a row vector whose first component is an
4035: ideal and whose second component is a row vector of $r_1$ 0 or 1, outputs
4036: necessary data for computing in the group $(\Z_K/I)^*$.
4037:
4038: If $\fl=2$, the result is a 5-component vector $w$. $w[1]$ is the ideal
4039: or module $I$ itself. $w[2]$ is the structure of the group. The other
4040: components are difficult to describe and are used only in conjunction with
4041: the function \kbd{ideallog}.
4042:
4043: If $\fl=1$ (default), as $\fl=2$, but do not compute explicit generators
4044: for the cyclic components, which saves time.
4045:
4046: If $\fl=0$, computes the structure of $(\Z_K/I)^*$ as a 3-component vector
4047: $v$. $v[1]$ is the order, $v[2]$ is the vector of SNF\sidx{Smith normal form}
4048: cyclic components and
4049: $v[3]$ the corresponding generators. When the row vector is explicitly
4050: included, the
4051: non-zero elements of this vector are considered as real embeddings of
4052: \var{nf} in the order given by \kbd{polroots}, i.e.~in \var{nf}[6]
4053: (\kbd{\var{nf}.roots}), and then $I$ is a module with components at infinity.
4054:
4055: To solve discrete logarithms (using \kbd{ideallog}), you have to choose
4056: $\fl=2$.
4057:
4058: \syn{idealstar0}{\var{nf},I,\fl}.
4059:
4060: \subsecidx{idealtwoelt}$(\var{nf},x,\{a\})$: computes a two-element
4061: representation of the ideal $x$ in the number field $\var{nf}$, using a
4062: straightforward (exponential time) search. $x$ can be an ideal in any form,
4063: (including perhaps an Archimedean part, which is ignored) and the result is a
4064: row vector $[a,\alpha]$ with two components such that $x=a\Z_K+\alpha\Z_K$
4065: and $a\in\Z$, where $a$ is the one passed as argument if any. If $x$ is given
4066: by at least two generators, $a$ is chosen to be the positive generator of
4067: $x\cap\Z$.
4068:
4069: Note that when an explicit $a$ is given, we use an asymptotically faster
4070: method, however in practice it is usually slower.
4071:
4072: \syn{ideal_two_elt0}{\var{nf},x,a}, where an omitted $a$ is entered as
4073: \kbd{NULL}.
4074:
4075: \subsecidx{idealval}$(\var{nf},x,\var{vp})$: gives the valuation of the
4076: ideal $x$ at the prime ideal \var{vp} in the number field $\var{nf}$,
4077: where \var{vp} must be a
4078: 5-component vector as given by \kbd{idealprimedec}.
4079:
4080: \syn{idealval}{\var{nf},x,\var{vp}}, and the result is a \kbd{long}
4081: integer.
4082:
4083: \subsecidx{ideleprincipal}$(\var{nf},x)$: creates the principal idele
4084: generated by the algebraic number $x$ (which must be of type integer,
4085: rational or polmod) in the number field $\var{nf}$. The result is a
4086: two-component vector, the first being a one-column matrix representing the
4087: corresponding principal ideal, and the second being the vector with $r_1+r_2$
4088: components giving the complex logarithmic embedding of $x$.
4089:
4090: \syn{principalidele}{\var{nf},x}.
4091:
4092: \subsecidx{matalgtobasis}$(\var{nf},x)$: $\var{nf}$ being a number field in
4093: \kbd{nfinit} format, and $x$ a matrix whose coefficients are expressed as
4094: polmods in $\var{nf}$, transforms this matrix into a matrix whose
4095: coefficients are expressed on the integral basis of $\var{nf}$. This is the
4096: same as applying \kbd{nfalgtobasis} to each entry, but it would be dangerous
4097: to use the same name.
4098:
4099: \syn{matalgtobasis}{\var{nf},x}.
4100:
4101: \subsecidx{matbasistoalg}$(\var{nf},x)$: $\var{nf}$ being a number field in
4102: \kbd{nfinit} format, and $x$ a matrix whose coefficients are expressed as
4103: column vectors on the integral basis of $\var{nf}$, transforms this matrix
4104: into a matrix whose coefficients are algebraic numbers expressed as
4105: polmods. This is the same as applying \kbd{nfbasistoalg} to each entry, but
4106: it would be dangerous to use the same name.
4107:
4108: \syn{matbasistoalg}{\var{nf},x}.
4109:
4110: \subsecidx{modreverse}$(a)$: $a$ being a polmod $A(X)$ modulo $T(X)$, finds
4111: the ``reverse polmod'' $B(X)$ modulo $Q(X)$, where $Q$ is the minimal
4112: polynomial of $a$, which must be equal to the degree of $T$, and such that if
4113: $\theta$ is a root of $T$ then $\theta=B(\alpha)$ for a certain root $\alpha$
4114: of $Q$.
4115:
4116: This is very useful when one changes the generating element in algebraic
4117: extensions.
4118:
4119: \syn{polmodrecip}{x}.
4120:
4121: \subsecidx{newtonpoly}$(x,p)$: gives the vector of the slopes of the Newton
4122: polygon of the polynomial $x$ with respect to the prime number $p$. The $n$
4123: components of the vector are in decreasing order, where $n$ is equal to the
4124: degree of $x$. Vertical slopes occur iff the constant coefficient of $x$ is
4125: zero and are denoted by \kbd{VERYBIGINT}, the biggest single precision
4126: integer representable on the machine ($2^{31}-1$ (resp.~$2^{63}-1$) on 32-bit
4127: (resp.~64-bit) machines), see \secref{se:valuation}.
4128:
4129: \syn{newtonpoly}{x,p}.
4130:
4131: \subsecidx{nfalgtobasis}$(\var{nf},x)$: this is the inverse function of
4132: \kbd{nfbasistoalg}. Given an object $x$ whose entries are expressed as
4133: algebraic numbers in the number field $\var{nf}$, transforms it so that the
4134: entries are expressed as a column vector on the integral basis
4135: \kbd{\var{nf}.zk}.
4136:
4137: \syn{algtobasis}{\var{nf},x}.
4138:
1.2 ! noro 4139: \subsecidx{nfbasis}$(x,\{\fl=0\},\{fa\})$: \idx{integral basis} of the number
! 4140: field defined by the irreducible, preferably monic, polynomial $x$, using a
! 4141: modified version of the \idx{round 4} algorithm by default, due to David
! 4142: \idx{Ford}, Sebastian \idx{Pauli} and Xavier \idx{Roblot}. The binary digits
! 4143: of $\fl$ have the following meaning:
1.1 noro 4144:
4145: 1: assume that no square of a prime greater than the default \kbd{primelimit}
4146: divides the discriminant of $x$, i.e.~that the index of $x$ has only small
4147: prime divisors.
4148:
1.2 ! noro 4149: 2: use \idx{round 2} algorithm. For small degrees and coefficient size, this
! 4150: is sometimes a little faster. (This program is the translation into C of a
! 4151: program written by David \idx{Ford} in Algeb.)
1.1 noro 4152:
4153: Thus for instance, if $\fl=3$, this uses the round 2 algorithm and outputs
4154: an order which will be maximal at all the small primes.
4155:
1.2 ! noro 4156: If $fa$ is present, we assume (without checking!) that it is the two-column
1.1 noro 4157: matrix of the factorization of the discriminant of the polynomial $x$. Note
4158: that it does \var{not} have to be a complete factorization. This is
4159: especially useful if only a local integral basis for some small set of places
4160: is desired: only factors with exponents greater or equal to 2 will be
4161: considered.
4162:
1.2 ! noro 4163: \syn{nfbasis0}{x,\fl,fa}. An extended version
! 4164: is $\teb{nfbasis}(x,\&d,\fl,fa)$, where $d$ will receive the discriminant of
! 4165: the number field (\var{not} of the polynomial $x$), and an omitted $fa$ should
! 4166: be input as \kbd{NULL}. Also available are $\teb{base}(x,\&d)$ ($\fl=0$),
! 4167: $\teb{base2}(x,\&d)$ ($\fl=2$) and $\teb{factoredbase}(x,fa,\&d)$.
1.1 noro 4168:
4169: \subsecidx{nfbasistoalg}$(\var{nf},x)$: this is the inverse function of
4170: \kbd{nfalgtobasis}. Given an object $x$ whose entries are expressed on the
4171: integral basis \kbd{\var{nf}.zk}, transforms it into an object whose entries
4172: are algebraic numbers (i.e.~polmods).
4173:
4174: \syn{basistoalg}{\var{nf},x}.
4175:
4176: \subsecidx{nfdetint}$(\var{nf},x)$: given a pseudo-matrix $x$, computes a
4177: non-zero ideal contained in (i.e.~multiple of) the determinant of $x$. This
4178: is particularly useful in conjunction with \kbd{nfhnfmod}.
4179:
4180: \syn{nfdetint}{\var{nf},x}.
4181:
1.2 ! noro 4182: \subsecidx{nfdisc}$(x,\{\fl=0\},\{fa\})$: \idx{field discriminant} of the
1.1 noro 4183: number field defined by the integral, preferably monic, irreducible
1.2 ! noro 4184: polynomial $x$. $\fl$ and $fa$ are exactly as in \kbd{nfbasis}. That is, $fa$
1.1 noro 4185: provides the matrix of a partial factorization of the discriminant of $x$,
4186: and binary digits of $\fl$ are as follows:
4187:
1.2 ! noro 4188: 1: assume that no square of a prime greater than \kbd{primelimit}
1.1 noro 4189: divides the discriminant.
4190:
1.2 ! noro 4191: 2: use the round 2 algorithm, instead of the default \idx{round 4}. This
! 4192: should be slower except maybe for polynomials of small degree and
! 4193: coefficients.
1.1 noro 4194:
1.2 ! noro 4195: \syn{nfdiscf0}{x,\fl,fa} where, to omit $fa$, you should input \kbd{NULL}. You
1.1 noro 4196: can also use $\teb{discf}(x)$ ($\fl=0$).
4197:
4198: \subsecidx{nfeltdiv}$(\var{nf},x,y)$: given two elements $x$ and $y$ in
4199: \var{nf}, computes their quotient $x/y$ in the number field $\var{nf}$.
4200:
4201: \syn{element_div}{\var{nf},x,y}.
4202:
4203: \subsecidx{nfeltdiveuc}$(\var{nf},x,y)$: given two elements $x$ and $y$ in
4204: \var{nf}, computes an algebraic integer $q$ in the number field $\var{nf}$
4205: such that the components of $x-qy$ are reasonably small. In fact, this is
4206: functionally identical to \kbd{round(nfeltdiv(\var{nf},x,y))}.
4207:
4208: \syn{nfdiveuc}{\var{nf},x,y}.
4209:
4210: \subsecidx{nfeltdivmodpr}$(\var{nf},x,y,\var{pr})$: given two elements $x$
4211: and $y$ in \var{nf} and \var{pr} a prime ideal in \kbd{modpr} format (see
4212: \tet{nfmodprinit}), computes their quotient $x / y$ modulo the prime ideal
4213: \var{pr}.
4214:
4215: \syn{element_divmodpr}{\var{nf},x,y,\var{pr}}.
4216:
4217: \subsecidx{nfeltdivrem}$(\var{nf},x,y)$: given two elements $x$ and $y$ in
4218: \var{nf}, gives a two-element row vector $[q,r]$ such that $x=qy+r$, $q$ is
4219: an algebraic integer in $\var{nf}$, and the components of $r$ are
4220: reasonably small.
4221:
4222: \syn{nfdivres}{\var{nf},x,y}.
4223:
4224: \subsecidx{nfeltmod}$(\var{nf},x,y)$: given two elements $x$ and $y$ in
4225: \var{nf}, computes an element $r$ of $\var{nf}$ of the form $r=x-qy$ with
4226: $q$ and algebraic integer, and such that $r$ is small. This is functionally
4227: identical to
4228: $$\kbd{x - nfeltmul(\var{nf},round(nfeltdiv(\var{nf},x,y)),y)}.$$
4229:
4230: \syn{nfmod}{\var{nf},x,y}.
4231:
4232: \subsecidx{nfeltmul}$(\var{nf},x,y)$: given two elements $x$ and $y$ in
4233: \var{nf}, computes their product $x*y$ in the number field $\var{nf}$.
4234:
4235: \syn{element_mul}{\var{nf},x,y}.
4236:
4237: \subsecidx{nfeltmulmodpr}$(\var{nf},x,y,\var{pr})$: given two elements $x$ and
4238: $y$ in \var{nf} and \var{pr} a prime ideal in \kbd{modpr} format (see
4239: \tet{nfmodprinit}), computes their product $x*y$ modulo the prime ideal
4240: \var{pr}.
4241:
4242: \syn{element_mulmodpr}{\var{nf},x,y,\var{pr}}.
4243:
4244: \subsecidx{nfeltpow}$(\var{nf},x,k)$: given an element $x$ in \var{nf},
4245: and a positive or negative integer $k$, computes $x^k$ in the number field
4246: $\var{nf}$.
4247:
4248: \syn{element_pow}{\var{nf},x,k}.
4249:
4250: \subsecidx{nfeltpowmodpr}$(\var{nf},x,k,\var{pr})$: given an element $x$ in
4251: \var{nf}, an integer $k$ and a prime ideal \var{pr} in \kbd{modpr} format
4252: (see \tet{nfmodprinit}), computes $x^k$ modulo the prime ideal \var{pr}.
4253:
4254: \syn{element_powmodpr}{\var{nf},x,k,\var{pr}}.
4255:
4256: \subsecidx{nfeltreduce}$(\var{nf},x,\var{ideal})$: given an ideal in
4257: Hermite normal form and an element $x$ of the number field $\var{nf}$,
4258: finds an element $r$ in $\var{nf}$ such that $x-r$ belongs to the ideal
4259: and $r$ is small.
4260:
4261: \syn{element_reduce}{\var{nf},x,\var{ideal}}.
4262:
4263: \subsecidx{nfeltreducemodpr}$(\var{nf},x,\var{pr})$: given
4264: an element $x$ of the number field $\var{nf}$ and a prime ideal \var{pr} in
4265: \kbd{modpr} format compute a canonical representative for the class of $x$
4266: modulo \var{pr}.
4267:
1.2 ! noro 4268: \syn{nfreducemodpr}{\var{nf},x,\var{pr}}.
1.1 noro 4269:
4270: \subsecidx{nfeltval}$(\var{nf},x,\var{pr})$: given an element $x$ in
4271: \var{nf} and a prime ideal \var{pr} in the format output by
4272: \kbd{idealprimedec}, computes their the valuation at \var{pr} of the
4273: element $x$. The same result could be obtained using
4274: \kbd{idealval(\var{nf},x,\var{pr})} (since $x$ would then be converted to a
4275: principal ideal), but it would be less efficient.
4276:
4277: \syn{element_val}{\var{nf},x,\var{pr}}, and the result is a \kbd{long}.
4278:
4279: \subsecidx{nffactor}$(\var{nf},x)$: factorization of the univariate
4280: polynomial $x$ over the number field $\var{nf}$ given by \kbd{nfinit}. $x$
4281: has coefficients in $\var{nf}$ (i.e.~either scalar, polmod, polynomial or
4282: column vector). The main variable of $\var{nf}$ must be of \var{lower}
1.2 ! noro 4283: priority than that of $x$ (see \secref{se:priority}). However if
! 4284: the polynomial defining the number field occurs explicitly in the
! 4285: coefficients of $x$ (as modulus of a \typ{POLMOD}), its main variable must be
! 4286: \var{the same} as the main variable of $x$. For example,
1.1 noro 4287: \bprog
4288: ? nf = nfinit(y^2 + 1);
4289: ? nffactor(nf, x^2 + y); \\@com OK
4290: ? nffactor(nf, x^2 + Mod(y, y^2+1)); \\ @com OK
4291: ? nffactor(nf, x^2 + Mod(z, z^2+1)); \\ @com WRONG
4292: @eprog
4293:
4294: \syn{nffactor}{\var{nf},x}.
4295:
4296: \subsecidx{nffactormod}$(\var{nf},x,\var{pr})$: factorization of the
4297: univariate polynomial $x$ modulo the prime ideal \var{pr} in the number
4298: field $\var{nf}$. $x$ can have coefficients in the number field (scalar,
4299: polmod, polynomial, column vector) or modulo the prime ideal (integermod
4300: modulo the rational prime under \var{pr}, polmod or polynomial with
4301: integermod coefficients, column vector of integermod). The prime ideal
4302: \var{pr} \var{must} be in the format output by \kbd{idealprimedec}. The
1.2 ! noro 4303: main variable of $\var{nf}$ must be of lower priority than that of $x$
! 4304: (see \secref{se:priority}). However if the coefficients of the number
! 4305: field occur explicitly (as polmods) as coefficients of $x$, the variable of
! 4306: these polmods \var{must} be the same as the main variable of $t$ (see
! 4307: \kbd{nffactor}).
1.1 noro 4308:
4309: \syn{nffactormod}{\var{nf},x,\var{pr}}.
4310:
4311: \subsecidx{nfgaloisapply}$(\var{nf},\var{aut},x)$: $\var{nf}$ being a
4312: number field as output by \kbd{nfinit}, and \var{aut} being a \idx{Galois}
4313: automorphism of $\var{nf}$ expressed either as a polynomial or a polmod
4314: (such automorphisms being found using for example one of the variants of
4315: \kbd{nfgaloisconj}), computes the action of the automorphism \var{aut} on
4316: the object $x$ in the number field. $x$ can be an element (scalar, polmod,
4317: polynomial or column vector) of the number field, an ideal (either given by
4318: $\Z_K$-generators or by a $\Z$-basis), a prime ideal (given as a 5-element
4319: row vector) or an idele (given as a 2-element row vector). Because of
4320: possible confusion with elements and ideals, other vector or matrix
4321: arguments are forbidden.
4322:
4323: \syn{galoisapply}{\var{nf},\var{aut},x}.
4324:
4325: \subsecidx{nfgaloisconj}$(\var{nf},\{\fl=0\},\{d\})$: $\var{nf}$ being a
4326: number field as output by \kbd{nfinit}, computes the conjugates of a root
4327: $r$ of the non-constant polynomial $x=\var{nf}[1]$ expressed as
4328: polynomials in $r$. This can be used even if the number field $\var{nf}$ is
4329: not \idx{Galois} since some conjugates may lie in the field. As a note to
4330: old-timers of PARI, starting with version 2.0.17 this function works much
4331: better than in earlier versions.
4332:
4333: $\var{nf}$ can simply be a polynomial if $\fl\neq 1$.
4334:
4335: If no flags or $\fl=0$, if $\var{nf}$ is a number field use a
4336: combination of flag $4$ and $1$ and the result is always complete,
4337: else use a combination of flag $4$ and $2$ and the result is subject
4338: to the restriction of $\fl=2$, but a warning is issued when it is not
4339: proven complete.
4340:
4341: If $\fl=1$, use \kbd{nfroots} (require a number field).
4342:
4343: If $\fl=2$, use complex approximations to the roots and an integral
4344: \idx{LLL}. The result is not guaranteed to be complete: some
4345: conjugates may be missing (no warning issued), especially so if the
4346: corresponding polynomial has a huge index. In that case, increasing
4347: the default precision may help.
4348:
4349: If $\fl=4$, use Allombert's algorithm and permutation testing. If the
4350: field is Galois with ``weakly'' super solvable Galois group, return
4351: the complete list of automorphisms, else only the identity element. If
4352: present, $d$ is assumed to be a multiple of the least common
4353: denominator of the conjugates expressed as polynomial in a root of
4354: \var{pol}.
4355:
4356: A group G is ``weakly'' super solvable if it contains a super solvable
4357: normal subgroup $H$ such that $G=H$ , or $G/H \simeq A_4$ , or $G/H \simeq
4358: S_4$. Abelian and nilpotent groups are ``weakly'' super solvable. In
4359: practice, almost all groups of small order are ``weakly'' super solvable, the
4360: exceptions having order 36(1 exception), 48(2), 56(1), 60(1), 72(5), 75(1),
4361: 80(1), 96(10) and $\geq 108$.
4362:
4363: Hence $\fl = 4$ permits to quickly check whether a polynomial of order
4364: strictly less than $36$ is Galois or not. This method is much faster than
4365: \kbd{nfroots} and can be applied to polynomials of degree larger than $50$.
4366:
4367: \syn{galoisconj0}{\var{nf},\fl,d,\var{prec}}. Also available are
4368: $\teb{galoisconj}(\var{nf})$ for $\fl=0$,
4369: $\teb{galoisconj2}(\var{nf},n,\var{prec})$ for $\fl=2$ where $n$ is a bound
4370: on the number of conjugates, and $\teb{galoisconj4}(\var{nf},d)$
4371: corresponding to $\fl=4$.
4372:
4373: \subsecidx{nfhilbert}$(\var{nf},a,b,\{\var{pr}\})$: if \var{pr} is omitted,
4374: compute the global \idx{Hilbert symbol} $(a,b)$ in $\var{nf}$, that is $1$
4375: if $x^2 - a y^2 - b z^2$ has a non trivial solution $(x,y,z)$ in $\var{nf}$,
4376: and $-1$ otherwise. Otherwise compute the local symbol modulo the prime ideal
4377: \var{pr} (as output by \kbd{idealprimedec}).
4378:
4379: \syn{nfhilbert}{\var{nf},a,b,\var{pr}}, where an omitted \var{pr} is coded
4380: as \kbd{NULL}.
4381:
4382: \subsecidx{nfhnf}$(\var{nf},x)$: given a pseudo-matrix $(A,I)$, finds a
4383: pseudo-basis in \idx{Hermite normal form} of the module it generates.
4384:
4385: \syn{nfhermite}{\var{nf},x}.
4386:
4387: \subsecidx{nfhnfmod}$(\var{nf},x,\var{detx})$: given a pseudo-matrix $(A,I)$
4388: and an ideal \var{detx} which is contained in (read integral multiple of) the
4389: determinant of $(A,I)$, finds a pseudo-basis in \idx{Hermite normal form}
4390: of the module generated by $(A,I)$. This avoids coefficient explosion.
4391: \var{detx} can be computed using the function \kbd{nfdetint}.
4392:
4393: \syn{nfhermitemod}{\var{nf},x,\var{detx}}.
4394:
4395: \subsecidx{nfinit}$(\var{pol},\{\fl=0\})$: \var{pol} being a non-constant,
4396: preferably monic, irreducible polynomial in $\Z[X]$, initializes a
4397: \var{number field} structure (\kbd{nf}) associated to the field $K$ defined
4398: by \var{pol}. As such, it's a technical object passed as the first argument
4399: to most \kbd{nf}\var{xxx} functions, but it contains some information which
4400: may be directly useful. Access to this information via \var{member
1.2 ! noro 4401: functions} is preferred since the specific data organization specified below
1.1 noro 4402: may change in the future. Currently, \kbd{nf} is a row vector with 9
4403: components:
4404:
4405: $\var{nf}[1]$ contains the polynomial \var{pol} (\kbd{\var{nf}.pol}).
4406:
4407: $\var{nf}[2]$ contains $[r1,r2]$ (\kbd{\var{nf}.sign}), the number of real
4408: and complex places of $K$.
4409:
4410: $\var{nf}[3]$ contains the discriminant $d(K)$ (\kbd{\var{nf}.disc}) of $K$.
4411:
4412: $\var{nf}[4]$ contains the index of $\var{nf}[1]$,
4413: i.e.~$[\Z_K : \Z[\theta]]$, where $\theta$ is any root of $\var{nf}[1]$.
4414:
1.2 ! noro 4415: $\var{nf}[5]$ is a vector containing 7 matrices $M$, $G$, $T2$, $T$,
1.1 noro 4416: $MD$, $TI$, $MDI$ useful for certain computations in the number field $K$.
4417:
4418: \quad$\bullet$ $M$ is the $(r1+r2)\times n$ matrix whose columns represent
4419: the numerical values of the conjugates of the elements of the integral
4420: basis.
4421:
1.2 ! noro 4422: \quad$\bullet$ $G$ is such that $T2 = {}^t G G$, where $T2$ is the quadratic
! 4423: form $T_2(x) = \sum |\sigma(x)|^2$, $\sigma$ running over the embeddings of
! 4424: $K$ into $\C$.
1.1 noro 4425:
1.2 ! noro 4426: \quad$\bullet$ The $T2$ component is deprecated and currently unused.
1.1 noro 4427:
4428: \quad$\bullet$ $T$ is the $n\times n$ matrix whose coefficients are
4429: $\text{Tr}(\omega_i\omega_j)$ where the $\omega_i$ are the elements of the
1.2 ! noro 4430: integral basis. Note also that $\det(T)$ is equal to the discriminant of the
! 4431: field $K$.
1.1 noro 4432:
4433: \quad$\bullet$ The columns of $MD$ (\kbd{\var{nf}.diff}) express a $\Z$-basis
4434: of the different of $K$ on the integral basis.
4435:
4436: \quad$\bullet$ $TI$ is equal to $d(K)T^{-1}$, which has integral
4437: coefficients. Note that, understood as as ideal, the matrix $T^{-1}$
4438: generates the codifferent ideal.
4439:
4440: \quad$\bullet$ Finally, $MDI$ is a two-element representation (for faster
4441: ideal product) of $d(K)$ times the codifferent ideal
4442: (\kbd{\var{nf}.disc$*$\var{nf}.codiff}, which is an integral ideal). $MDI$
4443: is only used in \tet{idealinv}.
4444:
4445: $\var{nf}[6]$ is the vector containing the $r1+r2$ roots
4446: (\kbd{\var{nf}.roots}) of $\var{nf}[1]$ corresponding to the $r1+r2$
4447: embeddings of the number field into $\C$ (the first $r1$ components are real,
4448: the next $r2$ have positive imaginary part).
4449:
1.2 ! noro 4450: $\var{nf}[7]$ is an integral basis for $\Z_K$ (\kbd{\var{nf}.zk}) expressed
! 4451: on the powers of~$\theta$. Its first element is guaranteed to be $1$. This
! 4452: basis is LLL-reduced with respect to $T_2$ (strictly speaking, it is a
! 4453: permutation of such a basis, due to the condition that the first element be
! 4454: $1$).
1.1 noro 4455:
4456: $\var{nf}[8]$ is the $n\times n$ integral matrix expressing the power
4457: basis in terms of the integral basis, and finally
4458:
4459: $\var{nf}[9]$ is the $n\times n^2$ matrix giving the multiplication table
4460: of the integral basis.
4461:
4462: If a non monic polynomial is input, \kbd{nfinit} will transform it into a
4463: monic one, then reduce it (see $\fl=3$). It is allowed, though not very
4464: useful given the existence of \tet{nfnewprec}, to input a \kbd{nf} or a
4465: \kbd{bnf} instead of a polynomial.
4466:
4467: The special input format $[x,B]$ is also accepted where $x$ is a polynomial
1.2 ! noro 4468: as above and $B$ is the integer basis, as would be computed by \tet{nfbasis}.
! 4469: This can be useful if the integer basis is known in advance.
1.1 noro 4470:
4471: If $\fl=2$: \var{pol} is changed into another polynomial $P$ defining the same
4472: number field, which is as simple as can easily be found using the
4473: \kbd{polred} algorithm, and all the subsequent computations are done using
4474: this new polynomial. In particular, the first component of the result is the
4475: modified polynomial.
4476:
4477: If $\fl=3$, does a \kbd{polred} as in case 2, but outputs
4478: $[\var{nf},\kbd{Mod}(a,P)]$, where $\var{nf}$ is as before and
4479: $\kbd{Mod}(a,P)=\kbd{Mod}(x,\var{pol})$ gives the change of
4480: variables. This is implicit when \var{pol} is not monic: first a linear change
4481: of variables is performed, to get a monic polynomial, then a \kbd{polred}
4482: reduction.
4483:
4484: If $\fl=4$, as $2$ but uses a partial \kbd{polred}.
4485:
4486: If $\fl=5$, as $3$ using a partial \kbd{polred}.
4487:
4488: \syn{nfinit0}{x,\fl,\var{prec}}.
4489:
4490: \subsecidx{nfisideal}$(\var{nf},x)$: returns 1 if $x$ is an ideal in
4491: the number field $\var{nf}$, 0 otherwise.
4492:
4493: \syn{isideal}{x}.
4494:
4495: \subsecidx{nfisincl}$(x,y)$: tests whether the number field $K$ defined
4496: by the polynomial $x$ is conjugate to a subfield of the field $L$ defined
4497: by $y$ (where $x$ and $y$ must be in $\Q[X]$). If they are not, the output
4498: is the number 0. If they are, the output is a vector of polynomials, each
4499: polynomial $a$ representing an embedding of $K$ into $L$, i.e.~being such
4500: that $y\mid x\circ a$.
4501:
4502: If $y$ is a number field (\var{nf}), a much faster algorithm is used
4503: (factoring $x$ over $y$ using \tet{nffactor}). Before version 2.0.14, this
4504: wasn't guaranteed to return all the embeddings, hence was triggered by a
4505: special flag. This is no more the case.
4506:
4507: \syn{nfisincl}{x,y,\fl}.
4508:
4509: \subsecidx{nfisisom}$(x,y)$: as \tet{nfisincl}, but tests
4510: for isomorphism. If either $x$ or $y$ is a number field, a much faster
4511: algorithm will be used.
4512:
4513: \syn{nfisisom}{x,y,\fl}.
4514:
4515: \subsecidx{nfnewprec}$(\var{nf})$: transforms the number field $\var{nf}$
4516: into the corresponding data using current (usually larger) precision. This
4517: function works as expected if $\var{nf}$ is in fact a $\var{bnf}$ (update
4518: $\var{bnf}$ to current precision) but may be quite slow (many generators of
4519: principal ideals have to be computed).
4520:
4521: \syn{nfnewprec}{\var{nf},\var{prec}}.
4522:
4523: \subsecidx{nfkermodpr}$(\var{nf},a,\var{pr})$: kernel of the matrix $a$ in
4524: $\Z_K/\var{pr}$, where \var{pr} is in \key{modpr} format
4525: (see \kbd{nfmodprinit}).
4526:
4527: \syn{nfkermodpr}{\var{nf},a,\var{pr}}.
4528:
4529: \subsecidx{nfmodprinit}$(\var{nf},\var{pr})$: transforms the prime ideal
4530: \var{pr} into \tet{modpr} format necessary for all operations modulo
4531: \var{pr} in the number field \var{nf}. Returns a two-component vector
4532: $[P,a]$, where $P$ is the \idx{Hermite normal form} of \var{pr}, and $a$ is
4533: an integral element congruent to $1$ modulo \var{pr}, and congruent to $0$
4534: modulo $p / pr^e$. Here $p = \Z \cap \var{pr}$ and $e$
4535: is the absolute ramification index.\label{se:nfmodprinit}
4536:
4537: \syn{nfmodprinit}{\var{nf},\var{pr}}.
4538:
4539: \subsecidx{nfsubfields}$(\var{pol},\{d=0\})$: finds all subfields of degree
4540: $d$ of the number field defined by the (monic, integral) polynomial
4541: \var{pol} (all subfields if $d$ is null or omitted). The result is a vector
4542: of subfields, each being given by $[g,h]$, where $g$ is an absolute equation
4543: and $h$ expresses one of the roots of $g$ in terms of the root $x$ of the
1.2 ! noro 4544: polynomial defining $\var{nf}$. This routine uses J.~Kl\"uners's algorithm
! 4545: in the general case, and B.~Allombert's \tet{galoissubfields} when \var{nf}
! 4546: is Galois (with weakly supersolvable Galois group).\sidx{Galois}\sidx{subfield}
1.1 noro 4547:
4548: \syn{subfields}{\var{nf},d}.
4549:
4550: \subsecidx{nfroots}$(\var{nf},x)$: roots of the polynomial $x$ in the number
4551: field $\var{nf}$ given by \kbd{nfinit} without multiplicity. $x$ has
4552: coefficients in the number field (scalar, polmod, polynomial, column
4553: vector). The main variable of $\var{nf}$ must be of lower priority than that
1.2 ! noro 4554: of $x$ (see \secref{se:priority}). However if the coefficients of the
! 4555: number field occur explicitly (as polmods) as coefficients of $x$, the
! 4556: variable of these polmods \var{must} be the same as the main variable of $t$
! 4557: (see \kbd{nffactor}).
1.1 noro 4558:
4559: \syn{nfroots}{\var{nf},x}.
4560:
4561: \subsecidx{nfrootsof1}$(\var{nf})$: computes the number of roots of unity
4562: $w$ and a primitive $w$-th root of unity (expressed on the integral basis)
4563: belonging to the number field $\var{nf}$. The result is a two-component
4564: vector $[w,z]$ where $z$ is a column vector expressing a primitive $w$-th
4565: root of unity on the integral basis \kbd{\var{nf}.zk}.
4566:
4567: \syn{rootsof1}{\var{nf}}.
4568:
4569: \subsecidx{nfsnf}$(\var{nf},x)$: given a torsion module $x$ as a 3-component
4570: row
4571: vector $[A,I,J]$ where $A$ is a square invertible $n\times n$ matrix, $I$ and
4572: $J$ are two ideal lists, outputs an ideal list $d_1,\dots,d_n$ which is the
4573: \idx{Smith normal form} of $x$. In other words, $x$ is isomorphic to
4574: $\Z_K/d_1\oplus\cdots\oplus\Z_K/d_n$ and $d_i$ divides $d_{i-1}$ for $i\ge2$.
4575: The link between $x$ and $[A,I,J]$ is as follows: if $e_i$ is the canonical
4576: basis of $K^n$, $I=[b_1,\dots,b_n]$ and $J=[a_1,\dots,a_n]$, then $x$ is
4577: isomorphic to
4578: $$ (b_1e_1\oplus\cdots\oplus b_ne_n) / (a_1A_1\oplus\cdots\oplus a_nA_n)
4579: \enspace, $$
4580: where the $A_j$ are the columns of the matrix $A$. Note that every finitely
4581: generated torsion module can be given in this way, and even with $b_i=Z_K$
4582: for all $i$.
4583:
4584: \syn{nfsmith}{\var{nf},x}.
4585:
4586: \subsecidx{nfsolvemodpr}$(\var{nf},a,b,\var{pr})$: solution of $a\cdot x = b$
4587: in $\Z_K/\var{pr}$, where $a$ is a matrix and $b$ a column vector, and where
4588: \var{pr} is in \key{modpr} format (see \kbd{nfmodprinit}).
4589:
4590: \syn{nfsolvemodpr}{\var{nf},a,b,\var{pr}}.
4591:
4592: \subsecidx{polcompositum}$(x,y,\{\fl=0\})$: $x$ and $y$ being polynomials
4593: in $\Z[X]$ in the same variable, outputs a vector giving the list of all
4594: possible composita of the number fields defined by $x$ and $y$, if $x$ and
4595: $y$ are irreducible, or of the corresponding \'etale algebras, if they are
4596: only squarefree. Returns an error if one of the polynomials is not
4597: squarefree. When one of the polynomials is irreducible (say $x$), it is
4598: often \var{much} faster to use \kbd{nffactor(nfinit($x$), $y$)} then
4599: \tet{rnfequation}.
4600:
4601: If $\fl=1$, outputs a vector of 4-component vectors $[z,a,b,k]$, where $z$
4602: ranges through the list of all possible compositums as above, and $a$
4603: (resp. $b$) expresses the root of $x$ (resp. $y$) as a polmod in a root of
4604: $z$, and $k$ is a small integer k such that $a+kb$ is the chosen root of
4605: $z$.
4606:
4607: The compositum will quite often be defined by a complicated polynomial,
4608: which it is advisable to reduce before further work. Here is a simple
4609: example involving the field $\Q(\zeta_5, 5^{1/5})$:
4610: \bprog
4611: ? z = polcompositum(x^5 - 5, polcyclo(5), 1)[1];
4612: ? pol = z[1] \\@com \kbd{pol} defines the compositum
4613: %2 = x^20 + 5*x^19 + 15*x^18 + 35*x^17 + 70*x^16 + 141*x^15 + 260*x^14 \
4614: + 355*x^13 + 95*x^12 - 1460*x^11 - 3279*x^10 - 3660*x^9 - 2005*x^8 \
4615: + 705*x^7 + 9210*x^6 + 13506*x^5 + 7145*x^4 - 2740*x^3 + 1040*x^2 \
4616: - 320*x + 256
4617: ? a = z[2]; a^5 - 5 \\@com \kbd{a} is a fifth root of $5$
4618: %3 = 0
4619: ? z = polredabs(pol, 1); \\@com look for a simpler polynomial
4620: ? pol = z[1]
4621: %5 = x^20 + 25*x^10 + 5
4622: ? a = subst(a.pol, x, z[2]) \\@com \kbd{a} in the new coordinates
4623: %6 = Mod(-5/22*x^19 + 1/22*x^14 - 123/22*x^9 + 9/11*x^4, x^20 + 25*x^10 + 5)
4624: @eprog
4625:
4626: \syn{polcompositum0}{x,y,\fl}.
4627:
4628: \subsecidx{polgalois}$(x)$: \idx{Galois} group of the non-constant polynomial
4629: $x\in\Q[X]$. In the present version \vers, $x$ must be irreducible and
4630: the degree of $x$ must be less than or equal to 7. On certain versions for
4631: which the data file of Galois resolvents has been installed (available
4632: in the Unix distribution as a separate package), degrees 8, 9, 10 and 11
4633: are also implemented.
4634:
4635: The output is a 3-component vector $[n,s,k]$ with the following meaning: $n$
4636: is the cardinality of the group, $s$ is its signature ($s=1$ if the group is
1.2 ! noro 4637: a subgroup of the alternating group $A_n$, $s=-1$ otherwise).
! 4638:
! 4639: $k$ is more arbitrary and the choice made up to version~2.2.3 of PARI is rather
! 4640: unfortunate: for $n > 7$, $k$ is the numbering of the group among all
! 4641: transitive subgroups of $S_n$, as given in ``The transitive groups of degree up
! 4642: to eleven'', G.~Butler and J.~McKay, Communications in Algebra, vol.~11, 1983,
! 4643: pp.~863--911 (group $k$ is denoted $T_k$ there). And for $n \leq 7$, it was ad
! 4644: hoc, so as to ensure that a given triple would design a unique group.
! 4645: Specifically, for polynomials of degree $\leq 7$, the groups are coded as
! 4646: follows, using standard notations
1.1 noro 4647: \smallskip
1.2 ! noro 4648: In degree 1: $S_1=[1,1,1]$.
1.1 noro 4649: \smallskip
4650: In degree 2: $S_2=[2,-1,1]$.
4651: \smallskip
4652: In degree 3: $A_3=C_3=[3,1,1]$, $S_3=[6,-1,1]$.
4653: \smallskip
4654: In degree 4: $C_4=[4,-1,1]$, $V_4=[4,1,1]$, $D_4=[8,-1,1]$, $A_4=[12,1,1]$,
4655: $S_4=[24,-1,1]$.
4656: \smallskip
4657: In degree 5: $C_5=[5,1,1]$, $D_5=[10,1,1]$, $M_{20}=[20,-1,1]$,
4658: $A_5=[60,1,1]$, $S_5=[120,-1,1]$.
4659: \smallskip
4660: In degree 6: $C_6=[6,-1,1]$, $S_3=[6,-1,2]$, $D_6=[12,-1,1]$, $A_4=[12,1,1]$,
4661: $G_{18}=[18,-1,1]$, $S_4^-=[24,-1,1]$, $A_4\times C_2=[24,-1,2]$,
4662: $S_4^+=[24,1,1]$, $G_{36}^-=[36,-1,1]$, $G_{36}^+=[36,1,1]$,
4663: $S_4\times C_2=[48,-1,1]$, $A_5=PSL_2(5)=[60,1,1]$, $G_{72}=[72,-1,1]$,
4664: $S_5=PGL_2(5)=[120,-1,1]$, $A_6=[360,1,1]$, $S_6=[720,-1,1]$.
4665: \smallskip
4666: In degree 7: $C_7=[7,1,1]$, $D_7=[14,-1,1]$, $M_{21}=[21,1,1]$,
4667: $M_{42}=[42,-1,1]$, $PSL_2(7)=PSL_3(2)=[168,1,1]$, $A_7=[2520,1,1]$,
4668: $S_7=[5040,-1,1]$.
4669: \smallskip
1.2 ! noro 4670: This is deprecated and obsolete, but for reasons of backward compatibility,
! 4671: we cannot change this behaviour yet. So you can use the default
! 4672: \tet{newgaloisformat} to switch to a consistent naming scheme, namely $k$ is
! 4673: always the standard numbering of the group among all transitive subgroups of
! 4674: $S_n$. If this default is in effect, the above groups will be coded as:
! 4675: \smallskip
! 4676: In degree 1: $S_1=[1,1,1]$.
! 4677: \smallskip
! 4678: In degree 2: $S_2=[2,-1,1]$.
! 4679: \smallskip
! 4680: In degree 3: $A_3=C_3=[3,1,1]$, $S_3=[6,-1,2]$.
! 4681: \smallskip
! 4682: In degree 4: $C_4=[4,-1,1]$, $V_4=[4,1,2]$, $D_4=[8,-1,3]$, $A_4=[12,1,4]$,
! 4683: $S_4=[24,-1,5]$.
! 4684: \smallskip
! 4685: In degree 5: $C_5=[5,1,1]$, $D_5=[10,1,2]$, $M_{20}=[20,-1,3]$,
! 4686: $A_5=[60,1,4]$, $S_5=[120,-1,5]$.
! 4687: \smallskip
! 4688: In degree 6: $C_6=[6,-1,1]$, $S_3=[6,-1,2]$, $D_6=[12,-1,3]$, $A_4=[12,1,4]$,
! 4689: $G_{18}=[18,-1,5]$, $A_4\times C_2=[24,-1,6]$, $S_4^+=[24,1,7]$,
! 4690: $S_4^-=[24,-1,8]$, $G_{36}^-=[36,-1,9]$, $G_{36}^+=[36,1,10]$,
! 4691: $S_4\times C_2=[48,-1,11]$, $A_5=PSL_2(5)=[60,1,12]$, $G_{72}=[72,-1,13]$,
! 4692: $S_5=PGL_2(5)=[120,-1,14]$, $A_6=[360,1,15]$, $S_6=[720,-1,16]$.
! 4693: \smallskip
! 4694: In degree 7: $C_7=[7,1,1]$, $D_7=[14,-1,2]$, $M_{21}=[21,1,3]$,
! 4695: $M_{42}=[42,-1,4]$, $PSL_2(7)=PSL_3(2)=[168,1,5]$, $A_7=[2520,1,6]$,
! 4696: $S_7=[5040,-1,7]$.
! 4697: \smallskip
! 4698:
! 4699: \misctitle{Warning} The method used is that of resolvent polynomials and is
! 4700: sensitive to the current precision. The precision is updated internally but,
! 4701: in very rare cases, a wrong result may be returned if the initial precision
! 4702: was not sufficient.
1.1 noro 4703:
1.2 ! noro 4704: \syn{galois}{x,\var{prec}}. To enable the new format in library mode, set the
! 4705: global variable \tet{new_galois_format} to $1$.
1.1 noro 4706:
1.2 ! noro 4707: \subsecidx{polred}$(x,\{\fl=0\},\{fa\})$: finds polynomials with reasonably
1.1 noro 4708: small coefficients defining subfields of the number field defined by $x$.
4709: One of the polynomials always defines $\Q$ (hence is equal to $x-1$),
4710: and another always defines the same number field as $x$ if $x$ is irreducible.
4711: All $x$ accepted by \tet{nfinit} are also allowed here (e.g. non-monic
4712: polynomials, \kbd{nf}, \kbd{bnf}, \kbd{[x,Z\_K\_basis]}).
4713:
4714: The following binary digits of $\fl$ are significant:
4715:
1.2 ! noro 4716: 1: possibly use a suborder of the maximal order. The primes dividing the
! 4717: index of the order chosen are larger than \tet{primelimit} or divide integers
! 4718: stored in the \tet{addprimes} table.
1.1 noro 4719:
4720: 2: gives also elements. The result is a two-column matrix, the first column
4721: giving the elements defining these subfields, the second giving the
4722: corresponding minimal polynomials.
4723:
1.2 ! noro 4724: If $fa$ is given, it is assumed that it is the two-column matrix of the
1.1 noro 4725: factorization of the discriminant of the polynomial $x$.
4726:
1.2 ! noro 4727: \syn{polred0}{x,\fl,fa}, where an omitted $fa$ is coded by \kbd{NULL}. Also
! 4728: available are $\teb{polred}(x)$ and $\teb{factoredpolred}(x,fa)$, both
! 4729: corresponding to $\fl=0$.
1.1 noro 4730:
4731: \subsecidx{polredabs}$(x,\{\fl=0\})$: finds one of the polynomial defining
4732: the same number field as the one defined by $x$, and such that the sum of the
4733: squares of the modulus of the roots (i.e.~the $T_2$-norm) is minimal.
4734: All $x$ accepted by \tet{nfinit} are also allowed here (e.g. non-monic
4735: polynomials, \kbd{nf}, \kbd{bnf}, \kbd{[x,Z\_K\_basis]}).
4736:
1.2 ! noro 4737: \misctitle{Warning:} this routine uses an exponential-time algorithm to
! 4738: enumerate all potential generators, and may be exceedingly slow when the
! 4739: number field has many subfields, hence a lot of elements of small $T_2$-norm.
! 4740: E.g. do not try it on the compositum of many quadratic fields, use
! 4741: \tet{polred} instead.
! 4742:
1.1 noro 4743: The binary digits of $\fl$ mean
4744:
4745: 1: outputs a two-component row vector $[P,a]$, where $P$ is the default
4746: output and $a$ is an element expressed on a root of the polynomial $P$,
4747: whose minimal polynomial is equal to $x$.
4748:
4749: 4: gives \var{all} polynomials of minimal $T_2$ norm (of the two polynomials
4750: $P(x)$ and $P(-x)$, only one is given).
4751:
1.2 ! noro 4752: 16: possibly use a suborder of the maximal order. The primes dividing the
! 4753: index of the order chosen are larger than \tet{primelimit} or divide integers
! 4754: stored in the \tet{addprimes} table. In that case it may happen that the
! 4755: output polynomial does not have minimal $T_2$ norm.\label{se:polredabs}
! 4756:
! 4757: \syn{polredabs0}{x,\fl}.
1.1 noro 4758:
4759: \subsecidx{polredord}$(x)$: finds polynomials with reasonably small
4760: coefficients and of the same degree as that of $x$ defining suborders of the
4761: order defined by $x$. One of the polynomials always defines $\Q$ (hence
4762: is equal to $(x-1)^n$, where $n$ is the degree), and another always defines
4763: the same order as $x$ if $x$ is irreducible.
4764:
4765: \syn{ordred}{x}.
4766:
4767: \subsecidx{poltschirnhaus}$(x)$: applies a random Tschirnhausen
4768: transformation to the polynomial $x$, which is assumed to be non-constant
4769: and separable, so as to obtain a new equation for the \'etale algebra
4770: defined by $x$. This is for instance useful when computing resolvents,
4771: hence is used by the \kbd{polgalois} function.
4772:
4773: \syn{tschirnhaus}{x}.
4774:
4775: \subsecidx{rnfalgtobasis}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
4776: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an element of
4777: $L$ expressed as a polynomial or polmod with polmod coefficients, expresses
4778: $x$ on the relative integral basis.
4779:
4780: \syn{rnfalgtobasis}{\var{rnf},x}.
4781:
4782: \subsecidx{rnfbasis}$(\var{bnf},x)$: given a big number field $\var{bnf}$ as
4783: output by \kbd{bnfinit}, and either a polynomial $x$ with coefficients in
4784: $\var{bnf}$ defining a relative extension $L$ of $\var{bnf}$, or a
4785: pseudo-basis $x$ of such an extension, gives either a true $\var{bnf}$-basis
4786: of $L$ if it exists, or an $n+1$-element generating set of $L$ if not, where
4787: $n$ is the rank of $L$ over $\var{bnf}$.
4788:
4789: \syn{rnfbasis}{\var{bnf},x}.
4790:
4791: \subsecidx{rnfbasistoalg}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
4792: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an element of
4793: $L$ expressed on the relative integral basis, computes the representation of
4794: $x$ as a polmod with polmods coefficients.
4795:
4796: \syn{rnfbasistoalg}{\var{rnf},x}.
4797:
4798: \subsecidx{rnfcharpoly}$(\var{nf},T,a,\{v=x\})$: characteristic polynomial of
4799: $a$ over $\var{nf}$, where $a$ belongs to the algebra defined by $T$ over
4800: $\var{nf}$, i.e.~$\var{nf}[X]/(T)$. Returns a polynomial in variable $v$
4801: ($x$ by default).
4802:
4803: \syn{rnfcharpoly}{\var{nf},T,a,v}, where $v$ is a variable number.
4804:
4805: \subsecidx{rnfconductor}$(\var{bnf},\var{pol},\{\fl=0\})$: $\var{bnf}$
4806: being a big number field as output by \kbd{bnfinit}, and \var{pol} a
4807: relative polynomial defining an \idx{Abelian extension}, computes the
4808: class field theory conductor of this Abelian extension. The result is
4809: a 3-component vector $[\var{conductor},\var{rayclgp},\var{subgroup}]$,
4810: where \var{conductor} is the conductor of the extension given as a
4811: 2-component row vector $[f_0,f_\infty]$, \var{rayclgp} is the full ray
4812: class group corresponding to the conductor given as a 3-component
4813: vector [h,cyc,gen] as usual for a group, and \var{subgroup} is a
4814: matrix in HNF defining the subgroup of the ray class group on the
1.2 ! noro 4815: given generators gen. If $\fl$ is non-zero, check that \var{pol} indeed
! 4816: defines an Abelian extension, return 0 if it does not.
1.1 noro 4817:
4818: \syn{rnfconductor}{\var{rnf},\var{pol},\fl}.
4819:
4820: \subsecidx{rnfdedekind}$(\var{nf},\var{pol},\var{pr})$: given a number field
4821: $\var{nf}$ as output by \kbd{nfinit} and a polynomial \var{pol} with
4822: coefficients in $\var{nf}$ defining a relative extension $L$ of $\var{nf}$,
4823: evaluates the relative \idx{Dedekind} criterion over the order defined by a
4824: root of \var{pol} for the prime ideal \var{pr} and outputs a 3-component
4825: vector as the result. The first component is a flag equal to 1 if the
4826: enlarged order could be proven to be \var{pr}-maximal and to 0 otherwise (it
4827: may be maximal in the latter case if \var{pr} is ramified in $L$), the second
4828: component is a pseudo-basis of the enlarged order and the third component is
4829: the valuation at \var{pr} of the order discriminant.
4830:
4831: \syn{rnfdedekind}{\var{nf},\var{pol},\var{pr}}.
4832:
4833: \subsecidx{rnfdet}$(\var{nf},M)$: given a pseudomatrix $M$ over the maximal
4834: order of $\var{nf}$, computes its pseudodeterminant.
4835:
4836: \syn{rnfdet}{\var{nf},M}.
4837:
4838: \subsecidx{rnfdisc}$(\var{nf},\var{pol})$: given a number field $\var{nf}$ as
4839: output by \kbd{nfinit} and a polynomial \var{pol} with coefficients in
4840: $\var{nf}$ defining a relative extension $L$ of $\var{nf}$, computes
4841: the relative
4842: discriminant of $L$. This is a two-element row vector $[D,d]$, where $D$ is
4843: the relative ideal discriminant and $d$ is the relative discriminant
4844: considered as an element of $\var{nf}^*/{\var{nf}^*}^2$. The main variable of
1.2 ! noro 4845: $\var{nf}$ \var{must} be of lower priority than that of \var{pol}, see
! 4846: \secref{se:priority}.
1.1 noro 4847:
4848: Note: As usual, $\var{nf}$ can be a $\var{bnf}$ as output by \kbd{nfinit}.
4849:
4850: \syn{rnfdiscf}{\var{bnf},\var{pol}}.
4851:
4852: \subsecidx{rnfeltabstorel}$(\var{rnf},x)$: $\var{rnf}$ being a relative
4853: number field
4854: extension $L/K$ as output by \kbd{rnfinit} and $x$ being an element of $L$
4855: expressed as a polynomial modulo the absolute equation $\var{rnf}[11][1]$,
4856: computes $x$ as an element of the relative extension $L/K$ as a polmod with
4857: polmod coefficients.
4858:
4859: \syn{rnfelementabstorel}{\var{rnf},x}.
4860:
4861: \subsecidx{rnfeltdown}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
4862: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an element of
4863: $L$ expressed as a polynomial or polmod with polmod coefficients, computes
4864: $x$ as an element of $K$ as a polmod, assuming $x$ is in $K$ (otherwise an
4865: error will occur). If $x$ is given on the relative integral basis, apply
4866: \kbd{rnfbasistoalg} first, otherwise PARI will believe you are dealing with a
4867: vector.
4868:
4869: \syn{rnfelementdown}{\var{rnf},x}.
4870:
4871: \subsecidx{rnfeltreltoabs}$(\var{rnf},x)$: $\var{rnf}$ being a relative
4872: number field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an
4873: element of $L$ expressed as a polynomial or polmod with polmod
4874: coefficients, computes $x$ as an element of the absolute extension $L/\Q$ as
4875: a polynomial modulo the absolute equation $\var{rnf}[11][1]$. If $x$ is
4876: given on the relative integral basis, apply \kbd{rnfbasistoalg} first,
4877: otherwise PARI will believe you are dealing with a vector.
4878:
4879: \syn{rnfelementreltoabs}{\var{rnf},x}.
4880:
4881: \subsecidx{rnfeltup}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
4882: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an element of
4883: $K$ expressed as a polynomial or polmod, computes $x$ as an element of the
4884: absolute extension $L/\Q$ as a polynomial modulo the absolute equation
4885: $\var{rnf}[11][1]$. Note that it is unnecessary to compute $x$ as an
4886: element of the relative extension $L/K$ (its expression would be identical to
4887: itself). If $x$ is given on the integral basis of $K$, apply
4888: \kbd{nfbasistoalg} first, otherwise PARI will believe you are dealing with a
4889: vector.
4890:
4891: \syn{rnfelementup}{\var{rnf},x}.
4892:
4893: \subsecidx{rnfequation}$(\var{nf},\var{pol},\{\fl=0\})$: given a number field
4894: $\var{nf}$ as output by \kbd{nfinit} (or simply a polynomial) and a
4895: polynomial \var{pol} with coefficients in $\var{nf}$ defining a relative
4896: extension $L$ of $\var{nf}$, computes the absolute equation of $L$ over
4897: $\Q$.
4898:
4899: If $\fl$ is non-zero, outputs a 3-component row vector $[z,a,k]$, where
4900: $z$ is the absolute equation of $L$ over $\Q$, as in the default behaviour,
4901: $a$ expresses as an element of $L$ a root $\alpha$ of the polynomial
4902: defining the base field $\var{nf}$, and $k$ is a small integer such that
4903: $\theta = \beta+k\alpha$ where $\theta$ is a root of $z$ and $\beta$ a root
4904: of $\var{pol}$.
4905:
4906: The main variable of $\var{nf}$ \var{must} be of lower priority than that
1.2 ! noro 4907: of \var{pol} (see \secref{se:priority}). Note that for efficiency, this does
! 4908: not check whether the relative equation is irreducible over $\var{nf}$, but
! 4909: only if it is squarefree. If it is reducible but squarefree, the result will
! 4910: be the absolute equation of the \'etale algebra defined by \var{pol}. If
! 4911: \var{pol} is not squarefree, an error message will be issued.
1.1 noro 4912:
4913: \syn{rnfequation0}{\var{nf},\var{pol},\fl}.
4914:
4915: \subsecidx{rnfhnfbasis}$(\var{bnf},x)$: given a big number field $\var{bnf}$
4916: as output by \kbd{bnfinit}, and either a polynomial $x$ with coefficients in
4917: $\var{bnf}$ defining a relative extension $L$ of $\var{bnf}$, or a
4918: pseudo-basis $x$ of such an extension, gives either a true $\var{bnf}$-basis
4919: of $L$ in upper triangular Hermite normal form, if it exists,
4920: zero otherwise.
4921:
4922: \syn{rnfhermitebasis}{\var{nf},x}.
4923:
4924: \subsecidx{rnfidealabstorel}$(\var{rnf},x)$: $\var{rnf}$ being a relative
4925: number field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an
4926: ideal of the absolute extension $L/\Q$ given in HNF\sidx{Hermite normal form}
4927: (if it is not, apply \kbd{idealhnf} first), computes the relative pseudomatrix
4928: in HNF giving the ideal $x$ considered as an ideal of the relative extension
4929: $L/K$.
4930:
4931: \syn{rnfidealabstorel}{\var{rnf},x}.
4932:
4933: \subsecidx{rnfidealdown}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
4934: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an ideal of
4935: the absolute extension $L/\Q$ given in HNF (if it is not, apply
4936: \kbd{idealhnf} first), gives the ideal of $K$ below $x$, i.e.~the
4937: intersection of $x$ with $K$. Note that, if $x$ is given as a relative ideal
4938: (i.e.~a pseudomatrix in HNF), then it is not necessary to use this function
4939: since the result is simply the first ideal of the ideal list of the
4940: pseudomatrix.
4941:
4942: \syn{rnfidealdown}{\var{rnf},x}.
4943:
4944: \subsecidx{rnfidealhnf}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
4945: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being a relative
4946: ideal (which can be, as in the absolute case, of many different types,
4947: including of course elements), computes as a 2-component row vector the
4948: relative Hermite normal form of $x$, the first component being the HNF matrix
4949: (with entries on the integral basis), and the second component the ideals.
4950:
4951: \syn{rnfidealhermite}{\var{rnf},x}.
4952:
4953: \subsecidx{rnfidealmul}$(\var{rnf},x,y)$: $\var{rnf}$ being a relative number
4954: field extension $L/K$ as output by \kbd{rnfinit} and $x$ and $y$ being ideals
4955: of the relative extension $L/K$ given by pseudo-matrices, outputs the ideal
4956: product, again as a relative ideal.
4957:
4958: \syn{rnfidealmul}{\var{rnf},x,y}.
4959:
4960: \subsecidx{rnfidealnormabs}$(\var{rnf},x)$: $\var{rnf}$ being a relative
4961: number field extension $L/K$ as output by \kbd{rnfinit} and $x$ being a
4962: relative ideal (which can be, as in the absolute case, of many different
4963: types, including of course elements), computes the norm of the ideal $x$
4964: considered as an ideal of the absolute extension $L/\Q$. This is identical to
4965: \kbd{idealnorm(rnfidealnormrel(\var{rnf},x))}, only faster.
4966:
4967: \syn{rnfidealnormabs}{\var{rnf},x}.
4968:
4969: \subsecidx{rnfidealnormrel}$(\var{rnf},x)$: $\var{rnf}$ being a relative
4970: number field
4971: extension $L/K$ as output by \kbd{rnfinit} and $x$ being a relative ideal
4972: (which can be, as in the absolute case, of many different types, including
4973: of course elements), computes the relative norm of $x$ as a ideal of $K$
4974: in HNF.
4975:
4976: \syn{rnfidealnormrel}{\var{rnf},x}.
4977:
4978: \subsecidx{rnfidealreltoabs}$(\var{rnf},x)$: $\var{rnf}$ being a relative
4979: number field
4980: extension $L/K$ as output by \kbd{rnfinit} and $x$ being a relative ideal
4981: (which can be, as in the absolute case, of many different types, including
4982: of course elements), computes the HNF matrix of the ideal $x$ considered
4983: as an ideal of the absolute extension $L/\Q$.
4984:
4985: \syn{rnfidealreltoabs}{\var{rnf},x}.
4986:
4987: \subsecidx{rnfidealtwoelt}$(\var{rnf},x)$: $\var{rnf}$ being a relative
4988: number field
4989: extension $L/K$ as output by \kbd{rnfinit} and $x$ being an ideal of the
4990: relative extension $L/K$ given by a pseudo-matrix, gives a vector of
4991: two generators of $x$ over $\Z_L$ expressed as polmods with polmod
4992: coefficients.
4993:
4994: \syn{rnfidealtwoelement}{\var{rnf},x}.
4995:
4996: \subsecidx{rnfidealup}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
4997: field
4998: extension $L/K$ as output by \kbd{rnfinit} and $x$ being an ideal of
4999: $K$, gives the ideal $x\Z_L$ as an absolute ideal of $L/\Q$ (the relative
5000: ideal representation is trivial: the matrix is the identity matrix, and
5001: the ideal list starts with $x$, all the other ideals being $\Z_K$).
5002:
5003: \syn{rnfidealup}{\var{rnf},x}.
5004:
5005: \subsecidx{rnfinit}$(\var{nf},\var{pol})$: $\var{nf}$ being a number field in
5006: \kbd{nfinit}
5007: format considered as base field, and \var{pol} a polynomial defining a relative
5008: extension over $\var{nf}$, this computes all the necessary data to work in the
5009: relative extension. The main variable of \var{pol} must be of higher priority
1.2 ! noro 5010: (i.e.~lower number, see \secref{se:priority}) than that of $\var{nf}$, and
! 5011: the coefficients of \var{pol} must be in $\var{nf}$.
1.1 noro 5012:
5013: The result is an 11-component row vector as follows (most of the components
5014: are technical), the numbering being very close to that of \kbd{nfinit}. In
5015: the following description, we let $K$ be the base field defined by
5016: $\var{nf}$, $m$ the degree of the base field, $n$ the relative degree, $L$
5017: the large field (of relative degree $n$ or absolute degree $nm$), $r_1$ and
5018: $r_2$ the number of real and complex places of $K$.
5019:
5020: $\var{rnf}[1]$ contains the relative polynomial \var{pol}.
5021:
5022: $\var{rnf}[2]$ is a row vector with $r_1+r_2$ entries, entry $j$ being
5023: a 2-component row vector $[r_{j,1},r_{j,2}]$ where $r_{j,1}$ and $r_{j,2}$
5024: are the number of real and complex places of $L$ above the $j$-th place of
5025: $K$ so that $r_{j,1}=0$ and $r_{j,2}=n$ if $j$ is a complex place, while if
5026: $j$ is a real place we have $r_{j,1}+2r_{j,2}=n$.
5027:
1.2 ! noro 5028: $\var{rnf}[3]$ is a two-component row vector $[\goth{d}(L/K),s]$ where
! 5029: $\goth{d}(L/K)$ is the relative ideal discriminant of $L/K$ and $s$ is the
! 5030: discriminant of $L/K$ viewed as an element of $K^*/(K^*)^2$, in other words it is
! 5031: the output of \kbd{rnfdisc}.
1.1 noro 5032:
1.2 ! noro 5033: $\var{rnf}[4]$ is the ideal index $\goth{f}$, i.e.~such that
! 5034: $d(pol)\Z_K=\goth{f}^2\goth{d}(L/K)$.
1.1 noro 5035:
5036: $\var{rnf}[5]$ is a vector \var{vm} with 7 entries useful for certain
5037: computations in the relative extension $L/K$. $\var{vm}[1]$ is a vector of
5038: $r_1+r_2$ matrices, the $j$-th matrix being an $(r_{1,j}+r_{2,j})\times n$
5039: matrix $M_j$ representing the numerical values of the conjugates of the
5040: $j$-th embedding of the elements of the integral basis, where $r_{i,j}$ is as
5041: in $\var{rnf}[2]$. $\var{vm}[2]$ is a vector of $r_1+r_2$ matrices, the
5042: $j$-th matrix $MC_j$ being essentially the conjugate of the matrix $M_j$
5043: except that the last $r_{2,j}$ columns are also multiplied by 2.
5044: $\var{vm}[3]$ is a vector of $r_1+r_2$ matrices $T2_j$, where $T2_j$ is
5045: an $n\times n$ matrix equal to the real part of the product $MC_j\cdot M_j$
5046: (which is a real positive definite matrix). $\var{vm}[4]$ is the $n\times n$
5047: matrix $T$ whose entries are the relative traces of $\omega_i\omega_j$
5048: expressed as polmods in $\var{nf}$, where the $\omega_i$ are the elements
5049: of the relative integral basis. Note that the $j$-th embedding of $T$ is
5050: equal to $\overline{MC_j}\cdot M_j$, and in particular will be equal to
5051: $T2_j$ if $r_{2,j}=0$. Note also that the relative ideal discriminant of
5052: $L/K$ is equal to $\det(T)$ times the square of the product of the ideals
5053: in the relative pseudo-basis (in $\var{rnf}[7][2]$). The last 3 entries
5054: $\var{vm}[5]$, $\var{vm}[6]$ and $\var{vm}[7]$ are linked to the different
5055: as in \kbd{nfinit}, but have not yet been implemented.
5056:
5057: $\var{rnf}[6]$ is a row vector with $r_1+r_2$ entries, the $j$-th entry
5058: being the
5059: row vector with $r_{1,j}+r_{2,j}$ entries of the roots of the $j$-th embedding
5060: of the relative polynomial \var{pol}.
5061:
5062: $\var{rnf}[7]$ is a two-component row vector, where the first component is
5063: the relative integral pseudo basis expressed as polynomials (in the variable of
5064: $pol$) with polmod coefficients in $\var{nf}$, and the second component is the
5065: ideal list of the pseudobasis in HNF.
5066:
5067: $\var{rnf}[8]$ is the inverse matrix of the integral basis matrix, with
5068: coefficients polmods in $\var{nf}$.
5069:
5070: $\var{rnf}[9]$ may be the multiplication table of the integral basis, but
5071: is not implemented at present.
5072:
5073: $\var{rnf}[10]$ is $\var{nf}$.
5074:
5075: $\var{rnf}[11]$ is a vector \var{vabs} with 5 entries describing the
5076: \var{absolute} extension $L/\Q$. $\var{vabs}[1]$ is an absolute equation.
5077: $\var{vabs}[2]$ expresses the generator $\alpha$ of the number field
5078: $\var{nf}$ as a polynomial modulo the absolute equation $\var{vabs}[1]$.
5079: $\var{vabs}[3]$ is a small integer $k$ such that, if $\beta$ is an abstract
5080: root of \var{pol} and $\alpha$ the generator of $\var{nf}$, the generator
5081: whose root is \var{vabs} will be $\beta + k \alpha$. Note that one must
5082: be very careful if $k\neq0$ when dealing simultaneously with absolute and
5083: relative quantities since the generator chosen for the absolute extension
5084: is not the same as for the relative one. If this happens, one can of course
5085: go on working, but we strongly advise to change the relative polynomial so
5086: that its root will be $\beta + k \alpha$. Typically, the GP instruction would
5087: be
5088:
5089: \kbd{pol = subst(pol, x, x - k*Mod(y,\var{nf}.pol))}
5090:
5091: Finally, $\var{vabs}[4]$ is the absolute integral basis of $L$ expressed in HNF
5092: (hence as would be output by \kbd{nfinit(vabs[1])}), and $\var{vabs}[5]$ the
5093: inverse matrix of the integral basis, allowing to go from polmod to integral
5094: basis representation.
5095:
5096: \syn{rnfinitalg}{\var{nf},\var{pol},\var{prec}}.
5097:
5098: \subsecidx{rnfisfree}$(\var{bnf},x)$: given a big number field $\var{bnf}$ as
5099: output by \kbd{bnfinit}, and either a polynomial $x$ with coefficients in
5100: $\var{bnf}$ defining a relative extension $L$ of $\var{bnf}$, or a
5101: pseudo-basis $x$ of such an extension, returns true (1) if $L/\var{bnf}$ is
5102: free, false (0) if not.
5103:
5104: \syn{rnfisfree}{\var{bnf},x}, and the result is a \kbd{long}.
5105:
1.2 ! noro 5106: \subsecidx{rnfisnorm}$(\var{T},\var{a},\{\fl=0\})$: similar to
! 5107: \kbd{bnfisnorm} but in the relative case. $T$ is as output by
! 5108: \tet{rnfisnorminit} applied to the extension $L/K$. This tries to decide
! 5109: whether the element $a$ in $K$ is the norm of some $x$ in the extension
! 5110: $L/K$.
! 5111:
! 5112: The output is a vector $[x,q]$, where $\var{a}=\var{Norm}(x)*q$. The
! 5113: algorithm looks for a solution $x$ which is an $S$-integer, with $S$ a list
! 5114: of places of $K$ containing at least the ramified primes, the generators of
! 5115: the class group of $L$, as well as those primes dividing \var{a}. If $L/K$ is
! 5116: Galois, then this is enough; otherwise, $\fl$ is used to add more primes to
! 5117: $S$: all the places above the primes $p \leq \fl$ (resp.~$p|\fl$) if $\fl>0$
! 5118: (resp.~$\fl<0$).
! 5119:
! 5120: The answer is guaranteed (i.e.~\var{a} is a norm iff $q = 1$) if the field is
! 5121: Galois, or, under \idx{GRH}, if $S$ contains all primes less than
! 5122: $12\log^2\left|\text{disc}(\var{M})\right|$, where \var{M} is the normal
! 5123: closure of $L/K$.
! 5124:
! 5125: If \tet{rnfisnorminit} has determined (or was told) that $L/K$ is
! 5126: \idx{Galois}, and $\fl \neq 0$, a Warning is issued (so that you can set
! 5127: $\fl = 1$ to check whether $L/K$ is known to be Galois, according to $T$).
! 5128:
! 5129: Example:
1.1 noro 5130:
5131: \bprog
5132: bnf = bnfinit(y^3 + y^2 - 2*y - 1);
5133: p = x^2 + Mod(y^2 + 2*y + 1, bnf.pol);
1.2 ! noro 5134: T = rnfisnorminit(bnf, p);
! 5135: rnfisnorm(T, 17)
1.1 noro 5136: @eprog
5137: \noindent checks whether $17$ is a norm in the Galois extension $\Q(\beta) /
5138: \Q(\alpha)$, where $\alpha^3 + \alpha^2 - 2\alpha - 1 = 0$ and $\beta^2 +
1.2 ! noro 5139: \alpha^2 + 2\alpha + 1 = 0$ (it is).
! 5140:
! 5141: \syn{rnfisnorm}{\var{T},x,\fl}.
! 5142:
! 5143: \subsecidx{rnfisnorminit}$(\var{pol},\var{polrel},\{\fl=2\})$:
! 5144: let $K$ be defined by a root of \var{pol}, and $L/K$ the extension defined by
! 5145: the polynomial \var{polrel}. As usual, \var{pol} can in fact be an \var{nf},
! 5146: or \var{bnf}, etc; if \var{pol} has degree $1$ (the base field is $\Q$),
! 5147: polrel is also allowed to be an \var{nf}, etc. Computes technical data needed
! 5148: by \tet{rnfisnorm} to solve norm equations $Nx = a$, for $x$ in $L$, and $a$
! 5149: in $K$.
1.1 noro 5150:
1.2 ! noro 5151: If $\fl = 0$, do not care whether $L/K$ is Galois or not.
1.1 noro 5152:
1.2 ! noro 5153: If $\fl = 1$, $L/K$ is assumed to be Galois (unchecked), which speeds up
! 5154: \tet{rnfisnorm}.
! 5155:
! 5156: If $\fl = 2$, let the routine determine whether $L/K$ is Galois.
! 5157:
! 5158: \syn{rnfisnorminit}{\var{pol},\var{polrel},\fl}.
! 5159:
! 5160: \subsecidx{rnfkummer}$(\var{bnr},\{\var{subgroup}\},\{deg=0\})$: \var{bnr}
1.1 noro 5161: being as output by \kbd{bnrinit}, finds a relative equation for the
5162: class field corresponding to the module in \var{bnr} and the given
1.2 ! noro 5163: congruence subgroup (the full ray class field if \var{subgroup} is omitted).
! 5164: If \var{deg} is positive, outputs the list of all relative equations of
! 5165: degree \var{deg} contained in the ray class field defined by \var{bnr}, with
! 5166: the same conductor as $(\var{bnr}, \var{subgroup})$.
! 5167:
! 5168: \misctitle{Warning:} this routine only works for subgroups of prime index. It
! 5169: uses Kummer theory, adjoining necessary roots of unity (it needs to compute a
! 5170: tough \kbd{bnfinit} here), and finds a generator via Hecke's characterization
! 5171: of ramification in Kummer extensions of prime degree. If your extension does
! 5172: not have prime degree, for the time being, you have to split it by hand as a
! 5173: tower of such extensions.
! 5174:
! 5175: \syn{rnfkummer}{\var{bnr},\var{subgroup},\var{deg},\var{prec}}, where
! 5176: \var{deg} is a \kbd{long} and an omitted \var{subgroup} is coded as
! 5177: \kbd{NULL}
1.1 noro 5178:
5179: \subsecidx{rnflllgram}$(\var{nf},\var{pol},\var{order})$: given a polynomial
5180: \var{pol} with coefficients in \var{nf} defining a relative extension $L$ and
5181: a suborder \var{order} of $L$ (of maximal rank), as output by
5182: \kbd{rnfpseudobasis}$(\var{nf},\var{pol})$ or similar, gives
5183: $[[\var{neworder}],U]$, where \var{neworder} is a reduced order and $U$ is
5184: the unimodular transformation matrix.
5185:
5186: \syn{rnflllgram}{\var{nf},\var{pol},\var{order},\var{prec}}.
5187:
5188: \subsecidx{rnfnormgroup}$(\var{bnr},\var{pol})$: \var{bnr} being a big ray
5189: class field as output by \kbd{bnrinit} and \var{pol} a relative polynomial
5190: defining an \idx{Abelian extension}, computes the norm group (alias Artin
5191: or Takagi group) corresponding to the Abelian extension of $\var{bnf}=bnr[1]$
5192: defined by \var{pol}, where the module corresponding to \var{bnr} is assumed
1.2 ! noro 5193: to be a multiple of the conductor (i.e.~\var{pol} defines a subextension of
1.1 noro 5194: bnr). The result is the HNF defining the norm group on the given generators
5195: of $\var{bnr}[5][3]$. Note that neither the fact that \var{pol} defines an
5196: Abelian extension nor the fact that the module is a multiple of the conductor
5197: is checked. The result is undefined if the assumption is not correct.
5198:
5199: \syn{rnfnormgroup}{\var{bnr},\var{pol}}.
5200:
5201: \subsecidx{rnfpolred}$(\var{nf},\var{pol})$: relative version of \kbd{polred}.
5202: Given a monic polynomial \var{pol} with coefficients in $\var{nf}$, finds a
5203: list of relative polynomials defining some subfields, hopefully simpler and
5204: containing the original field. In the present version \vers, this is slower
1.2 ! noro 5205: and less efficient than \kbd{rnfpolredabs}.
1.1 noro 5206:
5207: \syn{rnfpolred}{\var{nf},\var{pol},\var{prec}}.
5208:
5209: \subsecidx{rnfpolredabs}$(\var{nf},\var{pol},\{\fl=0\})$: relative version of
5210: \kbd{polredabs}. Given a monic polynomial \var{pol} with coefficients in
1.2 ! noro 5211: $\var{nf}$, finds a simpler relative polynomial defining the same field. The
! 5212: binary digits of $\fl$ mean
! 5213:
! 5214: 1: returns $[P,a]$ where $P$ is the default output and $a$ is an
1.1 noro 5215: element expressed on a root of $P$ whose characteristic polynomial is
1.2 ! noro 5216: \var{pol}
1.1 noro 5217:
1.2 ! noro 5218: 2: returns an absolute polynomial (same as
1.1 noro 5219: {\tt rnfequation(\var{nf},rnfpolredabs(\var{nf},\var{pol}))}
1.2 ! noro 5220: but faster).
1.1 noro 5221:
1.2 ! noro 5222: 16: possibly use a suborder of the maximal order. This is slower than the
! 5223: default when the relative discriminant is smooth, and much faster otherwise.
! 5224: See \secref{se:polredabs}.
1.1 noro 5225:
5226: \misctitle{Remark.} In the present implementation, this is both faster and
5227: much more efficient than \kbd{rnfpolred}, the difference being more
5228: dramatic than in the absolute case. This is because the implementation of
5229: \kbd{rnfpolred} is based on (a partial implementation of) an incomplete
5230: reduction theory of lattices over number fields (i.e.~the function
5231: \kbd{rnflllgram}) which deserves to be improved.
5232:
5233: \syn{rnfpolredabs}{\var{nf},\var{pol},\fl,\var{prec}}.
5234:
5235: \subsecidx{rnfpseudobasis}$(\var{nf},\var{pol})$: given a number field
5236: $\var{nf}$ as output by \kbd{nfinit} and a polynomial \var{pol} with
5237: coefficients in $\var{nf}$ defining a relative extension $L$ of $\var{nf}$,
5238: computes a pseudo-basis $(A,I)$ and the relative discriminant of $L$.
5239: This is output as
5240: a four-element row vector $[A,I,D,d]$, where $D$ is the relative ideal
5241: discriminant and $d$ is the relative discriminant considered as an element of
5242: $\var{nf}^*/{\var{nf}^*}^2$.
5243:
5244: \syn{rnfpseudobasis}{\var{nf},\var{pol}}.
5245:
5246: \subsecidx{rnfsteinitz}$(\var{nf},x)$: given a number field $\var{nf}$ as
5247: output by \kbd{nfinit} and either a polynomial $x$ with coefficients in
5248: $\var{nf}$ defining a relative extension $L$ of $\var{nf}$, or a pseudo-basis
5249: $x$ of such an extension as output for example by \kbd{rnfpseudobasis},
5250: computes another pseudo-basis $(A,I)$ (not in HNF in general) such that all
5251: the ideals of $I$ except perhaps the last one are equal to the ring of
5252: integers of $\var{nf}$, and outputs the four-component row vector $[A,I,D,d]$
5253: as in \kbd{rnfpseudobasis}. The name of this function comes from the fact
5254: that the ideal class of the last ideal of $I$ (which is well defined) is
5255: called the \idx{Steinitz class} of the module $\Z_L$.
5256:
5257: \syn{rnfsteinitz}{\var{nf},x}.
5258:
5259: \subsecidx{subgrouplist}$(\var{bnr},\{\var{bound}\},\{\fl=0\})$:
5260: \var{bnr} being as output by \kbd{bnrinit} or a list of cyclic components
1.2 ! noro 5261: of a finite Abelian group $G$, outputs the list of subgroups of $G$. Subgroups
! 5262: are given as HNF\sidx{Hermite normal form} left divisors of the
! 5263: SNF\sidx{Smith normal form} matrix corresponding to $G$.
! 5264:
! 5265: \misctitle{Warning:} the present implementation cannot treat a group $G$
! 5266: where any cyclic factor has more than $2^{31}$, resp.~$2^{63}$ elements on a
! 5267: $32$-bit, resp.~$64$-bit architecture. \tet{forsubgroup} is a bit more
! 5268: general and can handle $G$ if all $p$-Sylow subgroups of $G$ satisfy the
! 5269: condition above.
! 5270:
! 5271: If $\fl=0$ (default) and \var{bnr} is as output by $\kbd{bnrinit}(,,1)$, gives
! 5272: only the subgroups whose modulus is the conductor. Otherwise, the modulus is
! 5273: not taken into account.
! 5274:
! 5275: If \var{bound} is present, and is a positive integer, restrict the output to
! 5276: subgroups of index less than \var{bound}. If \var{bound} is a vector
! 5277: containing a single positive integer $B$, then only subgroups of index
! 5278: exactly equal to $B$ are computed. For instance
! 5279: \bprog
! 5280: ? subgrouplist([6,2])
! 5281: %1 = [[6, 0; 0, 2], [2, 0; 0, 2], [6, 3; 0, 1], [2, 1; 0, 1], [3, 0; 0, 2],
! 5282: [1, 0; 0, 2], [6, 0; 0, 1], [2, 0; 0, 1], [3, 0; 0, 1], [1, 0; 0, 1]]
! 5283: ? subgrouplist([6,2],3) \\@com index less than 3
! 5284: %2 = [[2, 1; 0, 1], [1, 0; 0, 2], [2, 0; 0, 1], [3, 0; 0, 1], [1, 0; 0, 1]]
! 5285: ? subgrouplist([6,2],[3]) \\@com index 3
! 5286: %3 = [[3, 0; 0, 1]]
! 5287: ? bnr = bnrinit(bnfinit(x), [120,[1]], 1);
! 5288: ? L = subgrouplist(bnr, [8]);
! 5289: @eprog\noindent
! 5290: In the last example, $L$ corresponds to the 24 subfields of
! 5291: $\Q(\zeta_{120})$, of degree $8$ and conductor $120\infty$ (by setting \fl,
! 5292: we see there are a total of $43$ subgroups of degree $8$).
! 5293: \bprog
! 5294: ? vector(#L, i, galoissubcyclo(bnr, L[i]))
! 5295: @eprog\noindent
! 5296: will produce their equations. (For a general base field, you would
! 5297: have to rely on \tet{bnrstark}, or \tet{rnfkummer}.)
1.1 noro 5298:
1.2 ! noro 5299: \syn{subgrouplist0}{\var{bnr},\var{bound},\fl}, where $\fl$
! 5300: is a long integer, and an omitted \var{bound} is coded by \kbd{NULL}.
1.1 noro 5301:
5302: \subsecidx{zetak}$(\var{znf},x,\{\fl=0\})$: \var{znf} being a number
5303: field initialized by \kbd{zetakinit} (\var{not} by \kbd{nfinit}),
5304: computes the value of the \idx{Dedekind} zeta function of the number
5305: field at the complex number $x$. If $\fl=1$ computes Dedekind $\Lambda$
5306: function instead (i.e.~the product of the
5307: Dedekind zeta function by its gamma and exponential factors).
5308:
5309: The accuracy of the result depends in an essential way on the accuracy of
5310: both the \kbd{zetakinit} program and the current accuracy, but even so the
5311: result may be off by up to 5 or 10 decimal digits.
5312:
5313: \syn{glambdak}{\var{znf},x,\var{prec}} or
5314: $\teb{gzetak}(\var{znf},x,\var{prec})$.
5315:
5316: \subsecidx{zetakinit}$(x)$: computes a number of initialization data
5317: concerning the number field defined by the polynomial $x$ so as to be able
5318: to compute the \idx{Dedekind} zeta and lambda functions (respectively
5319: $\kbd{zetak}(x)$ and $\kbd{zetak}(x,1)$). This function calls in particular
5320: the \kbd{bnfinit} program. The result is a 9-component vector $v$ whose
5321: components are very technical and cannot really be used by the user except
5322: through the \kbd{zetak} function. The only component which can be used if
5323: it has not been computed already is $v[1][4]$ which is the result of the
5324: \kbd{bnfinit} call.
5325:
5326: This function is very inefficient and should be rewritten. It needs to
5327: computes millions of coefficients of the corresponding Dirichlet series if
5328: the precision is big. Unless the discriminant is small it will not be able
5329: to handle more than 9 digits of relative precision
5330: (e.g~\kbd{zetakinit(x\pow 8 - 2)} needs 440MB of memory at default
5331: precision).
5332:
5333: \syn{initzeta}{x}.
5334:
5335: \section{Polynomials and power series}
5336:
5337: We group here all functions which are specific to polynomials or power
5338: series. Many other functions which can be applied on these objects are
5339: described in the other sections. Also, some of the functions described here
5340: can be applied to other types.
5341:
5342: \subsecidx{O}$(a$\kbd{\pow}$b)$: $p$-adic (if $a$ is an integer greater or
5343: equal to 2) or power series zero (in all other cases), with precision given
5344: by $b$.
5345:
5346: \syn{ggrandocp}{a,b}, where $b$ is a \kbd{long}.
5347:
5348: \subsecidx{deriv}$(x,\{v\})$: derivative of $x$ with respect to the main
5349: variable if $v$ is omitted, and with respect to $v$ otherwise. $x$ can be any
5350: type except polmod. The derivative of a scalar type is zero, and the
5351: derivative of a vector or matrix is done componentwise. One can use $x'$ as a
5352: shortcut if the derivative is with respect to the main variable of $x$.
5353:
5354: \syn{deriv}{x,v}, where $v$ is a \kbd{long}, and an omitted $v$ is coded as
5355: $-1$. When $x$ is a \typ{POL}, $\tet{derivpol}(x)$ is a shortcut for
5356: $\kbd{deriv}(x, -1)$.
5357:
5358: \subsecidx{eval}$(x)$: replaces in $x$ the formal variables by the values that
5359: have been assigned to them after the creation of $x$. This is mainly useful
5360: in GP, and not in library mode. Do not confuse this with substitution (see
5361: \kbd{subst}). Applying this function to a character string yields the
5362: output from the corresponding GP command, as if directly input from the
5363: keyboard (see \secref{se:strings}).\label{se:eval}
5364:
5365: \syn{geval}{x}. The more basic functions $\teb{poleval}(q,x)$,
5366: $\teb{qfeval}(q,x)$, and $\teb{hqfeval}(q,x)$ evaluate $q$ at $x$, where $q$
5367: is respectively assumed to be a polynomial, a quadratic form (a symmetric
5368: matrix), or an Hermitian form (an Hermitian complex matrix).
5369:
5370: \subsecidx{factorpadic}$(\var{pol},p,r,\{\fl=0\})$: $p$-adic factorization
5371: of the polynomial \var{pol} to precision $r$, the result being a
5372: two-column matrix as in \kbd{factor}. The factors are normalized so that
5373: their leading coefficient is a power of $p$. $r$ must be strictly larger than
5374: the $p$-adic valuation of the discriminant of \var{pol} for the result to
5375: make any sense. The method used is a modified version of the \idx{round 4}
5376: algorithm of \idx{Zassenhaus}.
5377:
5378: If $\fl=1$, use an algorithm due to \idx{Buchmann} and \idx{Lenstra}, which is
5379: usually less efficient.
5380:
5381: \syn{factorpadic4}{\var{pol},p,r}, where $r$ is a \kbd{long} integer.
5382:
5383: \subsecidx{intformal}$(x,\{v\})$: \idx{formal integration} of $x$ with
5384: respect to the main variable if $v$ is omitted, with respect to the variable
5385: $v$ otherwise. Since PARI does not know about ``abstract'' logarithms (they
5386: are immediately evaluated, if only to a power series), logarithmic terms in
5387: the result will yield an error. $x$ can be of any type. When $x$ is a
5388: rational function, it is assumed that the base ring is an integral domain of
5389: characteristic zero.
5390:
5391: \syn{integ}{x,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded
5392: as $-1$.
5393:
5394: \subsecidx{padicappr}$(\var{pol},a)$: vector of $p$-adic roots of the
5395: polynomial
5396: $pol$ congruent to the $p$-adic number $a$ modulo $p$ (or modulo 4 if $p=2$),
5397: and with the same $p$-adic precision as $a$. The number $a$ can be an
5398: ordinary $p$-adic number (type \typ{PADIC}, i.e.~an element of $\Q_p$) or
5399: can be an element of a finite extension of $\Q_p$, in which case it is of
5400: type \typ{POLMOD}, where at least one of the coefficients of the polmod is a
5401: $p$-adic number. In this case, the result is the vector of roots belonging to
5402: the same extension of $\Q_p$ as $a$.
5403:
5404: \syn{apprgen9}{\var{pol},a}, but if $a$ is known to be simply a $p$-adic number
5405: (type \typ{PADIC}), the syntax $\teb{apprgen}(\var{pol},a)$ can be used.
5406:
5407: \subsecidx{polcoeff}$(x,s,\{v\})$: coefficient of degree $s$ of the
5408: polynomial $x$, with respect to the main variable if $v$ is omitted, with
1.2 ! noro 5409: respect to $v$ otherwise. Also applies to power series, scalars (polynomial
! 5410: of degree $0$), and to rational functions provided the denominator is a
! 5411: monomial.
1.1 noro 5412:
5413: \syn{polcoeff0}{x,s,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded
5414: as $-1$. Also available is \teb{truecoeff}$(x,v)$.
5415:
5416: \subsecidx{poldegree}$(x,\{v\})$: degree of the polynomial $x$ in the main
5417: variable if $v$ is omitted, in the variable $v$ otherwise. This is to be
5418: understood as follows. When $x$ is a polynomial or a rational function, it
5419: gives the degree of $x$, the degree of $0$ being $-1$ by convention. When $x$
5420: is a non-zero scalar, it gives 0, and when $x$ is a zero scalar, it gives
5421: $-1$. Return an error otherwise.
5422:
5423: \syn{poldegree}{x,v}, where $v$ and the result are \kbd{long}s (and an
5424: omitted $v$ is coded as $-1$). Also available is \teb{degree}$(x)$, which is
5425: equivalent to \kbd{poldegree($x$,-1)}.
5426:
5427: \subsecidx{polcyclo}$(n,\{v=x\})$: $n$-th cyclotomic polynomial, in variable
5428: $v$ ($x$ by default). The integer $n$ must be positive.
5429:
5430: \syn{cyclo}{n,v}, where $n$ and $v$ are \kbd{long}
5431: integers ($v$ is a variable number, usually obtained through \kbd{varn}).
5432:
5433: \subsecidx{poldisc}$(\var{pol},\{v\})$: discriminant of the polynomial
5434: \var{pol} in the main variable is $v$ is omitted, in $v$ otherwise. The
5435: algorithm used is the \idx{subresultant algorithm}.
5436:
5437: \syn{poldisc0}{x,v}. Also available is \teb{discsr}$(x)$, equivalent
5438: to \kbd{poldisc0(x,-1)}.
5439:
5440: \subsecidx{poldiscreduced}$(f)$: reduced discriminant vector of the
5441: (integral, monic) polynomial $f$. This is the vector of elementary divisors
5442: of $\Z[\alpha]/f'(\alpha)\Z[\alpha]$, where $\alpha$ is a root of the
5443: polynomial $f$. The components of the result are all positive, and their
5444: product is equal to the absolute value of the discriminant of~$f$.
5445:
5446: \syn{reduceddiscsmith}{x}.
5447:
5448: \subsecidx{polhensellift}$(x, y, p, e)$: given a prime $p$, an integral
5449: polynomial $x$ whose leading coefficient is a $p$-unit, a vector $y$ of
5450: integral polynomials that are pairwise relatively prime modulo $p$, and whose
5451: product is congruent to $x$ modulo $p$, lift the elements of $y$ to
5452: polynomials whose product is congruent to $x$ modulo $p^e$.
5453:
5454: \syn{polhensellift}{x,y,p,e} where $e$ must be a \kbd{long}.
5455:
5456: \subsecidx{polinterpolate}$(xa,\{ya\},\{v=x\},\{\&e\})$: given the data vectors
5457: $xa$ and $ya$ of the same length $n$ ($xa$ containing the $x$-coordinates,
5458: and $ya$ the corresponding $y$-coordinates), this function finds the
5459: \idx{interpolating polynomial} passing through these points and evaluates it
5460: at~$v$. If $ya$ is omitted, return the polynomial interpolating the
5461: $(i,xa[i])$. If present, $e$ will contain an error estimate on the returned
5462: value.
5463:
5464: \syn{polint}{xa,ya,v,\&e}, where $e$ will contain an error estimate on the
5465: returned value.
5466:
5467: \subsecidx{polisirreducible}$(\var{pol})$: \var{pol} being a polynomial
5468: (univariate in the present version \vers), returns 1 if \var{pol} is
5469: non-constant and irreducible, 0 otherwise. Irreducibility is checked over
5470: the smallest base field over which \var{pol} seems to be defined.
5471:
5472: \syn{gisirreducible}{\var{pol}}.
5473:
5474: \subsecidx{pollead}$(x,\{v\})$: leading coefficient of the polynomial or
5475: power series $x$. This is computed with respect to the main variable of $x$
5476: if $v$ is omitted, with respect to the variable $v$ otherwise.
5477:
5478: \syn{pollead}{x,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded as
5479: $-1$. Also available is \teb{leadingcoeff}$(x)$.
5480:
5481: \subsecidx{pollegendre}$(n,\{v=x\})$: creates the $n^{\text{th}}$
5482: \idx{Legendre polynomial}, in variable $v$.
5483:
5484: \syn{legendre}{n}, where $x$ is a \kbd{long}.
5485:
5486: \subsecidx{polrecip}$(\var{pol})$: reciprocal polynomial of \var{pol},
5487: i.e.~the coefficients are in reverse order. \var{pol} must be a polynomial.
5488:
5489: \syn{polrecip}{x}.
5490:
5491: \subsecidx{polresultant}$(x,y,\{v\},\{\fl=0\})$: resultant of the two
5492: polynomials $x$ and $y$ with exact entries, with respect to the main
5493: variables of $x$ and $y$ if $v$ is omitted, with respect to the variable $v$
5494: otherwise. The algorithm used is the \idx{subresultant algorithm} by default.
5495:
5496: If $\fl=1$, uses the determinant of Sylvester's matrix instead (here $x$ and
5497: $y$ may have non-exact coefficients).
5498:
5499: If $\fl=2$, uses Ducos's modified subresultant algorithm. It should be much
5500: faster than the default if the coefficient ring is complicated (e.g
5501: multivariate polynomials or huge coefficients), and slightly slower
5502: otherwise.
5503:
5504: \syn{polresultant0}{x,y,v,\fl}, where $v$ is a \kbd{long} and an omitted $v$
5505: is coded as $-1$. Also available are $\teb{subres}(x,y)$ ($\fl=0$) and
5506: $\teb{resultant2}(x,y)$ ($\fl=1$).
5507:
5508: \subsecidx{polroots}$(\var{pol},\{\fl=0\})$: complex roots of the polynomial
5509: \var{pol}, given as a column vector where each root is repeated according to
5510: its multiplicity. The precision is given as for transcendental functions: under
5511: GP it is kept in the variable \kbd{realprecision} and is transparent to the
5512: user, but it must be explicitly given as a second argument in library mode.
5513:
5514: The algorithm used is a modification of A.~Sch\"onhage\sidx{Sch\"onage}'s
1.2 ! noro 5515: root-finding algorithm, due to and implemented by X.~Gourdon. Barring bugs, it
! 5516: is guaranteed to converge and to give the roots to the required accuracy.
1.1 noro 5517:
5518: If $\fl=1$, use a variant of the Newton-Raphson method, which is \var{not}
5519: guaranteed to converge, but is rather fast. If you get the messages ``too
5520: many iterations in roots'' or ``INTERNAL ERROR: incorrect result in roots'',
1.2 ! noro 5521: use the default algorithm. This used to be the default root-finding function in
! 5522: PARI until version 1.39.06.
1.1 noro 5523:
5524: \syn{roots}{\var{pol},\var{prec}} or $\teb{rootsold}(\var{pol},\var{prec})$.
5525:
5526: \subsecidx{polrootsmod}$(\var{pol},p,\{\fl=0\})$: row vector of roots modulo
5527: $p$ of the polynomial \var{pol}. The particular non-prime value $p=4$ is
5528: accepted, mainly for $2$-adic computations. Multiple roots are \var{not}
5529: repeated.
5530:
5531: If $p<100$, you may try setting $\fl=1$, which uses a naive search. In this
5532: case, multiple roots \var{are} repeated with their order of multiplicity.
5533:
5534: \syn{rootmod}{\var{pol},p} ($\fl=0$) or
5535: $\teb{rootmod2}(\var{pol},p)$ ($\fl=1$).
5536:
5537: \subsecidx{polrootspadic}$(\var{pol},p,r)$: row vector of $p$-adic roots of the
5538: polynomial \var{pol} with $p$-adic precision equal to $r$. Multiple roots are
1.2 ! noro 5539: \var{not} repeated. $p$ is assumed to be a prime, and \var{pol} to be
! 5540: non-zero modulo $p$.
1.1 noro 5541:
5542: \syn{rootpadic}{\var{pol},p,r}, where $r$ is a \kbd{long}.
5543:
5544: \subsecidx{polsturm}$(\var{pol},\{a\},\{b\})$: number of real roots of the real
5545: polynomial \var{pol} in the interval $]a,b]$, using Sturm's algorithm. $a$
5546: (resp.~$b$) is taken to be $-\infty$ (resp.~$+\infty$) if omitted.
5547:
5548: \syn{sturmpart}{\var{pol},a,b}. Use \kbd{NULL} to omit an argument.
5549: \teb{sturm}\kbd{(\var{pol})} is equivalent to
5550: \key{sturmpart}\kbd{(\var{pol},NULL,NULL)}. The result is a \kbd{long}.
5551:
1.2 ! noro 5552: \subsecidx{polsubcyclo}$(n,d,\{v=x\})$: gives polynomials (in variable
! 5553: $v$) defining the sub-Abelian extensions of degree $d$ of the cyclotomic
! 5554: field $\Q(\zeta_n)$, where $d\mid \phi(n)$.
! 5555:
! 5556: If there is exactly one such extension the output is a polynomial, else it is
! 5557: a vector of polynomials, eventually empty.
! 5558:
! 5559: To be sure to get a vector, you can use \kbd{concat([],polsubcyclo(n,d))}
! 5560:
! 5561: The function \tet{galoissubcyclo} allows to specify more closely which sub-Abelian extension should be computed.
1.1 noro 5562:
1.2 ! noro 5563: \syn{polsubcyclo}{n,d,v}, where $n$, $d$ and $v$ are \kbd{long} and $v$ is a
! 5564: variable number. When $(\Z/n\Z)^*$ is cyclic, you can use
! 5565: \teb{subcyclo}$(n,d,v)$, where $n$, $d$ and $v$ are \kbd{long} and $v$ is a
! 5566: variable number.
1.1 noro 5567:
5568: \subsecidx{polsylvestermatrix}$(x,y)$: forms the Sylvester matrix
5569: corresponding to the two polynomials $x$ and $y$, where the coefficients of
5570: the polynomials are put in the columns of the matrix (which is the natural
5571: direction for solving equations afterwards). The use of this matrix can be
5572: essential when dealing with polynomials with inexact entries, since
5573: polynomial Euclidean division doesn't make much sense in this case.
5574:
5575: \syn{sylvestermatrix}{x,y}.
5576:
5577: \subsecidx{polsym}$(x,n)$: creates the vector of the \idx{symmetric powers}
5578: of the roots of the polynomial $x$ up to power $n$, using Newton's
5579: formula.
5580:
5581: \syn{polsym}{x}.
5582:
5583: \subsecidx{poltchebi}$(n,\{v=x\})$: creates the $n^{\text{th}}$
5584: \idx{Chebyshev} polynomial, in variable $v$.
5585:
5586: \syn{tchebi}{n,v}, where $n$ and $v$ are \kbd{long}
5587: integers ($v$ is a variable number).
5588:
5589: \subsecidx{polzagier}$(n,m)$: creates Zagier's polynomial $P_{n,m}$ used in
5590: the functions \kbd{sumalt} and \kbd{sumpos} (with $\fl=1$). The exact
5591: definition can be found in a forthcoming paper. One must have $m\le n$.
5592:
5593: \syn{polzagreel}{n,m,\var{prec}} if the result is only wanted as a polynomial
5594: with real coefficients to the precision $\var{prec}$, or $\teb{polzag}(n,m)$
5595: if the result is wanted exactly, where $n$ and $m$ are \kbd{long}s.
5596:
5597: \subsecidx{serconvol}$(x,y)$: convolution (or \idx{Hadamard product}) of the
5598: two power series $x$ and $y$; in other words if $x=\sum a_k*X^k$ and $y=\sum
5599: b_k*X^k$ then $\kbd{serconvol}(x,y)=\sum a_k*b_k*X^k$.
5600:
5601: \syn{convol}{x,y}.
5602:
5603: \subsecidx{serlaplace}$(x)$: $x$ must be a power series with only
5604: non-negative exponents. If $x=\sum (a_k/k!)*X^k$ then the result is $\sum
5605: a_k*X^k$.
5606:
5607: \syn{laplace}{x}.
5608:
5609: \subsecidx{serreverse}$(x)$: reverse power series (i.e.~$x^{-1}$, not $1/x$)
5610: of $x$. $x$ must be a power series whose valuation is exactly equal to one.
5611:
5612: \syn{recip}{x}.
5613:
5614: \subsecidx{subst}$(x,y,z)$:
5615: replace the simple variable $y$ by the argument $z$ in the ``polynomial''
5616: expression $x$. Every type is allowed for $x$, but if it is not a genuine
5617: polynomial (or power series, or rational function), the substitution will be
5618: done as if the scalar components were polynomials of degree one. In
5619: particular, beware that:
5620:
5621: \bprog
5622: ? subst(1, x, [1,2; 3,4])
5623: %1 =
5624: [1 0]
5625:
5626: [0 1]
5627:
5628: ? subst(1, x, Mat([0,1]))
5629: *** forbidden substitution by a non square matrix
5630: @eprog
5631:
5632: If $x$ is a power series, $z$ must be either a polynomial, a power series, or
5633: a rational function. $y$ must be a simple variable name, or a monome of the
5634: form $t^k$ for some simple variable $t$. In the latter case, substitution
5635: may not always be possible since PARI doesn't know about algebraic functions.
5636:
5637: \syn{gsubst}{x,v,z}, where $v$ is the number of the variable $y$ for regular
5638: usage. Also available is \tet{gsubst0}$(x,y,z)$ where $y$ is a \kbd{GEN}
5639: monomial of the form $t^k$.
5640:
5641: \subsecidx{taylor}$(x,y)$: Taylor expansion around $0$ of $x$ with respect
5642: to\label{se:taylor}
5643: the simple variable $y$. $x$ can be of any reasonable type, for example a
5644: rational function. The number of terms of the expansion is transparent to the
5645: user under GP, but must be given as a second argument in library mode.
5646:
5647: \syn{tayl}{x,y,n}, where the \kbd{long} integer $n$ is the desired number of
5648: terms in the expansion.
5649:
5650: \subsecidx{thue}$(\var{tnf},a,\{\var{sol}\})$: solves the equation
5651: $P(x,y)=a$ in integers $x$ and $y$, where \var{tnf} was created with
5652: $\kbd{thueinit}(P)$. \var{sol}, if present, contains the solutions of
5653: $\text{Norm}(x)=a$ modulo units of positive norm in the number field
5654: defined by $P$ (as computed by \kbd{bnfisintnorm}). If \var{tnf} was
5655: computed without assuming \idx{GRH} ($\fl=1$ in \kbd{thueinit}), the
5656: result is unconditional. For instance, here's how to solve the Thue
5657: equation $x^{13} - 5y^{13} = - 4$:
5658:
5659: \bprog
5660: ? tnf = thueinit(x^13 - 5);
5661: ? thue(tnf, -4)
5662: %1 = [[1, 1]]
5663: @eprog
5664: Hence, assuming GRH, the only solution is $x = 1$, $y = 1$.
5665:
5666: \syn{thue}{\var{tnf},a,\var{sol}}, where an omitted \var{sol} is coded
5667: as \kbd{NULL}.
5668:
5669: \subsecidx{thueinit}$(P,\{\fl=0\})$: initializes the \var{tnf}
5670: corresponding to $P$. It is meant to be used in conjunction with \tet{thue}
5671: to solve Thue equations $P(x,y) = a$, where $a$ is an integer. If $\fl$ is
1.2 ! noro 5672: non-zero, certify the result unconditionnally, Otherwise, assume \idx{GRH},
1.1 noro 5673: this being much faster of course.
5674:
5675: \syn{thueinit}{P,\fl,\var{prec}}.
5676:
5677: \section{Vectors, matrices, linear algebra and sets}
5678: \label{se:linear_algebra}
5679:
5680: Note that most linear algebra functions operating on subspaces defined by
5681: generating sets (such as \tet{mathnf}, \tet{qflll}, etc.) take matrices as
5682: arguments. As usual, the generating vectors are taken to be the
5683: \var{columns} of the given matrix.
5684:
5685: \subsecidx{algdep}$(x,k,\{\fl=0\})$:\sidx{algebraic dependence} $x$ being
5686: real, complex, or $p$-adic, finds a polynomial of degree at most $k$ with
5687: integer coefficients having $x$ as approximate root. Note that the polynomial
5688: which is obtained is not necessarily the ``correct'' one (it's not even
5689: guaranteed to be irreducible!). One can check the closeness either by a
5690: polynomial evaluation or substitution, or by computing the roots of the
5691: polynomial given by algdep.
5692:
1.2 ! noro 5693: If $x$ is $p$-adic, $\fl$ is meaningless and the algorithm LLL-reduces the
1.1 noro 5694: ``dual lattice'' corresponding to the powers of $x$.
5695:
5696: Otherwise, if $\fl$ is zero, the algorithm used is a variant of the \idx{LLL}
5697: algorithm due to Hastad, Lagarias and Schnorr (STACS 1986). If the precision
5698: is too low, the routine may enter an infinite loop.
5699:
5700: If $\fl$ is non-zero, use a standard LLL. $\fl$ then indicates a precision,
5701: which should be between $0.5$ and $1.0$ times the number of decimal digits
5702: to which $x$ was computed.
5703:
5704: \syn{algdep0}{x,k,\fl,\var{prec}}, where $k$ and $\fl$ are \kbd{long}s.
5705: Also available is $\teb{algdep}(x,k,\var{prec})$ ($\fl=0$).
5706:
5707: \subsecidx{charpoly}$(A,\{v=x\},\{\fl=0\})$: \idx{characteristic polynomial}
5708: of $A$ with respect to the variable $v$, i.e.~determinant of $v*I-A$ if $A$
5709: is a square matrix, determinant of the map ``multiplication by $A$'' if $A$
5710: is a scalar, in particular a polmod (e.g.~\kbd{charpoly(I,x)=x\pow2+1}).
5711: Note that in the latter case, the \idx{minimal polynomial} can be obtained
5712: as
5713: \bprog
5714: minpoly(A)=
5715: {
5716: local(y);
5717: y = charpoly(A);
5718: y / gcd(y,y')
5719: }
5720: @eprog
5721: \noindent The value of $\fl$ is only significant for matrices.
5722:
5723: If $\fl=0$, the method used is essentially the same as for computing the
5724: adjoint matrix, i.e.~computing the traces of the powers of $A$.
5725:
5726: If $\fl=1$, uses Lagrange interpolation which is almost always slower.
5727:
5728: If $\fl=2$, uses the Hessenberg form. This is faster than the default when
5729: the coefficients are integermod a prime or real numbers, but is usually
5730: slower in other base rings.
5731:
5732: \syn{charpoly0}{A,v,\fl}, where $v$ is the variable number. Also available
5733: are the functions $\teb{caract}(A,v)$ ($\fl=1$), $\teb{carhess}(A,v)$
5734: ($\fl=2$), and $\teb{caradj}(A,v,\var{pt})$ where, in this last case,
5735: \var{pt} is a \kbd{GEN*} which, if not equal to \kbd{NULL}, will receive
5736: the address of the adjoint matrix of $A$ (see \kbd{matadjoint}), so both
5737: can be obtained at once.
5738:
5739: \subsecidx{concat}$(x,\{y\})$: concatenation of $x$ and $y$. If $x$ or $y$ is
5740: not a vector or matrix, it is considered as a one-dimensional vector. All
5741: types are allowed for $x$ and $y$, but the sizes must be compatible. Note
5742: that matrices are concatenated horizontally, i.e.~the number of rows stays
5743: the same. Using transpositions, it is easy to concatenate them vertically.
5744:
5745: To concatenate vectors sideways (i.e.~to obtain a two-row or two-column
5746: matrix), first transform the vector into a one-row or one-column matrix using
5747: the function \tet{Mat}. Concatenating a row vector to a matrix having the
5748: same number of columns will add the row to the matrix (top row if the vector
5749: is $x$, i.e.~comes first, and bottom row otherwise).
5750:
5751: The empty matrix \kbd{[;]} is considered to have a number of rows compatible
5752: with any operation, in particular concatenation. (Note that this is
5753: definitely \var{not} the case for empty vectors \kbd{[~]} or \kbd{[~]\til}.)
5754:
5755: If $y$ is omitted, $x$ has to be a row vector or a list, in which case its
5756: elements are concatenated, from left to right, using the above rules.
5757:
5758: \bprog
5759: ? concat([1,2], [3,4])
5760: %1 = [1, 2, 3, 4]
5761: ? a = [[1,2]~, [3,4]~]; concat(a)
5762: %2 = [1, 2, 3, 4]~
5763: ? a[1] = Mat(a[1]); concat(a)
5764: %3 =
5765: [1 3]
5766:
5767: [2 4]
5768:
5769: ? concat([1,2; 3,4], [5,6]~)
5770: %4 =
5771: [1 2 5]
5772:
5773: [3 4 6]
5774: ? concat([%, [7,8]~, [1,2,3,4]])
5775: %5 =
5776: [1 2 5 7]
5777:
5778: [3 4 6 8]
5779:
5780: [1 2 3 4]
5781: @eprog
5782:
5783: \syn{concat}{x,y}.
5784:
5785: \subsecidx{lindep}$(x,\{\fl=0\})$:\sidx{linear dependence}$x$ being a
5786: vector with real or complex coefficients, finds a small integral linear
5787: combination among these coefficients.
5788:
5789: If $\fl=0$, uses a variant of the \idx{LLL} algorithm due to Hastad, Lagarias
5790: and Schnorr (STACS 1986).
5791:
5792: If $\fl>0$, uses the LLL algorithm. $\fl$ is a parameter which should be
5793: between one half the number of decimal digits of precision and that number
5794: (see \kbd{algdep}).
5795:
1.2 ! noro 5796: If $\fl<0$, $x$ is allowed to be (and in any case interpreted as) a matrix.
! 5797: Returns a non trivial element of the kernel of $x$, or $0$ if $x$ has trivial
! 5798: kernel.
1.1 noro 5799:
5800: \syn{lindep0}{x,\fl,\var{prec}}. Also available is
5801: $\teb{lindep}(x,\var{prec})$ ($\fl=0$).
5802:
5803: \subsecidx{listcreate}$(n)$: creates an empty list of maximal length $n$.
5804:
5805: This function is useless in library mode.
5806:
5807: \subsecidx{listinsert}$(\var{list},x,n)$: inserts the object $x$ at
5808: position $n$ in \var{list} (which must be of type \typ{LIST}). All the
5809: remaining elements of \var{list} (from position $n+1$ onwards) are shifted
5810: to the right. This and \kbd{listput} are the only commands which enable
5811: you to increase a list's effective length (as long as it remains under
5812: the maximal length specified at the time of the \kbd{listcreate}).
5813:
5814: This function is useless in library mode.
5815:
5816: \subsecidx{listkill}$(\var{list})$: kill \var{list}. This deletes all
5817: elements from \var{list} and sets its effective length to $0$. The maximal
5818: length is not affected.
5819:
5820: This function is useless in library mode.
5821:
5822: \subsecidx{listput}$(\var{list},x,\{n\})$: sets the $n$-th element of the list
5823: \var{list} (which must be of type \typ{LIST}) equal to $x$. If $n$ is omitted,
5824: or greater than the list current effective length, just appends $x$. This and
5825: \kbd{listinsert} are the only commands which enable you to increase a list's
5826: effective length (as long as it remains under the maximal length specified at
5827: the time of the \kbd{listcreate}).
5828:
5829: If you want to put an element into an occupied cell, i.e.~if you don't want to
5830: change the effective length, you can consider the list as a vector and use
5831: the usual \kbd{list[n] = x} construct.
5832:
5833: This function is useless in library mode.
5834:
5835: \subsecidx{listsort}$(\var{list},\{\fl=0\})$: sorts \var{list} (which must
5836: be of type \typ{LIST}) in place. If $\fl$ is non-zero, suppresses all repeated
5837: coefficients. This is much faster than the \kbd{vecsort} command since no
5838: copy has to be made.
5839:
5840: This function is useless in library mode.
5841:
5842: \subsecidx{matadjoint}$(x)$: \idx{adjoint matrix} of $x$, i.e.~the matrix $y$
5843: of cofactors of $x$, satisfying $x*y=\det(x)*\text{Id}$. $x$ must be a
5844: (non-necessarily invertible) square matrix.
5845:
5846: \syn{adj}{x}.
5847:
5848: \subsecidx{matcompanion}$(x)$: the left companion matrix to the polynomial $x$.
5849:
5850: \syn{assmat}{x}.
5851:
5852: \subsecidx{matdet}$(x,\{\fl=0\})$: determinant of $x$. $x$ must be a
5853: square matrix.
5854:
5855: If $\fl=0$, uses Gauss-Bareiss.
5856:
5857: If $\fl=1$, uses classical Gaussian elimination, which is better when the
5858: entries of the matrix are reals or integers for example, but usually much
5859: worse for more complicated entries like multivariate polynomials.
5860:
5861: \syn{det}{x} ($\fl=0$) and $\teb{det2}(x)$
5862: ($\fl=1$).
5863:
5864: \subsecidx{matdetint}$(x)$: $x$ being an $m\times n$ matrix with integer
5865: coefficients, this function computes a \var{multiple} of the determinant of the
5866: lattice generated by the columns of $x$ if it is of rank $m$, and returns
5867: zero otherwise. This function can be useful in conjunction with the function
5868: \kbd{mathnfmod} which needs to know such a multiple. To obtain the
5869: exact determinant (assuming the rank is maximal), you can compute
5870: \kbd{matdet(mathnfmod(x, matdetint(x)))}.
5871:
5872: Note that as soon as one of the dimensions gets large ($m$ or $n$ is larger
5873: than 20, say), it will often be much faster to use \kbd{mathnf(x, 1)} or
5874: \kbd{mathnf(x, 4)} directly.
5875:
5876: \syn{detint}{x}.
5877:
5878: \subsecidx{matdiagonal}$(x)$: $x$ being a vector, creates the diagonal matrix
5879: whose diagonal entries are those of $x$.
5880:
5881: \syn{diagonal}{x}.
5882:
5883: \subsecidx{mateigen}$(x)$: gives the eigenvectors of $x$ as columns of a
5884: matrix.
5885:
5886: \syn{eigen}{x}.
5887:
5888: \subsecidx{mathess}$(x)$: Hessenberg form of the square matrix $x$.
5889:
5890: \syn{hess}{x}.
5891:
5892: \subsecidx{mathilbert}$(x)$: $x$ being a \kbd{long}, creates the \idx{Hilbert
5893: matrix} of order $x$, i.e.~the matrix whose coefficient ($i$,$j$) is $1/
5894: (i+j-1)$.
5895:
5896: \syn{mathilbert}{x}.
5897:
5898: \subsecidx{mathnf}$(x,\{\fl=0\})$: if $x$ is a (not necessarily square)
5899: matrix, finds the \var{upper triangular} \idx{Hermite normal form} of $x$. If
5900: the rank of $x$ is equal to its number of rows, the result is a square
5901: matrix. In general, the columns of the result form a basis of the lattice
5902: spanned by the columns of $x$.
5903:
5904: If $\fl=0$, uses the naive algorithm. This should never be used if the
5905: dimension is at all large (larger than 10, say). It is recommanded to use
5906: either \kbd{mathnfmod(x, matdetint(x))} (when $x$ has maximal rank) or
5907: \kbd{mathnf(x, 1)}. Note that the latter is in general faster than
5908: \kbd{mathnfmod}, and also provides a base change matrix.
5909:
5910: If $\fl=1$, uses Batut's algorithm, which is much faster than the default.
5911: Outputs a two-component row vector $[H,U]$, where $H$ is the \var{upper
5912: triangular} Hermite normal form of $x$ defined as above, and $U$ is the
5913: unimodular transformation matrix such that $xU=[0|H]$. $U$ has in general
5914: huge coefficients, in particular when the kernel is large.
5915:
5916: If $\fl=3$, uses Batut's algorithm, but outputs $[H,U,P]$, such that $H$ and
5917: $U$ are as before and $P$ is a permutation of the rows such that $P$ applied
5918: to $xU$ gives $H$. The matrix $U$ is smaller than with $\fl=1$, but may still
5919: be large.
5920:
5921: If $\fl=4$, as in case 1 above, but uses a heuristic variant of \idx{LLL}
5922: reduction along the way. The matrix $U$ is in general close to optimal (in
5923: terms of smallest $L_2$ norm), but the reduction is slower than in case $1$.
5924:
5925: \syn{mathnf0}{x,\fl}. Also available are $\teb{hnf}(x)$ ($\fl=0$) and
5926: $\teb{hnfall}(x)$ ($\fl=1$). To reduce \var{huge} (say $400 \times 400$ and
5927: more) relation matrices (sparse with small entries), you can use the pair
5928: \kbd{hnfspec} / \kbd{hnfadd}. Since this is rather technical and the
5929: calling interface may change, they are not documented yet. Look at the code
5930: in \kbd{basemath/alglin1.c}.
5931:
5932: \subsecidx{mathnfmod}$(x,d)$: if $x$ is a (not necessarily square) matrix of
5933: maximal rank with integer entries, and $d$ is a multiple of the (non-zero)
5934: determinant of the lattice spanned by the columns of $x$, finds the
5935: \var{upper triangular} \idx{Hermite normal form} of $x$.
5936:
5937: If the rank of $x$ is equal to its number of rows, the result is a square
5938: matrix. In general, the columns of the result form a basis of the lattice
5939: spanned by the columns of $x$. This is much faster than \kbd{mathnf} when $d$
5940: is known.
5941:
5942: \syn{hnfmod}{x,d}.
5943:
5944: \subsecidx{mathnfmodid}$(x,d)$: outputs the (upper triangular)
5945: \idx{Hermite normal form} of $x$ concatenated with $d$ times
5946: the identity matrix.
5947:
5948: \syn{hnfmodid}{x,d}.
5949:
5950: \subsecidx{matid}$(n)$: creates the $n\times n$ identity matrix.
5951:
5952: \syn{idmat}{n} where $n$ is a \kbd{long}.
5953:
5954: Related functions are $\teb{gscalmat}(x,n)$, which creates $x$ times the
5955: identity matrix ($x$ being a \kbd{GEN} and $n$ a \kbd{long}), and
5956: $\teb{gscalsmat}(x,n)$ which is the same when $x$ is a \kbd{long}.
5957:
5958: \subsecidx{matimage}$(x,\{\fl=0\})$: gives a basis for the image of the
5959: matrix $x$ as columns of a matrix. A priori the matrix can have entries of
5960: any type. If $\fl=0$, use standard Gauss pivot. If $\fl=1$, use
5961: \kbd{matsupplement}.
5962:
5963: \syn{matimage0}{x,\fl}. Also available is $\teb{image}(x)$ ($\fl=0$).
5964:
5965: \subsecidx{matimagecompl}$(x)$: gives the vector of the column indices which
5966: are not extracted by the function \kbd{matimage}. Hence the number of
5967: components of \kbd{matimagecompl(x)} plus the number of columns of
5968: \kbd{matimage(x)} is equal to the number of columns of the matrix $x$.
5969:
5970: \syn{imagecompl}{x}.
5971:
5972: \subsecidx{matindexrank}$(x)$: $x$ being a matrix of rank $r$, gives two
5973: vectors $y$ and $z$ of length $r$ giving a list of rows and columns
5974: respectively (starting from 1) such that the extracted matrix obtained from
5975: these two vectors using $\tet{vecextract}(x,y,z)$ is invertible.
5976:
5977: \syn{indexrank}{x}.
5978:
5979: \subsecidx{matintersect}$(x,y)$: $x$ and $y$ being two matrices with the same
5980: number of rows each of whose columns are independent, finds a basis of the
5981: $\Q$-vector space equal to the intersection of the spaces spanned by the
5982: columns of $x$ and $y$ respectively. See also the function
5983: \tet{idealintersect}, which does the same for free $\Z$-modules.
5984:
5985: \syn{intersect}{x,y}.
5986:
5987: \subsecidx{matinverseimage}$(x,y)$: gives a column vector belonging to the
5988: inverse image of the column vector $y$ by the matrix $x$ if one exists, the
5989: empty vector otherwise. To get the complete inverse image, it suffices to add
5990: to the result any element of the kernel of $x$ obtained for example by
5991: \kbd{matker}.
5992:
5993: \syn{inverseimage}{x,y}.
5994:
5995: \subsecidx{matisdiagonal}$(x)$: returns true (1) if $x$ is a diagonal matrix,
5996: false (0) if not.
5997:
5998: \syn{isdiagonal}{x}, and this returns a \kbd{long}
5999: integer.
6000:
6001: \subsecidx{matker}$(x,\{\fl=0\})$: gives a basis for the kernel of the
6002: matrix $x$ as columns of a matrix. A priori the matrix can have entries of
6003: any type.
6004:
6005: If $x$ is known to have integral entries, set $\fl=1$.
6006:
1.2 ! noro 6007: \noindent Note: The library function $\tet{FpM_ker}(x, p)$, where $x$ has
1.1 noro 6008: integer entries and $p$ is prime, which is equivalent to but many orders of
6009: magnitude faster than \kbd{matker(x*Mod(1,p))} and needs much less stack
1.2 ! noro 6010: space. To use it under GP, type \kbd{install(FpM\_ker, GG)} first.
1.1 noro 6011:
6012: \syn{matker0}{x,\fl}. Also available are $\teb{ker}(x)$ ($\fl=0$),
6013: $\teb{keri}(x)$ ($\fl=1$) and $\kbd{ker\_mod\_p}(x,p)$.
6014:
6015: \subsecidx{matkerint}$(x,\{\fl=0\})$: gives an \idx{LLL}-reduced $\Z$-basis
6016: for the lattice equal to the kernel of the matrix $x$ as columns of the
6017: matrix $x$ with integer entries (rational entries are not permitted).
6018:
6019: If $\fl=0$, uses a modified integer LLL algorithm.
6020:
6021: If $\fl=1$, uses $\kbd{matrixqz}(x,-2)$. If LLL reduction of the final result
6022: is not desired, you can save time using \kbd{matrixqz(matker(x),-2)} instead.
6023:
6024: \syn{matkerint0}{x,\fl}. Also available is
6025: $\teb{kerint}(x)$ ($\fl=0$).
6026:
6027: \subsecidx{matmuldiagonal}$(x,d)$: product of the matrix $x$ by the diagonal
6028: matrix whose diagonal entries are those of the vector $d$. Equivalent to,
6029: but much faster than $x*\kbd{matdiagonal}(d)$.
6030:
6031: \syn{matmuldiagonal}{x,d}.
6032:
6033: \subsecidx{matmultodiagonal}$(x,y)$: product of the matrices $x$ and $y$
6034: knowing that the result is a diagonal matrix. Much faster than $x*y$ in
6035: that case.
6036:
6037: \syn{matmultodiagonal}{x,y}.
6038:
6039: \subsecidx{matpascal}$(x,\{q\})$: creates as a matrix the lower triangular
6040: \idx{Pascal triangle} of order $x+1$ (i.e.~with binomial coefficients
6041: up to $x$). If $q$ is given, compute the $q$-Pascal triangle (i.e.~using
6042: $q$-binomial coefficients).
6043:
6044: \syn{matqpascal}{x,q}, where $x$ is a \kbd{long} and $q=\kbd{NULL}$ is used
6045: to omit $q$. Also available is $\teb{matpascal}(x)$.
6046:
6047: \subsecidx{matrank}$(x)$: rank of the matrix $x$.
6048:
6049: \syn{rank}{x}, and the result is a \kbd{long}.
6050:
6051: \subsecidx{matrix}$(m,n,\{X\},\{Y\},\{\var{expr}=0\})$: creation of the
6052: $m\times n$ matrix whose coefficients are given by the expression
6053: \var{expr}. There are two formal parameters in \var{expr}, the first one
6054: ($X$) corresponding to the rows, the second ($Y$) to the columns, and $X$
6055: goes from 1 to $m$, $Y$ goes from 1 to $n$. If one of the last 3 parameters
6056: is omitted, fill the matrix with zeroes.
6057:
6058: \synt{matrice}{GEN nlig,GEN ncol,entree *e1,entree *e2,char *expr}.
6059:
6060: \subsecidx{matrixqz}$(x,p)$: $x$ being an $m\times n$ matrix with $m\ge n$
6061: with rational or integer entries, this function has varying behaviour
6062: depending on the sign of $p$:
6063:
6064: If $p\geq 0$, $x$ is assumed to be of maximal rank. This function returns a
6065: matrix having only integral entries, having the same image as $x$, such that
6066: the GCD of all its $n\times n$ subdeterminants is equal to 1 when $p$ is
6067: equal to 0, or not divisible by $p$ otherwise. Here $p$ must be a prime
6068: number (when it is non-zero). However, if the function is used when $p$ has
6069: no small prime factors, it will either work or give the message ``impossible
6070: inverse modulo'' and a non-trivial divisor of $p$.
6071:
6072: If $p=-1$, this function returns a matrix whose columns form a basis of the
6073: lattice equal to $\Z^n$ intersected with the lattice generated by the
6074: columns of $x$.
6075:
6076: If $p=-2$, returns a matrix whose columns form a basis of the lattice equal
6077: to $\Z^n$ intersected with the $\Q$-vector space generated by the
6078: columns of $x$.
6079:
6080: \syn{matrixqz0}{x,p}.
6081:
6082: \subsecidx{matsize}$(x)$: $x$ being a vector or matrix, returns a row vector
6083: with two components, the first being the number of rows (1 for a row vector),
6084: the second the number of columns (1 for a column vector).
6085:
6086: \syn{matsize}{x}.
6087:
6088: \subsecidx{matsnf}$(X,\{\fl=0\})$: if $X$ is a (singular or non-singular)
6089: square matrix outputs the vector of elementary divisors of $X$ (i.e.~the
6090: diagonal of the \idx{Smith normal form} of $X$).
6091:
6092: The binary digits of \fl\ mean:
6093:
6094: 1 (complete output): if set, outputs $[U,V,D]$, where $U$ and $V$ are two
6095: unimodular matrices such that $UXV$ is the diagonal matrix $D$. Otherwise
6096: output only the diagonal of $D$.
6097:
6098: 2 (generic input): if set, allows polynomial entries. Otherwise, assume
6099: that $X$ has integer coefficients.
6100:
6101: 4 (cleanup): if set, cleans up the output. This means that elementary
6102: divisors equal to $1$ will be deleted, i.e.~outputs a shortened vector $D'$
6103: instead of $D$. If complete output was required, returns $[U',V',D']$ so
6104: that $U'XV' = D'$ holds. If this flag is set, $X$ is allowed to be of the
6105: form $D$ or $[U,V,D]$ as would normally be output with the cleanup flag
6106: unset.
6107:
6108: \syn{matsnf0}{X,\fl}. Also available is $\teb{smith}(X)$ ($\fl=0$).
6109:
6110: \subsecidx{matsolve}$(x,y)$: $x$ being an invertible matrix and $y$ a column
6111: vector, finds the solution $u$ of $x*u=y$, using Gaussian elimination. This
6112: has the same effect as, but is a bit faster, than $x^{-1}*y$.
6113:
6114: \syn{gauss}{x,y}.
6115:
6116: \subsecidx{matsolvemod}$(m,d,y,\{\fl=0\})$: $m$ being any integral matrix,
6117: $d$ a vector of positive integer moduli, and $y$ an integral
6118: column vector, gives a small integer solution to the system of congruences
6119: $\sum_i m_{i,j}x_j\equiv y_i\pmod{d_i}$ if one exists, otherwise returns
6120: zero. Shorthand notation: $y$ (resp.~$d$) can be given as a single integer,
6121: in which case all the $y_i$ (resp.~$d_i$) above are taken to be equal to $y$
6122: (resp.~$d$).
6123:
6124: If $\fl=1$, all solutions are returned in the form of a two-component row
6125: vector $[x,u]$, where $x$ is a small integer solution to the system of
6126: congruences and $u$ is a matrix whose columns give a basis of the homogeneous
6127: system (so that all solutions can be obtained by adding $x$ to any linear
6128: combination of columns of $u$). If no solution exists, returns zero.
6129:
6130: \syn{matsolvemod0}{m,d,y,\fl}. Also available
6131: are $\teb{gaussmodulo}(m,d,y)$ ($\fl=0$)
6132: and $\teb{gaussmodulo2}(m,d,y)$ ($\fl=1$).
6133:
6134: \subsecidx{matsupplement}$(x)$: assuming that the columns of the matrix $x$
6135: are linearly independent (if they are not, an error message is issued), finds
6136: a square invertible matrix whose first columns are the columns of $x$,
6137: i.e.~supplement the columns of $x$ to a basis of the whole space.
6138:
6139: \syn{suppl}{x}.
6140:
6141: \subsecidx{mattranspose}$(x)$ or $x\til$: transpose of $x$.
6142: This has an effect only on vectors and matrices.
6143:
6144: \syn{gtrans}{x}.
6145:
6146: \subsecidx{qfgaussred}$(q)$: \idx{decomposition into squares} of the
6147: quadratic form represented by the symmetric matrix $q$. The result is a
6148: matrix whose diagonal entries are the coefficients of the squares, and the
6149: non-diagonal entries represent the bilinear forms. More precisely, if
6150: $(a_{ij})$ denotes the output, one has
6151: $$ q(x) = \sum_i a_{ii} (x_i + \sum_{j>i} a_{ij} x_j)^2 $$
6152:
6153: \syn{sqred}{x}.
6154:
6155: \subsecidx{qfjacobi}$(x)$: $x$ being a real symmetric matrix, this gives a
6156: vector having two components: the first one is the vector of eigenvalues of
6157: $x$, the second is the corresponding orthogonal matrix of eigenvectors of
6158: $x$. The method used is Jacobi's method for symmetric matrices.
6159:
6160: \syn{jacobi}{x}.
6161:
6162: \subsecidx{qflll}$(x,\{\fl=0\})$: \idx{LLL} algorithm applied to the
6163: \var{columns} of the (not necessarily square) matrix $x$. The columns of $x$
6164: must however be linearly independent, unless specified otherwise below. The
6165: result is a transformation matrix $T$ such that $x\cdot T$ is an LLL-reduced
6166: basis of the lattice generated by the column vectors of $x$.
6167:
6168: If $\fl=0$ (default), the computations are done with real numbers (i.e.~not
1.2 ! noro 6169: with rational numbers), using Householder matrices for orthogonalization
! 6170: (as presently programmed: slow but stable).
1.1 noro 6171:
6172: If $\fl=1$, it is assumed that the corresponding Gram matrix is integral.
6173: The computation is done entirely with integers and the algorithm is both
6174: accurate and quite fast. In this case, $x$ needs not be of maximal rank, but
6175: if it is not, $T$ will not be square.
6176:
6177: If $\fl=2$, similar to case 1, except $x$ should be an integer matrix whose
6178: columns are linearly independent. The lattice generated by the columns of
6179: $x$ is first partially reduced before applying the LLL algorithm. [A basis
6180: is said to be \var{partially reduced} if $|v_i \pm v_j| \geq |v_i|$ for any
6181: two distinct basis vectors $v_i, \, v_j$.]
6182:
6183: This can be significantly faster than $\fl=1$ when one row is huge compared
6184: to the other rows.
6185:
6186: If $\fl=4$, $x$ is assumed to have integral entries, but needs not be of
6187: maximal rank. The result is a two-component vector of matrices~: the
6188: columns of the first matrix represent a basis of the integer kernel of $x$
6189: (not necessarily LLL-reduced) and the second matrix is the transformation
6190: matrix $T$ such that $x\cdot T$ is an LLL-reduced $\Z$-basis of the image
6191: of the matrix $x$.
6192:
6193: If $\fl=5$, case as case $4$, but $x$ may have polynomial coefficients.
6194:
6195: If $\fl=8$, same as case $0$, where $x$ may have polynomial coefficients.
6196:
6197: \syn{qflll0}{x,\fl,\var{prec}}. Also available are
6198: $\teb{lll}(x,\var{prec})$ ($\fl=0$), $\teb{lllint}(x)$ ($\fl=1$), and
6199: $\teb{lllkerim}(x)$ ($\fl=4$).
6200:
6201: \subsecidx{qflllgram}$(x,\{\fl=0\})$: same as \kbd{qflll} except that the
6202: matrix $x$ which must now be a square symmetric real matrix is the Gram
6203: matrix of the lattice vectors, and not the coordinates of the vectors
6204: themselves. The result is again the transformation matrix $T$ which gives (as
6205: columns) the coefficients with respect to the initial basis vectors. The
6206: flags have more or less the same meaning, but some are missing. In brief:
6207:
6208: $\fl=0$: numerically unstable in the present version \vers.
6209:
6210: $\fl=1$: $x$ has integer entries, the computations are all done in integers.
6211:
6212: $\fl=4$: $x$ has integer entries, gives the kernel and reduced image.
6213:
6214: $\fl=5$: same as $4$ for generic $x$.
6215:
6216: \syn{qflllgram0}{x,\fl,\var{prec}}. Also available are
6217: $\teb{lllgram}(x,\var{prec})$ ($\fl=0$), $\teb{lllgramint}(x)$ ($\fl=1$), and
6218: $\teb{lllgramkerim}(x)$ ($\fl=4$).
6219:
6220: \subsecidx{qfminim}$(x,b,m,\{\fl=0\})$: $x$ being a square and symmetric
6221: matrix representing a positive definite quadratic form, this function
6222: deals with the minimal vectors of $x$, depending on $\fl$.
6223:
6224: If $\fl=0$ (default), seeks vectors of square norm less than or equal to $b$
6225: (for the norm defined by $x$), and at most $2m$ of these vectors. The result
6226: is a three-component vector, the first component being the number of vectors,
6227: the second being the maximum norm found, and the last vector is a matrix
6228: whose columns are the vectors found, only one being given for each
6229: pair $\pm v$ (at most $m$ such pairs).
6230:
6231: If $\fl=1$, ignores $m$ and returns the first vector whose norm is less than
6232: $b$.
6233:
6234: In both these cases, $x$ {\it is assumed to have integral entries}, and the
6235: function searches for the minimal non-zero vectors whenever $b=0$.
6236:
6237: If $\fl=2$, $x$ can have non integral real entries, but $b=0$ is now
6238: meaningless (uses Fincke-Pohst algorithm).
6239:
6240: \syn{qfminim0}{x,b,m,\fl,\var{prec}}, also available are \funs{minim}{x,b,m}
6241: ($\fl=0$), \funs{minim2}{x,b,m} ($\fl=1$), and finally
6242: \funs{fincke_pohst}{x,b,m,\var{prec}} ($\fl=2$).
6243:
6244: \subsecidx{qfperfection}$(x)$: $x$ being a square and symmetric matrix with
6245: integer entries representing a positive definite quadratic form, outputs the
6246: perfection rank of the form. That is, gives the rank of the family of the $s$
6247: symmetric matrices $v_iv_i^t$, where $s$ is half the number of minimal
6248: vectors and the $v_i$ ($1\le i\le s$) are the minimal vectors.
6249:
6250: As a side note to old-timers, this used to fail bluntly when $x$ had more
6251: than $5000$ minimal vectors. Beware that the computations can now be very
6252: lengthy when $x$ has many minimal vectors.
6253:
6254: \syn{perf}{x}.
6255:
6256: \subsecidx{qfsign}$(x)$: signature of the quadratic form represented by the
6257: symmetric matrix $x$. The result is a two-component vector.
6258:
6259: \syn{signat}{x}.
6260:
6261: \subsecidx{setintersect}$(x,y)$: intersection of the two sets $x$ and $y$.
6262:
6263: \syn{setintersect}{x,y}.
6264:
6265: \subsecidx{setisset}$(x)$: returns true (1) if $x$ is a set, false (0) if
6266: not. In PARI, a set is simply a row vector whose entries are strictly
6267: increasing. To convert any vector (and other objects) into a set, use the
6268: function \kbd{Set}.
6269:
6270: \syn{setisset}{x}, and this returns a \kbd{long}.
6271:
6272: \subsecidx{setminus}$(x,y)$: difference of the two sets $x$ and $y$,
6273: i.e.~set of elements of $x$ which do not belong to $y$.
6274:
6275: \syn{setminus}{x,y}.
6276:
6277: \subsecidx{setsearch}$(x,y,\{\fl=0\})$: searches if $y$ belongs to the set
6278: $x$. If it does and $\fl$ is zero or omitted, returns the index $j$ such that
6279: $x[j]=y$, otherwise returns 0. If $\fl$ is non-zero returns the index $j$
6280: where $y$ should be inserted, and $0$ if it already belongs to $x$ (this is
6281: meant to be used in conjunction with \kbd{listinsert}).
6282:
6283: This function works also if $x$ is a \var{sorted} list (see \kbd{listsort}).
6284:
6285: \syn{setsearch}{x,y,\fl} which returns a \kbd{long}
6286: integer.
6287:
6288: \subsecidx{setunion}$(x,y)$: union of the two sets $x$ and $y$.
6289:
6290: \syn{setunion}{x,y}.
6291:
6292: \subsecidx{trace}$(x)$: this applies to quite general $x$. If $x$ is not a
6293: matrix, it is equal to the sum of $x$ and its conjugate, except for polmods
6294: where it is the trace as an algebraic number.
6295:
6296: For $x$ a square matrix, it is the ordinary trace. If $x$ is a
6297: non-square matrix (but not a vector), an error occurs.
6298:
6299: \syn{gtrace}{x}.
6300:
6301: \subsecidx{vecextract}$(x,y,\{z\})$: extraction of components of the
6302: vector or matrix $x$ according to $y$. In case $x$ is a matrix, its
6303: components are as usual the \var{columns} of $x$. The parameter $y$ is a
6304: component specifier, which is either an integer, a string describing a
6305: range, or a vector.
6306:
6307: If $y$ is an integer, it is considered as a mask: the binary bits of $y$ are
6308: read from right to left, but correspond to taking the components from left to
6309: right. For example, if $y=13=(1101)_2$ then the components 1,3 and 4 are
6310: extracted.
6311:
6312: If $y$ is a vector, which must have integer entries, these entries correspond
6313: to the component numbers to be extracted, in the order specified.
6314:
6315: If $y$ is a string, it can be
6316:
6317: $\bullet$ a single (non-zero) index giving a component number (a negative
6318: index means we start counting from the end).
6319:
6320: $\bullet$ a range of the form \kbd{"$a$..$b$"}, where $a$ and $b$ are
6321: indexes as above. Any of $a$ and $b$ can be omitted; in this case, we take
6322: as default values $a = 1$ and $b = -1$, i.e.~ the first and last components
6323: respectively. We then extract all components in the interval $[a,b]$, in
6324: reverse order if $b < a$.
6325:
6326: In addition, if the first character in the string is \kbd{\pow}, the
6327: complement of the given set of indices is taken.
6328:
6329: If $z$ is not omitted, $x$ must be a matrix. $y$ is then the \var{line}
6330: specifier, and $z$ the \var{column} specifier, where the component specifier
6331: is as explained above.
6332:
6333: \bprog
6334: ? v = [a, b, c, d, e];
6335: ? vecextract(v, 5) \\@com mask
6336: %1 = [a, c]
6337: ? vecextract(v, [4, 2, 1]) \\@com component list
6338: %2 = [d, b, a]
6339: ? vecextract(v, "2..4") \\@com interval
6340: %3 = [b, c, d]
6341: ? vecextract(v, "-1..-3") \\@com interval + reverse order
6342: %4 = [e, d, c]
6343: ? vecextract([1,2,3], "^2") \\@com complement
6344: %5 = [1, 3]
6345: ? vecextract(matid(3), "2..", "..")
6346: %6 =
6347: [0 1 0]
6348:
6349: [0 0 1]
6350: @eprog
6351:
6352: \syn{extract}{x,y} or $\teb{matextract}(x,y,z)$.
6353:
6354: \subsecidx{vecsort}$(x,\{k\},\{\fl=0\})$: sorts the vector $x$ in ascending
6355: order, using the heapsort method. $x$ must be a vector, and its components
6356: integers, reals, or fractions.
6357:
6358: If $k$ is present and is an integer, sorts according to the value of the
6359: $k$-th subcomponents of the components of~$x$. $k$ can also be a vector,
6360: in which case the
6361: sorting is done lexicographically according to the components listed in the
6362: vector $k$. For example, if $k=[2,1,3]$, sorting will be done with respect
6363: to the second component, and when these are equal, with respect to the
6364: first, and when these are equal, with respect to the third.
6365:
6366: \noindent The binary digits of \fl\ mean:
6367:
6368: $\bullet$ 1: indirect sorting of the vector $x$, i.e.~if $x$ is an
6369: $n$-component vector, returns a permutation of $[1,2,\dots,n]$ which
6370: applied to the components of $x$ sorts $x$ in increasing order.
6371: For example, \kbd{vecextract(x, vecsort(x,,1))} is equivalent to
6372: \kbd{vecsort(x)}.
6373:
6374: $\bullet$ 2: sorts $x$ by ascending lexicographic order (as per the
6375: \kbd{lex} comparison function).
6376:
1.2 ! noro 6377: $\bullet$ 4: use descending instead of ascending order.
1.1 noro 6378:
6379: \syn{vecsort0}{x,k,flag}. To omit $k$, use \kbd{NULL} instead. You can also
6380: use the simpler functions
6381:
6382: $\teb{sort}(x)$ (= $\kbd{vecsort0}(x,\text{NULL},0)$).
6383:
6384: $\teb{indexsort}(x)$ (= $\kbd{vecsort0}(x,\text{NULL},1)$).
6385:
6386: $\teb{lexsort}(x)$ (= $\kbd{vecsort0}(x,\text{NULL},2)$).
6387:
6388: Also available are \teb{sindexsort} and \teb{sindexlexsort} which return a
6389: vector of C-long integers (private type \typ{VECSMALL}) $v$, where
6390: $v[1]\dots v[n]$ contain the indices. Note that the resulting $v$ is
6391: \var{not} a generic PARI object, but is in general easier to use in C
6392: programs!
6393:
6394: \subsecidx{vector}$(n,\{X\},\{\var{expr}=0\})$: creates a row vector (type
6395: \typ{VEC}) with $n$ components whose components are the expression
6396: \var{expr} evaluated at the integer points between 1 and $n$. If one of the
6397: last two arguments is omitted, fill the vector with zeroes.
6398:
6399: \synt{vecteur}{GEN nmax, entree *ep, char *expr}.
6400:
1.2 ! noro 6401: \subsecidx{vectorsmall}$(n,\{X\},\{\var{expr}=0\})$: creates a row vector of small integers (type
! 6402: \typ{VECSMALL}) with $n$ components whose components are the expression
! 6403: \var{expr} evaluated at the integer points between 1 and $n$. If one of the
! 6404: last two arguments is omitted, fill the vector with zeroes.
! 6405:
! 6406: \synt{vecteursmall}{GEN nmax, entree *ep, char *expr}.
! 6407:
1.1 noro 6408: \subsecidx{vectorv}$(n,X,\var{expr})$: as \tet{vector}, but returns a
6409: column vector (type \typ{COL}).
6410:
6411: \synt{vvecteur}{GEN nmax, entree *ep, char *expr}.
6412:
6413: \section{Sums, products, integrals and similar functions}
6414: \label{se:sums}
6415:
6416: Although the GP calculator is programmable, it is useful to have
6417: preprogrammed a number of loops, including sums, products, and a certain
6418: number of recursions. Also, a number of functions from numerical analysis
6419: like numerical integration and summation of series will be described here.
6420:
6421: One of the parameters in these loops must be the control variable, hence a
6422: simple variable name. The last parameter can be any legal PARI expression,
6423: including of course expressions using loops. Since it is much easier to
6424: program directly the loops in library mode, these functions are mainly
6425: useful for GP programming. The use of these functions in library mode is a
6426: little tricky and its explanation will be mostly omitted, although the
6427: reader can try and figure it out by himself by checking the example given
6428: for the \tet{sum} function. In this section we only give the library
6429: syntax, with no semantic explanation.
6430:
6431: The letter $X$ will always denote any simple variable name, and represents
6432: the formal parameter used in the function.
6433:
6434: \misctitle{(numerical) integration}:\sidx{numerical integration} A number
6435: of Romberg-like integration methods are implemented (see \kbd{intnum} as
6436: opposed to \kbd{intformal} which we already described). The user should not
6437: require too much accuracy: 18 or 28 decimal digits is OK, but not much more.
6438: In addition, analytical cleanup of the integral must have been done: there
6439: must be no singularities in the interval or at the boundaries. In practice
6440: this can be accomplished with a simple change of variable. Furthermore, for
6441: improper integrals, where one or both of the limits of integration are plus
6442: or minus infinity, the function must decrease sufficiently rapidly at
6443: infinity. This can often be accomplished through integration by parts.
6444: Finally, the function to be integrated should not be very small
6445: (compared to the current precision) on the entire interval. This can
6446: of course be accomplished by just multiplying by an appropriate
6447: constant.
6448:
6449: Note that \idx{infinity} can be represented with essentially no loss of
6450: accuracy by 1e4000. However beware of real underflow when dealing with
6451: rapidly decreasing functions. For example, if one wants to compute the
6452: $\int_0^\infty e^{-x^2}\,dx$ to 28 decimal digits, then one should set
6453: infinity equal to 10 for example, and certainly not to 1e4000.
6454:
6455: The integrand may have values belonging to a vector space over the real
6456: numbers; in particular, it can be complex-valued or vector-valued.
6457:
6458: See also the discrete summation methods below (sharing the prefix \kbd{sum}).
6459:
6460: \subsecidx{intnum}$(X=a,b,\var{expr},\{\fl=0\})$: numerical integration of
6461: \var{expr} (smooth in $]a,b[$), with respect to $X$.
6462:
6463: Set $\fl=0$ (or omit it altogether) when $a$ and $b$ are not too large, the
6464: function is smooth, and can be evaluated exactly everywhere on the interval
6465: $[a,b]$.
6466:
6467: If $\fl=1$, uses a general driver routine for doing numerical integration,
6468: making no particular assumption (slow).
6469:
6470: $\fl=2$ is tailored for being used when $a$ or $b$ are infinite. One
6471: \var{must} have $ab>0$, and in fact if for example $b=+\infty$, then it is
6472: preferable to have $a$ as large as possible, at least $a\ge1$.
6473:
6474: If $\fl=3$, the function is allowed to be undefined (but continuous) at $a$
6475: or $b$, for example the function $\sin(x)/x$ at $x=0$.
6476:
6477: \synt{intnum0}{entree$\,$*e,GEN a,GEN b,char$\,$*expr,long \fl,long prec}.
6478:
6479: \subsecidx{prod}$(X=a,b,\var{expr},\{x=1\})$: product of expression \var{expr},
6480: initialized at $x$, the formal parameter $X$ going from $a$ to $b$. As for
6481: \kbd{sum}, the main purpose of the initialization parameter $x$ is to force
6482: the type of the operations being performed. For example if it is set equal to
6483: the integer 1, operations will start being done exactly. If it is set equal
6484: to the real $1.$, they will be done using real numbers having the default
6485: precision. If it is set equal to the power series $1+O(X^k)$ for a certain
6486: $k$, they will be done using power series of precision at most $k$. These
6487: are the three most common initializations.
6488:
6489: \noindent As an extreme example, compare
6490:
6491: \bprog
6492: ? prod(i=1, 100, 1 - X^i); \\@com this has degree $5050$ !!
6493: time = 3,335 ms.
6494: ? prod(i=1, 100, 1 - X^i, 1 + O(X^101))
6495: time = 43 ms.
6496: %2 = 1 - X - X^2 + X^5 + X^7 - X^12 - X^15 + X^22 + X^26 - X^35 - X^40 + \
6497: X^51 + X^57 - X^70 - X^77 + X^92 + X^100 + O(X^101)
6498: @eprog
6499:
6500: \synt{produit}{entree *ep, GEN a, GEN b, char *expr, GEN x}.
6501:
6502: \subsecidx{prodeuler}$(X=a,b,\var{expr})$: product of expression \var{expr},
6503: initialized at 1. (i.e.~to a \var{real} number equal to 1 to the current
6504: \kbd{realprecision}), the formal parameter $X$ ranging over the prime numbers
6505: between $a$ and $b$.\sidx{Euler product}
6506:
6507: \synt{prodeuler}{entree *ep, GEN a, GEN b, char *expr, long prec}.
6508:
6509: \subsecidx{prodinf}$(X=a,\var{expr},\{\fl=0\})$: \idx{infinite product} of
6510: expression \var{expr}, the formal parameter $X$ starting at $a$. The evaluation
6511: stops when the relative error of the expression minus 1 is less than the
6512: default precision. The expressions must always evaluate to an element of
6513: $\C$.
6514:
6515: If $\fl=1$, do the product of the ($1+\var{expr}$) instead.
6516:
6517: \synt{prodinf}{entree *ep, GEN a, char *expr, long prec} ($\fl=0$), or
6518: \teb{prodinf1} with the same arguments ($\fl=1$).
6519:
6520: \subsecidx{solve}$(X=a,b,\var{expr})$: find a real root of expression
6521: \var{expr} between $a$ and $b$, under the condition
6522: $\var{expr}(X=a) * \var{expr}(X=b) \le 0$.
6523: This routine uses Brent's method and can fail miserably if \var{expr} is
6524: not defined in the whole of $[a,b]$ (try \kbd{solve(x=1, 2, tan(x)}).
6525:
6526: \synt{zbrent}{entree *ep, GEN a, GEN b, char *expr, long prec}.
6527:
6528: \subsecidx{sum}$(X=a,b,\var{expr},\{x=0\})$: sum of expression \var{expr},
6529: initialized at $x$, the formal parameter going from $a$ to $b$. As for
6530: \kbd{prod}, the initialization parameter $x$ may be given to force the type
6531: of the operations being performed.
6532:
6533: \noindent As an extreme example, compare
6534:
6535: \bprog
6536: ? sum(i=1, 5000, 1/i); \\@com rational number: denominator has $2166$ digits.
6537: time = 1,241 ms.
6538: ? sum(i=1, 5000, 1/i, 0.)
6539: time = 158 ms.
6540: %2 = 9.094508852984436967261245533
6541: @eprog
6542:
6543: \synt{somme}{entree *ep, GEN a, GEN b, char *expr, GEN x}. This is to be
6544: used as follows: \kbd{ep} represents the dummy variable used in the
6545: expression \kbd{expr}
6546: \bprog
6547: /* compute a^2 + @dots + b^2 */
6548: {
6549: /* define the dummy variable "i" */
6550: entree *ep = is_entry("i");
6551: /* sum for a <= i <= b */
6552: return somme(ep, a, b, "i^2", gzero);
6553: }
6554: @eprog
6555:
6556: \subsecidx{sumalt}$(X=a,\var{expr},\{\fl=0\})$: numerical summation of the
6557: series \var{expr}, which should be an \idx{alternating series}, the formal
6558: variable $X$ starting at $a$.
6559:
6560: If $\fl=0$, use an algorithm of F.~Villegas as modified by D.~Zagier. This
6561: is much better than \idx{Euler}-Van Wijngaarden's method which was used
6562: formerly.
6563: Beware that the stopping criterion is that the term gets small enough, hence
6564: terms which are equal to 0 will create problems and should be removed.
6565:
6566: If $\fl=1$, use a variant with slightly different polynomials. Sometimes
6567: faster.
6568:
6569: Divergent alternating series can sometimes be summed by this method, as well
6570: as series which are not exactly alternating (see for example
6571: \secref{se:user_defined}).
6572:
6573: \misctitle{Important hint:} a significant speed gain can be obtained by
6574: writing the $(-1)^X$ which may occur in the expression as
6575: \kbd{(1.~- X\%2*2)}.
6576:
6577: \synt{sumalt}{entree *ep, GEN a, char *expr, long \fl, long prec}.
6578:
6579: \subsecidx{sumdiv}$(n,X,\var{expr})$: sum of expression \var{expr} over
6580: the positive divisors of $n$.
6581:
6582: Arithmetic functions like \tet{sigma} use the multiplicativity of the
6583: underlying expression to speed up the computation. In the present version
6584: \vers, there is no way to indicate that \var{expr} is multiplicative in
1.2 ! noro 6585: $n$, hence specialized functions should be preferred whenever possible.
1.1 noro 6586:
6587: \synt{divsum}{entree *ep, GEN num, char *expr}.
6588:
6589: \subsecidx{suminf}$(X=a,\var{expr})$: \idx{infinite sum} of expression
6590: \var{expr}, the formal parameter $X$ starting at $a$. The evaluation stops
6591: when the relative error of the expression is less than the default precision.
6592: The expressions must always evaluate to a complex number.
6593:
6594: \synt{suminf}{entree *ep, GEN a, char *expr, long prec}.
6595:
6596: \subsecidx{sumpos}$(X=a,\var{expr},\{\fl=0\})$: numerical summation of the
6597: series \var{expr}, which must be a series of terms having the same sign,
6598: the formal
6599: variable $X$ starting at $a$. The algorithm used is Van Wijngaarden's trick
6600: for converting such a series into an alternating one, and is quite slow.
6601: Beware that the stopping criterion is that the term gets small enough, hence
6602: terms which are equal to 0 will create problems and should be removed.
6603:
6604: If $\fl=1$, use slightly different polynomials. Sometimes faster.
6605:
6606: \synt{sumpos}{entree *ep, GEN a, char *expr, long \fl, long prec}.
6607:
6608: \section{Plotting functions}
6609:
6610: Although plotting is not even a side purpose of PARI, a number of plotting
6611: functions are provided. Moreover, a lot of people felt like suggesting
6612: ideas or submitting huge patches for this section of the code. Among these,
6613: special thanks go to Klaus-Peter Nischke who suggested the recursive plotting
6614: and the forking/resizing stuff under X11, and Ilya Zakharevich who
6615: undertook a complete rewrite of the graphic code, so that most of it is now
6616: platform-independent and should be relatively easy to port or expand.
6617:
6618: These graphic functions are either
6619:
6620: $\bullet$ high-level plotting functions (all the functions starting with
6621: \kbd{ploth}) in which the user has little to do but explain what type of plot
6622: he wants, and whose syntax is similar to the one used in the preceding
6623: section (with somewhat more complicated flags).
6624:
6625: $\bullet$ low-level plotting functions, where every drawing primitive (point,
6626: line, box, etc.) must be specified by the user. These low-level functions
6627: (called \var{rectplot} functions, sharing the prefix \kbd{plot}) work as
6628: follows. You have at your disposal 16 virtual windows which are filled
6629: independently, and can then be physically ORed on a single window at
6630: user-defined positions. These windows are numbered from 0 to 15, and must be
6631: initialized before being used by the function \kbd{plotinit}, which specifies
6632: the height and width of the virtual window (called a \var{rectwindow} in the
6633: sequel). At all times, a virtual cursor (initialized at $[0,0]$) is
6634: associated to the window, and its current value can be obtained using the
6635: function \kbd{plotcursor}.
6636:
6637: A number of primitive graphic objects (called \var{rect} objects) can then
6638: be drawn in these windows, using a default color associated to that window
6639: (which can be changed under X11, using the \kbd{plotcolor} function, black
6640: otherwise) and only the part of the object which is inside the window will be
6641: drawn, with the exception of polygons and strings which are drawn entirely
6642: (but the virtual cursor can move outside of the window). The ones sharing the
6643: prefix \kbd{plotr} draw relatively to the current position of the virtual
6644: cursor, the others use absolute coordinates. Those having the prefix
6645: \kbd{plotrecth} put in the rectwindow a large batch of rect objects
6646: corresponding to the output of the related \kbd{ploth} function.
6647:
6648: Finally, the actual physical drawing is done using the function
6649: \kbd{plotdraw}. Note that the windows are preserved so that further drawings
6650: using the same windows at different positions or different windows can be
6651: done without extra work. If you want to erase a window (and free the
6652: corresponding memory), use the function \kbd{plotkill}. It is not possible to
6653: partially erase a window. Erase it completely, initialize it again and then
6654: fill it with the graphic objects that you want to keep.
6655:
6656: In addition to initializing the window, you may want to have a scaled
6657: window to avoid unnecessary conversions. For this, use the function
6658: \kbd{plotscale} below. As long as this function is not called, the scaling is
6659: simply the number of pixels, the origin being at the upper left and the
6660: $y$-coordinates going downwards.
6661:
6662: Note that in the present version \vers\ all these plotting functions
6663: (both low and high level) have been written for the X11-window system
6664: (hence also for GUI's based on X11 such as Openwindows and Motif) only,
6665: though very little code remains which is actually platform-dependent. A
6666: Suntools/Sunview, Macintosh, and an Atari/Gem port were provided for
6667: previous versions. These \var{may} be adapted in future releases.
6668:
6669: Under X11/Suntools, the physical window (opened by \kbd{plotdraw} or any
6670: of the \kbd{ploth*} functions) is completely separated from GP (technically,
6671: a \kbd{fork} is done, and the non-graphical memory is immediately freed in
6672: the child process), which means you can go on working in the current GP
6673: session, without having to kill the window first. Under X11, this window can
6674: be closed, enlarged or reduced using the standard window manager functions.
6675: No zooming procedure is implemented though (yet).
6676:
6677: $\bullet$ Finally, note that in the same way that \kbd{printtex} allows you
6678: to have a \TeX\ output corresponding to printed results, the functions
6679: starting with \kbd{ps} allow you to have \tet{PostScript} output of the
6680: plots. This will not be absolutely identical with the screen output, but will
6681: be sufficiently close. Note that you can use PostScript output even if you do
6682: not have the plotting routines enabled. The PostScript output is written in a
6683: file whose name is derived from the \tet{psfile} default (\kbd{./pari.ps} if
6684: you did not tamper with it). Each time a new PostScript output is asked for,
6685: the PostScript output is appended to that file. Hence the user must remove
6686: this file, or change the value of \kbd{psfile}, first if he does not want
6687: unnecessary drawings from preceding sessions to appear. On the other hand, in
6688: this manner as many plots as desired can be kept in a single file. \smallskip
6689:
6690: {\it None of the graphic functions are available within the PARI library, you
6691: must be under GP to use them}. The reason for that is that you really should
6692: not use PARI for heavy-duty graphical work, there are much better specialized
6693: alternatives around. This whole set of routines was only meant as a
6694: convenient, but simple-minded, visual aid. If you really insist on using
6695: these in your program (we warned you), the source (\kbd{plot*.c}) should be
6696: readable enough for you to achieve something.
6697:
6698: \subsecidx{plot}$(X=a,b,\var{expr},\{\var{Ymin}\},\{\var{Ymax}\})$: crude
6699: (ASCII) plot of the function represented by expression \var{expr} from
6700: $a$ to $b$, with \var{Y} ranging from \var{Ymin} to \var{Ymax}. If
6701: \var{Ymin} (resp. \var{Ymax}) is not given, the minima (resp. the
6702: maxima) of the computed values of the expression is used instead.
6703:
6704: \subsecidx{plotbox}$(w,x2,y2)$: let $(x1,y1)$ be the current position of the
6705: virtual cursor. Draw in the rectwindow $w$ the outline of the rectangle which
6706: is such that the points $(x1,y1)$ and $(x2,y2)$ are opposite corners. Only
6707: the part of the rectangle which is in $w$ is drawn. The virtual cursor does
6708: \var{not} move.
6709:
6710: \subsecidx{plotclip}$(w)$: `clips' the content of rectwindow $w$, i.e
6711: remove all parts of the drawing that would not be visible on the screen.
6712: Together with \tet{plotcopy} this function enables you to draw on a
6713: scratchpad before commiting the part you're interested in to the final
6714: picture.
6715:
6716: \subsecidx{plotcolor}$(w,c)$: set default color to $c$ in rectwindow $w$.
6717: In present version \vers, this is only implemented for X11 window system,
6718: and you only have the following palette to choose from:
6719:
6720: 1=black, 2=blue, 3=sienna, 4=red, 5=cornsilk, 6=grey, 7=gainsborough.
6721:
6722: Note that it should be fairly easy for you to hardwire some more colors by
6723: tweaking the files \kbd{rect.h} and \kbd{plotX.c}. User-defined
6724: colormaps would be nice, and \var{may} be available in future versions.
6725:
6726: \subsecidx{plotcopy}$(w1,w2,dx,dy)$: copy the contents of rectwindow
6727: $w1$ to rectwindow $w2$, with offset $(dx,dy)$.
6728:
6729: \subsecidx{plotcursor}$(w)$: give as a 2-component vector the current
6730: (scaled) position of the virtual cursor corresponding to the rectwindow $w$.
6731:
6732: \subsecidx{plotdraw}$(list)$: physically draw the rectwindows given in $list$
6733: which must be a vector whose number of components is divisible by 3. If
6734: $list=[w1,x1,y1,w2,x2,y2,\dots]$, the windows $w1$, $w2$, etc.~are
6735: physically placed with their upper left corner at physical position
6736: $(x1,y1)$, $(x2,y2)$,\dots\ respectively, and are then drawn together.
6737: Overlapping regions will thus be drawn twice, and the windows are considered
6738: transparent. Then display the whole drawing in a special window on your
6739: screen.
6740:
1.2 ! noro 6741: \subsecidx{plotfile}$(s)$: set the output file for plotting output. The
! 6742: special filename \kbd{"-"} redirects to the same place as PARI output. This
! 6743: is only taken into account by the \kbd{gnuplot} interface.
1.1 noro 6744:
6745: \subsecidx{ploth}$(X=a,b,\var{expr},\{\fl=0\},\{n=0\})$: high precision
6746: plot of the function $y=f(x)$ represented by the expression \var{expr}, $x$
6747: going from $a$ to $b$. This opens a specific window (which is killed
6748: whenever you click on it), and returns a four-component vector giving the
6749: coordinates of the bounding box in the form
6750: $[\var{xmin},\var{xmax},\var{ymin},\var{ymax}]$.
6751:
6752: \misctitle{Important note}: Since this may involve a lot of function calls,
6753: it is advised to keep the current precision to a minimum (e.g.~9) before
6754: calling this function.
6755:
6756: $n$ specifies the number of reference point on the graph (0 means use the
6757: hardwired default values, that is: 1000 for general plot, 1500 for
6758: parametric plot, and 15 for recursive plot).
6759:
6760: If no $\fl$ is given, \var{expr} is either a scalar expression $f(X)$, in which
6761: case the plane curve $y=f(X)$ will be drawn, or a vector
6762: $[f_1(X),\dots,f_k(X)]$, and then all the curves $y=f_i(X)$ will be drawn in
6763: the same window.
6764:
6765: \noindent The binary digits of $\fl$ mean:
6766:
1.2 ! noro 6767: $\bullet$ $1 = \kbd{Parametric}$: \tev{parametric plot}. Here \var{expr} must
! 6768: be a vector with an even number of components. Successive pairs are then
! 6769: understood as the parametric coordinates of a plane curve. Each of these are
! 6770: then drawn.
1.1 noro 6771:
6772: For instance:
6773:
6774: \kbd{ploth(X=0,2*Pi,[sin(X),cos(X)],1)} will draw a circle.
6775:
6776: \kbd{ploth(X=0,2*Pi,[sin(X),cos(X)])} will draw two entwined sinusoidal
6777: curves.
6778:
6779: \kbd{ploth(X=0,2*Pi,[X,X,sin(X),cos(X)],1)} will draw a circle and the line
6780: $y=x$.
6781:
6782:
1.2 ! noro 6783: $\bullet$ $2 = \kbd{Recursive}$: \tev{recursive plot}. If this flag is set,
! 6784: only \var{one} curve can be drawn at time, i.e.~\var{expr} must be either a
! 6785: two-component vector (for a single parametric curve, and the parametric flag
! 6786: \var{has} to be set), or a scalar function. The idea is to choose pairs of
! 6787: successive reference points, and if their middle point is not too far away
! 6788: from the segment joining them, draw this as a local approximation to the
! 6789: curve. Otherwise, add the middle point to the reference points. This is very
! 6790: fast, and usually more precise than usual plot. Compare the results of
1.1 noro 6791: $$\kbd{ploth(X=-1,1,sin(1/X),2)}\quad
6792: \text{and}\quad\kbd{ploth(X=-1,1,sin(1/X))}$$
6793: for instance. But beware that if you are extremely unlucky, or choose too few
6794: reference points, you may draw some nice polygon bearing little resemblance
6795: to the original curve. For instance you should \var{never} plot recursively
6796: an odd function in a symmetric interval around 0. Try
6797: \bprog
6798: ploth(x = -20, 20, sin(x), 2)
6799: @eprog
6800: \noindent to see why. Hence, it's usually a good idea to try and plot the same
6801: curve with slightly different parameters.
6802:
6803: The other values toggle various display options:
6804:
1.2 ! noro 6805: $\bullet$ $4 = \kbd{no\_Rescale}$: do not rescale plot according to the
! 6806: computed extrema. This is meant to be used when graphing multiple functions
! 6807: on a rectwindow (as a \tet{plotrecth} call), in conjunction with
! 6808: \tet{plotscale}.
1.1 noro 6809:
1.2 ! noro 6810: $\bullet$ $8 = \kbd{no\_X\_axis}$: do not print the $x$-axis.
1.1 noro 6811:
1.2 ! noro 6812: $\bullet$ $16 = \kbd{no\_Y\_axis}$: do not print the $y$-axis.
1.1 noro 6813:
1.2 ! noro 6814: $\bullet$ $32 = \kbd{no\_Frame}$: do not print frame.
1.1 noro 6815:
1.2 ! noro 6816: $\bullet$ $64 = \kbd{no\_Lines}$: only plot reference points, do not join them.
1.1 noro 6817:
1.2 ! noro 6818: $\bullet$ $128 = \kbd{Points_too}$: plot both lines and points.
1.1 noro 6819:
1.2 ! noro 6820: $\bullet$ $256 = \kbd{Splines}$: use splines to interpolate the points.
1.1 noro 6821:
1.2 ! noro 6822: $\bullet$ $512 = \kbd{no\_X\_ticks}$: plot no $x$-ticks.
1.1 noro 6823:
1.2 ! noro 6824: $\bullet$ $1024 = \kbd{no\_Y\_ticks}$: plot no $y$-ticks.
! 6825:
! 6826: $\bullet$ $2048 = \kbd{Same\_ticks}$: plot all ticks with the same length.
1.1 noro 6827:
6828: \subsecidx{plothraw}$(\var{listx},\var{listy},\{\fl=0\})$: given
6829: \var{listx} and \var{listy} two vectors of equal length, plots (in high
6830: precision) the points whose $(x,y)$-coordinates are given in \var{listx}
6831: and \var{listy}. Automatic positioning and scaling is done, but with the
6832: same scaling factor on $x$ and $y$. If $\fl$ is 1, join points, other non-0
6833: flags toggle display options and should be combinations of bits $2^k$, $k
6834: \geq 3$ as in \kbd{ploth}.
6835:
6836: \subsecidx{plothsizes}$()$: return data corresponding to the output window
6837: in the form of a 6-component vector: window width and height, sizes for ticks
6838: in horizontal and vertical directions (this is intended for the \kbd{gnuplot}
6839: interface and is currently not significant), width and height of characters.
6840:
6841: \subsecidx{plotinit}$(w,x,y,\{\fl\})$: initialize the rectwindow $w$,
6842: destroying any rect objects you may have already drawn in $w$. The virtual
6843: cursor is set to $(0,0)$. The rectwindow size is set to width $x$ and height
6844: $y$. If $\fl=0$, $x$ and $y$ represent pixel units. Otherwise, $x$ and $y$
6845: are understood as fractions of the size of the current output device (hence
6846: must be between $0$ and $1$) and internally converted to pixels.
6847:
6848: The plotting device imposes an upper bound for $x$ and $y$, for instance the
6849: number of pixels for screen output. These bounds are available through the
6850: \tet{plothsizes} function. The following sequence initializes in a portable
1.2 ! noro 6851: way (i.e independent of the output device) a window of maximal size, accessed
1.1 noro 6852: through coordinates in the $[0,1000] \times [0,1000]$ range~:
6853:
6854: \bprog
6855: s = plothsizes();
6856: plotinit(0, s[1]-1, s[2]-1);
6857: plotscale(0, 0,1000, 0,1000);
6858: @eprog
6859:
6860: \subsecidx{plotkill}$(w)$: erase rectwindow $w$ and free the corresponding
6861: memory. Note that if you want to use the rectwindow $w$ again, you have to
1.2 ! noro 6862: use \kbd{plotinit} first to specify the new size. So it's better in this case
! 6863: to use \kbd{plotinit} directly as this throws away any previous work in the
1.1 noro 6864: given rectwindow.
6865:
6866: \subsecidx{plotlines}$(w,X,Y,\{\fl=0\})$: draw on the rectwindow $w$
6867: the polygon such that the (x,y)-coordinates of the vertices are in the
6868: vectors of equal length $X$ and $Y$. For simplicity, the whole
6869: polygon is drawn, not only the part of the polygon which is inside the
6870: rectwindow. If $\fl$ is non-zero, close the polygon. In any case, the
6871: virtual cursor does not move.
6872:
6873: $X$ and $Y$ are allowed to be scalars (in this case, both have to).
6874: There, a single segment will be drawn, between the virtual cursor current
6875: position and the point $(X,Y)$. And only the part thereof which
6876: actually lies within the boundary of $w$. Then \var{move} the virtual cursor
6877: to $(X,Y)$, even if it is outside the window. If you want to draw a
6878: line from $(x1,y1)$ to $(x2,y2)$ where $(x1,y1)$ is not necessarily the
6879: position of the virtual cursor, use \kbd{plotmove(w,x1,y1)} before using this
6880: function.
6881:
6882: \subsecidx{plotlinetype}$(w,\var{type})$: change the type of lines
6883: subsequently plotted in rectwindow $w$. \var{type} $-2$ corresponds to
6884: frames, $-1$ to axes, larger values may correspond to something else. $w =
6885: -1$ changes highlevel plotting. This is only taken into account by the
6886: \kbd{gnuplot} interface.
6887:
6888: \subsecidx{plotmove}$(w,x,y)$: move the virtual cursor of the rectwindow $w$
6889: to position $(x,y)$.
6890:
6891: \subsecidx{plotpoints}$(w,X,Y)$: draw on the rectwindow $w$ the
6892: points whose $(x,y)$-coordinates are in the vectors of equal length $X$ and
6893: $Y$ and which are inside $w$. The virtual cursor does \var{not} move. This
6894: is basically the same function as \kbd{plothraw}, but either with no scaling
6895: factor or with a scale chosen using the function \kbd{plotscale}.
6896:
6897: As was the case with the \kbd{plotlines} function, $X$ and $Y$ are allowed to
6898: be (simultaneously) scalar. In this case, draw the single point $(X,Y)$ on
6899: the rectwindow $w$ (if it is actually inside $w$), and in any case
6900: \var{move} the virtual cursor to position $(x,y)$.
6901:
6902: \subsecidx{plotpointsize}$(w,size)$: changes the ``size'' of following
6903: points in rectwindow $w$. If $w = -1$, change it in all rectwindows.
6904: This only works in the \kbd{gnuplot} interface.
6905:
6906: \subsecidx{plotpointtype}$(w,\var{type})$: change the type of
6907: points subsequently plotted in rectwindow $w$. $\var{type} = -1$
6908: corresponds to a dot, larger values may correspond to something else. $w = -1$
6909: changes highlevel plotting. This is only taken into account by the
6910: \kbd{gnuplot} interface.
6911:
6912: \subsecidx{plotrbox}$(w,dx,dy)$: draw in the rectwindow $w$ the outline of
6913: the rectangle which is such that the points $(x1,y1)$ and $(x1+dx,y1+dy)$ are
6914: opposite corners, where $(x1,y1)$ is the current position of the cursor.
6915: Only the part of the rectangle which is in $w$ is drawn. The virtual cursor
6916: does \var{not} move.
6917:
6918: \subsecidx{plotrecth}$(w,X=a,b,\var{expr},\{\fl=0\},\{n=0\})$: writes to
6919: rectwindow $w$ the curve output of \kbd{ploth}$(w,X=a,b,\var{expr},\fl,n)$.
6920:
6921: \subsecidx{plotrecthraw}$(w,\var{data},\{\fl=0\})$: plot graph(s) for
6922: \var{data} in rectwindow $w$. $\fl$ has the same significance here as in
6923: \kbd{ploth}, though recursive plot is no more significant.
6924:
6925: \var{data} is a vector of vectors, each corresponding to a list a coordinates.
6926: If parametric plot is set, there must be an even number of vectors, each
1.2 ! noro 6927: successive pair corresponding to a curve. Otherwise, the first one contains
1.1 noro 6928: the $x$ coordinates, and the other ones contain the $y$-coordinates
6929: of curves to plot.
6930:
6931: \subsecidx{plotrline}$(w,dx,dy)$: draw in the rectwindow $w$ the part of the
6932: segment $(x1,y1)-(x1+dx,y1+dy)$ which is inside $w$, where $(x1,y1)$ is the
6933: current position of the virtual cursor, and move the virtual cursor to
6934: $(x1+dx,y1+dy)$ (even if it is outside the window).
6935:
6936: \subsecidx{plotrmove}$(w,dx,dy)$: move the virtual cursor of the rectwindow
6937: $w$ to position $(x1+dx,y1+dy)$, where $(x1,y1)$ is the initial position of
6938: the cursor (i.e.~to position $(dx,dy)$ relative to the initial cursor).
6939:
6940: \subsecidx{plotrpoint}$(w,dx,dy)$: draw the point $(x1+dx,y1+dy)$ on the
6941: rectwindow $w$ (if it is inside $w$), where $(x1,y1)$ is the current position
6942: of the cursor, and in any case move the virtual cursor to position
6943: $(x1+dx,y1+dy)$.
6944:
6945: \subsecidx{plotscale}$(w,x1,x2,y1,y2)$: scale the local coordinates of the
6946: rectwindow $w$ so that $x$ goes from $x1$ to $x2$ and $y$ goes from $y1$ to
6947: $y2$ ($x2<x1$ and $y2<y1$ being allowed). Initially, after the initialization
6948: of the rectwindow $w$ using the function \kbd{plotinit}, the default scaling
6949: is the graphic pixel count, and in particular the $y$ axis is oriented
6950: downwards since the origin is at the upper left. The function \kbd{plotscale}
6951: allows to change all these defaults and should be used whenever functions are
6952: graphed.
6953:
6954: \subsecidx{plotstring}$(w,x,\{\fl=0\})$: draw on the rectwindow $w$ the
6955: String $x$ (see \secref{se:strings}), at the current position of the cursor.
6956:
6957: \fl\ is used for justification: bits 1 and 2 regulate horizontal alignment:
6958: left if 0, right if 2, center if 1. Bits 4 and 8 regulate vertical
6959: alignment: bottom if 0, top if 8, v-center if 4. Can insert additional
6960: small gap between point and string: horizontal if bit 16 is set, vertical
6961: if bit 32 is set (see the tutorial for an example).
6962:
6963: \subsecidx{plotterm}$(\var{term})$: sets terminal where high resolution
6964: plots go (this is currently only taken into account by the \kbd{gnuplot}
6965: graphical driver). Using the \kbd{gnuplot} driver, possible terminals are
6966: the same as in gnuplot. If \var{term} is "?", lists possible values.
6967:
6968: Terminal options can be appended to the terminal name and space; terminal
6969: size can be put immediately after the name, as in \kbd{"gif=300,200"}.
6970: Positive return value means success.
6971:
6972: \subsecidx{psdraw}$(\var{list})$: same as \kbd{plotdraw}, except that the
6973: output is a PostScript program appended to the \kbd{psfile}.
6974:
6975: \subsecidx{psploth}$(X=a,b,\var{expr})$: same as \kbd{ploth}, except that the
6976: output is a PostScript program appended to the \kbd{psfile}.
6977:
6978: \subsecidx{psplothraw}$(\var{listx},\var{listy})$: same as \kbd{plothraw},
6979: except that the output is a PostScript program appended to the \kbd{psfile}.
6980:
6981: \section{Programming under GP}
6982: \sidx{programming}\label{se:programming}
6983: \subsecidx{Control statements}.
6984:
6985: A number of control statements are available under GP. They are simpler and
6986: have a syntax slightly different from their C counterparts, but are quite
6987: powerful enough to write any kind of program. Some of them are specific to
6988: GP, since they are made for number theorists. As usual, $X$ will denote any
6989: simple variable name, and \var{seq} will always denote a sequence of
6990: expressions, including the empty sequence.
6991:
6992: \subsubsecidx{break}$(\{n=1\})$: interrupts execution of current \var{seq}, and
6993: immediately exits from the $n$ innermost enclosing loops, within the
6994: current function call (or the top level loop). $n$ must be bigger than 1.
6995: If $n$ is greater than the number of enclosing loops, all enclosing loops
6996: are exited.
6997:
6998: \subsubsecidx{for}$(X=a,b,\var{seq})$: the formal variable $X$ going from
6999: $a$ to $b$, the \var{seq} is evaluated. Nothing is done if $a>b$.
7000: $a$ and $b$ must be in $\R$.
7001:
7002: \subsubsecidx{fordiv}$(n,X,\var{seq})$: the formal variable $X$ ranging
7003: through the positive divisors of $n$, the sequence \var{seq} is evaluated.
7004: $n$ must be of type integer.
7005:
7006: \subsubsecidx{forprime}$(X=a,b,\var{seq})$: the formal variable $X$
7007: ranging over the prime numbers between $a$ to $b$ (including $a$ and $b$
7008: if they are prime), the \var{seq} is evaluated. More precisely, the value
7009: of $X$ is incremented to the smallest prime strictly larger than $X$ at the
7010: end of each iteration. Nothing is done if $a>b$. Note that $a$ and $b$ must
7011: be in $\R$.
7012:
7013: \bprog
7014: ? { forprime(p = 2, 12,
7015: print(p);
7016: if (p == 3, p = 6);
7017: )
7018: }
7019: 2
7020: 3
7021: 7
7022: 11
7023: @eprog
7024:
7025: \subsubsecidx{forstep}$(X=a,b,s,\var{seq})$: the formal variable $X$
7026: going from $a$ to $b$, in increments of $s$, the \var{seq} is evaluated.
7027: Nothing is done if $s>0$ and $a>b$ or if $s<0$ and $a<b$. $s$ must be in
7028: $\R^*$ or a vector of steps $[s_1,\dots,s_n]$. In the latter case, the
7029: successive steps are used in the order they appear in $s$.
7030:
7031: \bprog
7032: ? forstep(x=5, 20, [2,4], print(x))
7033: 5
7034: 7
7035: 11
7036: 13
7037: 17
7038: 19
7039: @eprog
7040:
7041: \subsubsecidx{forsubgroup}$(H=G,\{B\},\var{seq})$: executes \var{seq} for
7042: each subgroup $H$ of the \var{abelian} group $G$ (given in
7043: SNF\sidx{Smith normal form} form or as a vector of elementary divisors),
7044: whose index is bounded by $B$. The subgroups are not ordered in any
7045: obvious way, unless $G$ is a $p$-group in which case Birkhoff's algorithm
7046: produces them by decreasing index. A \idx{subgroup} is given as a matrix
7047: whose columns give its generators on the implicit generators of $G$. For
7048: example, the following prints all subgroups of index less than 2 in $G =
7049: \Z/2\Z g_1 \times \Z/2\Z g_2$~:
7050:
7051: \bprog
7052: ? G = [2,2]; forsubgroup(H=G, 2, print(H))
7053: [1; 1]
7054: [1; 2]
7055: [2; 1]
7056: [1, 0; 1, 1]
7057: @eprog
7058: The last one, for instance is generated by $(g_1, g_1 + g_2)$. This
7059: routine is intended to treat huge groups, when \tet{subgrouplist} is not an
7060: option due to the sheer size of the output.
7061:
7062: For maximal speed the subgroups have been left as produced by the algorithm.
7063: To print them in canonical form (as left divisors of $G$ in
7064: HNF\sidx{Hermite normal form} form), one can for instance use
7065: \bprog
7066: ? G = matdiagonal([2,2]); forsubgroup(H=G, 2, print(mathnf(concat(G,H))))
7067: [2, 1; 0, 1]
7068: [1, 0; 0, 2]
7069: [2, 0; 0, 1]
7070: [1, 0; 0, 1]
1.2 ! noro 7071: @eprog\noindent
1.1 noro 7072: Note that in this last representation, the index $[G:H]$ is given by the
7073: determinant. See \tet{galoissubcyclo} and \tet{galoisfixedfield} for
7074: \tet{nfsubfields} applications to \idx{Galois} theory.
7075:
1.2 ! noro 7076: \misctitle{Warning:} the present implementation cannot treat a group $G$, if
! 7077: one of its $p$-Sylow subgroups has a cyclic factor has more than $2^{31}$,
! 7078: resp.~$2^{63}$ elements on a $32$-bit, resp.~$64$-bit architecture.
! 7079:
1.1 noro 7080: \subsubsecidx{forvec}$(X=v,\var{seq},\{\fl=0\})$: $v$ being an $n$-component
7081: vector (where $n$ is arbitrary) of two-component vectors $[a_i,b_i]$
7082: for $1\le i\le n$, the \var{seq} is evaluated with the formal variable
7083: $X[1]$ going from $a_1$ to $b_1$,\dots,$X[n]$ going from $a_n$ to $b_n$.
7084: The formal variable with the highest index moves the fastest. If $\fl=1$,
7085: generate only nondecreasing vectors $X$, and if $\fl=2$, generate only
7086: strictly increasing vectors $X$.
7087:
7088: \subsubsecidx{if}$(a,\{\var{seq1}\},\{\var{seq2}\})$: if $a$ is non-zero,
7089: the expression sequence \var{seq1} is evaluated, otherwise the expression
7090: \var{seq2} is evaluated. Of course, \var{seq1} or \var{seq2} may be empty,
7091: so \kbd{if ($a$,\var{seq})} evaluates \var{seq} if $a$ is not equal to zero
7092: (you don't have to write the second comma), and does nothing otherwise,
7093: whereas \kbd{if ($a$,,\var{seq})} evaluates \var{seq} if $a$ is equal to
7094: zero, and does nothing otherwise. You could get the same result using
7095: the \kbd{!} (\kbd{not}) operator: \kbd{if (!$a$,\var{seq})}.
7096:
7097: Note that the boolean operators \kbd{\&\&} and \kbd{||} are evaluated
7098: according to operator precedence as explained in \secref{se:operators}, but
7099: that, contrary to other operators, the evaluation of the arguments is
7100: stopped as soon as the final truth value has been determined. For instance
7101: \bprog
7102: if (reallydoit && longcomplicatedfunction(), ...)%
7103: @eprog
7104: \noindent is a perfectly safe statement.
7105:
7106: Recall that functions such as \kbd{break} and \kbd{next} operate on
7107: \var{loops} (such as \kbd{for$xxx$}, \kbd{while}, \kbd{until}). The \kbd{if}
7108: statement is \var{not} a loop (obviously!).
7109:
7110: \subsubsecidx{next}$(\{n=1\})$: interrupts execution of current $seq$,
7111: resume the next iteration of the innermost enclosing loop, within the
1.2 ! noro 7112: current function call (or top level loop). If $n$ is specified, resume at
1.1 noro 7113: the $n$-th enclosing loop. If $n$ is bigger than the number of enclosing
7114: loops, all enclosing loops are exited.
7115:
7116: \subsubsecidx{return}$(\{x=0\})$: returns from current subroutine, with
1.2 ! noro 7117: result $x$. If $x$ is omitted, return the \kbd{(void)} value (return no
! 7118: result, like \kbd{print}).
1.1 noro 7119:
7120: \subsubsecidx{until}$(a,\var{seq})$: evaluates expression sequence \var{seq}
7121: until $a$ is not equal to 0 (i.e.~until $a$ is true). If $a$ is initially
7122: not equal to 0, \var{seq} is evaluated once (more generally, the condition
7123: on $a$ is tested \var{after} execution of the \var{seq}, not before as in
7124: \kbd{while}).
7125:
7126: \subsubsecidx{while}$(a,\var{seq})$: while $a$ is non-zero evaluate the
7127: expression sequence \var{seq}. The test is made \var{before} evaluating
7128: the $seq$, hence in particular if $a$ is initially equal to zero the
7129: \var{seq} will not be evaluated at all.\smallskip
7130:
7131: \subsec{Specific functions used in GP programming}.
7132: \label{se:gp_program}
7133:
7134: In addition to the general PARI functions, it is necessary to have some
7135: functions which will be of use specifically for GP, though a few of these can
7136: be accessed under library mode. Before we start describing these, we recall
7137: the difference between \var{strings} and \var{keywords} (see
7138: \secref{se:strings}): the latter don't get expanded at all, and you can type
7139: them without any enclosing quotes. The former are dynamic objects, where
7140: everything outside quotes gets immediately expanded.
7141:
7142: We need an additional notation for this chapter. An argument between braces,
7143: followed by a star, like $\{\var{str}\}*$, means that any number of such
7144: arguments (possibly none) can be given.
7145:
7146: \subsubsecidx{addhelp}$(S,\var{str})$:\label{se:addhelp} changes the help
7147: message for the symbol $S$. The string \var{str} is expanded on the spot
7148: and stored as the online help for $S$. If $S$ is a function \var{you} have
7149: defined, its definition will still be printed before the message \var{str}.
7150: It is recommended that you document global variables and user functions in
7151: this way. Of course GP won't protest if you don't do it.
7152:
7153: There's nothing to prevent you from modifying the help of built-in PARI
7154: functions (but if you do, we'd like to hear why you needed to do it!).
7155:
7156: \subsubsecidx{alias}$(\var{newkey},\var{key})$: defines the keyword
7157: \var{newkey} as an alias for keyword \var{key}. \var{key} must correspond
7158: to an existing \var{function} name. This is different from the general user
7159: macros in that alias expansion takes place immediately upon execution,
7160: without having to look up any function code, and is thus much faster. A
7161: sample alias file \kbd{misc/gpalias} is provided with the standard
7162: distribution. Alias commands are meant to be read upon startup from the
7163: \kbd{.gprc} file, to cope with function names you are dissatisfied with, and
7164: should be useless in interactive usage.
7165:
7166: \subsubsecidx{allocatemem}$(\{x=0\})$: this is a very special operation which
7167: allows the user to change the stack size \var{after} initialization. $x$
7168: must be a non-negative integer. If $x!=0$, a new stack of size $16*\lceil
7169: x/16\rceil$ bytes will be allocated, all the PARI data on the old stack will
7170: be moved to the new one, and the old stack will be discarded. If $x=0$, the
7171: size of the new stack will be twice the size of the old one.
7172:
7173: Although it is a function, this must be the \var{last} instruction in any GP
7174: sequence. The technical reason is that this routine usually moves the stack,
7175: so objects from the current sequence might not be correct anymore. Hence, to
7176: prevent such problems, this routine terminates by a \kbd{longjmp} (just as an
7177: error would) and not by a return.
7178:
7179: \syn{allocatemoremem}{x}, where $x$ is an unsigned long, and the return type
7180: is void. GP uses a variant which ends by a \kbd{longjmp}.
7181:
7182: \subsubsecidx{default}$(\{\var{key}\},\{\var{val}\},\{\fl\})$: sets the default
7183: corresponding to keyword \var{key} to value \var{val}. \var{val} is a string
7184: (which of course accepts numeric arguments without adverse effects, due to the
7185: expansion mechanism). See \secref{se:defaults} for a list of available
7186: defaults, and \secref{se:meta} for some shortcut alternatives. Typing
7187: \kbd{default()} (or \b{d}) yields the complete default list as well as
7188: their current values.\label{se:default}
7189:
7190: If \var{val} is omitted, prints the current value of default \var{key}.
7191: If $\fl$ is set, returns the result instead of printing it.
7192:
7193: \subsubsecidx{error}$(\{\var{str}\}*)$: outputs its argument list (each of
7194: them interpreted as a string), then interrupts the running GP program,
7195: returning to the input prompt.
7196:
7197: Example: \kbd{error("n = ", n, " is not squarefree !")}.
7198:
7199: Note that, due to the automatic concatenation of strings, you could in fact
7200: use only one argument, just by suppressing the commas.
7201:
7202: \subsubsecidxunix{extern}$(\var{str})$: the string \var{str} is the name
7203: of an external command (i.e.~one you would type from your UNIX shell prompt).
7204: This command is immediately run and its input fed into GP, just as if read
7205: from a file.
7206:
7207: \subsubsecidx{getheap}$()$: returns a two-component row vector giving the
7208: number of objects on the heap and the amount of memory they occupy in long
7209: words. Useful mainly for debugging purposes.
7210:
7211: \syn{getheap}{}.
7212:
7213: \subsubsecidx{getrand}$()$: returns the current value of the random number
7214: seed. Useful mainly for debugging purposes.
7215:
7216: \syn{getrand}{}, returns a C long.
7217:
7218: \subsubsecidx{getstack}$()$: returns the current value of
7219: \kbd{top${}-{}$avma},
7220: i.e.~the number of bytes used up to now on the stack. Should be equal to 0
7221: in between commands. Useful mainly for debugging purposes.
7222:
7223: \syn{getstack}{}, returns a C long.
7224:
7225: \subsubsecidx{gettime}$()$: returns the time (in milliseconds) elapsed since
7226: either the last call to \kbd{gettime}, or to the beginning of the containing
7227: GP instruction (if inside GP), whichever came last.
7228:
7229: \syn{gettime}{}, returns a C long.
7230:
7231: \subsubsecidx{global}$(\{\hbox{\it list of variables}\})$: \label{se:global}
7232: declares the corresponding variables to be global. From now on, you will be
7233: forbidden to use them as formal parameters for function definitions or as
7234: loop indexes. This is especially useful when patching together various
7235: scripts, possibly written with different naming conventions. For instance the
7236: following situation is dangerous:
7237: %
7238: \bprog
7239: p = 3 \\@com fix characteristic
7240: ...
7241: forprime(p = 2, N, ...)
7242: f(p) = ...
7243: @eprog
7244: since within the loop or within the function's body (even worse: in the
7245: subroutines called in that scope), the true global value of \kbd{p} will be
7246: hidden. If the statement \kbd{global(p = 3)} appears at the beginning of
7247: the script, then both expressions will trigger syntax errors.
7248:
7249: Calling \kbd{global} without arguments prints the list of global variables in
7250: use. In particular, \kbd{eval(global)} will output the values of all local
7251: variables.
7252:
7253: \subsubsecidx{input}$()$: reads a string, interpreted as a GP expression,
7254: from the input file, usually standard input (i.e.~the keyboard). If a
7255: sequence of expressions is given, the result is the result of the last
7256: expression of the sequence. When using this instruction, it is useful to
7257: prompt for the string by using the \kbd{print1} function. Note that in the
7258: present version 2.19 of \kbd{pari.el}, when using GP under GNU Emacs (see
7259: \secref{se:emacs}) one \var{must} prompt for the string, with a string
7260: which ends with the same prompt as any of the previous ones (a \kbd{"? "}
7261: will do for instance).
7262:
7263: \subsubsecidxunix{install}$(\var{name},\var{code},\{\var{gpname}\},\{\var{lib}\})$:
7264: loads from dynamic library \var{lib} the function \var{name}. Assigns to it
7265: the name \var{gpname} in this GP session, with argument code \var{code} (see
7266: \secref{se:gp.interface} for an explanation of those). If \var{lib} is
7267: omitted, uses \kbd{libpari.so}. If \var{gpname} is omitted, uses
7268: \var{name}.\label{se:install}
7269:
7270: This function is useful for adding custom functions to the GP interpreter,
7271: or picking useful functions from unrelated libraries. For instance, it
7272: makes the function \tet{system} obsolete:
7273:
7274: \bprog
7275: ? install(system, vs, sys, "libc.so")
7276: ? sys("ls gp*")
7277: gp.c gp.h gp_rl.c
7278: @eprog
7279:
7280: But it also gives you access to all (non static) functions defined in the
7281: PARI library. For instance, the function \kbd{GEN addii(GEN x, GEN y)} adds
7282: two PARI integers, and is not directly accessible under GP (it's eventually
7283: called by the \kbd{+} operator of course):
7284:
7285: \bprog
7286: ? install("addii", "GG")
7287: ? addii(1, 2)
7288: %1 = 3
7289: @eprog
7290:
7291: \misctitle{Caution:} This function may not work on all systems, especially
7292: when GP has been compiled statically. In that case, the first use of an
7293: installed function will provoke a Segmentation Fault, i.e.~a major internal
7294: blunder (this should never happen with a dynamically linked executable).
7295: Hence, if you intend to use this function, please check first on some
7296: harmless example such as the ones above that it works properly on your
7297: machine.
7298:
7299: \subsubsecidx{kill}$(s)$:\label{se:kill} kills the present value of the
7300: variable, alias or user-defined function $s$. The corresponding identifier
7301: can now be used to name any GP object (variable or function). This is the
7302: only way to replace a variable by a function having the same name (or the
7303: other way round), as in the following example:
7304:
7305: \bprog
7306: ? f = 1
7307: %1 = 1
7308: ? f(x) = 0
7309: *** unused characters: f(x)=0
7310: ^----
7311: ? kill(f)
7312: ? f(x) = 0
7313: ? f()
7314: %2 = 0
7315: @eprog
7316:
7317: When you kill a variable, all objects that used it become invalid. You
7318: can still display them, even though the killed variable will be printed in a
7319: funny way (following the same convention as used by the library function
7320: \kbd{fetch\_var}, see~\secref{se:vars}). For example:
7321:
7322: \bprog
7323: ? a^2 + 1
7324: %1 = a^2 + 1
7325: ? kill(a)
7326: ? %1
7327: %2 = #<1>^2 + 1
7328: @eprog
7329:
7330: If you simply want to restore a variable to its ``undefined'' value
7331: (monomial of degree one), use the \idx{quote} operator: \kbd{a = 'a}.
7332: Predefined symbols (\kbd{x} and GP function names) cannot be killed.
7333:
7334: \subsubsecidx{print}$(\{\var{str}\}*)$: outputs its (string) arguments in raw
7335: format, ending with a newline.
7336:
7337: \subsubsecidx{print1}$(\{\var{str}\}*)$: outputs its (string) arguments in raw
7338: format, without ending with a newline (note that you can still embed newlines
7339: within your strings, using the \b{n} notation~!).
7340:
7341: \subsubsecidx{printp}$(\{\var{str}\}*)$: outputs its (string) arguments in
7342: prettyprint (beautified) format, ending with a newline.
7343:
7344: \subsubsecidx{printp1}$(\{\var{str}\}*)$: outputs its (string) arguments in
7345: prettyprint (beautified) format, without ending with a newline.
7346:
7347: \subsubsecidx{printtex}$(\{\var{str}\}*)$: outputs its (string) arguments in
7348: \TeX\ format. This output can then be used in a \TeX\ manuscript.
7349: The printing is done on the standard output. If you want to print it to a
7350: file you should use \kbd{writetex} (see there).
7351:
7352: Another possibility is to enable the \tet{log} default
7353: (see~\secref{se:defaults}).
7354: You could for instance do:\sidx{logfile}
7355: %
7356: \bprog
7357: default(logfile, "new.tex");
7358: default(log, 1);
7359: printtex(result);
7360: @eprog
7361: \noindent
7362: (You can use the automatic string expansion/concatenation process to have
7363: dynamic file names if you wish).
7364:
7365: \subsubsecidx{quit}$()$: exits GP.\label{se:quit}
7366:
7367: \subsubsecidx{read}$(\{\var{str}\})$: reads in the file whose name results
7368: from the expansion of the string \var{str}. If \var{str} is omitted,
7369: re-reads the last file that was fed into GP. The return value is the result of
7370: the last expression evaluated.\label{se:read} If a GP \tet{binary file} is
7371: read using this command (see \secref{se:writebin}), the file is loaded and
7372: the last object in the file is returned.
7373:
7374: \subsubsecidx{reorder}$(\{x=[\,]\})$: $x$ must be a vector. If $x$ is the
7375: empty vector, this gives the vector whose components are the existing
7376: variables in increasing order (i.e.~in decreasing importance). Killed
7377: variables (see \kbd{kill}) will be shown as \kbd{0}. If $x$ is
7378: non-empty, it must be a permutation of variable names, and this permutation
7379: gives a new order of importance of the variables, {\it for output only}. For
7380: example, if the existing order is \kbd{[x,y,z]}, then after
7381: \kbd{reorder([z,x])} the order of importance of the variables, with respect
7382: to output, will be \kbd{[z,y,x]}. The internal representation is unaffected.
7383: \label{se:reorder}
7384:
7385: \subsubsecidx{setrand}$(n)$: reseeds the random number generator to the value
7386: $n$. The initial seed is $n=1$.
7387:
7388: \syn{setrand}{n}, where $n$ is a \kbd{long}. Returns $n$.
7389:
7390: \subsubsecidxunix{system}$(\var{str})$: \var{str} is a string representing
7391: a system command. This command is executed, its output written to the
7392: standard output (this won't get into your logfile), and control returns
7393: to the PARI system. This simply calls the C \kbd{system} command.
7394:
7395: \subsubsecidx{trap}$(\{e\}, \{\var{rec}\}, \{\var{seq}\})$: tries to
7396: execute \var{seq}, trapping error $e$, that is effectively preventing it
7397: from aborting computations in the usual way; the recovery sequence
7398: \var{rec} is executed if the error occurs and the evaluation of \var{rec}
7399: becomes the result of the command. If $e$ is omitted, all exceptions are
7400: trapped. Note in particular that hitting \kbd{\pow C} (Control-C) raises an
7401: exception.
7402:
7403: \bprog
7404: ? \\@com trap division by 0
7405: ? inv(x) = trap (gdiver2, INFINITY, 1/x)
7406: ? inv(2)
7407: %1 = 1/2
7408: ? inv(0)
7409: %2 = INFINITY
7410: @eprog
7411:
7412: If \var{seq} is omitted, defines \var{rec} as a default action when
7413: encountering exception $e$. The error message is printed, as well as the
7414: result of the evaluation of \var{rec}, and the control is given back to the
7415: GP prompt. In particular, current computation is then lost.
7416:
7417: The following error handler prints the list of all user variables, then
1.2 ! noro 7418: stores in a file their name and their values:\sidx{writebin}
1.1 noro 7419: \bprog
7420: ? { trap( ,
7421: print(reorder);
1.2 ! noro 7422: writebin("crash")) }
1.1 noro 7423: @eprog
7424:
7425: If no recovery code is given (\var{rec} is omitted) a so-called
7426: {\it\idx{break loop}} will be started. During a break loop, all commands are
7427: read and evaluated as during the main GP loop (except that no history of
7428: results is kept).
7429:
7430: To get out of the break loop, you can use \tet{next}, \tet{break} or
7431: \tet{return}; reading in a file by \b{r} will also terminate the loop once
7432: the file has been read (\kbd{read} will remain in the break loop). If the
7433: error is not fatal (\kbd{\pow C} is the only non-fatal error), \kbd{next}
7434: will continue the computation as if nothing had happened (except of course,
7435: you may have changed GP state during the break loop); otherwise control
7436: will come back to the GP prompt. After a user interrupt (\kbd{\pow C}),
7437: entering an empty input line (i.e hitting the return key) has the same
7438: effect as \kbd{next}.
7439:
7440: Break loops are useful as a debugging tool to inspect the values of GP
7441: variables to understand why a problem occurred, or to change GP behaviour
7442: (increase debugging level, start storing results in a logfile, modify
7443: parameters\dots) in the middle of a long computation (hit \kbd{\pow C}, type
7444: in your modifications, then type \kbd{next}).
7445:
7446: If \var{rec} is the empty string \kbd{""} the last default handler is popped
7447: out, and replaced by the previous one for that error.
7448:
7449: \misctitle{Note:} The interface is currently not adequate for trapping
7450: individual exceptions. In the current version \vers, the following keywords
7451: are recognized, but the name list will be expanded and changed in the
7452: future (all library mode errors can be trapped: it's a matter of defining
7453: the keywords to GP, and there are currently far too many useless ones):
7454:
7455: \kbd{accurer}: accuracy problem
7456:
7457: \kbd{gdiver2}: division by 0
7458:
7459: \kbd{invmoder}: impossible inverse modulo
7460:
7461: \kbd{archer}: not available on this architecture or operating system
7462:
7463: \kbd{typeer}: wrong type
7464:
7465: \kbd{errpile}: the PARI stack overflows
7466:
7467: \subsubsecidx{type}$(x,\{t\})$: this is useful only under GP. If $t$ is
7468: not present, returns the internal type number of the PARI object $x$.
7469: Otherwise, makes a copy of $x$ and sets its type equal to type $t$, which
7470: can be either a number or, preferably since internal codes may eventually
7471: change, a symbolic name such as \typ{FRACN} (you can skip the \typ{}
7472: part here, so that \kbd{FRACN} by itself would also be all right). Check out
7473: existing type names with the metacommand \b{t}.\label{se:gptype}
7474:
7475: GP won't let you create meaningless objects in this way where the internal
7476: structure doesn't match the type. This function can be useful to create
7477: reducible rationals (type \typ{FRACN}) or rational functions (type
7478: \typ{RFRACN}). In fact it's the only way to do so in GP. In this case, the
7479: created object, as well as the objects created from it, will not be reduced
7480: automatically, making some operations a bit faster.
7481:
7482: There is no equivalent library syntax, since the internal functions \kbd{typ}
7483: and \kbd{settyp} are available. Note that \kbd{settyp} does \var{not}
7484: create a copy of \kbd{x}, contrary to most PARI functions. It also doesn't
7485: check for consistency. \kbd{settyp} just changes the type in place and
7486: returns nothing. \kbd{typ} returns a C long integer. Note also the different
7487: spellings of the internal functions (\kbd{set})\kbd{typ} and of the GP
7488: function \kbd{type}, which is due to the fact that \kbd{type} is a reserved
7489: identifier for some C compilers.
7490:
7491: \subsubsecidx{whatnow}$(\var{key})$: if keyword \var{key} is the name
7492: of a function that was present in GP version 1.39.15 or lower, outputs
7493: the new function name and syntax, if it changed at all ($387$ out of $560$
7494: did).\label{se:whatnow}
7495:
7496: \subsubsecidx{write}$(\var{filename},\{\var{str}*\})$: writes (appends)
7497: to \var{filename} the remaining arguments, and appends a newline (same output
7498: as \kbd{print}).\label{se:write}
7499:
7500: \subsubsecidx{write1}$(\var{filename},\{\var{str}*\})$: writes (appends) to
7501: \var{filename} the remaining arguments without a trailing newline
7502: (same output as \kbd{print1}).
7503:
7504: \subsubsecidx{writebin}$(\var{filename},\{x\})$: writes (appends) to
7505: \var{filename} the object $x$ in binary format. This format is not human
7506: readable, but contains the exact internal structure of $x$, and is much
7507: faster to save/load than a string expression, as would be produced by
7508: \tet{write}. The binary file format includes a magic number, so that such a
7509: file can be recognized and correctly input by the regular \tet{read} or \b{r}
7510: function. If saved objects refer to (polynomial) variables that are not
7511: defined in the new session, they will be displayed in a funny way (see
7512: \secref{se:kill}).
7513:
7514: If $x$ is omitted, saves all user variables from the session, together with
7515: their names. Reading such a ``named object'' back in a GP session will set
7516: the corresponding user variable to the saved value. E.g after
7517: \bprog
7518: x = 1; writebin("log")
7519: @eprog
7520: \noindent reading \kbd{log} into a clean session will set \kbd{x} to $1$.
1.2 ! noro 7521: The relative variables priorities (see \secref{se:priority}) of new variables
! 7522: set in this way remain the same (preset variables retain their former
! 7523: priority, but are set to the new value). In particular, reading such a
! 7524: session log into a clean session will restore all variables exactly as they
! 7525: were in the original one.
1.1 noro 7526:
7527: User functions, installed functions and history objects can not be saved via
7528: this function. Just as a regular input file, a binary file can be compressed
7529: using \tet{gzip}, provided the file name has the standard \kbd{.gz}
7530: extension. \label{se:writebin}\sidx{binary file}
1.2 ! noro 7531:
! 7532: In the present implementation, the binary files are architecture dependant
! 7533: and compatibility with future versions of GP is not guaranteed. Hence
! 7534: binary files should not be used for long term storage (also, they are
! 7535: larger and harder to compress than text files).
1.1 noro 7536:
7537: \subsubsecidx{writetex}$(\var{filename},\{\var{str}*\})$: as \kbd{write},
7538: in \TeX\ format.\label{se:writetex}
7539:
7540: \vfill\eject
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to usersch3.tex CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM_contrib / pari-2.2 / doc