Annotation of OpenXM_contrib/pari-2.2/doc/usersch3.tex, Revision 1.1
1.1 ! noro 1: % $Id: usersch3.tex,v 1.127 2001/09/29 16:36:17 karim Exp $
! 2: % Copyright (c) 2000 The PARI Group
! 3: %
! 4: % This file is part of the PARI/GP documentation
! 5: %
! 6: % Permission is granted to copy, distribute and/or modify this document
! 7: % under the terms of the GNU Free Documentation License
! 8: \chapter{Functions and Operations Available in PARI and GP}
! 9: \label{se:functions}
! 10:
! 11: The functions and operators available in PARI and in the GP/PARI calculator
! 12: are numerous and everexpanding. Here is a description of the ones available
! 13: in version \vers. It should be noted that many of these functions accept
! 14: quite different types as arguments, but others are more restricted. The list
! 15: of acceptable types will be given for each function or class of functions.
! 16: Except when stated otherwise, it is understood that a function or operation
! 17: which should make natural sense is legal. In this chapter, we will describe
! 18: the functions according to a rough classification. The general entry looks
! 19: something like:
! 20:
! 21: \key{foo}$(x,\{\fl=0\})$: short description.
! 22:
! 23: \syn{foo}{x,\fl}.
! 24:
! 25: \noindent
! 26: This means that the GP function \kbd{foo} has one mandatory argument $x$, and
! 27: an optional one, $\fl$, whose default value is 0 (the $\{\}$ should never be
! 28: typed, it is just a convenient notation we will use throughout to denote
! 29: optional arguments). That is, you can type \kbd{foo(x,2)}, or \kbd{foo(x)},
! 30: which is then understood to mean \kbd{foo(x,0)}. As well, a comma or closing
! 31: parenthesis, where an optional argument should have been, signals to GP it
! 32: should use the default. Thus, the syntax \kbd{foo(x,)} is also accepted as a
! 33: synonym for our last expression. When a function has more than one optional
! 34: argument, the argument list is filled with user supplied values, in order.
! 35: And when none are left, the defaults are used instead. Thus, assuming that
! 36: \kbd{foo}'s prototype had been
! 37: $$\hbox{%
! 38: \key{foo}$(\{x=1\},\{y=2\},\{z=3\})$,%
! 39: }$$
! 40: typing in \kbd{foo(6,4)} would give
! 41: you \kbd{foo(6,4,3)}. In the rare case when you want to set some far away
! 42: flag, and leave the defaults in between as they stand, you can use the
! 43: ``empty arg'' trick alluded to above: \kbd{foo(6,,1)} would yield
! 44: \kbd{foo(6,2,1)}. By the way, \kbd{foo()} by itself yields
! 45: \kbd{foo(1,2,3)} as was to be expected. In this rather special case of a
! 46: function having no mandatory argument, you can even omit the $()$: a
! 47: standalone \kbd{foo} would be enough (though we don't really recommend it for
! 48: your scripts, for the sake of clarity). In defining GP syntax, we strove
! 49: to put optional arguments at the end of the argument list (of course, since
! 50: they would not make sense otherwise), and in order of decreasing usefulness
! 51: so that, most of the time, you will be able to ignore them.
! 52:
! 53: \misctitle{Binary Flags}.\sidx{binary flag} For some of these optional
! 54: flags, we adopted the customary binary notation as a compact way to
! 55: represent many toggles with just one number. Letting $(p_0,\dots,p_n)$ be a
! 56: list of switches (i.e.~of properties which can be assumed to take either
! 57: the value $0$ or~$1$), the number $2^3 + 2^5=40$ means that $p_3$ and $p_5$
! 58: have been set (that is, set to $1$), and none of the others were (that is,
! 59: they were set to 0). This will usually be announced as ``The binary digits
! 60: of $\fl$ mean 1: $p_0$, 2: $p_1$, 4: $p_2$'', and so on, using the
! 61: available consecutive powers of~$2$.
! 62:
! 63: \misctitle{Pointers}.\sidx{pointer} If a parameter in the function
! 64: prototype is prefixed with a \& sign, as in
! 65:
! 66: \key{foo}$(x,\&e)$
! 67:
! 68: \noindent it means that, besides the normal return value, the variable named
! 69: $e$ may be set as a side effect. When passing the argument, the \& sign has
! 70: to be typed in explicitly. As of version \vers, this \tet{pointer} argument
! 71: is optional for all documented functions, hence the \& will always appear
! 72: between brackets as in \kbd{issquare}$(x,\{\&e\})$.
! 73:
! 74: \misctitle{About library programming}. To finish with our generic
! 75: simple-minded example, the \var{library} function \kbd{foo}, as defined
! 76: above, is seen to have two mandatory arguments, $x$ and \fl (no PARI
! 77: mathematical function has been implemented so as to accept a variable
! 78: number of arguments). When not mentioned otherwise, the result and
! 79: arguments of a function are assumed implicitly to be of type \kbd{GEN}.
! 80: Most other functions return an object of type \kbd{long} integer in C (see
! 81: Chapter~4). The variable or parameter names \var{prec} and \fl\ always
! 82: denote \kbd{long} integers.
! 83:
! 84: The \tet{entree} type is used by the library to implement iterators (loops,
! 85: sums, integrals, etc.) when a formal variable has to successively assume a
! 86: number of values in a given set. When programming with the library, it is
! 87: easier and much more efficient to code loops and the like directly. Hence
! 88: this type is not documented, although it does appear in a few library
! 89: function prototypes below. See \secref{se:sums} for more details.
! 90:
! 91: \section{Standard monadic or dyadic operators}
! 92:
! 93: \subseckbd{+$/$-}: The expressions \kbd{+}$x$ and \kbd{-}$x$ refer
! 94: to monadic operators (the first does nothing, the second negates $x$).
! 95:
! 96: \syn{gneg}{x} for \kbd{-}$x$.
! 97:
! 98: \subseckbd{+}, \kbd{-}: The expression $x$ \kbd{+} $y$ is the \idx{sum} and
! 99: $x$ \kbd{-} $y$ is the \idx{difference} of $x$ and $y$. Among the prominent
! 100: impossibilities are addition/subtraction between a scalar type and a vector
! 101: or a matrix, between vector/matrices of incompatible sizes and between an
! 102: integermod and a real number.
! 103:
! 104: \syn{gadd}{x,y} $x$ \kbd{+} $y$, $\teb{gsub}(x,y)$ for $x$ \kbd{-} $y$.
! 105:
! 106: \subseckbd{*}: The expression $x$ \kbd{*} $y$ is the \idx{product} of $x$
! 107: and $y$. Among the prominent impossibilities are multiplication between
! 108: vector/matrices of incompatible sizes, between an integermod and a real
! 109: number. Note that because of vector and matrix operations, \kbd{*} is not
! 110: necessarily commutative. Note also that since multiplication between two
! 111: column or two row vectors is not allowed, to obtain the \idx{scalar product}
! 112: of two vectors of the same length, you must multiply a line vector by a
! 113: column vector, if necessary by transposing one of the vectors (using
! 114: the operator \kbd{\til} or the function \kbd{mattranspose}, see
! 115: \secref{se:linear_algebra}).
! 116:
! 117: If $x$ and $y$ are binary quadratic forms, compose them. See also
! 118: \kbd{qfbnucomp} and \kbd{qfbnupow}.
! 119:
! 120: \syn{gmul}{x,y} for $x$ \kbd{*} $y$. Also available is
! 121: $\teb{gsqr}(x)$ for $x$ \kbd{*} $x$ (faster of course!).
! 122:
! 123: \subseckbd{/}: The expression $x$ \kbd{/} $y$ is the \idx{quotient} of $x$
! 124: and $y$. In addition to the impossibilities for multiplication, note that if
! 125: the divisor is a matrix, it must be an invertible square matrix, and in that
! 126: case the result is $x*y^{-1}$. Furthermore note that the result is as exact
! 127: as possible: in particular, division of two integers always gives a rational
! 128: number (which may be an integer if the quotient is exact) and \var{not} the
! 129: Euclidean quotient (see $x$ \kbd{\bs} $y$ for that), and similarly the
! 130: quotient of two polynomials is a rational function in general. To obtain the
! 131: approximate real value of the quotient of two integers, add \kbd{0.} to the
! 132: result; to obtain the approximate $p$-adic value of the quotient of two
! 133: integers, add \kbd{O(p\pow k)} to the result; finally, to obtain the
! 134: \idx{Taylor series} expansion of the quotient of two polynomials, add
! 135: \kbd{O(X\pow k)} to the result or use the \kbd{taylor} function
! 136: (see \secref{se:taylor}). \label{se:gdiv}
! 137:
! 138: \syn{gdiv}{x,y} for $x$ \kbd{/} $y$.
! 139:
! 140: \subseckbd{\bs}: The expression $x$ \kbd{\bs} $y$ is the
! 141: % keep "Euclidean" and "quotient" on same line for gphelp
! 142: \idx{Euclidean quotient} of $x$ and $y$. The types must be either both
! 143: integer or both polynomials. The result is the Euclidean quotient. In the
! 144: case of integer division, the quotient is such that the corresponding
! 145: remainder is non-negative.
! 146:
! 147: \syn{gdivent}{x,y} for $x$ \kbd{\bs} $y$.
! 148:
! 149: \subseckbd{\bs/}: The expression $x$ \b{/} $y$ is the Euclidean
! 150: quotient of $x$ and $y$. The types must be either both integer or both
! 151: polynomials. The result is the rounded Euclidean quotient. In the case of
! 152: integer division, the quotient is such that the corresponding remainder is
! 153: smallest in absolute value and in case of a tie the quotient closest to
! 154: $+\infty$ is chosen.
! 155:
! 156: \syn{gdivround}{x,y} for $x$ \b{/} $y$.
! 157:
! 158: \subseckbd{\%}: The expression $x$ \kbd{\%} $y$ is the
! 159: % keep "Euclidean" and "remainder" on same line for gphelp
! 160: \idx{Euclidean remainder} of $x$ and $y$. The modulus $y$ must be of type
! 161: integer or polynomial. The result is the remainder, always non-negative in
! 162: the case of integers. Allowed dividend types are scalar exact types when
! 163: the modulus is an integer, and polynomials, polmods and rational functions
! 164: when the modulus is a polynomial.
! 165:
! 166: \syn{gmod}{x,y} for $x$ \kbd{\%} $y$.
! 167:
! 168: \subsecidx{divrem}$(x,y)$: creates a column vector with two components,
! 169: the first being the Euclidean quotient, the second the Euclidean remainder,
! 170: of the division of $x$ by $y$. This avoids the need to do two divisions if
! 171: one needs both the quotient and the remainder. The arguments must be both
! 172: integers or both polynomials; in the case of integers, the remainder is
! 173: non-negative.
! 174:
! 175: \syn{gdiventres}{x,y}.
! 176:
! 177: \subseckbd{\pow}: The expression $x\hbox{\kbd{\pow}}n$ is \idx{powering}.
! 178: If the exponent is an integer, then exact operations are performed using
! 179: binary (left-shift) powering techniques. In particular, in this case $x$
! 180: cannot be a vector or matrix unless it is a square matrix (and moreover
! 181: invertible if the exponent is negative). If $x$ is a $p$-adic number, its
! 182: precision will increase if $v_p(n) > 0$. PARI is able to rewrite the
! 183: multiplication $x * x$ of two {\it identical} objects as $x^2$, or
! 184: $\kbd{sqr}(x)$ (here, identical means the operands are two different labels
! 185: referencing the same chunk of memory; no equality test is performed). This
! 186: is no longer true when more than two arguments are involved.
! 187:
! 188: If the exponent is not of type integer, this is treated as a transcendental
! 189: function (see \secref{se:trans}), and in particular has the effect of
! 190: componentwise powering on vector or matrices.
! 191:
! 192: As an exception, if the exponent is a rational number $p/q$ and $x$ an
! 193: integer modulo a prime, return a solution $y$ of $y^q=x^p$ if it
! 194: exists. Currently, $q$ must not have large prime factors.
! 195:
! 196: Beware that
! 197:
! 198: \bprog
! 199: ? Mod(7,19)^(1/2)
! 200: %1 = Mod(11, 19)/*is any square root*/
! 201: ? sqrt(Mod(7,19))
! 202: %2 = Mod(8, 19)/*is the smallest square root*/
! 203: ? Mod(7,19)^(3/5)
! 204: %3 = Mod(1, 19)
! 205: ? %3^(5/3)
! 206: %4 = Mod(1, 19)/*Mod(7,19) is just another cubic root*/
! 207: @eprog\noindent
! 208:
! 209: \syn{gpow}{x,n,\var{prec}} for $x\hbox{\kbd{\pow}}n$.
! 210:
! 211: \subsecidx{shift}$(x,n)$ or $x$ \kbd{<<} $n$ (= $x$ \kbd{>>} $(-n)$): shifts
! 212: $x$ componentwise left by $n$ bits if $n\ge0$ and right by $|n|$ bits if
! 213: $n<0$. A left shift by $n$ corresponds to multiplication by $2^n$. A right
! 214: shift of an integer $x$ by $|n|$ corresponds to a Euclidean division of
! 215: $x$ by $2^{|n|}$ with a
! 216: remainder of the same sign as $x$, hence is not the same (in general) as
! 217: $x \kbd{\bs} 2^n$.
! 218:
! 219: \syn{gshift}{x,n} where $n$ is a \kbd{long}.
! 220:
! 221: \subsecidx{shiftmul}$(x,n)$: multiplies $x$ by $2^n$. The difference with
! 222: \kbd{shift} is that when $n<0$, ordinary division takes place, hence for
! 223: example if $x$ is an integer the result may be a fraction, while for
! 224: \kbd{shift} Euclidean division takes place when $n<0$ hence if $x$ is an
! 225: integer the result is still an integer.
! 226:
! 227: \syn{gmul2n}{x,n} where $n$ is a \kbd{long}.
! 228:
! 229: \subsec{Comparison and boolean operators}.\sidx{boolean operators}
! 230: The six standard \idx{comparison operators} \kbd{<=}, \kbd{<}, \kbd{>=},
! 231: \kbd{>}, \kbd{==}, \kbd{!=} are available in GP, and in library mode under
! 232: the names \tet{gle}, \tet{glt}, \tet{gge}, \tet{ggt}, \tet{geq}, \tet{gne}
! 233: respectively. The library syntax is $\var{co}(x,y)$, where \var{co} is the
! 234: comparison operator. The result is 1 (as a \kbd{GEN}) if the comparison is
! 235: true, 0 (as a \kbd{GEN}) if it is false.
! 236:
! 237: The standard boolean functions \kbd{||} (\idx{inclusive or}), \kbd{\&\&}
! 238: (\idx{and})\sidx{or} and \kbd{!} (\idx{not}) are also available, and the
! 239: library syntax is $\teb{gor}(x,y)$, $\teb{gand}(x,y)$ and $\teb{gnot}(x)$
! 240: respectively.
! 241:
! 242: In library mode, it is in fact usually preferable to use the two basic
! 243: functions which are $\teb{gcmp}(x,y)$ which gives the sign (1, 0, or -1) of
! 244: $x-y$, where $x$ and $y$ must be in $\R$, and $\teb{gegal}(x,y)$ which
! 245: can be applied to any two PARI objects $x$ and $y$ and gives 1 (i.e.~true) if
! 246: they are equal (but not necessarily identical), 0 (i.e.~false) otherwise.
! 247: Particular cases of \teb{gegal} which should be used are $\teb{gcmp0}(x)$
! 248: ($x==0$ ?), $\teb{gcmp1}(x)$ ($x==1$ ?), and
! 249: $\teb{gcmp_1}(x)$ ($x==-1$ ?).
! 250:
! 251: Note that $\teb{gcmp0}(x)$ tests whether $x$ is equal to zero, even if $x$ is
! 252: not an exact object. To test whether $x$ is an exact object which is equal to
! 253: zero, one must use $\tet{isexactzero}$.
! 254:
! 255: Also note that the \kbd{gcmp} and \kbd{gegal} functions return a C-integer,
! 256: and \var{not} a \kbd{GEN} like \kbd{gle} etc.
! 257:
! 258: \smallskip
! 259: GP accepts the following synonyms for some of the above functions: since we
! 260: thought it might easily lead to confusion, we don't use the customary C
! 261: operators for bitwise \kbd{and} or bitwise \kbd{or} (use \tet{bitand} or
! 262: \tet{bitor}), hence \kbd{|} and \kbd{\&} are accepted as\sidx{bitwise
! 263: and}\sidx{bitwise or} synonyms of \kbd{||} and \kbd{\&\&} respectively.
! 264: Also, \kbd{<>} is accepted as a synonym for \kbd{!=}. On the other hand,
! 265: \kbd{=} is definitely \var{not} a synonym for \kbd{==} since it is the
! 266: assignment statement.
! 267:
! 268: \subsecidx{lex}$(x,y)$: gives the result of a lexicographic comparison
! 269: between $x$ and $y$. This is to be interpreted in quite a wide sense. For
! 270: example, the vector $[1,3]$ will be considered smaller than the longer
! 271: vector $[1,3,-1]$ (but of course larger than $[1,2,5]$),
! 272: i.e.~\kbd{lex([1,3], [1,3,-1])} will return $-1$.
! 273:
! 274: \syn{lexcmp}{x,y}.
! 275:
! 276: \subsecidx{sign}$(x)$: \idx{sign} ($0$, $1$ or $-1$) of $x$, which must be of
! 277: type integer, real or fraction.
! 278:
! 279: \syn{gsigne}{x}. The result is a \kbd{long}.
! 280:
! 281: \subsecidx{max}$(x,y)$ and \teb{min}$(x,y)$: creates the
! 282: maximum and minimum of $x$ and $y$ when they can be compared.
! 283:
! 284: \syn{gmax}{x,y} and $\teb{gmin}(x,y)$.
! 285:
! 286: \subsecidx{vecmax}$(x)$: if $x$ is a vector or a matrix, returns the maximum
! 287: of the elements of $x$, otherwise returns a copy of $x$. Returns $-\infty$
! 288: in the form of $-(2^{31}-1)$ (or $-(2^{63}-1)$ for 64-bit machines) if $x$ is
! 289: empty.
! 290:
! 291: \syn{vecmax}{x}.
! 292:
! 293: \subsecidx{vecmin}$(x)$: if $x$ is a vector or a matrix, returns the minimum
! 294: of the elements of $x$, otherwise returns a copy of $x$. Returns $+\infty$
! 295: in the form of $2^{31}-1$ (or $2^{63}-1$ for 64-bit machines) if $x$ is empty.
! 296:
! 297: \syn{vecmin}{x}.
! 298:
! 299: \section{Conversions and similar elementary functions or commands}
! 300: \label{se:conversion}
! 301:
! 302: \noindent
! 303: Many of the conversion functions are rounding or truncating operations. In
! 304: this case, if the argument is a rational function, the result is the
! 305: Euclidean quotient of the numerator by the denominator, and if the argument
! 306: is a vector or a matrix, the operation is done componentwise. This will not
! 307: be restated for every function.
! 308:
! 309: \subsecidx{List}$({x=[\,]})$: transforms a (row or column) vector $x$
! 310: into a list. The only other way to create a \typ{LIST} is to use the
! 311: function \kbd{listcreate}.
! 312:
! 313: This is useless in library mode.
! 314:
! 315: \subsecidx{Mat}$({x=[\,]})$: transforms the object $x$ into a matrix.
! 316: If $x$ is not a vector or a matrix, this creates a $1\times 1$ matrix.
! 317: If $x$ is a row (resp. column) vector, this creates a 1-row (resp.
! 318: 1-column) matrix. If $x$ is already a matrix, a copy of $x$ is created.
! 319:
! 320: This function can be useful in connection with the function \kbd{concat}
! 321: (see there).
! 322:
! 323: \syn{gtomat}{x}.
! 324:
! 325: \subsecidx{Mod}$(x,y,\{\fl=0\})$:\label{se:Mod} creates the PARI object
! 326: $(x \mod y)$, i.e.~an integermod or a polmod. $y$ must be an integer or a
! 327: polynomial. If $y$ is an integer, $x$ must be an integer, a rational
! 328: number, or a $p$-adic number compatible with the modulus $y$. If $y$ is a
! 329: polynomial, $x$ must be a scalar (which is not a polmod), a polynomial, a
! 330: rational function, or a power series.
! 331:
! 332: This function is not the same as $x$ \kbd{\%} $y$, the result of which is an
! 333: integer or a polynomial.
! 334:
! 335: If $\fl$ is equal to $1$, the modulus of the created result is put on the
! 336: heap and not on the stack, and hence becomes a permanent copy which cannot be
! 337: erased later by garbage collecting (see \secref{se:garbage}). Functions
! 338: will operate faster on such objects and memory consumption will be lower.
! 339: On the other hand, care should be taken to avoid creating too many such
! 340: objects.
! 341:
! 342: Under GP, the same effect can be obtained by assigning the object to a GP
! 343: variable (the value of which is a permanent object for the duration of the
! 344: relevant library function call, and is treated as such). This value is
! 345: subject to garbage collection, since it will be deleted when the value
! 346: changes. This is preferable and the above flag is only retained for
! 347: compatibility reasons (it can still be useful in library mode).
! 348:
! 349: \syn{Mod0}{x,y,\fl}. Also available are
! 350:
! 351: $\bullet$ for $\fl=1$: $\teb{gmodulo}(x,y)$.
! 352:
! 353: $\bullet$ for $\fl=0$: $\teb{gmodulcp}(x,y)$.
! 354:
! 355: \subsecidx{Pol}$(x,\{v=x\})$: transforms the object $x$ into a polynomial with
! 356: main variable $v$. If $x$ is a scalar, this gives a constant polynomial. If
! 357: $x$ is a power series, the effect is identical to \kbd{truncate} (see there),
! 358: i.e.~it chops off the $O(X^k)$. If $x$ is a vector, this function creates
! 359: the polynomial whose coefficients are given in $x$, with $x[1]$ being the
! 360: leading coefficient (which can be zero).
! 361:
! 362: Warning: this is \var{not} a substitution function. It is intended to be
! 363: quick and dirty. So if you try \kbd{Pol(a,y)} on the polynomial \kbd{a = x+y},
! 364: you will get \kbd{y+y}, which is not a valid PARI object.
! 365:
! 366: \syn{gtopoly}{x,v}, where $v$ is a variable number.
! 367:
! 368: \subsecidx{Polrev}$(x,\{v=x\})$: transform the object $x$ into a polynomial
! 369: with main variable $v$. If $x$ is a scalar, this gives a constant polynomial.
! 370: If $x$ is a power series, the effect is identical to \kbd{truncate} (see
! 371: there), i.e.~it chops off the $O(X^k)$. If $x$ is a vector, this function
! 372: creates the polynomial whose coefficients are given in $x$, with $x[1]$ being
! 373: the constant term. Note that this is the reverse of \kbd{Pol} if $x$ is a
! 374: vector, otherwise it is identical to \kbd{Pol}.
! 375:
! 376: \syn{gtopolyrev}{x,v}, where $v$ is a variable number.
! 377:
! 378: \subsecidx{Qfb}$(a,b,c,\{D=0.\})$: creates the binary quadratic form
! 379: $ax^2+bxy+cy^2$. If $b^2-4ac>0$, initialize \idx{Shanks}' distance
! 380: function to $D$.
! 381:
! 382: \syn{Qfb0}{a,b,c,D,\var{prec}}. Also available are
! 383: $\teb{qfi}(a,b,c)$ (when $b^2-4ac<0$), and
! 384: $\teb{qfr}(a,b,c,d)$ (when $b^2-4ac>0$).\sidx{binary quadratic form}
! 385:
! 386: \subsecidx{Ser}$(x,\{v=x\})$: transforms the object $x$ into a power series
! 387: with main variable $v$ ($x$ by default). If $x$ is a scalar, this gives a
! 388: constant power series with precision given by the default \kbd{serieslength}
! 389: (corresponding to the C global variable \kbd{precdl}). If $x$ is a
! 390: polynomial, the precision is the greatest of \kbd{precdl} and the degree of
! 391: the polynomial. If $x$ is a vector, the precision is similarly given, and the
! 392: coefficients of the vector are understood to be the coefficients of the power
! 393: series starting from the constant term (i.e.~the reverse of the function
! 394: \kbd{Pol}).
! 395:
! 396: The warning given for \kbd{Pol} applies here: this is not a substitution
! 397: function.
! 398:
! 399: \syn{gtoser}{x,v}, where $v$ is a variable number (i.e.~a C integer).
! 400:
! 401: \subsecidx{Set}$(\{x=[\,]\})$: converts $x$ into a set, i.e.~into a row vector
! 402: with strictly increasing entries. $x$ can be of any type, but is most useful
! 403: when $x$ is already a vector. The components of $x$ are put in canonical form
! 404: (type \typ{STR}) so as to be easily sorted. To recover an ordinary \kbd{GEN}
! 405: from such an element, you can apply \tet{eval} to it.
! 406:
! 407: \syn{gtoset}{x}.
! 408:
! 409: \subsecidx{Str}$(\{x=\hbox{\kbd{""}}\},\{\fl=0\})$: converts $x$ into a
! 410: character string (type \typ{STR}, the empty string if $x$ is omitted). To
! 411: recover an ordinary \kbd{GEN} from a string, apply \kbd{eval} to it. The
! 412: arguments of \kbd{Str} are evaluated in string context (see
! 413: \secref{se:strings}). If \fl\ is set, treat $x$ as a filename and perform
! 414: \idx{environment expansion} on the string. This feature can be used to read
! 415: \idx{environment variable} values.
! 416:
! 417: \bprog
! 418: ? i = 1; Str("x" i)
! 419: %1 = "x1"
! 420: ? eval(%)
! 421: %2 = x1;
! 422: ? Str("$HOME", 1)
! 423: %3 = "/home/pari"
! 424: @eprog
! 425:
! 426: \syn{strtoGENstr}{x,\fl}. This function is mostly useless in library mode. Use
! 427: the pair \tet{strtoGEN}/\tet{GENtostr} to convert between \kbd{char*} and
! 428: \kbd{GEN}.
! 429:
! 430: \subsecidx{Vec}$({x=[\,]})$: transforms the object $x$ into a row vector.
! 431: The vector will be with one component only, except when $x$ is a
! 432: vector/matrix or a quadratic form (in which case the resulting vector is
! 433: simply the initial object considered as a row vector), a character string
! 434: (a vector of individual characters is returned), but more importantly when
! 435: $x$ is a polynomial or a power series. In the case of a polynomial, the
! 436: coefficients of the vector start with the leading coefficient of the
! 437: polynomial, while for power series only the significant coefficients are
! 438: taken into account, but this time by increasing order of degree.
! 439:
! 440: \syn{gtovec}{x}.
! 441:
! 442: \subsecidx{Vecsmall}$({x=[\,]})$: transforms the object $x$ into a row
! 443: vector of type \typ{VECSMALL}. This acts as \kbd{Vec}, but only on a
! 444: limited set of objects (the result must be representable as a vector of small
! 445: integers). In particular, polynomials and power series are forbidden.
! 446:
! 447: \syn{gtovecsmall}{x}.
! 448:
! 449: \subsecidx{binary}$(x)$: outputs the vector of the binary digits of $|x|$.
! 450: Here $x$ can be an integer, a real number (in which case the result has two
! 451: components, one for the integer part, one for the fractional part) or a
! 452: vector/matrix.
! 453:
! 454: \syn{binaire}{x}.
! 455:
! 456: \subsecidx{bitand}$(x,y)$: bitwise \tet{and}\sidx{bitwise and} of two
! 457: integers $x$ and $y$, that is the integer
! 458: $$\sum (x_i~\kbd{and}~y_i) 2^i$$
! 459:
! 460: Negative numbers behave as if modulo a huge power of $2$.
! 461:
! 462: \syn{gbitand}{x,y}.
! 463:
! 464: \subsecidx{bitneg}$(x,\{n=-1\})$: \idx{bitwise negation} of an integer $x$,
! 465: truncated to $n$ bits, that is the integer
! 466: $$\sum_{i=0}^n \kbd{not}(x_i) 2^i$$
! 467: The special case $n=-1$ means no truncation: an infinite sequence of
! 468: leading $1$ is then represented as a negative number.
! 469:
! 470: Negative numbers behave as if modulo a huge power of $2$.
! 471:
! 472: \syn{gbitneg}{x}.
! 473:
! 474: \subsecidx{bitnegimply}$(x,y)$: bitwise negated imply of two integers $x$
! 475: and $y$ (or \kbd{not} $(x \Rightarrow y)$), that is the integer
! 476: $$\sum (x_i~\kbd{and not}(y_i)) 2^i$$
! 477:
! 478: Negative numbers behave as if modulo a huge power of $2$.
! 479:
! 480: \syn{gbitnegimply}{x,y}.
! 481:
! 482: \subsecidx{bitor}$(x,y)$: bitwise (inclusive) \tet{or}\sidx{bitwise
! 483: inclusive or} of two integers $x$ and $y$, that is the integer
! 484: $$\sum (x_i~\kbd{or}~y_i) 2^i$$
! 485:
! 486: Negative numbers behave as if modulo a huge power of $2$.
! 487:
! 488: \syn{gbitor}{x,y}.
! 489:
! 490: \subsecidx{bittest}$(x,n)$: outputs the $n^{\text{th}}$ bit of $|x|$ starting
! 491: from the right (i.e.~the coefficient of $2^n$ in the binary expansion of $x$).
! 492: The result is 0 or 1. To extract several bits at once as a vector, pass a
! 493: vector for $n$.
! 494:
! 495: \syn{bittest}{x,n}, where $n$ and the result are \kbd{long}s.
! 496:
! 497: \subsecidx{bitxor}$(x,y)$: bitwise (exclusive) \tet{or}\sidx{bitwise
! 498: exclusive or} of two integers $x$ and $y$, that is the integer
! 499: $$\sum (x_i~\kbd{xor}~y_i) 2^i$$
! 500: Negative numbers behave as if modulo a huge power of $2$.
! 501:
! 502: \syn{gbitxor}{x,y}.
! 503:
! 504: \subsecidx{ceil}$(x)$: ceiling of $x$. When $x$ is in $\R$,
! 505: the result is the smallest integer greater than or equal to $x$. Applied to a
! 506: rational function, $\kbd{ceil}(x)$ returns the euclidian quotient of the
! 507: numerator by the denominator.
! 508:
! 509: \syn{gceil}{x}.
! 510:
! 511: \subsecidx{centerlift}$(x,\{v\})$: lifts an element $x=a \bmod n$ of $\Z/n\Z$
! 512: to $a$ in $\Z$, and similarly lifts a polmod to a polynomial. This is the
! 513: same as \tet{lift} except that in the particular case of elements of
! 514: $\Z/n\Z$, the lift $y$ is such that $-n/2<y\le n/2$. If $x$ is of type
! 515: fraction, complex, quadratic, polynomial, power series, rational function,
! 516: vector or matrix, the lift is done for each coefficient. Reals are forbidden.
! 517:
! 518: \syn{centerlift0}{x,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded
! 519: as $-1$. Also available is \teb{centerlift}$(x)$ = \kbd{centerlift0($x$,-1)}.
! 520:
! 521: \subsecidx{changevar}$(x,y)$: creates a copy of the object $x$ where its
! 522: variables are modified according to the permutation specified by the vector
! 523: $y$. For example, assume that the variables have been introduced in the
! 524: order \kbd{x}, \kbd{a}, \kbd{b}, \kbd{c}. Then, if $y$ is the vector
! 525: \kbd{[x,c,a,b]}, the variable \kbd{a} will be replaced by \kbd{c}, \kbd{b} by
! 526: \kbd{a}, and \kbd{c} by \kbd{b}, \kbd{x} being unchanged. Note that the
! 527: permutation must be completely specified, e.g.~\kbd{[c,a,b]} would not work,
! 528: since this would replace \kbd{x} by \kbd{c}, and leave \kbd{a} and \kbd{b}
! 529: unchanged (as well as \kbd{c} which is the fourth variable of the initial
! 530: list). In particular, the new variable names must be distinct.
! 531:
! 532: \syn{changevar}{x,y}.
! 533:
! 534: \subsec{components of a PARI object}:
! 535:
! 536: There are essentially three ways to extract the \idx{components} from a PARI
! 537: object.
! 538:
! 539: The first and most general, is the function $\teb{component}(x,n)$ which
! 540: extracts the $n^{\text{th}}$-component of $x$. This is to be understood as
! 541: follows: every PARI type has one or two initial \idx{code words}. The
! 542: components are counted, starting at 1, after these code words. In particular
! 543: if $x$ is a vector, this is indeed the $n^{\text{th}}$-component of $x$, if
! 544: $x$ is a matrix, the $n^{\text{th}}$ column, if $x$ is a polynomial, the
! 545: $n^{\text{th}}$ coefficient (i.e.~of degree $n-1$), and for power series, the
! 546: $n^{\text{th}}$ significant coefficient. The use of the function
! 547: \kbd{component} implies the knowledge of the structure of the different PARI
! 548: types, which can be recalled by typing \b{t} under GP.
! 549:
! 550: \syn{compo}{x,n}, where $n$ is a \kbd{long}.
! 551:
! 552: The two other methods are more natural but more restricted. The function
! 553: \funs{polcoeff}{x,n} gives the coefficient of degree $n$ of the polynomial
! 554: or power series $x$, with respect to the main variable of $x$ (to check
! 555: variable ordering, or to change it, use the function \tet{reorder}, see
! 556: \secref{se:reorder}). In particular if $n$ is less than the valuation of
! 557: $x$ or in the case of a polynomial, greater than the degree, the result is
! 558: zero (contrary to \kbd{compo} which would send an error message). If $x$ is
! 559: a power series and $n$ is greater than the largest significant degree, then
! 560: an error message is issued.
! 561:
! 562: For greater flexibility, vector or matrix types are also accepted for $x$,
! 563: and the meaning is then identical with that of \kbd{compo}.
! 564:
! 565: Finally note that a scalar type is considered by \kbd{polcoeff} as a
! 566: polynomial of degree zero.
! 567:
! 568: \syn{truecoeff}{x,n}.
! 569:
! 570: The third method is specific to vectors or matrices under GP. If $x$ is a
! 571: (row or column) vector, then \tet{x[n]} represents the $n^{\text{th}}$
! 572: component of $x$, i.e.~\kbd{compo(x,n)}. It is more natural and shorter to
! 573: write. If $x$ is a matrix, \tet{x[m,n]} represents the coefficient of
! 574: row \kbd{m} and column \kbd{n} of the matrix, \tet{x[m,]} represents
! 575: the $m^{\text{th}}$ \var{row} of $x$, and \tet{x[,n]} represents
! 576: the $n^{\text{th}}$ \var{column} of $x$.
! 577:
! 578: Finally note that in library mode, the macros \teb{coeff} and \teb{mael}
! 579: are available to deal with the non-recursivity of the \kbd{GEN} type from the
! 580: compiler's point of view. See the discussion on typecasts in Chapter 4.
! 581:
! 582: \subsecidx{conj}$(x)$: conjugate of $x$. The meaning of this
! 583: is clear, except that for real quadratic numbers, it means conjugation in the
! 584: real quadratic field. This function has no effect on integers, reals,
! 585: integermods, fractions or $p$-adics. The only forbidden type is polmod
! 586: (see \kbd{conjvec} for this).
! 587:
! 588: \syn{gconj}{x}.
! 589:
! 590: \subsecidx{conjvec}$(x)$: conjugate vector representation of $x$. If $x$ is a
! 591: polmod, equal to \kbd{Mod}$(a,q)$, this gives a vector of length
! 592: $\text{degree}(q)$ containing the complex embeddings of the polmod if $q$ has
! 593: integral or rational coefficients, and the conjugates of the polmod if $q$
! 594: has some integermod coefficients. The order is the same as that of the
! 595: \kbd{polroots} functions. If $x$ is an integer or a rational number, the
! 596: result is~$x$. If $x$ is a (row or column) vector, the result is a matrix
! 597: whose columns are the conjugate vectors of the individual elements of $x$.
! 598:
! 599: \syn{conjvec}{x,\var{prec}}.
! 600:
! 601: \subsecidx{denominator}$(x)$: lowest denominator of $x$. The meaning of this
! 602: is clear when $x$ is a rational number or function. When $x$ is an integer
! 603: or a polynomial, the result is equal to $1$. When $x$ is a vector or a matrix,
! 604: the lowest common denominator of the components of $x$ is computed. All other
! 605: types are forbidden.
! 606:
! 607: \syn{denom}{x}.
! 608:
! 609: \subsecidx{floor}$(x)$: floor of $x$. When $x$ is in $\R$, the result is the
! 610: largest integer smaller than or equal to $x$. Applied to a rational function,
! 611: $\kbd{floor}(x)$ returns the euclidian quotient of the numerator by the
! 612: denominator.
! 613:
! 614: \syn{gfloor}{x}.
! 615:
! 616: \subsecidx{frac}$(x)$: fractional part of $x$. Identical to
! 617: $x-\text{floor}(x)$. If $x$ is real, the result is in $[0,1[$.
! 618:
! 619: \syn{gfrac}{x}.
! 620:
! 621: \subsecidx{imag}$(x)$: imaginary part of $x$. When
! 622: $x$ is a quadratic number, this is the coefficient of $\omega$ in
! 623: the ``canonical'' integral basis $(1,\omega)$.
! 624:
! 625: \syn{gimag}{x}.
! 626:
! 627: \subsecidx{length}$(x)$: number of non-code words in $x$ really used (i.e.~the
! 628: effective length minus 2 for integers and polynomials). In particular,
! 629: the degree of a polynomial is equal to its length minus 1. If $x$ has type
! 630: \typ{STR}, output number of letters.
! 631:
! 632: \syn{glength}{x} and the result is a C long.
! 633:
! 634: \subsecidx{lift}$(x,\{v\})$: lifts an element $x=a \bmod n$ of $\Z/n\Z$ to
! 635: $a$ in $\Z$, and similarly lifts a polmod to a polynomial if $v$ is omitted.
! 636: Otherwise, lifts only polmods with main variable $v$ (if $v$ does not occur
! 637: in $x$, lifts only intmods). If $x$ is of type fraction, complex, quadratic,
! 638: polynomial, power series, rational function, vector or matrix, the lift is
! 639: done for each coefficient. For $p$-adics, this routine acts as
! 640: \tet{truncate}. It is not allowed to have $x$ of type \typ{REAL}.
! 641:
! 642: \syn{lift0}{x,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded as
! 643: $-1$. Also available is \teb{lift}$(x)$ = \kbd{lift0($x$,-1)}.
! 644:
! 645: \subsecidx{norm}$(x)$: algebraic norm of $x$, i.e.~the product of $x$ with
! 646: its conjugate (no square roots are taken), or conjugates for polmods. For
! 647: vectors and matrices, the norm is taken componentwise and hence is not the
! 648: $L^2$-norm (see \kbd{norml2}). Note that the norm of an element of
! 649: $\R$ is its square, so as to be compatible with the complex norm.
! 650:
! 651: \syn{gnorm}{x}.
! 652:
! 653: \subsecidx{norml2}$(x)$: square of the $L^2$-norm of $x$. $x$ must
! 654: be a (row or column) vector.
! 655:
! 656: \syn{gnorml2}{x}.
! 657:
! 658: \subsecidx{numerator}$(x)$: numerator of $x$. When $x$ is a rational number
! 659: or function, the meaning is clear. When $x$ is an integer or a polynomial,
! 660: the result is $x$ itself. When $x$ is a vector or a matrix, then
! 661: \kbd{numerator(x)} is defined to be \kbd{denominator(x)*x}. All other types
! 662: are forbidden.
! 663:
! 664: \syn{numer}{x}.
! 665:
! 666: \subsecidx{numtoperm}$(n,k)$: generates the $k$-th permutation (as a
! 667: row vector of length $n$) of the numbers $1$ to $n$. The number $k$ is taken
! 668: modulo $n!\,$, i.e.~inverse function of \tet{permtonum}.
! 669:
! 670: \syn{numtoperm}{n,k}, where $n$ is a \kbd{long}.
! 671:
! 672: \subsecidx{padicprec}$(x,p)$: absolute $p$-adic precision of the object $x$.
! 673: This is the minimum precision of the components of $x$. The result is
! 674: \kbd{VERYBIGINT} ($2^{31}-1$ for 32-bit machines or $2^{63}-1$ for 64-bit
! 675: machines) if $x$ is an exact object.
! 676:
! 677: \syn{padicprec}{x,p} and the result is a \kbd{long}
! 678: integer.
! 679:
! 680: \subsecidx{permtonum}$(x)$: given a permutation $x$ on $n$ elements,
! 681: gives the number $k$ such that $x=\kbd{numtoperm(n,k)}$, i.e.~inverse
! 682: function of \tet{numtoperm}.
! 683:
! 684: \syn{permtonum}{x}.
! 685:
! 686: \subsecidx{precision}$(x,\{n\})$: gives the precision in decimal digits of the
! 687: PARI object $x$. If $x$ is an exact object, the largest single precision
! 688: integer is returned. If $n$ is not omitted, creates a new object equal to $x$
! 689: with a new precision $n$. This is to be understood as follows:
! 690:
! 691: For exact types, no change. For $x$ a vector or a matrix, the operation
! 692: is done componentwise.
! 693:
! 694: For real $x$, $n$ is the number of desired significant \var{decimal} digits.
! 695: If $n$ is smaller than the precision of $x$, $x$ is truncated, otherwise $x$
! 696: is extended with zeros.
! 697:
! 698: For $x$ a $p$-adic or a power series, $n$ is the desired number of
! 699: significant $p$-adic or $X$-adic digits, where $X$ is the main variable of
! 700: $x$.
! 701:
! 702: Note that the function \kbd{precision} never changes the type of the result.
! 703: In particular it is not possible to use it to obtain a polynomial from a
! 704: power series. For that, see \kbd{truncate}.
! 705:
! 706: \syn{precision0}{x,n}, where $n$ is a \kbd{long}. Also available are
! 707: $\teb{ggprecision}(x)$ (result is a \kbd{GEN}) and $\teb{gprec}(x,n)$, where
! 708: $n$ is a \kbd{long}.
! 709:
! 710: \subsecidx{random}$(\{N=2^{31}\})$: gives a random integer between 0 and
! 711: $N-1$. $N$ can be arbitrary large. This is an internal PARI function and does
! 712: not depend on the system's random number generator. Note that the resulting
! 713: integer is obtained by means of linear congruences and will not be well
! 714: distributed in arithmetic progressions.
! 715:
! 716: \syn{genrand}{N}.
! 717:
! 718: \subsecidx{real}$(x)$: real part of $x$. In the case where $x$ is a quadratic
! 719: number, this is the coefficient of $1$ in the ``canonical'' integral basis
! 720: $(1,\omega)$.
! 721:
! 722: \syn{greal}{x}.
! 723:
! 724: \subsecidx{round}$(x,\{\&e\})$: If $x$ is in $\R$, rounds $x$ to the nearest
! 725: integer and sets $e$ to the number of error bits, that is the binary exponent
! 726: of the difference between the original and the rounded value (the
! 727: ``fractional part''). If the exponent of $x$ is too large compared to its
! 728: precision (i.e.~$e>0$), the result is undefined and an error occurs if $e$
! 729: was not given.
! 730:
! 731: \misctitle{Important remark:} note that, contrary to the other truncation
! 732: functions, this function operates on every coefficient at every level of a
! 733: PARI object. For example
! 734: $$\text{truncate}\left(\dfrac{2.4*X^2-1.7}{X}\right)=2.4*X,$$ whereas
! 735: $$\text{round}\left(\dfrac{2.4*X^2-1.7}{X}\right)=\dfrac{2*X^2-2}{X}.$$
! 736: An important use of \kbd{round} is to get exact results after a long
! 737: approximate computation, when theory tells you that the coefficients
! 738: must be integers.
! 739:
! 740: \syn{grndtoi}{x,\&e}, where $e$ is a \kbd{long} integer. Also available is
! 741: $\teb{ground}(x)$.
! 742:
! 743: \subsecidx{simplify}$(x)$: this function tries to simplify the object $x$ as
! 744: much as it can. The simplifications do not concern rational functions (which
! 745: PARI automatically tries to simplify), but type changes. Specifically, a
! 746: complex or quadratic number whose imaginary part is exactly equal to 0
! 747: (i.e.~not a real zero) is converted to its real part, and a polynomial of
! 748: degree zero is converted to its constant term. For all types, this of course
! 749: occurs recursively. This function is useful in any case, but in particular
! 750: before the use of arithmetic functions which expect integer arguments, and
! 751: not for example a complex number of 0 imaginary part and integer real part
! 752: (which is however printed as an integer).
! 753:
! 754: \syn{simplify}{x}.
! 755:
! 756: \subsecidx{sizebyte}$(x)$: outputs the total number of bytes occupied by the
! 757: tree representing the PARI object $x$.
! 758:
! 759: \syn{taille2}{x} which returns a \kbd{long}. The
! 760: function \teb{taille} returns the number of \var{words} instead.
! 761:
! 762: \subsecidx{sizedigit}$(x)$: outputs a quick bound for the number of decimal
! 763: digits of (the components of) $x$, off by at most $1$. If you want the
! 764: exact value, you can use \kbd{length(Str(x))}, which is much slower.
! 765:
! 766: \syn{sizedigit}{x} which returns a \kbd{long}.
! 767:
! 768: \subsecidx{truncate}$(x,\{\&e\})$: truncates $x$ and sets $e$ to the number of
! 769: error bits. When $x$ is in $\R$, this means that the part after the decimal
! 770: point is chopped away, $e$ is the binary exponent of the difference between
! 771: the original and the truncated value (the ``fractional part''). If the
! 772: exponent of $x$ is too large compared to its precision (i.e.~$e>0$), the
! 773: result is undefined and an error occurs if $e$ was not given. The function
! 774: applies componentwise on vector / matrices; $e$ is then the maximal number of
! 775: error bits. If $x$ is a rational function, the result is the ``integer part''
! 776: (Euclidean quotient of numerator by denominator) and $e$ is not set.
! 777:
! 778: Note a very special use of \kbd{truncate}: when applied to a power series, it
! 779: transforms it into a polynomial or a rational function with denominator
! 780: a power of $X$, by chopping away the $O(X^k)$. Similarly, when applied to
! 781: a $p$-adic number, it transforms it into an integer or a rational number
! 782: by chopping away the $O(p^k)$.
! 783:
! 784: \syn{gcvtoi}{x,\&e}, where $e$ is a \kbd{long} integer. Also available is
! 785: \teb{gtrunc}$(x)$.
! 786:
! 787: \subsecidx{valuation}$(x,p)$:\label{se:valuation} computes the highest
! 788: exponent of $p$ dividing $x$. If $p$ is of type integer, $x$ must be an
! 789: integer, an integermod whose modulus is divisible by $p$, a fraction, a
! 790: $q$-adic number with $q=p$, or a polynomial or power series in which case the
! 791: valuation is the minimum of the valuation of the coefficients.
! 792:
! 793: If $p$ is of type polynomial, $x$ must be of type polynomial or rational
! 794: function, and also a power series if $x$ is a monomial. Finally, the
! 795: valuation of a vector, complex or quadratic number is the minimum of the
! 796: component valuations.
! 797:
! 798: If $x=0$, the result is \kbd{VERYBIGINT} ($2^{31}-1$ for 32-bit machines or
! 799: $2^{63}-1$ for 64-bit machines) if $x$ is an exact object. If $x$ is a
! 800: $p$-adic numbers or power series, the result is the exponent of the zero.
! 801: Any other type combinations gives an error.
! 802:
! 803: \syn{ggval}{x,p}, and the result is a \kbd{long}.
! 804:
! 805: \subsecidx{variable}$(x)$: gives the main variable of the object $x$, and
! 806: $p$ if $x$ is a $p$-adic number. Gives an error if $x$ has no variable
! 807: associated to it. Note that this function is useful only in GP, since in
! 808: library mode the function \kbd{gvar} is more appropriate.
! 809:
! 810: \syn{gpolvar}{x}. However, in library mode, this function should not be used.
! 811: Instead, test whether $x$ is a $p$-adic (type \typ{PADIC}), in which case $p$
! 812: is in $x[2]$, or call the function $\key{gvar}(x)$ which returns the variable
! 813: \var{number} of $x$ if it exists, \kbd{BIGINT} otherwise.
! 814:
! 815: \section{Transcendental functions}\label{se:trans}
! 816:
! 817: As a general rule, which of course in some cases may have exceptions,
! 818: transcendental functions operate in the following way:
! 819:
! 820: $\bullet$ If the argument is either an integer, a real, a rational, a complex
! 821: or a quadratic number, it is, if necessary, first converted to a real (or
! 822: complex) number using the current \idx{precision} held in the default
! 823: \kbd{realprecision}. Note that only exact arguments are converted, while
! 824: inexact arguments such as reals are not.
! 825:
! 826: Under GP this is transparent to the user, but when programming in library
! 827: mode, care must be taken to supply a meaningful parameter \var{prec} as the
! 828: last argument of the function if the first argument is an exact object.
! 829: This parameter is ignored if the argument is inexact.
! 830:
! 831: Note that in library mode the precision argument \var{prec} is a word
! 832: count including codewords, i.e.~represents the length in words of a real
! 833: number, while under GP the precision (which is changed by the metacommand
! 834: \b{p} or using \kbd{default(realprecision,...)}) is the number of significant
! 835: decimal digits.
! 836:
! 837: Note that some accuracies attainable on 32-bit machines cannot be attained
! 838: on 64-bit machines for parity reasons. For example the default GP accuracy
! 839: is 28 decimal digits on 32-bit machines, corresponding to \var{prec} having
! 840: the value 5, but this cannot be attained on 64-bit machines.\smallskip
! 841:
! 842: After possible conversion, the function is computed. Note that even if the
! 843: argument is real, the result may be complex (e.g.~$\text{acos}(2.0)$ or
! 844: $\text{acosh}(0.0)$). Note also that the principal branch is always chosen.
! 845:
! 846: $\bullet$ If the argument is an integermod or a $p$-adic, at present only a
! 847: few functions like \kbd{sqrt} (square root), \kbd{sqr} (square), \kbd{log},
! 848: \kbd{exp}, powering, \kbd{teichmuller} (Teichm\"uller character) and
! 849: \kbd{agm} (arithmetic-geometric mean) are implemented.
! 850:
! 851: Note that in the case of a $2$-adic number, $\kbd{sqr}(x)$ may not be
! 852: identical to $x*x$: for example if $x = 1+O(2^5)$ and $y = 1+O(2^5)$ then
! 853: $x*y = 1+O(2^5)$ while $\kbd{sqr}(x) = 1+O(2^6)$. Here, $x * x$ yields the
! 854: same result as $\kbd{sqr}(x)$ since the two operands are known to be {\it
! 855: identical}. The same statement holds true for $p$-adics raised to the power
! 856: $n$, where $v_p(n) > 0$.
! 857:
! 858: \misctitle{Remark:} note that if we wanted to be strictly consistent with
! 859: the PARI philosophy, we should have $x*y = (4 \mod 8)$ and $\kbd{sqr}(x) =
! 860: (4 \mod 32)$ when both $x$ and $y$ are congruent to $2$ modulo $4$.
! 861: However, since integermod is an exact object, PARI assumes that the modulus
! 862: must not change, and the result is hence $(0\, \mod\, 4)$ in both cases. On
! 863: the other hand, $p$-adics are not exact objects, hence are treated
! 864: differently.
! 865:
! 866: $\bullet$ If the argument is a polynomial, power series or rational function,
! 867: it is, if necessary, first converted to a power series using the current
! 868: precision held in the variable \tet{precdl}. Under GP this again is
! 869: transparent to the user. When programming in library mode, however, the
! 870: global variable \kbd{precdl} must be set before calling the function if the
! 871: argument has an exact type (i.e.~not a power series). Here \kbd{precdl} is
! 872: not an argument of the function, but a global variable.
! 873:
! 874: Then the Taylor series expansion of the function around $X=0$ (where $X$ is
! 875: the main variable) is computed to a number of terms depending on the number
! 876: of terms of the argument and the function being computed.
! 877:
! 878: $\bullet$ If the argument is a vector or a matrix, the result is the
! 879: componentwise evaluation of the function. In particular, transcendental
! 880: functions on square matrices, which are not implemented in the present
! 881: version \vers\ (see Appendix~B however), will have a slightly different name
! 882: if they are implemented some day.
! 883:
! 884: \subseckbd{\pow}: If $y$ is not of type integer, \kbd{x\pow y} has the same
! 885: effect as \kbd{exp(y*ln(x))}. It can be applied to $p$-adic numbers as
! 886: well as to the more usual types.\sidx{powering}
! 887:
! 888: \syn{gpow}{x,y,\var{prec}}.
! 889:
! 890: \subsecidx{Euler}: Euler's constant $0.57721\cdots$. Note that \kbd{Euler}
! 891: is one of the few special reserved names which cannot be used for variables
! 892: (the others are \kbd{I} and \kbd{Pi}, as well as all function names).
! 893: \label{se:euler}
! 894:
! 895: \syn{mpeuler}{\var{prec}} where $\var{prec}$ \var{must} be given. Note that
! 896: this creates $\gamma$ on the PARI stack, but a copy is also created on the
! 897: heap for quicker computations next time the function is called.
! 898:
! 899: \subsecidx{I}: the complex number $\sqrt{-1}$.
! 900:
! 901: The library syntax is the global variable \kbd{gi} (of type \kbd{GEN}).
! 902:
! 903: \subsecidx{Pi}: the constant $\pi$ ($3.14159\cdots$).\label{se:pi}
! 904:
! 905: \syn{mppi}{\var{prec}} where $\var{prec}$ \var{must} be given. Note that this
! 906: creates $\pi$ on the PARI stack, but a copy is also created on the heap for
! 907: quicker computations next time the function is called.
! 908:
! 909: \subsecidx{abs}$(x)$: absolute value of $x$ (modulus if $x$ is complex).
! 910: Power series and rational functions are not allowed. Contrary to most
! 911: transcendental functions, an exact argument is \var{not} converted to a real
! 912: number before applying \kbd{abs} and an exact result is returned if possible.
! 913: \bprog
! 914: ? abs(-1)
! 915: %1 = 1
! 916: ? abs(3/7 + 4/7*I)
! 917: %2 = 5/7
! 918: ? abs(1 + I)
! 919: %3 = 1.414213562373095048801688724
! 920: @eprog
! 921: \noindent If $x$ is a polynomial, returns $-x$ if the leading coefficient is
! 922: real and negative else returns $x$. For a power series, the constant
! 923: coefficient is considered instead.
! 924:
! 925: \syn{gabs}{x,\var{prec}}.
! 926:
! 927: \subsecidx{acos}$(x)$: principal branch of $\text{cos}^{-1}(x)$,
! 928: i.e.~such that $\text{Re(acos}(x))\in [0,\pi]$. If
! 929: $x\in \R$ and $|x|>1$, then $\text{acos}(x)$ is complex.
! 930:
! 931: \syn{gacos}{x,\var{prec}}.
! 932:
! 933: \subsecidx{acosh}$(x)$: principal branch of $\text{cosh}^{-1}(x)$,
! 934: i.e.~such that $\text{Im(acosh}(x))\in [0,\pi]$. If
! 935: $x\in \R$ and $x<1$, then $\text{acosh}(x)$ is complex.
! 936:
! 937: \syn{gach}{x,\var{prec}}.
! 938:
! 939: \subsecidx{agm}$(x,y)$: arithmetic-geometric mean of $x$ and $y$. In the
! 940: case of complex or negative numbers, the principal square root is always
! 941: chosen. $p$-adic or power series arguments are also allowed. Note that
! 942: a $p$-adic agm exists only if $x/y$ is congruent to 1 modulo $p$ (modulo
! 943: 16 for $p=2$). $x$ and $y$ cannot both be vectors or matrices.
! 944:
! 945: \syn{agm}{x,y,\var{prec}}.
! 946:
! 947: \subsecidx{arg}$(x)$: argument of the complex number $x$, such that
! 948: $-\pi<\text{arg}(x)\le\pi$.
! 949:
! 950: \syn{garg}{x,\var{prec}}.
! 951:
! 952: \subsecidx{asin}$(x)$: principal branch of $\text{sin}^{-1}(x)$, i.e.~such
! 953: that $\text{Re(asin}(x))\in [-\pi/2,\pi/2]$. If $x\in \R$ and $|x|>1$ then
! 954: $\text{asin}(x)$ is complex.
! 955:
! 956: \syn{gasin}{x,\var{prec}}.
! 957:
! 958: \subsecidx{asinh}$(x)$: principal branch of $\text{sinh}^{-1}(x)$, i.e.~such
! 959: that $\text{Im(asinh}(x))\in [-\pi/2,\pi/2]$.
! 960:
! 961: \syn{gash}{x,\var{prec}}.
! 962:
! 963: \subsecidx{atan}$(x)$: principal branch of $\text{tan}^{-1}(x)$, i.e.~such
! 964: that $\text{Re(atan}(x))\in{} ]-\pi/2,\pi/2[$.
! 965:
! 966: \syn{gatan}{x,\var{prec}}.
! 967:
! 968: \subsecidx{atanh}$(x)$: principal branch of $\text{tanh}^{-1}(x)$, i.e.~such
! 969: that $\text{Im(atanh}(x))\in{} ]-\pi/2,\pi/2]$. If $x\in \R$ and $|x|>1$ then
! 970: $\text{atanh}(x)$ is complex.
! 971:
! 972: \syn{gath}{x,\var{prec}}.
! 973:
! 974: \subsecidx{bernfrac}$(x)$: Bernoulli number\sidx{Bernoulli numbers} $B_x$,
! 975: where $B_0=1$, $B_1=-1/2$, $B_2=1/6$,\dots, expressed as a rational number.
! 976: The argument $x$ should be of type integer.
! 977:
! 978: \syn{bernfrac}{x}.
! 979:
! 980: \subsecidx{bernreal}$(x)$: Bernoulli number\sidx{Bernoulli numbers}
! 981: $B_x$, as \kbd{bernfrac}, but $B_x$ is returned as a real number
! 982: (with the current precision).
! 983:
! 984: \syn{bernreal}{x,\var{prec}}.
! 985:
! 986: \subsecidx{bernvec}$(x)$: creates a vector containing, as rational numbers,
! 987: the \idx{Bernoulli numbers} $B_0$, $B_2$,\dots, $B_{2x}$. These Bernoulli
! 988: numbers can then be used as follows. Assume that this vector has been put
! 989: into a variable, say \kbd{bernint}. Then you can define under GP:
! 990: \bprog
! 991: bern(x) =
! 992: {
! 993: if (x == 1, return(-1/2));
! 994: if (x < 0 || x % 2, return(0));
! 995: bernint[x/2+1]
! 996: }
! 997: @eprog
! 998: \noindent and then \kbd{bern(k)} gives the Bernoulli number of index $k$ as a
! 999: rational number, exactly as \kbd{bernreal(k)} gives it as a real number. If
! 1000: you need only a few values, calling \kbd{bernfrac(k)} each time will be much
! 1001: more efficient than computing the huge vector above.
! 1002:
! 1003: \syn{bernvec}{x}.
! 1004:
! 1005: \subsecidx{besseljh}$(n,x)$: $J$-Bessel function of half integral index.
! 1006: More precisely, $\kbd{besseljh}(n,x)$ computes $J_{n+1/2}(x)$ where $n$
! 1007: must be of type integer, and $x$ is any element of $\C$. In the
! 1008: present version \vers, this function is not very accurate when $x$ is
! 1009: small.
! 1010:
! 1011: \syn{jbesselh}{n,x,\var{prec}}.
! 1012:
! 1013: \subsecidx{besselk}$(\var{nu},x,\{\fl=0\})$: $K$-Bessel function of index
! 1014: \var{nu} (which can be complex) and argument $x$. Only real and positive
! 1015: arguments
! 1016: $x$ are allowed in the present version \vers. If $\fl$ is equal to 1,
! 1017: uses another implementation of this function which is often faster.
! 1018:
! 1019: \syn{kbessel}{\var{nu},x,\var{prec}} and
! 1020: $\teb{kbessel2}(\var{nu},x,\var{prec})$ respectively.
! 1021:
! 1022: \subsecidx{cos}$(x)$: cosine of $x$.
! 1023:
! 1024: \syn{gcos}{x,\var{prec}}.
! 1025:
! 1026: \subsecidx{cosh}$(x)$: hyperbolic cosine of $x$.
! 1027:
! 1028: \syn{gch}{x,\var{prec}}.
! 1029:
! 1030: \subsecidx{cotan}$(x)$: cotangent of $x$.
! 1031:
! 1032: \syn{gcotan}{x,\var{prec}}.
! 1033:
! 1034: \subsecidx{dilog}$(x)$: principal branch of the dilogarithm of $x$,
! 1035: i.e.~analytic continuation of the power series $\log_2(x)=\sum_{n\ge1}x^n/n^2$.
! 1036:
! 1037: \syn{dilog}{x,\var{prec}}.
! 1038:
! 1039: \subsecidx{eint1}$(x,\{n\})$: exponential integral
! 1040: $\int_x^\infty \dfrac{e^{-t}}{t}\,dt$ ($x\in\R$)
! 1041:
! 1042: If $n$ is present, outputs the $n$-dimensional vector
! 1043: $[\kbd{eint1}(x),\dots,\kbd{eint1}(nx)]$ ($x \geq 0$). This is faster than
! 1044: repeatedly calling \kbd{eint1($i$ * x)}.
! 1045:
! 1046: \syn{veceint1}{x,n,\var{prec}}. Also available is
! 1047: $\teb{eint1}(x,\var{prec})$.
! 1048:
! 1049: \subsecidx{erfc}$(x)$: complementary error function
! 1050: $(2/\sqrt\pi)\int_x^\infty e^{-t^2}\,dt$.
! 1051:
! 1052: \syn{erfc}{x,\var{prec}}.
! 1053:
! 1054: \subsecidx{eta}$(x,\{\fl=0\})$: \idx{Dedekind}'s $\eta$ function, without the
! 1055: $q^{1/24}$. This means the following: if $x$ is a complex number with positive
! 1056: imaginary part, the result is $\prod_{n=1}^\infty(1-q^n)$, where
! 1057: $q=e^{2i\pi x}$. If $x$ is a power series (or can be converted to a power
! 1058: series) with positive valuation, the result is $\prod_{n=1}^\infty(1-x^n)$.
! 1059:
! 1060: If $\fl=1$ and $x$ can be converted to a complex number (i.e.~is not a power
! 1061: series), computes the true $\eta$ function, including the leading $q^{1/24}$.
! 1062:
! 1063: \syn{eta}{x,\var{prec}}.
! 1064:
! 1065: \subsecidx{exp}$(x)$: exponential of $x$.
! 1066: $p$-adic arguments with positive valuation are accepted.
! 1067:
! 1068: \syn{gexp}{x,\var{prec}}.
! 1069:
! 1070: \subsecidx{gammah}$(x)$: gamma function evaluated at the argument
! 1071: $x+1/2$. When $x$ is an integer, this is much faster than using
! 1072: $\kbd{gamma}(x+1/2)$.
! 1073:
! 1074: \syn{ggamd}{x,\var{prec}}.
! 1075:
! 1076: \subsecidx{gamma}$(x)$: gamma function of $x$. In the present version
! 1077: \vers\ the $p$-adic gamma function is not implemented.
! 1078:
! 1079: \syn{ggamma}{x,\var{prec}}.
! 1080:
! 1081: \subsecidx{hyperu}$(a,b,x)$: $U$-confluent hypergeometric function with
! 1082: parameters $a$ and $b$. The parameters $a$ and $b$ can be complex but
! 1083: the present implementation requires $x$ to be positive.
! 1084:
! 1085: \syn{hyperu}{a,b,x,\var{prec}}.
! 1086:
! 1087: \subsecidx{incgam}$(s,x,{y})$: incomplete gamma function.
! 1088:
! 1089: $x$ must be positive and $s$ real. The result returned is $\int_x^\infty
! 1090: e^{-t}t^{s-1}\,dt$. When $y$ is given, assume (of course without checking!)
! 1091: that $y=\Gamma(s)$. For small $x$, this will tremendously speed up the
! 1092: computation.
! 1093:
! 1094: \syn{incgam}{s,x,\var{prec}} and $\teb{incgam4}(s,x,y,\var{prec})$,
! 1095: respectively. There exist also the functions \teb{incgam1} and
! 1096: \teb{incgam2} which are used for internal purposes.
! 1097:
! 1098: \subsecidx{incgamc}$(s,x)$: complementary incomplete gamma function.
! 1099:
! 1100: The arguments $s$ and $x$ must be positive. The result returned is
! 1101: $\int_0^x e^{-t}t^{s-1}\,dt$, when $x$ is not too large.
! 1102:
! 1103: \syn{incgam3}{s,x,\var{prec}}.
! 1104:
! 1105: \subsecidx{log}$(x,\{\fl=0\})$: principal branch of the natural logarithm of
! 1106: $x$, i.e.~such that $\text{Im(ln}(x))\in{} ]-\pi,\pi]$. The result is complex
! 1107: (with imaginary part equal to $\pi$) if $x\in \R$ and $x<0$.
! 1108:
! 1109: $p$-adic arguments are also accepted for $x$, with the convention that
! 1110: $\ln(p)=0$. Hence in particular $\exp(\ln(x))/x$ will not in general be
! 1111: equal to 1 but to a $(p-1)$-th root of unity (or $\pm1$ if $p=2$)
! 1112: times a power of $p$.
! 1113:
! 1114: If $\fl$ is equal to 1, use an agm formula suggested by Mestre, when $x$ is
! 1115: real, otherwise identical to \kbd{log}.
! 1116:
! 1117: \syn{glog}{x,\var{prec}} or $\teb{glogagm}(x,\var{prec})$.
! 1118:
! 1119: \subsecidx{lngamma}$(x)$: principal branch of the logarithm of the gamma
! 1120: function of $x$. Can have much larger arguments than \kbd{gamma} itself.
! 1121: In the present version \vers, the $p$-adic \kbd{lngamma} function is not
! 1122: implemented.
! 1123:
! 1124: \syn{glngamma}{x,\var{prec}}.
! 1125:
! 1126: \subsecidx{polylog}$(m,x,{\fl=0})$: one of the different polylogarithms,
! 1127: depending on \fl:
! 1128:
! 1129: If $\fl=0$ or is omitted: $m^\text{th}$ polylogarithm of $x$, i.e.~analytic
! 1130: continuation of the power series $\text{Li}_m(x)=\sum_{n\ge1}x^n/n^m$. The
! 1131: program uses the power series when $|x|^2\le1/2$, and the power series
! 1132: expansion in $\log(x)$ otherwise. It is valid in a large domain (at least
! 1133: $|x|<230$), but should not be used too far away from the unit circle since it
! 1134: is then better to use the functional equation linking the value at $x$ to the
! 1135: value at $1/x$, which takes a trivial form for the variant below. Power
! 1136: series, polynomial, rational and vector/matrix arguments are allowed.
! 1137:
! 1138: For the variants to follow we need a notation: let $\Re_m$
! 1139: denotes $\Re$ or $\Im$ depending whether $m$ is odd or even.
! 1140:
! 1141: If $\fl=1$: modified $m^\text{th}$ polylogarithm of $x$, called
! 1142: $\tilde D_m(x)$ in Zagier, defined for $|x|\le1$ by
! 1143: $$\Re_m\left(\sum_{k=0}^{m-1} \dfrac{(-\log|x|)^k}{k!}\text{Li}_{m-k}(x)
! 1144: +\dfrac{(-\log|x|)^{m-1}}{m!}\log|1-x|\right).$$
! 1145:
! 1146: If $\fl=2$: modified $m^\text{th}$ polylogarithm of $x$,
! 1147: called $D_m(x)$ in Zagier, defined for $|x|\le1$ by
! 1148: $$\Re_m\left(\sum_{k=0}^{m-1}\dfrac{(-\log|x|)^k}{k!}\text{Li}_{m-k}(x)
! 1149: -\dfrac{1}{2}\dfrac{(-\log|x|)^m}{m!}\right).$$
! 1150:
! 1151: If $\fl=3$: another modified $m^\text{th}$
! 1152: polylogarithm of $x$, called $P_m(x)$ in Zagier, defined for $|x|\le1$ by
! 1153: $$\Re_m\left(\sum_{k=0}^{m-1}\dfrac{2^kB_k}{k!}(\log|x|)^k\text{Li}_{m-k}(x)
! 1154: -\dfrac{2^{m-1}B_m}{m!}(\log|x|)^m\right).$$
! 1155:
! 1156: These three functions satisfy the functional equation
! 1157: $f_m(1/x)=(-1)^{m-1}f_m(x)$.
! 1158:
! 1159: \syn{polylog0}{m,x,\fl,\var{prec}}.
! 1160:
! 1161: \subsecidx{psi}$(x)$: the $\psi$-function of $x$, i.e.~the
! 1162: logarithmic derivative $\Gamma'(x)/\Gamma(x)$.
! 1163:
! 1164: \syn{gpsi}{x,\var{prec}}.
! 1165:
! 1166: \subsecidx{sin}$(x)$: sine of $x$.
! 1167:
! 1168: \syn{gsin}{x,\var{prec}}.
! 1169:
! 1170: \subsecidx{sinh}$(x)$: hyperbolic sine of $x$.
! 1171:
! 1172: \syn{gsh}{x,\var{prec}}.
! 1173:
! 1174: \subsecidx{sqr}$(x)$: square of $x$. This operation is not completely
! 1175: straightforward, i.e.~identical to $x * x$, since it can usually be
! 1176: computed more efficiently (roughly one-half of the elementary
! 1177: multiplications can be saved). Also, squaring a $2$-adic number increases
! 1178: its precision. For example,
! 1179: \bprog
! 1180: ? (1 + O(2^4))^2
! 1181: %1 = 1 + O(2^5)
! 1182: ? (1 + O(2^4)) * (1 + O(2^4))
! 1183: %2 = 1 + O(2^4)
! 1184: @eprog\noindent
! 1185: Note that this function is also called whenever one multiplies two objects
! 1186: which are known to be {\it identical}, e.g.~they are the value of the same
! 1187: variable, or we are computing a power.
! 1188: \bprog
! 1189: ? x = (1 + O(2^4)); x * x
! 1190: %3 = 1 + O(2^5)
! 1191: ? (1 + O(2^4))^4
! 1192: %4 = 1 + O(2^6)
! 1193: @eprog
! 1194: \noindent(note the difference between \kbd{\%2} and \kbd{\%3} above).
! 1195:
! 1196: \syn{gsqr}{x}.
! 1197:
! 1198: \subsecidx{sqrt}$(x)$: principal branch of the square root of $x$,
! 1199: i.e.~such that $\text{Arg}(\text{sqrt}(x))\in{} ]-\pi/2, \pi/2]$, or in other
! 1200: words such that $\Re(\text{sqrt}(x))>0$ or $\Re(\text{sqrt}(x))=0$ and
! 1201: $\Im(\text{sqrt}(x))\ge 0$. If $x\in \R$ and $x<0$, then the result is
! 1202: complex with positive imaginary part.
! 1203:
! 1204: Integermod a prime and $p$-adics are allowed as arguments. In that case,
! 1205: the square root (if it exists) which is returned is the one whose
! 1206: first $p$-adic digit (or its unique $p$-adic digit in the case of
! 1207: integermods) is in the interval $[0,p/2]$. When the argument is an
! 1208: integermod a non-prime (or a non-prime-adic), the result is undefined.
! 1209:
! 1210: \syn{gsqrt}{x,\var{prec}}.
! 1211:
! 1212: \subsecidx{sqrtn}$(x,n,\{\&z\})$: principal branch of the $n$th root of $x$,
! 1213: i.e.~such that $\text{Arg}(\text{sqrt}(x))\in{} ]-\pi/n, \pi/n]$.
! 1214:
! 1215: Integermod a prime and $p$-adics are allowed as arguments.
! 1216:
! 1217: If $z$ is present, it is set to a suitable root of unity allowing to
! 1218: recover all the other roots. If it was not possible, z is
! 1219: set to zero.
! 1220:
! 1221: The following script computes all roots in all possible cases:
! 1222:
! 1223: \bprog
! 1224: sqrtnall(x,n)=
! 1225: {
! 1226: local(V,r,z,r2);
! 1227: r = sqrtn(x,n, &z);
! 1228: if (!z, error("Impossible case in sqrtn"));
! 1229: if (type(x) == "t_INTMOD" || type(x)=="t_PADIC" ,
! 1230: r2 = r*z; n = 1;
! 1231: while (r2!=r, r2*=z;n++));
! 1232: V = vector(n); V[1] = r;
! 1233: for(i=2, n, V[i] = V[i-1]*z);
! 1234: V
! 1235: }
! 1236: addhelp(sqrtnall,"sqrtnall(x,n):compute the vector of nth-roots of x");
! 1237: @eprog\noindent
! 1238:
! 1239: \syn{gsqrtn}{x,n,\&z,\var{prec}}.
! 1240:
! 1241: \subsecidx{tan}$(x)$: tangent of $x$.
! 1242:
! 1243: \syn{gtan}{x,\var{prec}}.
! 1244:
! 1245: \subsecidx{tanh}$(x)$: hyperbolic tangent of $x$.
! 1246:
! 1247: \syn{gth}{x,\var{prec}}.
! 1248:
! 1249: \subsecidx{teichmuller}$(x)$: Teichm\"uller character of the $p$-adic number
! 1250: $x$.
! 1251:
! 1252: \syn{teich}{x}.
! 1253:
! 1254: \subsecidx{theta}$(q,z)$: Jacobi sine theta-function.
! 1255:
! 1256: \syn{theta}{q,z,\var{prec}}.
! 1257:
! 1258: \subsecidx{thetanullk}$(q,k)$: $k$-th derivative at $z=0$ of
! 1259: $\kbd{theta}(q,z)$.
! 1260:
! 1261: \syn{thetanullk}{q,k,\var{prec}}, where $k$ is a \kbd{long}.
! 1262:
! 1263: \subsecidx{weber}$(x,\{\fl=0\})$: one of Weber's three $f$ functions.
! 1264: If $\fl=0$, returns
! 1265: $$f(x)=\exp(-i\pi/24)\cdot\eta((x+1)/2)\,/\,\eta(x) \quad\hbox{such that}\quad
! 1266: j=(f^{24}-16)^3/f^{24}\,,$$
! 1267: where $j$ is the elliptic $j$-invariant (see the function \kbd{ellj}).
! 1268: If $\fl=1$, returns
! 1269: $$f_1(x)=\eta(x/2)\,/\,\eta(x)\quad\hbox{such that}\quad
! 1270: j=(f_1^{24}+16)^3/f_1^{24}\,.$$
! 1271: Finally, if $\fl=2$, returns
! 1272: $$f_2(x)=\sqrt{2}\eta(2x)\,/\,\eta(x)\quad\hbox{such that}\quad
! 1273: j=(f_2^{24}+16)^3/f_2^{24}.$$
! 1274: Note the identities $f^8=f_1^8+f_2^8$ and $ff_1f_2=\sqrt2$.
! 1275:
! 1276: \syn{weber0}{x,\fl,\var{prec}}, or
! 1277: $\teb{wf}(x,\var{prec})$, $\teb{wf1}(x,\var{prec})$ or
! 1278: $\teb{wf2}(x,\var{prec})$.
! 1279:
! 1280: \subsecidx{zeta}$(s)$: Riemann's zeta function\sidx{Riemann zeta-function}
! 1281: $\zeta(s)=\sum_{n\ge1}n^{-s}$, computed using the \idx{Euler-Maclaurin}
! 1282: summation formula, except when $s$ is of type integer, in which case it
! 1283: is computed using Bernoulli numbers\sidx{Bernoulli numbers} for
! 1284: $s\le0$ or $s>0$ and even, and using modular forms for $s>0$ and odd.
! 1285:
! 1286: \syn{gzeta}{s,\var{prec}}.
! 1287:
! 1288: \section{Arithmetic functions}\label{se:arithmetic}
! 1289:
! 1290: These functions are by definition functions whose natural domain of
! 1291: definition is either $\Z$ (or $\Z_{>0}$), or sometimes polynomials
! 1292: over a base ring. Functions which concern polynomials exclusively will be
! 1293: explained in the next section. The way these functions are used is
! 1294: completely different from transcendental functions: in general only the types
! 1295: integer and polynomial are accepted as arguments. If a vector or matrix type
! 1296: is given, the function will be applied on each coefficient independently.
! 1297:
! 1298: In the present version \vers, all arithmetic functions in the narrow sense
! 1299: of the word~--- Euler's totient\sidx{Euler totient function} function, the
! 1300: \idx{Moebius} function, the sums over divisors or powers of divisors
! 1301: etc.--- call, after trial division by small primes, the same versatile
! 1302: factoring machinery described under \kbd{factorint}. It includes
! 1303: \idx{Shanks SQUFOF}, \idx{Pollard Rho}, \idx{ECM} and \idx{MPQS} stages, and
! 1304: has an early exit option for the functions \teb{moebius} and (the integer
! 1305: function underlying) \teb{issquarefree}. Note that it relies on a (fairly
! 1306: strong) probabilistic primality test: numbers found to be strong
! 1307: pseudo-primes after 10 successful trials of the \idx{Rabin-Miller} test are
! 1308: declared primes.
! 1309:
! 1310: \bigskip
! 1311: \subsecidx{addprimes}$(\{x=[\,]\})$: adds the ``primes'' contained in the
! 1312: vector $x$ (or the single integer $x$) to the table computed upon GP
! 1313: initialization (by \kbd{pari\_init} in library mode), and returns a row
! 1314: vector entries contain all such user primes. Whenever \kbd{factor} or
! 1315: \kbd{smallfact} is subsequently called, first the primes in the table
! 1316: computed by \kbd{pari\_init} will be checked, and then the additional
! 1317: primes in this table. If $x$ is empty or omitted, just returns the current
! 1318: list of extra primes.
! 1319:
! 1320: The entries in $x$ are not checked for primality. They need only be positive
! 1321: integers not divisible by any of the pre-computed primes. It's in fact a nice
! 1322: trick to add composite numbers, which for example the function
! 1323: $\kbd{factor}(x,0)$ was not able to factor. In case the message
! 1324: ``impossible inverse modulo $\langle$\var{some INTMOD}$\rangle$'' shows up
! 1325: afterwards, you have just stumbled over a non-trivial factor. Note that the
! 1326: arithmetic functions in the narrow sense, like \teb{eulerphi}, do \var{not}
! 1327: use this extra table.
! 1328:
! 1329: To remove primes from the list use \kbd{removeprimes}.
! 1330:
! 1331: \syn{addprimes}{x}.
! 1332:
! 1333: \subsecidx{bestappr}$(x,A,\{B\})$: if $B$ is omitted, finds the best rational
! 1334: approximation to $x\in\R$ (or $\R[X]$, or $\R^n$, \dots) with denominator at
! 1335: most equal to $A$ using continued fractions.
! 1336:
! 1337: If $B$ is present, $x$ is assumed to be of type \typ{INTMOD} modulo $M$ (or a
! 1338: recursive combination of those), and the routine returns the unique fraction
! 1339: $a/b$ in coprime integers $a\leq A$ and $b\leq B$ which is congruent to $x$
! 1340: modulo $M$. If $M \leq 2AB$, uniqueness is not guaranteed and the function
! 1341: fails with an error message. If rational reconstruction is not possible
! 1342: (no such $a/b$ exists for at least one component of $x$), returns $-1$.
! 1343:
! 1344: \syn{bestappr0}{x,A,B}. Also available is $\teb{bestappr}(x,A)$ corresponding
! 1345: to an omitted $B$.
! 1346:
! 1347: \subsecidx{bezout}$(x,y)$: finds $u$ and $v$ minimal in a
! 1348: natural sense such that $x*u+y*v=\text{gcd}(x,y)$. The arguments
! 1349: must be both integers or both polynomials, and the result is a
! 1350: row vector with three components $u$, $v$, and $\text{gcd}(x,y)$.
! 1351:
! 1352: \syn{vecbezout}{x,y} to get the vector, or $\teb{gbezout}(x,y, \&u, \&v)$
! 1353: which gives as result the address of the created gcd, and puts
! 1354: the addresses of the corresponding created objects into $u$ and $v$.
! 1355:
! 1356: \subsecidx{bezoutres}$(x,y)$: as \kbd{bezout}, with the resultant of $x$ and
! 1357: $y$ replacing the gcd.
! 1358:
! 1359: \syn{vecbezoutres}{x,y} to get the vector, or $\teb{subresext}(x,y, \&u,
! 1360: \&v)$ which gives as result the address of the created gcd, and puts the
! 1361: addresses of the corresponding created objects into $u$ and $v$.
! 1362:
! 1363: \subsecidx{bigomega}$(x)$: number of prime divisors of $|x|$ counted with
! 1364: multiplicity. $x$ must be an integer.
! 1365:
! 1366: \syn{bigomega}{x}, the result is a \kbd{long}.
! 1367:
! 1368: \subsecidx{binomial}$(x,y)$: \idx{binomial coefficient} $\binom x y$.
! 1369: Here $y$ must be an integer, but $x$ can be any PARI object.
! 1370:
! 1371: \syn{binome}{x,y}, where $y$ must be a \kbd{long}.
! 1372:
! 1373: \subsecidx{chinese}$(x,y)$: if $x$ and $y$ are both integermods or both
! 1374: polmods, creates (with the same type) a $z$ in the same residue class
! 1375: as $x$ and in the same residue class as $y$, if it is possible.
! 1376:
! 1377: This function also allows vector and matrix arguments, in which case the
! 1378: operation is recursively applied to each component of the vector or matrix.
! 1379: For polynomial arguments, it is applied to each coefficient. Finally
! 1380: $\kbd{chinese}(x,x) = x$ regardless of the type of $x$; this allows vector
! 1381: arguments to contain other data, so long as they are identical in both
! 1382: vectors.
! 1383:
! 1384: \syn{chinois}{x,y}.
! 1385:
! 1386: \subsecidx{content}$(x)$: computes the gcd of all the coefficients of $x$,
! 1387: when this gcd makes sense. If $x$ is a scalar, this simply returns $x$. If $x$
! 1388: is a polynomial (and by extension a power series), it gives the usual content
! 1389: of $x$. If $x$ is a rational function, it gives the ratio of the contents of
! 1390: the numerator and the denominator. Finally, if $x$ is a vector or a matrix,
! 1391: it gives the gcd of all the entries.
! 1392:
! 1393: \syn{content}{x}.
! 1394:
! 1395: \subsecidx{contfrac}$(x,\{b\},\{lmax\})$: creates the row vector whose
! 1396: components are the partial quotients of the \idx{continued fraction}
! 1397: expansion of $x$, the number of partial quotients being limited to $lmax$.
! 1398: If $x$ is a real number, the expansion stops at the last significant partial
! 1399: quotient if $lmax$ is omitted. $x$ can also be a rational function or a power
! 1400: series.
! 1401:
! 1402: If a vector $b$ is supplied, the numerators will be equal to the coefficients
! 1403: of $b$. The length of the result is then equal to the length of $b$, unless a
! 1404: partial remainder is encountered which is equal to zero. In which case the
! 1405: expansion stops. In the case of real numbers, the stopping criterion is thus
! 1406: different from the one mentioned above since, if $b$ is too long, some partial
! 1407: quotients may not be significant.
! 1408:
! 1409: If $b$ is an integer, the command is understood as \kbd{contfrac($x,lmax$)}.
! 1410:
! 1411: \syn{contfrac0}{x,b,lmax}. Also available are
! 1412: $\teb{gboundcf}(x,lmax)$, $\teb{gcf}(x)$, or $\teb{gcf2}(b,x)$, where $lmax$
! 1413: is a C integer.
! 1414:
! 1415: \subsecidx{contfracpnqn}$(x)$: when $x$ is a vector or a one-row matrix, $x$
! 1416: is considered as the list of partial quotients $[a_0,a_1,\dots,a_n]$ of a
! 1417: rational number, and the result is the 2 by 2 matrix
! 1418: $[p_n,p_{n-1};q_n,q_{n-1}]$ in the standard notation of continued fractions,
! 1419: so $p_n/q_n=a_0+1/(a_1+\dots+1/a_n)\dots)$. If $x$ is a matrix with two rows
! 1420: $[b_0,b_1,\dots,b_n]$ and $[a_0,a_1,\dots,a_n]$, this is then considered as a
! 1421: generalized continued fraction and we have similarly
! 1422: $p_n/q_n=1/b_0(a_0+b_1/(a_1+\dots+b_n/a_n)\dots)$. Note that in this case one
! 1423: usually has $b_0=1$.
! 1424:
! 1425: \syn{pnqn}{x}.
! 1426:
! 1427: \subsecidx{core}$(n,\{\fl=0\})$: if $n$ is a non-zero integer written as
! 1428: $n=df^2$ with $d$ squarefree, returns $d$. If $\fl$ is non-zero,
! 1429: returns the two-element row vector $[d,f]$.
! 1430:
! 1431: \syn{core0}{n,\fl}.
! 1432: Also available are
! 1433: $\teb{core}(n)$ (= \teb{core}$(n,0)$) and
! 1434: $\teb{core2}(n)$ (= \teb{core}$(n,1)$).
! 1435:
! 1436: \subsecidx{coredisc}$(n,\{\fl\})$: if $n$ is a non-zero integer written as
! 1437: $n=df^2$ with $d$ fundamental discriminant (including 1), returns $d$. If
! 1438: $\fl$ is non-zero, returns the two-element row vector $[d,f]$. Note that if
! 1439: $n$ is not congruent to 0 or 1 modulo 4, $f$ will be a half integer and not
! 1440: an integer.
! 1441:
! 1442: \syn{coredisc0}{n,\fl}.
! 1443: Also available are
! 1444: $\teb{coredisc}(n)$ (= \teb{coredisc}$(n,0)$) and
! 1445: $\teb{coredisc2}(n)$ (= \teb{coredisc}$(n,1)$).
! 1446:
! 1447: \subsecidx{dirdiv}$(x,y)$: $x$ and $y$ being vectors of perhaps different
! 1448: lengths but with $y[1]\neq 0$ considered as \idx{Dirichlet series}, computes
! 1449: the quotient of $x$ by $y$, again as a vector.
! 1450:
! 1451: \syn{dirdiv}{x,y}.
! 1452:
! 1453: \subsecidx{direuler}$(p=a,b,\var{expr},\{c\})$: computes the
! 1454: \idx{Dirichlet series} to $b$ terms of the \idx{Euler product} of
! 1455: expression \var{expr} as $p$ ranges through the primes from $a$ to $b$.
! 1456: \var{expr} must be a polynomial or rational function in another variable
! 1457: than $p$ (say $X$) and $\var{expr}(X)$ is understood as the Dirichlet
! 1458: series (or more precisely the local factor) $\var{expr}(p^{-s})$. If $c$ is
! 1459: present, output only the first $c$ coefficients in the series.
! 1460:
! 1461: \synt{direuler}{entree *ep, GEN a, GEN b, char *expr}
! 1462:
! 1463: \subsecidx{dirmul}$(x,y)$: $x$ and $y$ being vectors of perhaps different
! 1464: lengths considered as \idx{Dirichlet series}, computes the product of
! 1465: $x$ by $y$, again as a vector.
! 1466:
! 1467: \syn{dirmul}{x,y}.
! 1468:
! 1469: \subsecidx{divisors}$(x)$: creates a row vector whose components are the
! 1470: positive divisors of the integer $x$ in increasing order. The factorization
! 1471: of $x$ (as output by \tet{factor}) can be used instead.
! 1472:
! 1473: \syn{divisors}{x}.
! 1474:
! 1475: \subsecidx{eulerphi}$(x)$: Euler's $\phi$
! 1476: (totient)\sidx{Euler totient function} function of $|x|$, in other words
! 1477: $|(\Z/x\Z)^*|$. $x$ must be of type integer.
! 1478:
! 1479: \syn{phi}{x}.
! 1480:
! 1481: \subsecidx{factor}$(x,\{\var{lim}=-1\})$: general factorization function.
! 1482: If $x$ is of type integer, rational, polynomial or rational function, the
! 1483: result is a two-column matrix, the first column being the irreducibles
! 1484: dividing $x$ (prime numbers or polynomials), and the second the exponents.
! 1485: If $x$ is a vector or a matrix, the factoring is done componentwise (hence
! 1486: the result is a vector or matrix of two-column matrices). By definition,
! 1487: $0$ is factored as $0^1$.
! 1488:
! 1489: If $x$ is of type integer or rational, an argument \var{lim} can be
! 1490: added, meaning that we look only for factors up to \var{lim}, or to
! 1491: \kbd{primelimit}, whichever is lowest (except when $\var{lim}=0$ where the
! 1492: effect is identical to setting $\var{lim}=\kbd{primelimit}$). Hence in this
! 1493: case, the remaining part is not necessarily prime. See \tet{factorint} for
! 1494: more information about the algorithms used.
! 1495:
! 1496: The polynomials or rational functions to be factored must have scalar
! 1497: coefficients. In particular PARI does \var{not} know how to factor
! 1498: multivariate polynomials.
! 1499:
! 1500: Note that PARI tries to guess in a sensible way over which ring you want
! 1501: to factor. Note also that factorization of polynomials is done up to
! 1502: multiplication by a constant. In particular, the factors of rational
! 1503: polynomials will have integer coefficients, and the content of a polynomial
! 1504: or rational function is discarded and not included in the factorization. If
! 1505: you need it, you can always ask for the content explicitly:
! 1506:
! 1507: \bprog
! 1508: ? factor(t^2 + 5/2*t + 1)
! 1509: %1 =
! 1510: [2*t + 1 1]
! 1511:
! 1512: [t + 2 1]
! 1513:
! 1514: ? content(t^2 + 5/2*t + 1)
! 1515: %2 = 1/2
! 1516: @eprog
! 1517:
! 1518: \noindent See also \tet{factornf}.
! 1519:
! 1520: \syn{factor0}{x,\var{lim}}, where \var{lim} is a C integer.
! 1521: Also available are
! 1522: $\teb{factor}(x)$ (= $\teb{factor0}(x,-1)$),
! 1523: $\teb{smallfact}(x)$ (= $\teb{factor0}(x,0)$).
! 1524:
! 1525: \subsecidx{factorback}$(f,\{nf\})$: $f$ being any factorization, gives back
! 1526: the factored object. If a second argument $\var{nf}$ is supplied, $f$ is
! 1527: assumed to be a prime ideal factorization in the number field $\var{nf}$.
! 1528: The resulting ideal is given in HNF\sidx{Hermite normal form} form.
! 1529:
! 1530: \syn{factorback}{f,\var{nf}}, where an omitted
! 1531: $\var{nf}$ is entered as \kbd{NULL}.
! 1532:
! 1533: \subsecidx{factorcantor}$(x,p)$: factors the polynomial $x$ modulo the
! 1534: prime $p$, using distinct degree plus
! 1535: \idx{Cantor-Zassenhaus}\sidx{Zassenhaus}. The coefficients of $x$ must be
! 1536: operation-compatible with $\Z/p\Z$. The result is a two-column matrix, the
! 1537: first column being the irreducible polynomials dividing $x$, and the second
! 1538: the exponents. If you want only the \var{degrees} of the irreducible
! 1539: polynomials (for example for computing an $L$-function), use
! 1540: $\kbd{factormod}(x,p,1)$. Note that the \kbd{factormod} algorithm is
! 1541: usually faster than \kbd{factorcantor}.
! 1542:
! 1543: \syn{factcantor}{x,p}.
! 1544:
! 1545: \subsecidx{factorff}$(x,p,a)$: factors the polynomial $x$ in the field
! 1546: $\F_q$ defined by the irreducible polynomial $a$ over $\F_p$. The
! 1547: coefficients of $x$ must be operation-compatible with $\Z/p\Z$. The result
! 1548: is a two-column matrix, the first column being the irreducible polynomials
! 1549: dividing $x$, and the second the exponents. It is recommended to use for
! 1550: the variable of $a$ (which will be used as variable of a polmod) a name
! 1551: distinct from the other variables used, so that a \kbd{lift()} of the
! 1552: result will be legible. If all the coefficients of $x$ are in $\F_p$, a much faster algorithm is applied, using the computation of isomorphisms between finite fields.
! 1553:
! 1554: \syn{factmod9}{x,p,a}.
! 1555:
! 1556: \subsecidx{factorial}$(x)$ or $x!$: factorial of $x$. The expression $x!$
! 1557: gives a result which is an integer, while $\kbd{factorial}(x)$ gives a real
! 1558: number.
! 1559:
! 1560: \syn{mpfact}{x} for $x!$ and
! 1561: $\teb{mpfactr}(x,\var{prec})$ for $\kbd{factorial}(x)$. $x$ must be a \kbd{long}
! 1562: integer and not a PARI integer.
! 1563:
! 1564: \subsecidx{factorint}$(n,\{\fl=0\})$: factors the integer n using a
! 1565: combination of the \idx{Shanks SQUFOF} and \idx{Pollard Rho} method (with
! 1566: modifications due to Brent), \idx{Lenstra}'s \idx{ECM} (with modifications by
! 1567: Montgomery), and \idx{MPQS} (the latter adapted from the \idx{LiDIA} code
! 1568: with the kind permission of the LiDIA maintainers), as well as a search for
! 1569: pure powers with exponents$\le 10$. The output is a two-column matrix as for
! 1570: \kbd{factor}.
! 1571:
! 1572: This gives direct access to the integer factoring engine called by most
! 1573: arithmetical functions. \fl\ is optional; its binary digits mean 1: avoid
! 1574: MPQS, 2: skip first stage ECM (we may still fall back to it later), 4: avoid
! 1575: Rho and SQUFOF, 8: don't run final ECM (as a result, a huge composite may be
! 1576: declared to be prime). Note that a (strong) probabilistic primality test is
! 1577: used; thus composites might (very rarely) not be detected.
! 1578:
! 1579: The machinery underlying this function is still in a somewhat experimental
! 1580: state, but should be much faster on average than pure ECM as used by all
! 1581: PARI versions up to 2.0.8, at the expense of heavier memory use. You are
! 1582: invited to play with the flag settings and watch the internals at work by
! 1583: using GP's \tet{debuglevel} default parameter (level 3 shows just the
! 1584: outline, 4 turns on time keeping, 5 and above show an increasing amount
! 1585: of internal details). If you see anything funny happening, please let
! 1586: us know.
! 1587:
! 1588: \syn{factorint}{n,\fl}.
! 1589:
! 1590: \subsecidx{factormod}$(x,p,\{\fl=0\})$: factors the polynomial $x$ modulo
! 1591: the prime integer $p$, using \idx{Berlekamp}. The coefficients of $x$ must be
! 1592: operation-compatible with $\Z/p\Z$. The result is a two-column matrix, the
! 1593: first column being the irreducible polynomials dividing $x$, and the second
! 1594: the exponents. If $\fl$ is non-zero, outputs only the \var{degrees} of the
! 1595: irreducible polynomials (for example, for computing an $L$-function). A
! 1596: different algorithm for computing the mod $p$ factorization is
! 1597: \kbd{factorcantor} which is sometimes faster.
! 1598:
! 1599: \syn{factormod}{x,p,\fl}. Also available are
! 1600: $\teb{factmod}(x,p)$ (which is equivalent to $\teb{factormod}(x,p,0)$) and
! 1601: $\teb{simplefactmod}(x,p)$ (= $\teb{factormod}(x,p,1)$).
! 1602:
! 1603: \subsecidx{fibonacci}$(x)$: $x^{\text{th}}$ Fibonacci number.
! 1604:
! 1605: \syn{fibo}{x}. $x$ must be a \kbd{long}.
! 1606:
! 1607: \subsecidx{ffinit}$(p,n,\{v=x\})$: computes a monic polynomial of degree
! 1608: $n$ which is irreducible over $\F_p$. For instance if
! 1609: \kbd{P = ffinit(3,2,y)}, you can represent elements in $\F_{3^2}$ as polmods
! 1610: modulo \kbd{P}.
! 1611:
! 1612: \syn{ffinit}{p,n,v}, where $v$ is a variable number.
! 1613:
! 1614: \subsecidx{gcd}$(x,y,\{\fl=0\})$: creates the greatest common divisor of $x$
! 1615: and $y$. $x$ and $y$ can be of quite general types, for instance both
! 1616: rational numbers. Vector/matrix types are also accepted, in which case
! 1617: the GCD is taken recursively on each component. Note that for these
! 1618: types, \kbd{gcd} is not commutative.
! 1619:
! 1620: If $\fl=0$, use \idx{Euclid}'s algorithm.
! 1621:
! 1622: If $\fl=1$, use the modular gcd algorithm ($x$ and $y$ have to be
! 1623: polynomials, with integer coefficients).
! 1624:
! 1625: If $\fl=2$, use the \idx{subresultant algorithm}.
! 1626:
! 1627: \syn{gcd0}{x,y,\fl}. Also available are
! 1628: $\teb{ggcd}(x,y)$, $\teb{modulargcd}(x,y)$, and $\teb{srgcd}(x,y)$
! 1629: corresponding to $\fl=0$, $1$ and $2$ respectively.
! 1630:
! 1631: \subsecidx{hilbert}$(x,y,\{p\})$: \idx{Hilbert symbol} of $x$ and $y$ modulo
! 1632: $p$. If $x$ and $y$ are of type integer or fraction, an explicit third
! 1633: parameter $p$ must be supplied, $p=0$ meaning the place at infinity.
! 1634: Otherwise, $p$ needs not be given, and $x$ and $y$ can be of compatible types
! 1635: integer, fraction, real, integermod or $p$-adic.
! 1636:
! 1637: \syn{hil}{x,y,p}.
! 1638:
! 1639: \subsecidx{isfundamental}$(x)$: true (1) if $x$ is equal to 1 or to the
! 1640: discriminant of a quadratic field, false (0) otherwise.
! 1641:
! 1642: \syn{gisfundamental}{x}, but the
! 1643: simpler function $\teb{isfundamental}(x)$ which returns a \kbd{long}
! 1644: should be used if $x$ is known to be of type integer.
! 1645:
! 1646: \subsecidx{isprime}$(x,\{\fl=0\})$: if $\fl=0$ (default), true (1) if $x$ is a strong pseudo-prime
! 1647: for 10 randomly chosen bases, false (0) otherwise.
! 1648:
! 1649: If $\fl=1$, use Pocklington-Lehmer ``P-1'' test. true (1) if $x$ is
! 1650: prime, false (0) otherwise.
! 1651:
! 1652: If $\fl=2$, use Pocklington-Lehmer ``P-1'' test and output a primality
! 1653: certificate as follows: return 0 if $x$ is composite, 1 if $x$ is a
! 1654: small prime (currently strictly less than $341 550 071 728 321$), and
! 1655: a matrix if $x$ is a large prime. The matrix has three columns. The
! 1656: first contains the prime factors $p$, the second the corresponding
! 1657: elements $a_p$ as in Proposition~8.3.1 in GTM~138, and the third the
! 1658: output of isprime(p,2).
! 1659:
! 1660: In the two last cases, the algorithm fails if one of the (strong
! 1661: pseudo-)prime factors is not prime, but it should be exceedingly rare.
! 1662:
! 1663:
! 1664: \syn{gisprime}{x,\fl}, but the simpler function $\teb{isprime}(x)$
! 1665: which returns a \kbd{long} should be used if $x$ is known to be of
! 1666: type integer. Also available is $\teb{plisprime}(N,\fl)$,
! 1667: corresponding to $\teb{gisprime}(x,\fl+1)$ if $x$ is known to be of
! 1668: type integer.
! 1669:
! 1670:
! 1671: \subsecidx{ispseudoprime}$(x)$: true (1) if $x$ is a strong
! 1672: pseudo-prime for a randomly chosen base, false (0) otherwise.
! 1673:
! 1674: \syn{gispsp}{x}, but the
! 1675: simpler function $\teb{ispsp}(x)$ which returns a \kbd{long}
! 1676: should be used if $x$ is known to be of type integer.
! 1677:
! 1678: \subsecidx{issquare}$(x,\{\&n\})$: true (1) if $x$ is square, false (0) if
! 1679: not. $x$ can be of any type. If $n$ is given and an exact square root had to
! 1680: be computed in the checking process, puts that square root in $n$. This is in
! 1681: particular the case when $x$ is an integer or a polynomial. This is \var{not}
! 1682: the case for intmods (use quadratic reciprocity) or series (only check the
! 1683: leading coefficient).
! 1684:
! 1685: \syn{gcarrecomplet}{x,\&n}. Also available is $\teb{gcarreparfait}(x)$.
! 1686:
! 1687: \subsecidx{issquarefree}$(x)$: true (1) if $x$ is squarefree, false (0) if not.
! 1688: Here $x$ can be an integer or a polynomial.
! 1689:
! 1690: \syn{gissquarefree}{x}, but the simpler function $\teb{issquarefree}(x)$
! 1691: which returns a \kbd{long} should be used if $x$ is known to be of type
! 1692: integer. This \teb{issquarefree} is just the square of the
! 1693: \idx{Moebius} function, and is computed as a multiplicative
! 1694: arithmetic function much like the latter.
! 1695:
! 1696: \subsecidx{kronecker}$(x,y)$:
! 1697: Kronecker\sidx{Kronecker symbol}\sidx{Legendre symbol}
! 1698: (i.e.~generalized Legendre) symbol $\left(\dfrac{x}{y}\right)$. $x$ and $y$
! 1699: must be of type integer.
! 1700:
! 1701: \syn{kronecker}{x,y}, the result ($0$ or $\pm 1$) is a \kbd{long}.
! 1702:
! 1703: \subsecidx{lcm}$(x,y)$: least common multiple of $x$ and $y$, i.e.~such
! 1704: that $\text{lcm}(x,y)*\text{gcd}(x,y)=\text{abs}(x*y)$.
! 1705:
! 1706: \syn{glcm}{x,y}.
! 1707:
! 1708: \subsecidx{moebius}$(x)$: \idx{Moebius} $\mu$-function of $|x|$. $x$ must
! 1709: be of type integer.
! 1710:
! 1711: \syn{mu}{x}, the result ($0$ or $\pm 1$) is a \kbd{long}.
! 1712:
! 1713: \subsecidx{nextprime}$(x)$: finds the smallest prime greater than or
! 1714: equal to $x$. $x$ can be of any real type. Note that if $x$ is a prime,
! 1715: this function returns $x$ and not the smallest prime strictly larger than $x$.
! 1716:
! 1717: \syn{nextprime}{x}.
! 1718:
! 1719: \subsecidx{numdiv}$(x)$: number of divisors of $|x|$. $x$ must be of type
! 1720: integer, and the result is a \kbd{long}.
! 1721:
! 1722: \syn{numbdiv}{x}.
! 1723:
! 1724: \subsecidx{omega}$(x)$: number of distinct prime divisors of $|x|$. $x$
! 1725: must be of type integer.
! 1726:
! 1727: \syn{omega}{x}, the result is a \kbd{long}.
! 1728:
! 1729: \subsecidx{precprime}$(x)$: finds the largest prime less than or equal to
! 1730: $x$. $x$ can be of any real type. Returns 0 if $x\le1$.
! 1731: Note that if $x$ is a prime, this function returns $x$ and not the largest
! 1732: prime strictly smaller than $x$.
! 1733:
! 1734: \syn{precprime}{x}.
! 1735:
! 1736: \subsecidx{prime}$(x)$: the $x^{\text{th}}$ prime number, which must be among
! 1737: the precalculated primes.
! 1738:
! 1739: \syn{prime}{x}. $x$ must be a \kbd{long}.
! 1740:
! 1741: \subsecidx{primes}$(x)$: creates a row vector whose components
! 1742: are the first $x$ prime numbers, which must be among the precalculated primes.
! 1743:
! 1744: \syn{primes}{x}. $x$ must be a \kbd{long}.
! 1745:
! 1746: \subsecidx{qfbclassno}$(x,\{\fl=0\})$: class number of the quadratic field
! 1747: of discriminant $x$. In the present version \vers, a simple algorithm is used
! 1748: for $x>0$, so $x$ should not be too large (say $x<10^7$) for the time to be
! 1749: reasonable. On the other hand, for $x<0$ one can reasonably compute
! 1750: classno($x$) for $|x|<10^{25}$, since the method used is \idx{Shanks}' method
! 1751: which is in $O(|x|^{1/4})$. For larger values of $|D|$, see
! 1752: \kbd{quadclassunit}.
! 1753:
! 1754: If $\fl=1$, compute the class number using \idx{Euler product}s and the
! 1755: functional equation. However, it is in $O(|x|^{1/2})$.
! 1756:
! 1757: \misctitle{Important warning.} For $D<0$, this function often gives
! 1758: incorrect results when the class group is non-cyclic, because the authors
! 1759: were too lazy to implement \idx{Shanks}' method completely. It is therefore
! 1760: strongly recommended to use either the version with $\fl=1$, the function
! 1761: $\kbd{qfhclassno}(-x)$ if $x$ is known to be a fundamental discriminant, or
! 1762: the function \kbd{quadclassunit}.
! 1763:
! 1764: \syn{qfbclassno0}{x,\fl}. Also available are
! 1765: $\teb{classno}(x)$ (= $\teb{qfbclassno}(x)$),
! 1766: $\teb{classno2}(x)$ (= $\teb{qfbclassno}(x,1)$), and finally
! 1767: there exists the function $\teb{hclassno}(x)$ which computes the class
! 1768: number of an imaginary quadratic field by counting reduced forms, an $O(|x|)$
! 1769: algorithm. See also \kbd{qfbhclassno}.
! 1770:
! 1771: \subsecidx{qfbcompraw}$(x,y)$ \idx{composition} of the binary quadratic forms
! 1772: $x$ and $y$, without \idx{reduction} of the result. This is useful e.g.~to
! 1773: compute a generating element of an ideal.
! 1774:
! 1775: \syn{compraw}{x,y}.
! 1776:
! 1777: \subsecidx{qfbhclassno}$(x)$: \idx{Hurwitz class number} of $x$, where $x$ is
! 1778: non-negative and congruent to 0 or 3 modulo 4. See also \kbd{qfbclassno}.
! 1779:
! 1780: \syn{hclassno}{x}.
! 1781:
! 1782: \subsecidx{qfbnucomp}$(x,y,l)$: \idx{composition} of the primitive positive
! 1783: definite binary quadratic forms $x$ and $y$ using the NUCOMP and NUDUPL
! 1784: algorithms of \idx{Shanks} (\`a la Atkin). $l$ is any positive constant,
! 1785: but for optimal speed, one should take $l=|D|^{1/4}$, where $D$ is the common
! 1786: discriminant of $x$ and $y$.
! 1787:
! 1788: \syn{nucomp}{x,y,l}. The auxiliary function
! 1789: $\teb{nudupl}(x,l)$ should be used instead for speed when $x=y$.
! 1790:
! 1791: \subsecidx{qfbnupow}$(x,n)$: $n$-th power of the primitive positive definite
! 1792: binary quadratic form $x$ using the NUCOMP and NUDUPL algorithms (see
! 1793: \kbd{qfbnucomp}).
! 1794:
! 1795: \syn{nupow}{x,n}.
! 1796:
! 1797: \subsecidx{qfbpowraw}$(x,n)$: $n$-th power of the binary quadratic form
! 1798: $x$, computed without doing any \idx{reduction} (i.e.~using \kbd{qfbcompraw}).
! 1799: Here $n$ must be non-negative and $n<2^{31}$.
! 1800:
! 1801: \syn{powraw}{x,n} where $n$ must be a \kbd{long}
! 1802: integer.
! 1803:
! 1804: \subsecidx{qfbprimeform}$(x,p)$: prime binary quadratic form of discriminant
! 1805: $x$ whose first coefficient is the prime number $p$. By abuse of notation,
! 1806: $p = 1$ is a valid special case which returns the unit form. Returns an
! 1807: error if $x$ is not a quadratic residue mod $p$. In the case where $x>0$,
! 1808: the ``distance'' component of the form is set equal to zero according to
! 1809: the current precision.
! 1810:
! 1811: \syn{primeform}{x,p,\var{prec}}, where the third variable $\var{prec}$ is a
! 1812: \kbd{long}, but is only taken into account when $x>0$.
! 1813:
! 1814: \subsecidx{qfbred}$(x,\{\fl=0\},\{D\},\{\var{isqrtD}\},\{\var{sqrtD}\})$:
! 1815: reduces the binary quadratic form $x$ (updating Shanks's distance function
! 1816: if $x$ is indefinite). The binary digits of $\fl$ are toggles meaning
! 1817:
! 1818: \quad 1: perform a single \idx{reduction} step
! 1819:
! 1820: \quad 2: don't update \idx{Shanks}'s distance
! 1821:
! 1822: $D$, \var{isqrtD}, \var{sqrtD}, if present, supply the values of the
! 1823: discriminant, $\lfloor \sqrt{D}\rfloor$, and $\sqrt{D}$ respectively
! 1824: (no checking is done of these facts). If $D<0$ these values are useless,
! 1825: and all references to Shanks's distance are irrelevant.
! 1826:
! 1827: \syn{qfbred0}{x,\fl,D,\var{isqrtD},\var{sqrtD}}. Use \kbd{NULL}
! 1828: to omit any of $D$, \var{isqrtD}, \var{sqrtD}.
! 1829:
! 1830: \noindent Also available are
! 1831:
! 1832: $\teb{redimag}(x)$ (= $\teb{qfbred}(x)$ where $x$ is definite),
! 1833:
! 1834: \noindent and for indefinite forms:
! 1835:
! 1836: $\teb{redreal}(x)$ (= $\teb{qfbred}(x)$),
! 1837:
! 1838: $\teb{rhoreal}(x)$ (= $\teb{qfbred}(x,1)$),
! 1839:
! 1840: $\teb{redrealnod}(x,sq)$ (= $\teb{qfbred}(x,2,,isqrtD)$),
! 1841:
! 1842: $\teb{rhorealnod}(x,sq)$ (= $\teb{qfbred}(x,3,,isqrtD)$).
! 1843:
! 1844: \subsecidx{quadclassunit}$(D,\{\fl=0\},\{\var{tech}=[]\})$:
! 1845: \idx{Buchmann-McCurley}'s sub-exponential algorithm for computing the class
! 1846: group of a quadratic field of discriminant $D$. If $D$ is not fundamental,
! 1847: the function may or may not be defined, but usually is, and often gives the
! 1848: right answer (a warning is issued). The more general function \tet{bnrinit}
! 1849: should be used to compute the class group of an order.
! 1850:
! 1851: This function should be used instead of \kbd{qfbclassno} or \kbd{quadregula}
! 1852: when $D<-10^{25}$, $D>10^{10}$, or when the \var{structure} is wanted.
! 1853:
! 1854: If $\fl$ is non-zero \var{and} $D>0$, computes the narrow class group and
! 1855: regulator, instead of the ordinary (or wide) ones. In the current version
! 1856: \vers, this doesn't work at all~: use the general function \tet{bnfnarrow}.
! 1857:
! 1858: Optional parameter \var{tech} is a row vector of the form
! 1859: $[c_1,c_2]$, where $c_1$ and $c_2$ are positive real numbers which
! 1860: control the execution time and the stack size. To get maximum speed,
! 1861: set $c_2=c$. To get a rigorous result (under \idx{GRH}) you must take
! 1862: $c_2=6$. Reasonable values for $c$ are between $0.1$ and $2$.
! 1863:
! 1864: The result of this function is a vector $v$ with 4 components if $D<0$, and
! 1865: $5$ otherwise. The correspond respectively to
! 1866:
! 1867: $\bullet$ $v[1]$~: the class number
! 1868:
! 1869: $\bullet$ $v[2]$~: a vector giving the structure of the class group as a
! 1870: product of cyclic groups;
! 1871:
! 1872: $\bullet$ $v[3]$~: a vector giving generators of those cyclic groups (as
! 1873: binary quadratic forms).
! 1874:
! 1875: $\bullet$ $v[4]$~: (omitted if $D < 0$) the regulator, computed to an
! 1876: accuracy which is the maximum of an internal accuracy determined by the
! 1877: program and the current default (note that once the regulator is known to a
! 1878: small accuracy it is trivial to compute it to very high accuracy, see the
! 1879: tutorial).
! 1880:
! 1881: $\bullet$ $v[5]$~: a measure of the correctness of the result. If it is
! 1882: close to 1, the result is correct (under \idx{GRH}). If it is close to a
! 1883: larger integer, this shows that the class number is off by a factor equal
! 1884: to this integer, and you must start again with a larger value for $c_1$ or
! 1885: a different random seed. In this case, a warning message is printed.
! 1886:
! 1887: \syn{quadclassunit0}{D,\fl,tech}. Also available are
! 1888: $\teb{buchimag}(D,c_1,c_2)$ and $\teb{buchreal}(D,\fl,c_1,c_2)$.
! 1889:
! 1890: \subsecidx{quaddisc}$(x)$: discriminant of the quadratic field
! 1891: $\Q(\sqrt{x})$, where $x\in\Q$.
! 1892:
! 1893: \syn{quaddisc}{x}.
! 1894:
! 1895: \subsecidx{quadhilbert}$(D,\{\fl=0\})$: relative equation defining the
! 1896: \idx{Hilbert class field} of the quadratic field of discriminant $D$.
! 1897: If $\fl$ is non-zero
! 1898: and $D<0$, outputs $[\var{form},\var{root}(\var{form})]$ (to be used for
! 1899: constructing subfields). If $\fl$ is non-zero and $D>0$, try hard to
! 1900: get the best modulus.
! 1901: Uses complex multiplication in the imaginary case and \idx{Stark units}
! 1902: in the real case.
! 1903:
! 1904: \syn{quadhilbert}{D,\fl,\var{prec}}.
! 1905:
! 1906: \subsecidx{quadgen}$(x)$: creates the quadratic number\sidx{omega}
! 1907: $\omega=(a+\sqrt{x})/2$ where $a=0$ if $x\equiv0\mod4$,
! 1908: $a=1$ if $x\equiv1\mod4$, so that $(1,\omega)$ is an integral basis for
! 1909: the quadratic order of discriminant $x$. $x$ must be an integer congruent to
! 1910: 0 or 1 modulo 4.
! 1911:
! 1912: \syn{quadgen}{x}.
! 1913:
! 1914: \subsecidx{quadpoly}$(D,\{v=x\})$: creates the ``canonical'' quadratic
! 1915: polynomial (in the variable $v$) corresponding to the discriminant $D$,
! 1916: i.e.~the minimal polynomial of $\kbd{quadgen}(x)$. $D$ must be an integer
! 1917: congruent to 0 or 1 modulo 4.
! 1918:
! 1919: \syn{quadpoly0}{x,v}.
! 1920:
! 1921: \subsecidx{quadray}$(D,f,\{\fl=0\})$: relative equation for the ray class
! 1922: field of conductor $f$ for the quadratic field of discriminant $D$ (which
! 1923: can also be a \kbd{bnf}), using analytic methods.
! 1924:
! 1925: For $D<0$, uses the $\sigma$ function. $\fl$ has the following meaning: if
! 1926: it's an odd integer, outputs instead the vector of $[\var{ideal},
! 1927: \var{corresponding root}]$. It can also be a two-component vector
! 1928: $[\lambda,\fl]$, where \fl\ is as above and $\lambda$ is the technical
! 1929: element of \kbd{bnf} necessary for Schertz's method. In that case, returns
! 1930: 0 if $\lambda$ is not suitable.
! 1931:
! 1932: For $D>0$, uses Stark's conjecture. If $\fl$ is non-zero, try hard to
! 1933: get the best modulus. The function may fail with the following message
! 1934: \bprog
! 1935: "Cannot find a suitable modulus in FindModulus"
! 1936: @eprog
! 1937: See \tet{bnrstark} for more details about the real case.
! 1938:
! 1939: \syn{quadray}{D,f,\fl}.
! 1940:
! 1941: \subsecidx{quadregulator}$(x)$: regulator of the quadratic field of
! 1942: positive discriminant $x$. Returns an error if $x$ is not a discriminant
! 1943: (fundamental or not) or if $x$ is a square. See also \kbd{quadclassunit} if
! 1944: $x$ is large.
! 1945:
! 1946: \syn{regula}{x,\var{prec}}.
! 1947:
! 1948: \subsecidx{quadunit}$(x)$: fundamental unit\sidx{fundamental units} of the
! 1949: real quadratic field $\Q(\sqrt x)$ where $x$ is the positive discriminant
! 1950: of the field. If $x$ is not a fundamental discriminant, this probably gives
! 1951: the fundamental unit of the corresponding order. $x$ must be of type
! 1952: integer, and the result is a quadratic number.
! 1953:
! 1954: \syn{fundunit}{x}.
! 1955:
! 1956: \subsecidx{removeprimes}$(\{x=[\,]\})$: removes the primes listed in $x$ from
! 1957: the prime number table. In particular \kbd{removeprimes(addprimes)} empties
! 1958: the extra prime table. $x$ can also be a single integer. List the current
! 1959: extra primes if $x$ is omitted.
! 1960:
! 1961: \syn{removeprimes}{x}.
! 1962:
! 1963: \subsecidx{sigma}$(x,\{k=1\})$: sum of the $k^{\text{th}}$ powers of the
! 1964: positive divisors of $|x|$. $x$ must be of type integer.
! 1965:
! 1966: \syn{sumdiv}{x} (= $\teb{sigma}(x)$) or $\teb{gsumdivk}(x,k)$ (=
! 1967: $\teb{sigma}(x,k)$), where $k$ is a C long integer.
! 1968:
! 1969: \subsecidx{sqrtint}$(x)$: integer square root of $x$, which must be of PARI
! 1970: type integer. The result is non-negative and rounded towards zero. A
! 1971: negative $x$ is allowed, and the result in that case is \kbd{I*sqrtint(-x)}.
! 1972:
! 1973: \syn{racine}{x}.
! 1974:
! 1975: \subsecidx{znlog}$(x,g)$: $g$ must be a primitive root mod a prime $p$, and
! 1976: the result is the discrete log of $x$ in the multiplicative group
! 1977: $(\Z/p\Z)^*$. This function uses a simple-minded combination of
! 1978: Pohlig-Hellman algorithm and Shanks baby-step/giant-step which requires
! 1979: $O(\sqrt{q})$ storage, where $q$ is the largest prime factor of $p-1$. Hence
! 1980: it cannot be used when the largest prime divisor of $p-1$ is greater than
! 1981: about $10^{13}$.
! 1982:
! 1983: \syn{znlog}{x,g}.
! 1984:
! 1985: \subsecidx{znorder}$(x)$: $x$ must be an integer mod $n$, and the result is the
! 1986: order of $x$ in the multiplicative group $(\Z/n\Z)^*$. Returns an error if $x$
! 1987: is not invertible.
! 1988:
! 1989: \syn{order}{x}.
! 1990:
! 1991: \subsecidx{znprimroot}$(n)$: returns a primitive root (generator) of
! 1992: $(\Z/n\Z)^*$, whenever this latter group is cyclic ($n = 4$ or $n = 2p^k$ or
! 1993: $n = p^k$, where $p$ is an odd prime and $k \geq 0$).
! 1994:
! 1995: \syn{gener}{x}.
! 1996:
! 1997: \subsecidx{znstar}$(n)$: gives the structure of the multiplicative group
! 1998: $(\Z/n\Z)^*$ as a 3-component row vector $v$, where $v[1]=\phi(n)$ is the
! 1999: order of that group, $v[2]$ is a $k$-component row-vector $d$ of integers
! 2000: $d[i]$ such that $d[i]>1$ and $d[i]\mid d[i-1]$ for $i \ge 2$ and
! 2001: $(\Z/n\Z)^* \simeq \prod_{i=1}^k(\Z/d[i]\Z)$, and $v[3]$ is a $k$-component row
! 2002: vector giving generators of the image of the cyclic groups $\Z/d[i]\Z$.
! 2003:
! 2004: \syn{znstar}{n}.
! 2005:
! 2006: \section{Functions related to elliptic curves}
! 2007:
! 2008: We have implemented a number of functions which are useful for number
! 2009: theorists working on elliptic curves. We always use \idx{Tate}'s notations.
! 2010: The functions assume that the curve is given by a general Weierstrass
! 2011: model\sidx{Weierstrass equation}
! 2012: $$
! 2013: y^2+a_1xy+a_3y=x^3+a_2x^2+a_4x+a_6,
! 2014: $$
! 2015: where a priori the $a_i$ can be of any scalar type. This curve can be
! 2016: considered as a five-component vector \kbd{E=[a1,a2,a3,a4,a6]}. Points on
! 2017: \kbd{E} are represented as two-component vectors \kbd{[x,y]}, except for the
! 2018: point at infinity, i.e.~the identity element of the group law, represented by
! 2019: the one-component vector \kbd{[0]}.
! 2020:
! 2021: It is useful to have at one's disposal more information. This is given by
! 2022: the function \tet{ellinit} (see there), which usually gives a 19 component
! 2023: vector (which we will call a long vector in this section). If a specific flag
! 2024: is added, a vector with only 13 component will be output (which we will call
! 2025: a medium vector). A medium vector just gives the first 13 components of the
! 2026: long vector corresponding to the same curve, but is of course faster to
! 2027: compute. The following \idx{member functions} are available to deal with the
! 2028: output of \kbd{ellinit}:
! 2029: \settabs\+xxxxxxxxxxxxxxxxxx&: &\cr
! 2030:
! 2031: \+ \kbd{a1}--\kbd{a6}, \kbd{b2}--\kbd{b8}, \kbd{c4}--\kbd{c6} &: &
! 2032: coefficients of the elliptic curve.\cr
! 2033:
! 2034: \+ \tet{area} &: & volume of the complex lattice defining $E$.\cr
! 2035:
! 2036: \+ \tet{disc} &: & discriminant of the curve.\cr
! 2037:
! 2038: \+ \tet{j} &: & $j$-invariant of the curve.\cr
! 2039:
! 2040: \+ \tet{omega}&: & $[\omega_1,\omega_2]$, periods forming a basis of
! 2041: the complex lattice defining $E$ ($\omega_1$ is the\cr
! 2042:
! 2043: \+ & & real period, and $\omega_2/\omega_1$ belongs to
! 2044: Poincar\'e's half-plane).\cr
! 2045:
! 2046: \+ \tet{eta} &: & quasi-periods $[\eta_1, \eta_2]$, such that
! 2047: $\eta_1\omega_2-\eta_2\omega_1=i\pi$.\cr
! 2048:
! 2049: \+ \tet{roots}&: & roots of the associated Weierstrass equation.\cr
! 2050:
! 2051: \+ \tet{tate} &: & $[u^2,u,v]$ in the notation of Tate.\cr
! 2052:
! 2053: \+ \tet{w} &: & Mestre's $w$ (this is technical).\cr
! 2054:
! 2055: Their use is best described by an example: assume that $E$ was output by
! 2056: \kbd{ellinit}, then typing \kbd{$E$.disc} will retrieve the curve's
! 2057: discriminant. The member functions \kbd{area}, \kbd{eta} and \kbd{omega} are
! 2058: only available for curves over $\Q$. Conversely, \kbd{tate} and \kbd{w} are
! 2059: only available for curves defined over $\Q_p$.\smallskip
! 2060:
! 2061: Some functions, in particular those relative to height computations (see
! 2062: \kbd{ellheight}) require also that the curve be in minimal Weierstrass
! 2063: form. This is achieved by the function \kbd{ellglobalred}.
! 2064:
! 2065: All functions related to elliptic curves share the prefix \kbd{ell}, and the
! 2066: precise curve we are interested in is always the first argument, in either
! 2067: one of the three formats discussed above, unless otherwise specified. For
! 2068: instance, in functions which do not use the extra information given by long
! 2069: vectors, the curve can be given either as a five-component vector, or by one
! 2070: of the longer vectors computed by \kbd{ellinit}.
! 2071:
! 2072: \subsecidx{elladd}$(E,z1,z2)$: sum of the points $z1$ and $z2$ on the
! 2073: elliptic curve corresponding to the vector $E$.
! 2074:
! 2075: \syn{addell}{E,z1,z2}.
! 2076:
! 2077: \subsecidx{ellak}$(E,n)$: computes the coefficient $a_n$ of the
! 2078: $L$-function of the elliptic curve $E$, i.e.~in principle coefficients of a
! 2079: newform of weight 2 assuming \idx{Taniyama-Weil conjecture} (which is now
! 2080: known to hold in full generality thanks to the work of \idx{Breuil},
! 2081: \idx{Conrad}, \idx{Diamond}, \idx{Taylor} and \idx{Wiles}). $E$ must be a
! 2082: medium or long vector of the type given by \kbd{ellinit}. For this function
! 2083: to work for every $n$ and not just those prime to the conductor, $E$ must
! 2084: be a minimal Weierstrass equation. If this is not the case, use the
! 2085: function \kbd{ellglobalred} first before using \kbd{ellak}.
! 2086:
! 2087: \syn{akell}{E,n}.
! 2088:
! 2089: \subsecidx{ellan}$(E,n)$: computes the vector of the first $n$ $a_k$
! 2090: corresponding to the elliptic curve $E$. All comments in \kbd{ellak}
! 2091: description remain valid.
! 2092:
! 2093: \syn{anell}{E,n}, where $n$ is a C integer.
! 2094:
! 2095: \subsecidx{ellap}$(E,p,\{\fl=0\})$: computes the $a_p$ corresponding to the
! 2096: elliptic curve $E$ and the prime number $p$. These are defined by the
! 2097: equation $\#E(\F_p) = p+1 - a_p$, where $\#E(\F_p)$ stands for the number
! 2098: of points of the curve $E$ over the finite field $\F_p$. When $\fl$ is $0$,
! 2099: this uses the baby-step giant-step method and a trick due to Mestre. This
! 2100: runs in time $O(p^{1/4})$ and requires $O(p^{1/4})$ storage, hence becomes
! 2101: unreasonable when $p$ has about 30 digits.
! 2102:
! 2103: If $\fl$ is $1$, computes the $a_p$ as a sum of Legendre symbols. This is
! 2104: slower than the previous method as soon as $p$ is greater than 100, say.
! 2105:
! 2106: No checking is done that $p$ is indeed prime. $E$ must be a medium or long
! 2107: vector of the type given by \kbd{ellinit}, defined over $\Q$, $\F_p$ or
! 2108: $\Q_p$. $E$ must be given by a Weierstrass equation minimal at $p$.
! 2109:
! 2110: \syn{ellap0}{E,p,\fl}. Also available are $\teb{apell}(E,p)$, corresponding
! 2111: to $\fl=0$, and $\teb{apell2}(E,p)$ ($\fl=1$).
! 2112:
! 2113: \subsecidx{ellbil}$(E,z1,z2)$: if $z1$ and $z2$ are points on the elliptic
! 2114: curve $E$, this function computes the value of the canonical bilinear form on
! 2115: $z1$, $z2$:
! 2116: $$
! 2117: \kbd{ellheight}(E,z1\kbd{+}z2) - \kbd{ellheight}(E,z1) - \kbd{ellheight}(E,z2)
! 2118: $$
! 2119: where \kbd{+} denotes of course addition on $E$. In addition, $z1$ or $z2$
! 2120: (but not both) can be vectors or matrices. Note that this is equal to twice
! 2121: some normalizations. $E$ is assumed to be integral, given by a minimal model.
! 2122:
! 2123: \syn{bilhell}{E,z1,z2,\var{prec}}.
! 2124:
! 2125: \subsecidx{ellchangecurve}$(E,v)$: changes the data for the elliptic curve $E$
! 2126: by changing the coordinates using the vector \kbd{v=[u,r,s,t]}, i.e.~if $x'$
! 2127: and $y'$ are the new coordinates, then $x=u^2x'+r$, $y=u^3y'+su^2x'+t$.
! 2128: The vector $E$ must be a medium or long vector of the type given by
! 2129: \kbd{ellinit}.
! 2130:
! 2131: \syn{coordch}{E,v}.
! 2132:
! 2133: \subsecidx{ellchangepoint}$(x,v)$: changes the coordinates of the point or
! 2134: vector of points $x$ using the vector \kbd{v=[u,r,s,t]}, i.e.~if $x'$ and
! 2135: $y'$ are the new coordinates, then $x=u^2x'+r$, $y=u^3y'+su^2x'+t$ (see also
! 2136: \kbd{ellchangecurve}).
! 2137:
! 2138: \syn{pointch}{x,v}.
! 2139:
! 2140: \subsecidx{elleisnum}$(E,k,\{\fl=0\})$: $E$ being an elliptic curve as
! 2141: output by \kbd{ellinit} (or, alternatively, given by a 2-component vector
! 2142: $[\omega_1,\omega_2]$), and $k$ being an even positive integer, computes
! 2143: the numerical value of the Eisenstein series of weight $k$ at $E$. When
! 2144: \fl\ is non-zero and $k=4$ or 6, returns $g_2$ or $g_3$ with the correct
! 2145: normalization.
! 2146:
! 2147: \syn{elleisnum}{E,k,\fl}.
! 2148:
! 2149: \subsecidx{elleta}$(om)$: returns the two-component row vector
! 2150: $[\eta_1,\eta_2]$ of quasi-periods associated to $\kbd{om} = [\omega_1,
! 2151: \omega_2]$
! 2152:
! 2153: \syn{elleta}{om, \var{prec}}
! 2154:
! 2155: \subsecidx{ellglobalred}$(E)$: calculates the arithmetic conductor, the global
! 2156: minimal model of $E$ and the global \idx{Tamagawa number} $c$. Here $E$ is an
! 2157: elliptic curve given by a medium or long vector of the type given by
! 2158: \kbd{ellinit}, {\it and is supposed to have all its coefficients $a_i$ in}
! 2159: $\Q$. The result is a 3 component vector $[N,v,c]$. $N$ is the arithmetic
! 2160: conductor of the curve, $v$ is itself a vector $[u,r,s,t]$ with rational
! 2161: components. It gives a coordinate change for $E$ over $\Q$ such that the
! 2162: resulting model has integral coefficients, is everywhere minimal, $a_1$ is 0
! 2163: or 1, $a_2$ is 0, 1 or $-1$ and $a_3$ is 0 or 1. Such a model is unique, and
! 2164: the vector $v$ is unique if we specify that $u$ is positive. To get the new
! 2165: model, simply type \kbd{ellchangecurve(E,v)}. Finally $c$ is the product of
! 2166: the local Tamagawa numbers $c_p$, a quantity which enters in the
! 2167: \idx{Birch and Swinnerton-Dyer conjecture}.
! 2168:
! 2169: \syn{globalreduction}{E}.
! 2170:
! 2171: \subsecidx{ellheight}$(E,z,\{\fl=0\})$: global \idx{N\'eron-Tate height} of
! 2172: the point $z$ on the elliptic curve $E$. The vector $E$ must be a long vector
! 2173: of the type given by \kbd{ellinit}, with $\fl=1$. If $\fl=0$, this
! 2174: computation is done using sigma and theta-functions and a trick due to J.
! 2175: Silverman. If $\fl=1$, use Tate's $4^n$ algorithm, which is much slower.
! 2176: $E$ is assumed to be integral, given by a minimal model.
! 2177:
! 2178: \syn{ellheight0}{E,z,\fl,\var{prec}}. The Archimedean
! 2179: contribution alone is given by the library function
! 2180: $\teb{hell}(E,z,\var{prec})$.
! 2181: Also available are $\teb{ghell}(E,z,\var{prec})$ ($\fl=0$) and
! 2182: $\teb{ghell2}(E,z,\var{prec})$ ($\fl=1$).
! 2183:
! 2184: \subsecidx{ellheightmatrix}$(E,x)$: $x$ being a vector of points, this
! 2185: function outputs the Gram matrix of $x$ with respect to the N\'eron-Tate
! 2186: height, in other words, the $(i,j)$ component of the matrix is equal to
! 2187: \kbd{ellbil($E$,x[$i$],x[$j$])}. The rank of this matrix, at least in some
! 2188: approximate sense, gives the rank of the set of points, and if $x$ is a
! 2189: basis of the \idx{Mordell-Weil group} of $E$, its determinant is equal to
! 2190: the regulator of $E$. Note that this matrix should be divided by 2 to be in
! 2191: accordance with certain normalizations. $E$ is assumed to be integral,
! 2192: given by a minimal model.
! 2193:
! 2194: \syn{mathell}{E,x,\var{prec}}.
! 2195:
! 2196: \subsecidx{ellinit}$(E,\{\fl=0\})$: computes some fixed data concerning the
! 2197: elliptic curve given by the five-component vector $E$, which will be
! 2198: essential for most further computations on the curve. The result is a
! 2199: 19-component vector E (called a long vector in this section), shortened
! 2200: to 13 components (medium vector) if $\fl=1$. Both contain the
! 2201: following information in the first 13 components:
! 2202: %
! 2203: $$ a_1,a_2,a_3,a_4,a_6,b_2,b_4,b_6,b_8,c_4,c_6,\Delta,j.$$
! 2204: %
! 2205: In particular, the discriminant is $E[12]$ (or \kbd{$E$.disc}), and the
! 2206: $j$-invariant is $E[13]$ (or \kbd{$E$.j}).
! 2207:
! 2208: The other six components are only present if $\fl$ is $0$ (or omitted!).
! 2209: Their content depends on whether the curve is defined over $\R$ or not:
! 2210: \smallskip
! 2211: $\bullet$ When $E$ is defined over $\R$, $E[14]$ (\kbd{$E$.roots}) is a
! 2212: vector whose three components contain the roots of the associated Weierstrass
! 2213: equation. If the roots are all real, then they are ordered by decreasing
! 2214: value. If only one is real, it is the first component of $E[14]$.
! 2215:
! 2216: $E[15]$ (\kbd{$E$.omega[1]}) is the real period of $E$ (integral of
! 2217: $dx/(2y+a_1x+a_3)$ over the connected component of the identity element of
! 2218: the real points of the curve), and $E[16]$ (\kbd{$E$.omega[2]}) is a complex
! 2219: period. In other words, $\omega_1=E[15]$ and $\omega_2=E[16]$ form a basis of
! 2220: the complex lattice defining $E$ (\kbd{$E$.omega}), with
! 2221: $\tau=\dfrac{\omega_2}{\omega_1}$ having positive imaginary part.
! 2222:
! 2223: $E[17]$ and $E[18]$ are the corresponding values $\eta_1$ and $\eta_2$ such
! 2224: that $\eta_1\omega_2-\eta_2\omega_1=i\pi$, and both can be retrieved by
! 2225: typing \kbd{$E$.eta} (as a row vector whose components are the $\eta_i$).
! 2226:
! 2227: Finally, $E[19]$ (\kbd{$E$.area}) is the volume of the complex lattice defining
! 2228: $E$.\smallskip
! 2229:
! 2230: $\bullet$ When $E$ is defined over $\Q_p$, the $p$-adic valuation of $j$
! 2231: must be negative. Then $E[14]$ (\kbd{$E$.roots}) is the vector with a single
! 2232: component equal to the $p$-adic root of the associated Weierstrass equation
! 2233: corresponding to $-1$ under the Tate parametrization.
! 2234:
! 2235: $E[15]$ is equal to the square of the $u$-value, in the notation of Tate.
! 2236:
! 2237: $E[16]$ is the $u$-value itself, if it belongs to $\Q_p$, otherwise zero.
! 2238:
! 2239: $E[17]$ is the value of Tate's $q$ for the curve $E$.
! 2240:
! 2241: \kbd{$E$.tate} will yield the three-component vector $[u^2,u,q]$.
! 2242:
! 2243: $E[18]$ (\kbd{$E$.w}) is the value of Mestre's $w$ (this is technical), and
! 2244: $E[19]$ is arbitrarily set equal to zero.
! 2245: \smallskip
! 2246: For all other base fields or rings, the last six components are arbitrarily
! 2247: set equal to zero (see also the description of member functions related to
! 2248: elliptic curves at the beginning of this section).
! 2249:
! 2250: \syn{ellinit0}{E,\fl,\var{prec}}. Also available are
! 2251: $\teb{initell}(E,\var{prec})$ ($\fl=0$) and
! 2252: $\teb{smallinitell}(E,\var{prec})$ ($\fl=1$).
! 2253:
! 2254: \subsecidx{ellisoncurve}$(E,z)$: gives 1 (i.e.~true) if the point $z$ is on
! 2255: the elliptic curve $E$, 0 otherwise. If $E$ or $z$ have imprecise coefficients,
! 2256: an attempt is made to take this into account, i.e.~an imprecise equality is
! 2257: checked, not a precise one.
! 2258:
! 2259: \syn{oncurve}{E,z}, and the result is a \kbd{long}.
! 2260:
! 2261: \subsecidx{ellj}$(x)$: elliptic $j$-invariant. $x$ must be a complex number
! 2262: with positive imaginary part, or convertible into a power series or a
! 2263: $p$-adic number with positive valuation.
! 2264:
! 2265: \syn{jell}{x,\var{prec}}.
! 2266:
! 2267: \subsecidx{elllocalred}$(E,p)$: calculates the \idx{Kodaira} type of the
! 2268: local fiber of the elliptic curve $E$ at the prime $p$.
! 2269: $E$ must be given by a medium or
! 2270: long vector of the type given by \kbd{ellinit}, and is assumed to have all
! 2271: its coefficients $a_i$ in $\Z$. The result is a 4-component vector
! 2272: $[f,kod,v,c]$. Here $f$ is the exponent of $p$ in the arithmetic conductor of
! 2273: $E$, and $kod$ is the Kodaira type which is coded as follows:
! 2274:
! 2275: 1 means good reduction (type I$_0$), 2, 3 and 4 mean types II, III and IV
! 2276: respectively, $4+\nu$ with $\nu>0$ means type I$_\nu$;
! 2277: finally the opposite values $-1$, $-2$, etc.~refer to the starred types
! 2278: I$_0^*$, II$^*$, etc. The third component $v$ is itself a vector $[u,r,s,t]$
! 2279: giving the coordinate changes done during the local reduction. Normally, this
! 2280: has no use if $u$ is 1, that is, if the given equation was already minimal.
! 2281: Finally, the last component $c$ is the local \idx{Tamagawa number} $c_p$.
! 2282:
! 2283: \syn{localreduction}{E,p}.
! 2284:
! 2285: \subsecidx{elllseries}$(E,s,\{A=1\})$: $E$ being a medium or long vector
! 2286: given by \kbd{ellinit}, this computes the value of the L-series of $E$ at
! 2287: $s$. It is assumed that $E$ is a minimal model over $\Z$ and that the curve
! 2288: is a modular elliptic curve. The optional parameter $A$ is a cutoff point for
! 2289: the integral, which must be chosen close to 1 for best speed. The result
! 2290: must be independent of $A$, so this allows some internal checking of the
! 2291: function.
! 2292:
! 2293: Note that if the conductor of the curve is large, say greater than $10^{12}$,
! 2294: this function will take an unreasonable amount of time since it uses an
! 2295: $O(N^{1/2})$ algorithm.
! 2296:
! 2297: \syn{lseriesell}{E,s,A,\var{prec}} where $\var{prec}$ is a \kbd{long} and an
! 2298: omitted $A$ is coded as \kbd{NULL}.
! 2299:
! 2300: \subsecidx{ellorder}$(E,z)$: gives the order of the point $z$ on the elliptic
! 2301: curve $E$ if it is a torsion point, zero otherwise. In the present version
! 2302: \vers, this is implemented only for elliptic curves defined over $\Q$.
! 2303:
! 2304: \syn{orderell}{E,z}.
! 2305:
! 2306: \subsecidx{ellordinate}$(E,x)$: gives a 0, 1 or 2-component vector containing
! 2307: the $y$-coordinates of the points of the curve $E$ having $x$ as
! 2308: $x$-coordinate.
! 2309:
! 2310: \syn{ordell}{E,x}.
! 2311:
! 2312: \subsecidx{ellpointtoz}$(E,z)$: if $E$ is an elliptic curve with coefficients
! 2313: in $\R$, this computes a complex number $t$ (modulo the lattice defining
! 2314: $E$) corresponding to the point $z$, i.e.~such that, in the standard
! 2315: Weierstrass model, $\wp(t)=z[1],\wp'(t)=z[2]$. In other words, this is the
! 2316: inverse function of \kbd{ellztopoint}.
! 2317:
! 2318: If $E$ has coefficients in $\Q_p$, then either Tate's $u$ is in $\Q_p$, in
! 2319: which case the output is a $p$-adic number $t$ corresponding to the point $z$
! 2320: under the Tate parametrization, or only its square is, in which case the
! 2321: output is $t+1/t$. $E$ must be a long vector output by \kbd{ellinit}.
! 2322:
! 2323: \syn{zell}{E,z,\var{prec}}.
! 2324:
! 2325: \subsecidx{ellpow}$(E,z,n)$: computes $n$ times the point $z$ for the
! 2326: group law on the elliptic curve $E$. Here, $n$ can be in $\Z$, or $n$
! 2327: can be a complex quadratic integer if the curve $E$ has complex multiplication
! 2328: by $n$ (if not, an error message is issued).
! 2329:
! 2330: \syn{powell}{E,z,n}.
! 2331:
! 2332: \subsecidx{ellrootno}$(E,\{p=1\})$: $E$ being a medium or long vector given
! 2333: by \kbd{ellinit}, this computes the local (if $p\neq 1$) or global (if $p=1$)
! 2334: root number of the L-series of the elliptic curve $E$. Note that the global
! 2335: root number is the sign of the functional equation and conjecturally is the
! 2336: parity of the rank of the \idx{Mordell-Weil group}.
! 2337: The equation for $E$ must have
! 2338: coefficients in $\Q$ but need \var{not} be minimal.
! 2339:
! 2340: \syn{ellrootno}{E,p} and the result (equal to $\pm1$) is a \kbd{long}.
! 2341:
! 2342: \subsecidx{ellsigma}$(E,z,\{\fl=0\})$: value of the Weierstrass $\sigma$
! 2343: function of the lattice associated to $E$ as given by \kbd{ellinit}
! 2344: (alternatively, $E$ can be given as a lattice $[\omega_1,\omega_2]$).
! 2345:
! 2346: If $\fl=1$, computes an (arbitrary) determination of $\log(\sigma(z))$.
! 2347:
! 2348: If $\fl=2,3$, same using the product expansion instead of theta series.
! 2349: \syn{ellsigma}{E,z,\fl}
! 2350:
! 2351: \subsecidx{ellsub}$(E,z1,z2)$: difference of the points $z1$ and $z2$ on the
! 2352: elliptic curve corresponding to the vector $E$.
! 2353:
! 2354: \syn{subell}{E,z1,z2}.
! 2355:
! 2356: \subsecidx{elltaniyama}$(E)$: computes the modular parametrization of the
! 2357: elliptic curve $E$, where $E$ is given in the (long or medium) format output
! 2358: by \kbd{ellinit}, in the form of a two-component vector $[u,v]$ of power
! 2359: series, given to the current default series precision. This vector is
! 2360: characterized by the following two properties. First the point $(x,y)=(u,v)$
! 2361: satisfies the equation of the elliptic curve. Second, the differential
! 2362: $du/(2v+a_1u+a_3)$ is equal to $f(z)dz$, a differential form on
! 2363: $H/\Gamma_0(N)$ where $N$ is the conductor of the curve. The variable used in
! 2364: the power series for $u$ and $v$ is $x$, which is implicitly understood to be
! 2365: equal to $\exp(2i\pi z)$. It is assumed that the curve is a \var{strong}
! 2366: \idx{Weil curve}, and the Manin constant is equal to 1. The equation of
! 2367: the curve $E$ must be minimal (use \kbd{ellglobalred} to get a minimal
! 2368: equation).
! 2369:
! 2370: \syn{taniyama}{E}, and the precision of the result is determined by the
! 2371: global variable \kbd{precdl}.
! 2372:
! 2373: \subsecidx{elltors}$(E,\{\fl=0\})$: if $E$ is an elliptic curve {\it defined
! 2374: over $\Q$}, outputs the torsion subgroup of $E$ as a 3-component vector
! 2375: \kbd{[t,v1,v2]}, where \kbd{t} is the order of the torsion group, \kbd{v1}
! 2376: gives the structure of the torsion group as a product of cyclic groups
! 2377: (sorted by decreasing order), and \kbd{v2} gives generators for these cyclic
! 2378: groups. $E$ must be a long vector as output by \kbd{ellinit}.
! 2379:
! 2380: \bprog
! 2381: ? E = ellinit([0,0,0,-1,0]);
! 2382: ? elltors(E)
! 2383: %1 = [4, [2, 2], [[0, 0], [1, 0]]]
! 2384: @eprog
! 2385: Here, the torsion subgroup is isomorphic to $\Z/2\Z \times \Z/2\Z$, with
! 2386: generators $[0,0]$ and $[1,0]$.
! 2387:
! 2388: If $\fl = 0$, use Doud's algorithm~: bound torsion by computing $\#E(\F_p)$
! 2389: for small primes of good reduction, then look for torsion points using
! 2390: Weierstrass parametrization (and Mazur's classification).
! 2391:
! 2392: If $\fl = 1$, use Lutz--Nagell (\var{much} slower), $E$ is allowed to be a
! 2393: medium vector.
! 2394:
! 2395: \syn{elltors0}{E,flag}.
! 2396:
! 2397: \subsecidx{ellwp}$(E,\{z=x\},\{\fl=0\})$:
! 2398:
! 2399: Computes the value at $z$ of the Weierstrass $\wp$ function attached to the
! 2400: elliptic curve $E$ as given by \kbd{ellinit} (alternatively, $E$ can be
! 2401: given as a lattice $[\omega_1,\omega_2]$).
! 2402:
! 2403: If $z$ is omitted or is a simple variable, computes the \var{power series}
! 2404: expansion in $z$ (starting $z^{-2}+O(z^2)$). The number of terms to an
! 2405: \var{even} power in the expansion is the default serieslength in GP, and the
! 2406: second argument (C long integer) in library mode.
! 2407:
! 2408: Optional \fl\ is (for now) only taken into account when $z$ is numeric, and
! 2409: means 0: compute only $\wp(z)$, 1: compute $[\wp(z),\wp'(z)]$.
! 2410:
! 2411: \syn{ellwp0}{E,z,\fl,\var{prec},\var{precdl}}. Also available is
! 2412: \teb{weipell}$(E,\var{precdl})$ for the power series (in
! 2413: $x=\kbd{polx[0]}$).
! 2414:
! 2415: \subsecidx{ellzeta}$(E,z)$: value of the Weierstrass $\zeta$ function of the
! 2416: lattice associated to $E$ as given by \kbd{ellinit} (alternatively, $E$ can
! 2417: be given as a lattice $[\omega_1,\omega_2]$).
! 2418:
! 2419: \syn{ellzeta}{E,z}.
! 2420:
! 2421: \subsecidx{ellztopoint}$(E,z)$: $E$ being a long vector, computes the
! 2422: coordinates $[x,y]$ on the curve $E$ corresponding to the complex number $z$.
! 2423: Hence this is the inverse function of \kbd{ellpointtoz}. In other words, if
! 2424: the curve is put in Weierstrass form, $[x,y]$ represents the
! 2425: \idx{Weierstrass $\wp$-function} and its derivative.
! 2426: If $z$ is in the lattice defining $E$ over
! 2427: $\C$, the result is the point at infinity $[0]$.
! 2428:
! 2429: \syn{pointell}{E,z,\var{prec}}.
! 2430:
! 2431: \section{Functions related to general number fields}
! 2432:
! 2433: In this section can be found functions which are used almost exclusively for
! 2434: working in general number fields. Other less specific functions can be found
! 2435: in the next section on polynomials. Functions related to quadratic number
! 2436: fields can be found in the section \secref{se:arithmetic} (Arithmetic
! 2437: functions).
! 2438:
! 2439: \noindent We shall use the following conventions:
! 2440:
! 2441: $\bullet$ $\tev{nf}$ denotes a number field, i.e.~a 9-component vector
! 2442: in the format output by \tet{nfinit}. This contains the basic arithmetic data
! 2443: associated to the number field: signature, maximal order, discriminant, etc.
! 2444:
! 2445: $\bullet$ $\tev{bnf}$ denotes a big number field, i.e.~a 10-component
! 2446: vector in the format output by \tet{bnfinit}. This contains $\var{nf}$ and
! 2447: the deeper invariants of the field: units, class groups, as well as a lot of
! 2448: technical data necessary for some complex fonctions like \kbd{bnfisprincipal}.
! 2449:
! 2450: $\bullet$ $\tev{bnr}$ denotes a big ``ray number field'', i.e.~some data
! 2451: structure output by \kbd{bnrinit}, even more complicated than $\var{bnf}$,
! 2452: corresponding to the ray class group structure of the field, for some
! 2453: modulus.
! 2454:
! 2455: $\bullet$ $\tev{rnf}$ denotes a relative number field (see below).
! 2456: \smallskip
! 2457:
! 2458: $\bullet$ $\tev{ideal}$ can mean any of the following:
! 2459:
! 2460: \quad -- a $\Z$-basis, in \idx{Hermite normal form}
! 2461: (HNF) or not. In this case $x$ is a square matrix.
! 2462:
! 2463: \quad -- an \tev{idele}, i.e.~a 2-component vector, the first being an
! 2464: ideal given as a $\Z$--basis, the second being a $r_1+r_2$-component row
! 2465: vector giving the complex logarithmic Archimedean information.
! 2466:
! 2467: \quad -- a $\Z_K$-generating system for an ideal.
! 2468:
! 2469: \quad -- a \var{column} vector $x$ expressing an element of the number field
! 2470: on the integral basis, in which case the ideal is treated as being the
! 2471: principal idele (or ideal) generated by $x$.
! 2472:
! 2473: \quad -- a prime ideal, i.e.~a 5-component vector in the format output by
! 2474: \kbd{idealprimedec}.
! 2475:
! 2476: \quad -- a polmod $x$, i.e.~an algebraic integer, in which case the ideal
! 2477: is treated as being the principal idele generated by $x$.
! 2478:
! 2479: \quad -- an integer or a rational number, also treated as a principal idele.
! 2480:
! 2481: $\bullet$ a \var{{character}} on the Abelian group
! 2482: $\bigoplus (\Z/N_i\Z) g_i$
! 2483: is given by a row vector $\chi = [a_1,\ldots,a_n]$ such that
! 2484: $\chi(\prod g_i^{n_i}) = exp(2i\pi\sum a_i n_i / N_i)$.
! 2485:
! 2486:
! 2487: \misctitle{Warnings:}
! 2488:
! 2489: 1) An element in $\var{nf}$ can be expressed either as a polmod or as a
! 2490: vector of components on the integral basis \kbd{\var{nf}.zk}. It is absolutely
! 2491: essential that all such vectors be \var{column} vectors.
! 2492:
! 2493: 2) When giving an ideal by a $\Z_K$ generating system to a function expecting
! 2494: an ideal, it must be ensured that the function understands that it is a
! 2495: $\Z_K$-generating system and not a $\Z$-generating system. When the number of
! 2496: generators is strictly less than the degree of the field, there is no
! 2497: ambiguity and the program assumes that one is giving a $\Z_K$-generating set.
! 2498: When the number of generators is greater than or equal to the degree of the
! 2499: field, however, the program assumes on the contrary that you are giving a
! 2500: $\Z$-generating set. If this is not the case, you \var{must} absolutely
! 2501: change it into a $\Z$-generating set, the simplest manner being to use
! 2502: \kbd{idealhnf(\var{nf},$x$)}.
! 2503:
! 2504: Concerning relative extensions, some additional definitions are necessary.
! 2505:
! 2506: $\bullet$ A \var{{relative matrix}} will be a matrix whose entries are
! 2507: elements of a (given) number field $\var{nf}$, always expressed as column
! 2508: vectors on the integral basis \kbd{\var{nf}.zk}. Hence it is a matrix of
! 2509: vectors.
! 2510:
! 2511: $\bullet$ An \tev{ideal list} will be a row vector of (fractional)
! 2512: ideals of the number field $\var{nf}$.
! 2513:
! 2514: $\bullet$ A \tev{pseudo-matrix} will be a pair $(A,I)$ where $A$ is a
! 2515: relative matrix and $I$ an ideal list whose length is the same as the number
! 2516: of columns of $A$. This pair will be represented by a 2-component row vector.
! 2517:
! 2518: $\bullet$ The \tev{module} generated by a pseudo-matrix $(A,I)$ is
! 2519: the sum $\sum_i{\Bbb a}_jA_j$ where the ${\Bbb a}_j$ are the ideals of $I$
! 2520: and $A_j$ is the $j$-th column of $A$.
! 2521:
! 2522: $\bullet$ A pseudo-matrix $(A,I)$ is a \tev{pseudo-basis} of the module
! 2523: it generates if $A$ is a square matrix with non-zero determinant and all the
! 2524: ideals of $I$ are non-zero. We say that it is in Hermite Normal
! 2525: Form\sidx{Hermite normal form} (HNF) if it is upper triangular and all the
! 2526: elements of the diagonal are equal to 1.
! 2527:
! 2528: $\bullet$ The \var{determinant} of a pseudo-basis $(A,I)$ is the ideal
! 2529: equal to the product of the determinant of $A$ by all the ideals of $I$. The
! 2530: determinant of a pseudo-matrix is the determinant of any pseudo-basis of the
! 2531: module it generates.
! 2532:
! 2533: Finally, when defining a relative extension, the base field should be
! 2534: defined by a variable having a lower priority (i.e.~a higher number)
! 2535: than the variable defining the extension. For example, under GP you can
! 2536: use the variable name $y$ (or $t$) to define the base field, and the
! 2537: variable name $x$ to define the relative extension.
! 2538:
! 2539: Now a last set of definitions concerning the way big ray number fields
! 2540: (or \var{bnr}) are input, using class field theory.
! 2541: These are defined by a triple
! 2542: $a1$, $a2$, $a3$, where the defining set $[a1,a2,a3]$ can have any of the
! 2543: following forms: $[\var{bnr}]$, $[\var{bnr},\var{subgroup}]$,
! 2544: $[\var{bnf},\var{module}]$, $[\var{bnf},\var{module},\var{subgroup}]$, where:
! 2545:
! 2546: $\bullet$ $\var{bnf}$ is as output by \kbd{bnfclassunit} or \kbd{bnfinit},
! 2547: where units are mandatory unless the ideal is trivial; \var{bnr} by
! 2548: \kbd{bnrclass} (with $\fl>0$) or \kbd{bnrinit}. This is the ground field.
! 2549:
! 2550: $\bullet$ \var{module} is either an ideal in any form (see above) or a
! 2551: two-component row vector containing an ideal and an $r_1$-component row
! 2552: vector of flags indicating which real Archimedean embeddings to take in the
! 2553: module.
! 2554:
! 2555: $\bullet$ \var{subgroup} is the HNF matrix of a subgroup of the ray class group
! 2556: of the ground field for the modulus \var{module}. This is input as a square
! 2557: matrix expressing generators of a subgroup of the ray class group
! 2558: \kbd{\var{bnr}.clgp} on the given generators.
! 2559:
! 2560: The corresponding \var{bnr} is then the subfield of the ray class field of the
! 2561: ground field for the given modulus, associated to the given subgroup.
! 2562:
! 2563: All the functions which are specific to relative extensions, number fields,
! 2564: big number fields, big number rays, share the prefix \kbd{rnf}, \kbd{nf},
! 2565: \kbd{bnf}, \kbd{bnr} respectively. They are meant to take as first argument a
! 2566: number field of that precise type, respectively output by \kbd{rnfinit},
! 2567: \kbd{nfinit}, \kbd{bnfinit}, and \kbd{bnrinit}.
! 2568:
! 2569: However, and even though it may not be specified in the descriptions of the
! 2570: functions below, it is permissible, if the function expects a $\var{nf}$, to
! 2571: use a $\var{bnf}$ instead (which contains much more information). The program
! 2572: will make the effort of converting to what it needs. On the other hand, if
! 2573: the program requires a big number field, the program will \var{not} launch
! 2574: \kbd{bnfinit} for you, which can be a costly operation. Instead, it will give
! 2575: you a specific error message.
! 2576:
! 2577: The data types corresponding to the structures described above are rather
! 2578: complicated. Thus, as we already have seen it with elliptic curves, GP
! 2579: provides you with some ``member functions'' to retrieve the data you need
! 2580: from these structures (once they have been initialized of course). The
! 2581: relevant types of number fields are indicated between parentheses:
! 2582: \smallskip
! 2583:
! 2584: \sidx{member functions}
! 2585: \settabs\+xxxxxxx&(\var{bnr},x&\var{bnf},x&nf\hskip2pt&)x&: &\cr
! 2586:
! 2587: \+\tet{bnf} &(\var{bnr},& \var{bnf}&&)&: & big number field.\cr
! 2588:
! 2589: \+\tet{clgp} &(\var{bnr},& \var{bnf}&&)&: & classgroup. This one admits the
! 2590: following three subclasses:\cr
! 2591:
! 2592: \+ \quad \tet{cyc} &&&&&: & \quad cyclic decomposition
! 2593: (SNF)\sidx{Smith normal form}.\cr
! 2594:
! 2595: \+ \quad \kbd{gen}\sidx{gen (member function)} &&&&&: &
! 2596: \quad generators.\cr
! 2597:
! 2598: \+ \quad \tet{no} &&&&&: & \quad number of elements.\cr
! 2599:
! 2600: \+\tet{diff} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & the different ideal.\cr
! 2601:
! 2602: \+\tet{codiff}&(\var{bnr},& \var{bnf},& \var{nf}&)&: & the codifferent
! 2603: (inverse of the different in the ideal group).\cr
! 2604:
! 2605: \+\tet{disc} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & discriminant.\cr
! 2606:
! 2607: \+\tet{fu} &(\var{bnr},& \var{bnf},& \var{nf}&)&: &
! 2608: \idx{fundamental units}.\cr
! 2609:
! 2610: \+\tet{futu} &(\var{bnr},& \var{bnf}&&)&: & $[u,w]$, $u$ is a vector of
! 2611: fundamental units, $w$ generates the torsion.\cr
! 2612:
! 2613: \+\tet{nf} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & number field.\cr
! 2614:
! 2615: \+\tet{reg} &(\var{bnr},& \var{bnf},&&)&: & regulator.\cr
! 2616:
! 2617: \+\tet{roots}&(\var{bnr},& \var{bnf},& \var{nf}&)&: & roots of the
! 2618: polnomial generating the field.\cr
! 2619:
! 2620: \+\tet{sign} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & $[r_1,r_2]$ the
! 2621: signature of the field. This means that the field has $r_1$ real \cr
! 2622: \+ &&&&&& embeddings, $2r_2$ complex ones.\cr
! 2623:
! 2624: \+\tet{t2} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & the T2 matrix (see
! 2625: \kbd{nfinit}).\cr
! 2626:
! 2627: \+\tet{tu} &(\var{bnr},& \var{bnf},&&)&: & a generator for the torsion
! 2628: units.\cr
! 2629:
! 2630: \+\tet{tufu} &(\var{bnr},& \var{bnf},&&)&: & as \kbd{futu}, but outputs
! 2631: $[w,u]$.\cr
! 2632:
! 2633: \+\tet{zk} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & integral basis, i.e.~a
! 2634: $\Z$-basis of the maximal order.\cr
! 2635:
! 2636: \+\tet{zkst} &(\var{bnr}& & &)&: & structure of $(\Z_K/m)^*$ (can be
! 2637: extracted also from an \var{idealstar}).\cr
! 2638:
! 2639: For instance, assume that $\var{bnf} = \kbd{bnfinit}(\var{pol})$, for some
! 2640: polynomial. Then \kbd{\var{bnf}.clgp} retrieves the class group, and
! 2641: \kbd{\var{bnf}.clgp.no} the class number. If we had set $\var{bnf} =
! 2642: \kbd{nfinit}(\var{pol})$, both would have output an error message. All these
! 2643: functions are completely recursive, thus for instance
! 2644: \kbd{\var{bnr}.bnf.nf.zk} will yield the maximal order of \var{bnr} (which
! 2645: you could get directly with a simple \kbd{\var{bnr}.zk} of course).
! 2646:
! 2647: \medskip
! 2648: The following functions, starting with \kbd{buch} in library mode, and with
! 2649: \kbd{bnf} under GP, are implementations of the sub-exponential algorithms for
! 2650: finding class and unit groups under \idx{GRH}, due to Hafner-McCurley,
! 2651: \idx{Buchmann} and Cohen-Diaz-Olivier.
! 2652:
! 2653: The general call to the functions concerning class groups of general number
! 2654: fields (i.e.~excluding \kbd{quadclassunit}) involves a polynomial $P$ and a
! 2655: technical vector
! 2656: $$\var{tech} = [c,c2,\var{nrel},\var{borne},\var{nrpid},\var{minsfb}],$$
! 2657: where the parameters are to be understood as follows:
! 2658:
! 2659: $P$ is the defining polynomial for the number field, which must be in
! 2660: $\Z[X]$, irreducible and, preferably, monic. In fact, if you supply a
! 2661: non-monic polynomial at this point, GP will issue a warning, then
! 2662: \var{transform your polynomial} so that it becomes monic. Instead of the
! 2663: normal result, say \kbd{res}, you then get a vector \kbd{[res,Mod(a,Q)]},
! 2664: where \kbd{Mod(a,Q)=Mod(X,P)} gives the change of variables.
! 2665:
! 2666: The numbers $c$ and $c2$ are positive real numbers which control the
! 2667: execution time and the stack size. To get maximum speed, set $c2=c$. To get a
! 2668: rigorous result (under \idx{GRH}) you must take $c2=12$ (or $c2=6$ in the
! 2669: quadratic case, but then you should use the much faster function
! 2670: \kbd{quadclassunit}). Reasonable values for $c$ are between $0.1$ and
! 2671: $2$. (The defaults are $c=c2=0.3$).
! 2672:
! 2673: $\var{nrel}$ is the number of initial extra relations requested in
! 2674: computing the
! 2675: relation matrix. Reasonable values are between 5 and 20. (The default is 5).
! 2676:
! 2677: $\var{borne}$ is a multiplicative coefficient of the Minkowski bound which
! 2678: controls
! 2679: the search for small norm relations. If this parameter is set equal to 0, the
! 2680: program does not search for small norm relations. Otherwise reasonable values
! 2681: are between $0.5$ and $2.0$. (The default is $1.0$).
! 2682:
! 2683: $\var{nrpid}$ is the maximal number of small norm relations associated to each
! 2684: ideal in the factor base. Irrelevant when $\var{borne}=0$. Otherwise,
! 2685: reasonable values are between 4 and 20. (The default is 4).
! 2686:
! 2687: $\var{minsfb}$ is the minimal number of elements in the ``sub-factorbase''.
! 2688: If the
! 2689: program does not seem to succeed in finding a full rank matrix (which you can
! 2690: see in GP by typing \kbd{\bs g 2}), increase this number. Reasonable values
! 2691: are between 2 and 5. (The default is 3).
! 2692:
! 2693: \misctitle{Remarks.}
! 2694:
! 2695: Apart from the polynomial $P$, you don't need to supply any of the technical
! 2696: parameters (under the library you still need to send at least an empty
! 2697: vector, \kbd{cgetg(1,t\_VEC)}). However, should you choose to set some of
! 2698: them, they \var{must} be given in the requested order. For example, if you
! 2699: want to specify a given value of $nrel$, you must give some values as well
! 2700: for $c$ and $c2$, and provide a vector $[c,c2,nrel]$.
! 2701:
! 2702: Note also that you can use an $\var{nf}$ instead of $P$, which avoids
! 2703: recomputing the integral basis and analogous quantities.
! 2704:
! 2705: \smallskip
! 2706: \subsecidx{bnfcertify}$(\var{bnf})$: $\var{bnf}$ being a big number field
! 2707: as output by \kbd{bnfinit} or \kbd{bnfclassunit}, checks whether the result
! 2708: is correct, i.e.~whether it is possible to remove the assumption of the
! 2709: Generalized Riemann Hypothesis\sidx{GRH}. If it is correct, the answer is 1.
! 2710: If not, the program may output some error message, but more probably will loop
! 2711: indefinitely. In \var{no} occasion can the program give a wrong answer
! 2712: (barring bugs of course): if the program answers 1, the answer is certified.
! 2713:
! 2714: \syn{certifybuchall}{\var{bnf}}, and the result is a C long.
! 2715:
! 2716: \subsecidx{bnfclassunit}$(P,\{\fl=0\},\{\var{tech}=[\,]\})$: \idx{Buchmann}'s
! 2717: sub-exponential algorithm for computing the class group, the regulator and a
! 2718: system of \idx{fundamental units} of the general algebraic number field $K$
! 2719: defined by the irreducible polynomial $P$ with integer coefficients.
! 2720:
! 2721: The result of this function is a vector $v$ with 10 components (it is
! 2722: \var{not} a $\var{bnf}$, you need \kbd{bnfinit} for that), which for ease of
! 2723: presentation is in fact output as a one column matrix. First we describe the
! 2724: default behaviour ($\fl=0$):
! 2725:
! 2726: $v[1]$ is equal to the polynomial $P$. Note that for optimum performance,
! 2727: $P$ should have gone through \kbd{polred} or $\kbd{nfinit}(x,2)$.
! 2728:
! 2729: $v[2]$ is the 2-component vector $[r1,r2]$, where $r1$ and $r2$ are as usual
! 2730: the number of real and half the number of complex embeddings of the number
! 2731: field $K$.
! 2732:
! 2733: $v[3]$ is the 2-component vector containing the field discriminant and the
! 2734: index.
! 2735:
! 2736: $v[4]$ is an integral basis in Hermite normal form.
! 2737:
! 2738: $v[5]$ (\kbd{$v$.clgp}) is a 3-component vector containing the class number
! 2739: (\kbd{$v$.clgp.no}), the structure of the class group as a product of cyclic
! 2740: groups of order $n_i$ (\kbd{$v$.clgp.cyc}), and the corresponding generators
! 2741: of the class group of respective orders $n_i$ (\kbd{$v$.clgp.gen}).
! 2742:
! 2743: $v[6]$ (\kbd{$v$.reg}) is the regulator computed to an accuracy which is the
! 2744: maximum of an internally determined accuracy and of the default.
! 2745:
! 2746: $v[7]$ is a measure of the correctness of the result. If it is close to 1,
! 2747: the results are correct (under \idx{GRH}). If it is close to a larger integer,
! 2748: this shows that the product of the class number by the regulator is off by a
! 2749: factor equal to this integer, and you must start again with a larger value
! 2750: for $c$ or a different random seed, i.e.~use the function \kbd{setrand}.
! 2751: (Since the computation involves a random process, starting again with exactly
! 2752: the same parameters may give the correct result.) In this case a warning
! 2753: message is printed.
! 2754:
! 2755: $v[8]$ (\kbd{$v$.tu}) a vector with 2 components, the first being the number
! 2756: $w$ of roots of unity in $K$ and the second a primitive $w$-th root of unity
! 2757: expressed as a polynomial.
! 2758:
! 2759: $v[9]$ (\kbd{$v$.fu}) is a system of fundamental units also expressed as
! 2760: polynomials.
! 2761:
! 2762: $v[10]$ gives a measure of the correctness of the computations of the
! 2763: fundamental units (not of the regulator), expressed as a number of bits. If
! 2764: this number is greater than $20$, say, everything is OK. If $v[10]\le0$,
! 2765: then we have lost all accuracy in computing the units (usually an error
! 2766: message will be printed and the units not given). In the intermediate cases,
! 2767: one must proceed with caution (for example by increasing the current
! 2768: precision).
! 2769:
! 2770: If $\fl=1$, and the precision happens to be insufficient for obtaining the
! 2771: fundamental units exactly, the internal precision is doubled and the
! 2772: computation redone, until the exact results are obtained. The user should be
! 2773: warned that this can take a very long time when the coefficients of the
! 2774: fundamental units on the integral basis are very large, for example in the
! 2775: case of large real quadratic fields. In that case, there are alternate
! 2776: methods for representing algebraic numbers which are not implemented in PARI.
! 2777:
! 2778: If $\fl=2$, the fundamental units and roots of unity are not computed.
! 2779: Hence the result has only 7 components, the first seven ones.
! 2780:
! 2781: $\var{tech}$ is a technical vector (empty by default) containing $c$, $c2$,
! 2782: \var{nrel}, \var{borne}, \var{nbpid}, \var{minsfb}, in this order (see
! 2783: the beginning of the section or the keyword \kbd{bnf}).
! 2784: You can supply any number of these {\it provided you give an actual value to
! 2785: each of them} (the ``empty arg'' trick won't work here). Careful use of these
! 2786: parameters may speed up your computations considerably.
! 2787:
! 2788: \syn{bnfclassunit0}{P,\fl,\var{tech},\var{prec}}.
! 2789:
! 2790: \subsecidx{bnfclgp}$(P,\{\var{tech}=[\,]\})$: as \kbd{bnfclassunit}, but only
! 2791: outputs $v[5]$, i.e.~the class group.
! 2792:
! 2793: \syn{bnfclassgrouponly}{P,\var{tech},\var{prec}}, where \var{tech}
! 2794: is as described under \kbd{bnfclassunit}.
! 2795:
! 2796: \subsecidx{bnfdecodemodule}$(\var{nf},m)$: if $m$ is a module as output in the
! 2797: first component of an extension given by \kbd{bnrdisclist}, outputs the
! 2798: true module.
! 2799:
! 2800: \syn{decodemodule}{\var{nf},m}.
! 2801:
! 2802: \subsecidx{bnfinit}$(P,\{\fl=0\},\{\var{tech}=[\,]\})$: essentially identical
! 2803: to \kbd{bnfclassunit} except that the output contains a lot of technical data,
! 2804: and should not be printed out explicitly in general. The result of
! 2805: \kbd{bnfinit} is used in programs such as \kbd{bnfisprincipal},
! 2806: \kbd{bnfisunit} or \kbd{bnfnarrow}. The result is a 10-component vector
! 2807: $\var{bnf}$.
! 2808:
! 2809: \noindent $\bullet$ The first 6 and last 2 components are technical and in
! 2810: principle are not used by the casual user. However, for the sake of
! 2811: completeness, their description is as follows. We use the notations explained
! 2812: in the book by H. Cohen, {\it A Course in Computational Algebraic Number
! 2813: Theory}, Graduate Texts in Maths \key{138}, Springer-Verlag, 1993, Section
! 2814: 6.5, and subsection 6.5.5 in particular.
! 2815:
! 2816: $\var{bnf}[1]$ contains the matrix $W$, i.e.~the matrix in Hermite normal
! 2817: form giving relations for the class group on prime ideal generators
! 2818: $(\p_i)_{1\le i\le r}$.
! 2819:
! 2820: $\var{bnf}[2]$ contains the matrix $B$, i.e.~the matrix containing the
! 2821: expressions of the prime ideal factorbase in terms of the $\p_i$. It is an
! 2822: $r\times c$ matrix.
! 2823:
! 2824: $\var{bnf}[3]$ contains the complex logarithmic embeddings of the system of
! 2825: fundamental units which has been found. It is an $(r_1+r_2)\times(r_1+r_2-1)$
! 2826: matrix.
! 2827:
! 2828: $\var{bnf}[4]$ contains the matrix $M''_C$ of Archimedean components of the
! 2829: relations of the matrix $(W|B)$.
! 2830:
! 2831: $\var{bnf}[5]$ contains the prime factor base, i.e.~the list of prime
! 2832: ideals used in finding the relations.
! 2833:
! 2834: $\var{bnf}[6]$ contains the permutation of the prime factor base which was
! 2835: necessary to reduce the relation matrix to the form explained in subsection
! 2836: 6.5.5 of GTM~138 (i.e.~with a big $c\times c$ identity matrix on the lower
! 2837: right). Note that in the above mentioned book, the need to permute the rows
! 2838: of the relation matrices which occur was not emphasized.
! 2839:
! 2840: $\var{bnf}[9]$ is a 3-element row vector used in \tet{bnfisprincipal} only
! 2841: and obtained as follows. Let $D = U W V$ obtained by applying the
! 2842: \idx{Smith normal form} algorithm to the matrix $W$ (= $\var{bnf}[1]$) and
! 2843: let $U_r$ be the reduction of $U$ modulo $D$. The first elements of the
! 2844: factorbase are given (in terms of \kbd{bnf.gen}) by the columns of $U_r$,
! 2845: with archimedian component $g_a$; let also $GD_a$ be the archimedian
! 2846: components of the generators of the (principal) ideals defined by the
! 2847: \kbd{bnf.gen[i]\pow bnf.cyc[i]}. Then $\var{bnf}[9]=[U_r, g_a, GD_a]$.
! 2848:
! 2849: Finally, $\var{bnf}[10]$ is by default unused and set equal to 0. This
! 2850: field is used to store further information about the field as it becomes
! 2851: available (which is rarely needed, hence would be too expensive to compute
! 2852: during the initial \kbd{bnfinit} call). For instance, the generators of the
! 2853: principal ideals \kbd{bnf.gen[i]\pow bnf.cyc[i]} (during a call to
! 2854: \tet{bnrisprincipal}), or those corresponding to the relations in $W$ and
! 2855: $B$ (when the \kbd{bnf} internal precision needs to be increased).
! 2856: \smallskip
! 2857:
! 2858: \noindent$\bullet$ The less technical components are as follows:
! 2859:
! 2860: $\var{bnf}[7]$ or \kbd{\var{bnf}.nf} is equal to the number field data
! 2861: $\var{nf}$ as would be given by \kbd{nfinit}.
! 2862:
! 2863: $\var{bnf}[8]$ is a vector containing the last 6 components of
! 2864: \kbd{bnfclassunit[,1]}, i.e.~the classgroup \kbd{\var{bnf}.clgp}, the
! 2865: regulator \kbd{\var{bnf}.reg}, the general ``check'' number which should be
! 2866: close to 1, the number of roots of unity and a generator \kbd{\var{bnf}.tu},
! 2867: the fundamental units \kbd{\var{bnf}.fu}, and finally the check on their
! 2868: computation. If the precision becomes insufficient, GP outputs a warning
! 2869: (\kbd{fundamental units too large, not given}) and does not strive to
! 2870: compute the units by default ($\fl=0$).
! 2871:
! 2872: When $\fl=1$, GP insists on finding the fundamental units exactly, the
! 2873: internal precision being doubled and the computation redone, until the exact
! 2874: results are obtained. The user should be warned that this can take a very
! 2875: long time when the coefficients of the fundamental units on the integral
! 2876: basis are very large.
! 2877:
! 2878: When $\fl=2$, on the contrary, it is initially agreed that GP
! 2879: will not compute units.
! 2880:
! 2881: When $\fl=3$, computes a very small version of \kbd{bnfinit}, a ``small big
! 2882: number field'' (or \var{sbnf} for short) which contains enough information
! 2883: to recover the full $\var{bnf}$ vector very rapidly, but which is much
! 2884: smaller and hence easy to store and print. It is supposed to be used in
! 2885: conjunction with \kbd{bnfmake}. The output is a 12 component vector $v$, as
! 2886: follows. Let $\var{bnf}$ be the result of a full \kbd{bnfinit}, complete with
! 2887: units. Then $v[1]$ is the polynomial $P$, $v[2]$ is the number of real
! 2888: embeddings $r_1$, $v[3]$ is the field discriminant, $v[4]$ is the integral
! 2889: basis, $v[5]$ is the list of roots as in the sixth component of \kbd{nfinit},
! 2890: $v[6]$ is the matrix $MD$ of \kbd{nfinit} giving a $\Z$-basis of the
! 2891: different, $v[7]$ is the matrix $\kbd{W} = \var{bnf}[1]$, $v[8]$ is the
! 2892: matrix $\kbd{matalpha}=\var{bnf}[2]$, $v[9]$ is the prime ideal factor base
! 2893: $\var{bnf}[5]$ coded in a compact way, and ordered according to the
! 2894: permutation $\var{bnf}[6]$, $v[10]$ is the 2-component vector giving the
! 2895: number of roots of unity and a generator, expressed on the integral basis,
! 2896: $v[11]$ is the list of fundamental units, expressed on the integral basis,
! 2897: $v[12]$ is a vector containing the algebraic numbers alpha corresponding to
! 2898: the columns of the matrix \kbd{matalpha}, expressed on the integral basis.
! 2899:
! 2900: Note that all the components are exact (integral or rational), except for
! 2901: the roots in $v[5]$. In practice, this is the only component which a user
! 2902: is allowed to modify, by recomputing the roots to a higher accuracy if
! 2903: desired. Note also that the member functions will \var{not} work on
! 2904: \var{sbnf}, you have to use \kbd{bnfmake} explicitly first.
! 2905:
! 2906: \syn{bnfinit0}{P,\fl,\var{tech},\var{prec}}.
! 2907:
! 2908: \subsecidx{bnfisintnorm}$(\var{bnf},x)$: computes a complete system of
! 2909: solutions (modulo units of positive norm) of the absolute norm equation
! 2910: $\text{Norm}(a)=x$,
! 2911: where $a$ is an integer in $\var{bnf}$. If $\var{bnf}$ has not been certified,
! 2912: the correctness of the result depends on the validity of \idx{GRH}.
! 2913:
! 2914: \syn{bnfisintnorm}{\var{bnf},x}.
! 2915:
! 2916: \subsecidx{bnfisnorm}$(\var{bnf},x,\{\fl=1\})$: tries to tell whether the
! 2917: rational number $x$ is the norm of some element y in $\var{bnf}$. Returns a
! 2918: vector $[a,b]$ where $x=Norm(a)*b$. Looks for a solution which is an $S$-unit,
! 2919: with $S$ a certain set of prime ideals containing (among others) all primes
! 2920: dividing $x$. If $\var{bnf}$ is known to be \idx{Galois}, set $\fl=0$ (in
! 2921: this case,
! 2922: $x$ is a norm iff $b=1$). If $\fl$ is non zero the program adds to $S$ the
! 2923: following prime ideals, depending on the sign of $\fl$. If $\fl>0$, the
! 2924: ideals of norm less than $\fl$. And if $\fl<0$ the ideals dividing $\fl$.
! 2925:
! 2926: If you are willing to assume \idx{GRH}, the answer is guaranteed
! 2927: (i.e.~$x$ is a norm iff $b=1$), if $S$ contains all primes less than
! 2928: $12\log(\var{disc}(\var{Bnf}))^2$,
! 2929: where $\var{Bnf}$ is the Galois closure of $\var{bnf}$.
! 2930:
! 2931: \syn{bnfisnorm}{\var{bnf},x,\fl,\var{prec}}, where $\fl$ and
! 2932: $\var{prec}$ are \kbd{long}s.
! 2933:
! 2934: \subsecidx{bnfissunit}$(\var{bnf},\var{sfu},x)$: $\var{bnf}$ being output by
! 2935: \kbd{bnfinit}, \var{sfu} by \kbd{bnfsunit}, gives the column vector of
! 2936: exponents of $x$ on the fundamental $S$-units and the roots of unity.
! 2937: If $x$ is not a unit, outputs an empty vector.
! 2938:
! 2939: \syn{bnfissunit}{\var{bnf},\var{sfu},x}.
! 2940:
! 2941: \subsecidx{bnfisprincipal}$(\var{bnf},x,\{\fl=1\})$: $\var{bnf}$ being the
! 2942: number field data output by \kbd{bnfinit}, and $x$ being either a $\Z$-basis
! 2943: of an ideal in the number field (not necessarily in HNF) or a prime ideal in
! 2944: the format output by the function \kbd{idealprimedec}, this function tests
! 2945: whether the ideal is principal or not. The result is more complete than a
! 2946: simple true/false answer: it gives a row vector $[v_1,v_2,check]$, where
! 2947:
! 2948: $v_1$ is the vector of components $c_i$ of the class of the ideal $x$ in the
! 2949: class group, expressed on the generators $g_i$ given by \kbd{bnfinit}
! 2950: (specifically \kbd{\var{bnf}.clgp.gen} which is the same as
! 2951: \kbd{\var{bnf}[8][1][3]}). The $c_i$ are chosen so that $0\le c_i<n_i$
! 2952: where $n_i$ is the order of $g_i$ (the vector of $n_i$ being
! 2953: \kbd{\var{bnf}.clgp.cyc}, that is \kbd{\var{bnf}[8][1][2]}).
! 2954:
! 2955: $v_2$ gives on the integral basis the components of $\alpha$ such that
! 2956: $x=\alpha\prod_ig_i^{c_i}$. In particular, $x$ is principal if and only if
! 2957: $v_1$ is equal to the zero vector, and if this the case $x=\alpha\Z_K$ where
! 2958: $\alpha$ is given by $v_2$. Note that if $\alpha$ is too large to be given, a
! 2959: warning message will be printed and $v_2$ will be set equal to the empty
! 2960: vector.
! 2961:
! 2962: Finally the third component \var{check} is analogous to the last component of
! 2963: \kbd{bnfclassunit}: it gives a check on the accuracy of the result, in bits.
! 2964: \var{check} should be at least $10$, and preferably much more. In any case, the
! 2965: result is checked for correctness.
! 2966:
! 2967: If $\fl=0$, outputs only $v_1$, which is much easier to compute.
! 2968:
! 2969: If $\fl=2$, does as if $\fl$ were $0$, but doubles the precision until a
! 2970: result is obtained.
! 2971:
! 2972: If $\fl=3$, as in the default behaviour ($\fl=1$), but doubles the precision
! 2973: until a result is obtained.
! 2974:
! 2975: The user is warned that these two last setting may induce \var{very} lengthy
! 2976: computations.
! 2977:
! 2978: \syn{isprincipalall}{\var{bnf},x,\fl}.
! 2979:
! 2980: \subsecidx{bnfisunit}$(\var{bnf},x)$: $\var{bnf}$ being the number field data
! 2981: output by
! 2982: \kbd{bnfinit} and $x$ being an algebraic number (type integer, rational or
! 2983: polmod), this outputs the decomposition of $x$ on the fundamental units and
! 2984: the roots of unity if $x$ is a unit, the empty vector otherwise. More
! 2985: precisely, if $u_1$,\dots,$u_r$ are the fundamental units, and $\zeta$ is
! 2986: the generator of the group of roots of unity (found by \kbd{bnfclassunit} or
! 2987: \kbd{bnfinit}), the output is a vector $[x_1,\dots,x_r,x_{r+1}]$ such that
! 2988: $x=u_1^{x_1}\cdots u_r^{x_r}\cdot\zeta^{x_{r+1}}$. The $x_i$ are integers for
! 2989: $i\le r$ and is an integer modulo the order of $\zeta$ for $i=r+1$.
! 2990:
! 2991: \syn{isunit}{\var{bnf},x}.
! 2992:
! 2993: \subsecidx{bnfmake}$(\var{sbnf})$: \var{sbnf} being a ``small $\var{bnf}$''
! 2994: as output by \kbd{bnfinit}$(x,3)$, computes the complete \kbd{bnfinit}
! 2995: information. The result is \var{not} identical to what \kbd{bnfinit} would
! 2996: yield, but is functionally identical. The execution time is very small
! 2997: compared to a complete \kbd{bnfinit}. Note that if the default precision in
! 2998: GP (or $\var{prec}$ in library mode) is greater than the precision of the
! 2999: roots $\var{sbnf}[5]$, these are recomputed so as to get a result with
! 3000: greater accuracy.
! 3001:
! 3002: Note that the member functions are \var{not} available for \var{sbnf}, you
! 3003: have to use \kbd{bnfmake} explicitly first.
! 3004:
! 3005: \syn{makebigbnf}{\var{sbnf},\var{prec}}, where $\var{prec}$ is a
! 3006: C long integer.
! 3007:
! 3008: \subsecidx{bnfnarrow}$(\var{bnf})$: $\var{bnf}$ being a big number field as
! 3009: output by \kbd{bnfinit}, computes the narrow class group of $\var{bnf}$. The
! 3010: output is a 3-component row vector $v$ analogous to the corresponding
! 3011: class group component \kbd{\var{bnf}.clgp} (\kbd{\var{bnf}[8][1]}): the
! 3012: first component is the narrow class number \kbd{$v$.no}, the second component
! 3013: is a vector containing the SNF\sidx{Smith normal form} cyclic components
! 3014: \kbd{$v$.cyc} of the narrow
! 3015: class group, and the third is a vector giving the generators of the
! 3016: corresponding \kbd{$v$.gen} cyclic groups. Note that this function is a
! 3017: special case of \kbd{bnrclass}.
! 3018:
! 3019: \syn{buchnarrow}{\var{bnf}}.
! 3020:
! 3021: \subsecidx{bnfsignunit}$(\var{bnf})$: $\var{bnf}$ being a big number field
! 3022: output by \kbd{bnfinit}, this computes an $r_1\times(r_1+r_2-1)$ matrix
! 3023: having $\pm1$ components, giving the signs of the real embeddings of the
! 3024: fundamental units.
! 3025:
! 3026: \syn{signunits}{\var{bnf}}.
! 3027:
! 3028: \subsecidx{bnfreg}$(\var{bnf})$: $\var{bnf}$ being a big number field
! 3029: output by \kbd{bnfinit}, computes its regulator.
! 3030:
! 3031: \syn{regulator}{\var{bnf},\var{tech},\var{prec}}, where \var{tech} is as in
! 3032: \kbd{bnfclassunit}.
! 3033:
! 3034: \subsecidx{bnfsunit}$(\var{bnf},S)$: computes the fundamental $S$-units of the
! 3035: number field $\var{bnf}$ (output by \kbd{bnfinit}), where $S$ is a list of
! 3036: prime ideals (output by \kbd{idealprimedec}). The output is a vector $v$ with
! 3037: 6 components.
! 3038:
! 3039: $v[1]$ gives a minimal system of (integral) generators of the $S$-unit group
! 3040: modulo the unit group.
! 3041:
! 3042: $v[2]$ contains technical data needed by \kbd{bnfissunit}.
! 3043:
! 3044: $v[3]$ is an empty vector (used to give the logarithmic embeddings of the
! 3045: generators in $v[1]$ in version 2.0.16).
! 3046:
! 3047: $v[4]$ is the $S$-regulator (this is the product of the regulator, the
! 3048: determinant of $v[2]$ and the natural logarithms of the norms of the ideals
! 3049: in $S$).
! 3050:
! 3051: $v[5]$ gives the $S$-class group structure, in the usual format
! 3052: (a row vector whose three components give in order the $S$-class number,
! 3053: the cyclic components and the generators).
! 3054:
! 3055: $v[6]$ is a copy of $S$.
! 3056:
! 3057: \syn{bnfsunit}{\var{bnf},S,\var{prec}}.
! 3058:
! 3059: \subsecidx{bnfunit}$(\var{bnf})$: $\var{bnf}$ being a big number field as
! 3060: output by
! 3061: \kbd{bnfinit}, outputs a two-component row vector giving in the first
! 3062: component the vector of fundamental units of the number field, and in the
! 3063: second component the number of bit of accuracy which remained in the
! 3064: computation (which is always correct, otherwise an error message is printed).
! 3065: This function is mainly for people who used the wrong flag in \kbd{bnfinit}
! 3066: and would like to skip part of a lengthy \kbd{bnfinit} computation.
! 3067:
! 3068: \syn{buchfu}{\var{bnf}}.
! 3069:
! 3070: \subsecidx{bnrL1}$(\var{bnr},\var{subgroup},\{\fl=0\})$:
! 3071: \var{bnr} being the number field data which is output by
! 3072: \kbd{bnrinit(,,1)} and \var{subgroup} being a square matrix defining a
! 3073: congruence subgroup of the ray class group corresponding to \var{bnr}
! 3074: (or $0$ for the trivial congruence subgroup), returns for each
! 3075: \idx{character} $\chi$ of the ray class group which is trivial on this
! 3076: subgroup, the value at $s = 1$ (or $s = 0$) of the abelian
! 3077: $L$-function associated to $\chi$. For the value at $s = 0$, the
! 3078: function returns in fact for each character $\chi$ a vector $[r_\chi ,
! 3079: c_\chi]$ where $r_\chi$ is the order of $L(s, \chi)$ at $s = 0$ and
! 3080: $c_\chi$ the first non-zero term in the expansion of $L(s,
! 3081: \chi)$ at $s = 0$; in other words
! 3082: %
! 3083: $$L(s, \chi) = c_\chi \cdot s^{r_\chi} + O(s^{r_\chi + 1})$$
! 3084: %
! 3085: \noindent near $0$. \fl\ is optional, default value is 0; its binary digits
! 3086: mean 1: compute at $s = 1$ if set to 1 or $s = 0$ if set to 0, 2: compute
! 3087: the primitive $L$-functions associated to $\chi$ if set to 0 or the
! 3088: $L$-function with Euler factors at prime ideals dividing the modulus of
! 3089: \var{bnr} removed if set to 1 (this is the so-called $L_S(s, \chi)$
! 3090: function where $S$ is the set of infinite places of the number field
! 3091: together with the finite prime ideals dividing the modulus of \var{bnr},
! 3092: see the example below), 3: returns also the character.
! 3093:
! 3094: Example:
! 3095: \bprog
! 3096: bnf = bnfinit(x^2 - 229);
! 3097: bnr = bnrinit(bnf,1,1);
! 3098: bnrL1(bnr, 0)
! 3099: @eprog\noindent
! 3100: returns the order and the first non-zero term of the abelian
! 3101: $L$-functions $L(s, \chi)$ at $s = 0$ where $\chi$ runs through the
! 3102: characters of the class group of $\Q(\sqrt{229})$. Then
! 3103: \bprog
! 3104: bnr2 = bnrinit(bnf,2,1);
! 3105: bnrL1(bnr2,0,2)
! 3106: @eprog\noindent
! 3107: returns the order and the first non-zero terms of the abelian
! 3108: $L$-functions $L_S(s, \chi)$ at $s = 0$ where $\chi$ runs through the
! 3109: characters of the class group of $\Q(\sqrt{229})$ and $S$ is the set
! 3110: of infinite places of $\Q(\sqrt{229})$ together with the finite prime
! 3111: $2$ (note that the ray class group modulo $2$ is in fact the class
! 3112: group, so \kbd{bnrL1(bnr2,0)} returns exactly the same answer as
! 3113: \kbd{bnrL1(bnr,0)}!).
! 3114:
! 3115: \syn{bnrL1}{\var{bnr},\var{subgroup},\fl,\var{prec}}
! 3116:
! 3117: \subsecidx{bnrclass}$(\var{bnf},\var{ideal},\{\fl=0\})$:
! 3118: $\var{bnf}$ being a big number field
! 3119: as output by \kbd{bnfinit} (the units are mandatory unless the ideal is
! 3120: trivial), and \var{ideal} being either an ideal in any form or a two-component
! 3121: row vector containing an ideal and an $r_1$-component row vector of flags
! 3122: indicating which real Archimedean embeddings to take in the module, computes
! 3123: the ray class group of the number field for the module \var{ideal}, as a
! 3124: 3-component vector as all other finite Abelian groups (cardinality, vector of
! 3125: cyclic components, corresponding generators).
! 3126:
! 3127: If $\fl=2$, the output is different. It is a 6-component vector $w$. $w[1]$
! 3128: is $\var{bnf}$. $w[2]$ is the result of applying
! 3129: $\kbd{idealstar}(\var{bnf},I,2)$. $w[3]$, $w[4]$ and $w[6]$ are technical
! 3130: components used only by the function \kbd{bnrisprincipal}. $w[5]$ is the
! 3131: structure of the ray class group as would have been output with $\fl=0$.
! 3132:
! 3133: If $\fl=1$, as above, except that the generators of the ray class group are
! 3134: not computed, which saves time.
! 3135:
! 3136: \syn{bnrclass0}{\var{bnf},\var{ideal},\fl}.
! 3137:
! 3138: \subsecidx{bnrclassno}$(\var{bnf},I)$: $\var{bnf}$ being a big number field
! 3139: as output
! 3140: by \kbd{bnfinit} (units are mandatory unless the ideal is trivial), and $I$
! 3141: being either an ideal in any form or a two-component row vector containing an
! 3142: ideal and an $r_1$-component row vector of flags indicating which real
! 3143: Archimedean embeddings to take in the modulus, computes the ray class number
! 3144: of the number field for the modulus $I$. This is faster than \kbd{bnrclass}
! 3145: and should be used if only the ray class number is desired.
! 3146:
! 3147: \syn{rayclassno}{\var{bnf},I}.
! 3148:
! 3149: \subsecidx{bnrclassnolist}$(\var{bnf},\var{list})$: $\var{bnf}$ being a
! 3150: big number field as output by \kbd{bnfinit} (units are mandatory unless
! 3151: the ideal is trivial), and \var{list} being a list of modules as output
! 3152: by \kbd{ideallist} of \kbd{ideallistarch},
! 3153: outputs the list of the class numbers of the corresponding ray class groups.
! 3154:
! 3155: \syn{rayclassnolist}{\var{bnf},\var{list}}.
! 3156:
! 3157: \subsecidx{bnrconductor}$(a_1,\{a_2\},\{a_3\}, \{\fl=0\})$: conductor of the
! 3158: subfield of a ray class field as defined by $[a_1,a_2,a_3]$ (see \kbd{bnr}
! 3159: at the beginning of this section).
! 3160:
! 3161: \syn{bnrconductor}{a_1,a_2,a_3,\fl}, where an omitted argument
! 3162: among the $a_i$ is input as \kbd{gzero}, and $\fl$ is a C long.
! 3163:
! 3164: \subsecidx{bnrconductorofchar}$(\var{bnr},\var{chi})$: \var{bnr} being a
! 3165: big ray number field
! 3166: as output by \kbd{bnrclass}, and \var{chi} being a row vector representing a
! 3167: \idx{character} as expressed on the generators of the ray class group, gives
! 3168: the conductor of this character as a modulus.
! 3169:
! 3170: \syn{bnrconductorofchar}{\var{bnr},\var{chi}}.
! 3171:
! 3172: \subsecidx{bnrdisc}$(a1,\{a2\},\{a3\},\{\fl=0\})$: $a1$, $a2$, $a3$
! 3173: defining a big ray number field $L$ over a groud field $K$ (see \kbd{bnr}
! 3174: at the beginning of this section for the
! 3175: meaning of $a1$, $a2$, $a3$), outputs a 3-component row vector $[N,R_1,D]$,
! 3176: where $N$ is the (absolute) degree of $L$, $R_1$ the number of real places of
! 3177: $L$, and $D$ the discriminant of $L/\Q$, including sign (if $\fl=0$).
! 3178:
! 3179: If $\fl=1$, as above but outputs relative data. $N$ is now the degree of
! 3180: $L/K$, $R_1$ is the number of real places of $K$ unramified in $L$ (so that
! 3181: the number of real places of $L$ is equal to $R_1$ times the relative degree
! 3182: $N$), and $D$ is the relative discriminant ideal of $L/K$.
! 3183:
! 3184: If $\fl=2$, does as in case 0, except that if the modulus is not the exact
! 3185: conductor corresponding to the $L$, no data is computed and the result is $0$
! 3186: (\kbd{gzero}).
! 3187:
! 3188: If $\fl=3$, as case 2, outputting relative data.
! 3189:
! 3190: \syn{bnrdisc0}{a1,a2,a3,\fl}.
! 3191:
! 3192: \subsecidx{bnrdisclist}$(\var{bnf},\var{bound},\{\var{arch}\},\{\fl=0\})$:
! 3193: $\var{bnf}$ being a big
! 3194: number field as output by \kbd{bnfinit} (the units are mandatory), computes a
! 3195: list of discriminants of Abelian extensions of the number field by increasing
! 3196: modulus norm up to bound \var{bound}, where the ramified Archimedean places are
! 3197: given by \var{arch} (unramified at infinity if \var{arch} is void or
! 3198: omitted). If
! 3199: \fl\ is non-zero, give \var{arch} all the possible values. (See \kbd{bnr}
! 3200: at the beginning of this section for the meaning of $a1$, $a2$, $a3$.)
! 3201:
! 3202: The alternative syntax $\kbd{bnrdisclist}(\var{bnf},\var{list})$
! 3203: is supported, where \var{list} is as output by \kbd{ideallist} or
! 3204: \kbd{ideallistarch} (with units).
! 3205:
! 3206: The output format is as follows. The output $v$ is a row vector of row
! 3207: vectors, allowing the bound to be greater than $2^{16}$ for 32-bit machines,
! 3208: and $v[i][j]$ is understood to be in fact $V[2^{15}(i-1)+j]$ of a unique big
! 3209: vector $V$ (note that $2^{15}$ is hardwired and can be increased in the
! 3210: source code only on 64-bit machines and higher).
! 3211:
! 3212: Such a component $V[k]$ is itself a vector $W$ (maybe of length 0) whose
! 3213: components correspond to each possible ideal of norm $k$. Each component
! 3214: $W[i]$ corresponds to an Abelian extension $L$ of $\var{bnf}$ whose modulus is
! 3215: an ideal of norm $k$ and no Archimedean components (hence the extension is
! 3216: unramified at infinity). The extension $W[i]$ is represented by a 4-component
! 3217: row vector $[m,d,r,D]$ with the following meaning. $m$ is the prime ideal
! 3218: factorization of the modulus, $d=[L:\Q]$ is the absolute degree of $L$,
! 3219: $r$ is the number of real places of $L$, and $D$ is the factorization of the
! 3220: absolute discriminant. Each prime ideal $pr=[p,\alpha,e,f,\beta]$ in the
! 3221: prime factorization $m$ is coded as $p\cdot n^2+(f-1)\cdot n+(j-1)$, where
! 3222: $n$ is the degree of the base field and $j$ is such that
! 3223:
! 3224: \kbd{pr = idealprimedec(\var{nf},p)[j]}.
! 3225:
! 3226: $m$ can be decoded using \kbd{bnfdecodemodule}.
! 3227:
! 3228: \syn{bnrdisclist0}{a1,a2,a3,\var{bound},\var{arch},\fl}.
! 3229:
! 3230: \subsecidx{bnrinit}$(\var{bnf},\var{ideal},\{\fl=0\})$: $\var{bnf}$ is as
! 3231: output by \kbd{bnfinit}, \var{ideal} is a valid ideal (or a module),
! 3232: initializes data linked
! 3233: to the ray class group structure corresponding to this module. This is the
! 3234: same as $\kbd{bnrclass}(\var{bnf},\var{ideal},\fl+1)$.
! 3235:
! 3236: \syn{bnrinit0}{\var{bnf},\var{ideal},\fl}.
! 3237:
! 3238: \subsecidx{bnrisconductor}$(a1,\{a2\},\{a3\})$: $a1$, $a2$, $a3$ represent
! 3239: an extension of the base field, given by class field theory for some modulus
! 3240: encoded in the parameters. Outputs 1 if this modulus is the conductor, and 0
! 3241: otherwise. This is slightly faster than \kbd{bnrconductor}.
! 3242:
! 3243: \syn{bnrisconductor}{a1,a2,a3} and the result is a \kbd{long}.
! 3244:
! 3245: \subsecidx{bnrisprincipal}$(\var{bnr},x,\{\fl=1\})$: \var{bnr} being the
! 3246: number field data which is output by \kbd{bnrinit}$(,,1)$ and $x$ being an
! 3247: ideal in any form, outputs the components of $x$ on the ray class group
! 3248: generators in a way similar to \kbd{bnfisprincipal}. That is a 3-component
! 3249: vector $v$ where $v[1]$ is the vector of components of $x$ on the ray class
! 3250: group generators, $v[2]$ gives on the integral basis an element $\alpha$ such
! 3251: that $x=\alpha\prod_ig_i^{x_i}$. Finally $v[3]$ indicates the number of bits
! 3252: of accuracy left in the result. In any case the result is checked for
! 3253: correctness, but $v[3]$ is included to see if it is necessary to increase the
! 3254: accuracy in other computations.
! 3255:
! 3256: If $\fl=0$, outputs only $v_1$. In that case, \var{bnr} need not contain the
! 3257: ray class group generators, i.e.~it may be created with \kbd{bnrinit}$(,,0)$
! 3258:
! 3259: \syn{isprincipalrayall}{\var{bnr},x,\fl}.
! 3260:
! 3261: \subsecidx{bnrrootnumber}$(\var{bnr},\var{chi},\{\fl=0\})$:
! 3262: if $\chi=\var{chi}$ is a (not necessarily primitive)
! 3263: \idx{character} over \var{bnr}, let
! 3264: $L(s,\chi) = \sum_{id} \chi(id) N(id)^{-s}$ be the associated
! 3265: \idx{Artin L-function}. Returns the so-called \idx{Artin root number}, i.e.~the
! 3266: complex number $W(\chi)$ of modulus 1 such that
! 3267: %
! 3268: $$\Lambda(1-s,\chi) = W(\chi) \Lambda(s,\overline{\chi})$$
! 3269: %
! 3270: \noindent where $\Lambda(s,\chi) = A(\chi)^{s/2}\gamma_\chi(s) L(s,\chi)$ is
! 3271: the enlarged L-function associated to $L$.
! 3272:
! 3273: The generators of the ray class group are needed, and you can set $\fl=1$ if
! 3274: the character is known to be primitive. Example:
! 3275:
! 3276: \bprog
! 3277: bnf = bnfinit(x^2 - 145);
! 3278: bnr = bnrinit(bnf,7,1);
! 3279: bnrrootnumber(bnr, [5])
! 3280: @eprog\noindent
! 3281: returns the root number of the character $\chi$ of $Cl_7(\Q(\sqrt{145}))$
! 3282: such that $\chi(g) = \zeta^5$, where $g$ is the generator of the ray-class
! 3283: field and $\zeta = e^{2i\pi/N}$ where $N$ is the order of $g$ ($N=12$ as
! 3284: \kbd{bnr.cyc} readily tells us).
! 3285:
! 3286: \syn{bnrrootnumber}{\var{bnf},\var{chi},\fl}
! 3287:
! 3288: \subsecidx{bnrstark}${(\var{bnr},\var{subgroup},\{\fl=0\})}$: \var{bnr}
! 3289: being as output by \kbd{bnrinit(,,1)}, finds a relative equation for the
! 3290: class field corresponding to the modulus in \var{bnr} and the given
! 3291: congruence subgroup using \idx{Stark units} (set $\var{subgroup}=0$ if you
! 3292: want the whole ray class group). The main variable of \var{bnr} must not be
! 3293: $x$, and the ground field and the class field must be totally real and not
! 3294: isomorphic to $\Q$ (over the rationnals, use \tet{polsubcyclo} or
! 3295: \tet{galoissubcyclo}). \fl\ is optional and may be set to 0 to obtain a
! 3296: reduced relative polynomial, 1 to be satisfied with any relative
! 3297: polynomial, 2 to obtain an absolute polynomial and 3 to obtain the
! 3298: irreducible relative polynomial of the Stark unit, 0 being default.
! 3299: Example:
! 3300:
! 3301: \bprog
! 3302: bnf = bnfinit(y^2 - 3);
! 3303: bnr = bnrinit(bnf, 5, 1);
! 3304: bnrstark(bnr, 0)
! 3305: @eprog\noindent
! 3306: returns the ray class field of $\Q(\sqrt{3})$ modulo $5$.
! 3307:
! 3308: \misctitle{Remark.} The result of the computation depends on the choice of
! 3309: a modulus verifying special conditions. By default the function will try
! 3310: few moduli, choosing the one giving the smallest result. In some cases
! 3311: where the result is however very large, you can tell the function to
! 3312: try more moduli by adding $4$ to the value of flag. Whether this flag is
! 3313: set or not, the function may fail in some extreme cases, returning the
! 3314: error message
! 3315:
! 3316: \kbd{"Cannot find a suitable modulus in FindModule"}.
! 3317:
! 3318: In this case, the corresponding congruence group is a product of cyclic
! 3319: groups and, for the time being, the class field has to be obtained by
! 3320: splitting this group into its cyclic components.
! 3321:
! 3322: \syn{bnrstark}{\var{bnr},\var{subgroup},\fl}.
! 3323:
! 3324: \subsecidx{dirzetak}$(\var{nf},b)$: gives as a vector the first $b$
! 3325: coefficients of the \idx{Dedekind} zeta function of the number field $\var{nf}$
! 3326: considered as a \idx{Dirichlet series}.
! 3327:
! 3328: \syn{dirzetak}{\var{nf},b}.
! 3329:
! 3330: \subsecidx{factornf}$(x,t)$: factorization of the univariate polynomial $x$
! 3331: over the number field defined by the (univariate) polynomial $t$. $x$ may
! 3332: have coefficients in $\Q$ or in the number field. The main variable of
! 3333: $t$ must be of \var{lower} priority than that of $x$ (in other words the
! 3334: variable number of $t$ must be \var{greater} than that of $x$). However if
! 3335: the coefficients of the number field occur explicitly (as polmods) as
! 3336: coefficients of $x$, the variable of these polmods \var{must} be the same as
! 3337: the main variable of $t$. For example
! 3338: \bprog
! 3339: ? factornf(x^2 + Mod(y, y^2+1), y^2+1);
! 3340: ? factornf(x^2 + 1, y^2+1); \\@com these two are OK
! 3341: ? factornf(x^2 + Mod(z,z^2+1), y^2+1)
! 3342: *** incorrect type in gmulsg
! 3343: @eprog
! 3344:
! 3345: \syn{polfnf}{x,t}.
! 3346:
! 3347: \subsecidx{galoisfixedfield}$(\var{gal},\var{perm},\{fl=0\},\{v=y\}))$:
! 3348: \var{gal} being be a Galois field as output by \tet{galoisinit} and
! 3349: \var{perm} an element of $\var{gal}.group$ or a vector of such elements,
! 3350: computes the fixed field of \var{gal} by the automorphism defined by the
! 3351: permutations \var{perm} of the roots $\var{gal}.roots$. $P$ is guaranteed to
! 3352: be squarefree modulo $\var{gal}.p$.
! 3353:
! 3354: If no flags or $\fl=0$, output format is the same as for \tet{nfsubfield},
! 3355: returning $[P,x]$ such that $P$ is a polynomial defining the fixed field, and
! 3356: $x$ is a root of $P$ expressed as a polmod in $\var{gal}.pol$.
! 3357:
! 3358: If $\fl=1$ return only the polynomial $P$.
! 3359:
! 3360: If $\fl=2$ return $[P,x,F]$ where $P$ and $x$ are as above and $F$ is the
! 3361: factorization of $\var{gal}.pol$ over the field defined by $P$, where
! 3362: variable $v$ ($y$ by default) stands for a root of $P$. The priority of $v$
! 3363: must be less than the priority of the variable of $\var{gal}.pol$.
! 3364:
! 3365: Example:
! 3366:
! 3367: \bprog
! 3368: G = galoisinit(x^4+1);
! 3369: galoisfixedfield(G,G.group[2],2)
! 3370: [x^2 + 2, Mod(x^3 + x, x^4 + 1), [x^2 - y*x - 1, x^2 + y*x - 1]]
! 3371: @eprog
! 3372: computes the factorization $x^4+1=(x^2-\sqrt{-2}x-1)(x^2+\sqrt{-2}x-1)$
! 3373:
! 3374: \syn{galoisfixedfield}{\var{gal},\var{perm},p}.
! 3375:
! 3376: \subsecidx{galoisinit}$(\var{pol},\{den\})$: computes the Galois group
! 3377: and all neccessary information for computing the fixed fields of the
! 3378: Galois extension $K/\Q$ where $K$ is the number field defined by
! 3379: $\var{pol}$ (monic irreducible polynomial in $\Z[X]$ or
! 3380: a number field as output by \tet{nfinit}). The extension $K/\Q$ must be
! 3381: Galois with Galois group ``weakly'' super-solvable (see \tet{nfgaloisconj})
! 3382:
! 3383: \misctitle{Warning:} The interface of this function is experimental,
! 3384: so the described output can be subject to important changes in the
! 3385: near future. However the function itself should work as described. For any
! 3386: remarks about this interface, please mail \kbd{allomber@math.u-bordeaux.fr}.
! 3387:
! 3388: The output is an 8-component vector \var{gal}.
! 3389:
! 3390: $\var{gal}[1]$ contains the polynomial \var{pol}
! 3391: (\kbd{\var{gal}.pol}).
! 3392:
! 3393: $\var{gal}[2]$ is a three--components vector $[p,e,q]$ where $p$ is a
! 3394: prime number (\kbd{\var{gal}.p}) such that \var{pol} totally split
! 3395: modulo $p$ , $e$ is an integer and $q=p^e$ (\kbd{\var{gal}.mod}) is the
! 3396: modulus of the roots in \kbd{\var{gal}.roots}.
! 3397:
! 3398: $\var{gal}[3]$ is a vector $L$ containing the $p$-adic roots of
! 3399: \var{pol} as integers implicitly modulo \kbd{\var{gal}.mod}.
! 3400: (\kbd{\var{gal}.roots}).
! 3401:
! 3402: $\var{gal}[4]$ is the inverse of the Van der Monde matrix of the
! 3403: $p$-adic roots of \var{pol}, multiplied by $\var{gal}[5]$.
! 3404:
! 3405: $\var{gal}[5]$ is a multiple of the least common denominator of the
! 3406: automorphisms expressed as polynomial in a root of \var{pol}.
! 3407:
! 3408: $\var{gal}[6]$ is the Galois group $G$ expressed as a vector of
! 3409: permutations of $L$ (\kbd{\var{gal}.group}).
! 3410:
! 3411: $\var{gal}[7]$ is a generating subset $S=[s_1,\ldots,s_g]$ of $G$
! 3412: expressed as a vector of permutations of $L$ (\kbd{\var{gal}.gen}).
! 3413:
! 3414: $\var{gal}[8]$ contains the relative orders $[o_1,\ldots,o_g]$ of
! 3415: the generators of $S$ (\kbd{\var{gal}.orders}).
! 3416:
! 3417: Let $H$ be the maximal normal supersolvable subgroup of $G$, we have the
! 3418: following properties:
! 3419:
! 3420: \quad$\bullet$ if $G/H\simeq A_4$ then $[o_1,\ldots,o_g]$ ends by
! 3421: $[2,2,3]$.
! 3422:
! 3423: \quad$\bullet$ if $G/H\simeq S_4$ then $[o_1,\ldots,o_g]$ ends by
! 3424: $[2,2,3,2]$.
! 3425:
! 3426: \quad$\bullet$ else $G$ is super-solvable.
! 3427:
! 3428: \quad$\bullet$ for $1\leq i \leq g$ the subgroup of $G$ generated by
! 3429: $[s_1,\ldots,s_g]$ is normal, with the exception of $i=g-2$ in the
! 3430: second case and of $i=g-3$ in the third.
! 3431:
! 3432: \quad$\bullet$ the relative order $o_i$ of $s_i$ is its order in the
! 3433: quotient group $G/\langle s_1,\ldots,s_{i-1}\rangle$, with the same
! 3434: exceptions.
! 3435:
! 3436: \quad$\bullet$ for any $x\in G$ there exists a unique family
! 3437: $[e_1,\ldots,e_g]$ such that (no exceptions):
! 3438:
! 3439: -- for $1\leq i \leq g$ we have $0\leq e_i<o_i$
! 3440:
! 3441: -- $x=g_1^{e_1}g_2^{e_2}\ldots g_n^{e_n}$
! 3442:
! 3443: If present $den$ must be a suitable value for $\var{gal}[5]$.
! 3444:
! 3445: \syn{galoisinit}{\var{gal},\var{den}}.
! 3446:
! 3447: \subsecidx{galoispermtopol}$(\var{gal},\var{perm})$: \var{gal} being a
! 3448: Galois field as output by \kbd{galoisinit} and \var{perm} a element of
! 3449: $\var{gal}.group$, return the polynomial defining the Galois
! 3450: automorphism, as output by \kbd{nfgaloisconj}, associated with the
! 3451: permutation \var{perm} of the roots $\var{gal}.roots$. \var{perm} can
! 3452: also be a vector or matrix, in this case, \kbd{galoispermtopol} is
! 3453: applied to all components recursively.
! 3454:
! 3455: \noindent Note that
! 3456: \bprog
! 3457: G = galoisinit(pol);
! 3458: galoispermtopol(G, G[6])~
! 3459: @eprog
! 3460: \noindent is equivalent to \kbd{nfgaloisconj(pol)}, if degree of \var{pol}
! 3461: is greater or equal to $2$.
! 3462:
! 3463: \syn{galoispermtopol}{\var{gal},\var{perm}}.
! 3464:
! 3465: \subsecidx{galoissubcyclo}$(n,H,\{Z\},\{v\},\{fl=0\})$: If $fl=0$, compute a polynomial
! 3466: defining the subfield of $\Q(\zeta_n)$ fixed by the subgroup \var{H} of
! 3467: $(\Z/n\Z)^*$. The subgroup \var{H} can be given by a generator, a set of
! 3468: generators given by a vector or a HNF matrix. If present \kbd{Z} must be
! 3469: \kbd{znstar(n)}, and is currently only used when \var{H} is a HNF matrix. If
! 3470: \var{v} is given, the polynomial is given in the variable \var{v}.
! 3471:
! 3472: If $fl=1$, compute only the (finite part of) conductor of the abelian extension.
! 3473:
! 3474: If $fl=2$, output $[pol, f_0]$, where $pol$ is the polynomial as output when $fl=0$ and $f_0$ the conductor as output when $fl=1$.
! 3475:
! 3476: The following function can be used to compute all subfields of
! 3477: $\Q(\zeta_n)$ (of order less than \kbd{d}, if \kbd{d} is set):
! 3478:
! 3479: \bprog
! 3480: subcyclo(n, d = -1)=
! 3481: {
! 3482: local(Z,G,S);
! 3483: if (d < 0, d = n);
! 3484: Z = znstar(n);
! 3485: G = matdiagonal(Z[2]);
! 3486: S = [];
! 3487: forsubgroup(H = G, d,
! 3488: S = concat(S, galoissubcyclo(n, mathnf(concat(G,H)),Z));
! 3489: );
! 3490: S
! 3491: }
! 3492: @eprog
! 3493:
! 3494: \misctitle{Note:} The interface to this function needs to be cleaned up, and
! 3495: so is subject to change.
! 3496:
! 3497: \syn{galoissubcyclo}{n,H,Z,v} where n is a C long integer.
! 3498:
! 3499: \subsecidx{idealadd}$(\var{nf},x,y)$: sum of the two ideals $x$ and $y$ in the
! 3500: number field $\var{nf}$. When $x$ and $y$ are given by $\Z$-bases, this does
! 3501: not depend on $\var{nf}$ and can be used to compute the sum of any two
! 3502: $\Z$-modules. The result is given in HNF.
! 3503:
! 3504: \syn{idealadd}{\var{nf},x,y}.
! 3505:
! 3506: \subsecidx{idealaddtoone}$(\var{nf},x,\{y\})$: $x$ and $y$ being two co-prime
! 3507: integral ideals (given in any form), this gives a two-component row vector
! 3508: $[a,b]$ such that $a\in x$, $b\in y$ and $a+b=1$.
! 3509:
! 3510: The alternative syntax $\kbd{idealaddtoone}(\var{nf},v)$, is supported, where
! 3511: $v$ is a $k$-component vector of ideals (given in any form) which sum to
! 3512: $\Z_K$. This outputs a $k$-component vector $e$ such that $e[i]\in x[i]$ for
! 3513: $1\le i\le k$ and $\sum_{1\le i\le k}e[i]=1$.
! 3514:
! 3515: \syn{idealaddtoone0}{\var{nf},x,y}, where an omitted $y$ is coded as
! 3516: \kbd{NULL}.
! 3517:
! 3518: \subsecidx{idealappr}$(\var{nf},x,\{\fl=0\})$: if $x$ is a fractional ideal
! 3519: (given in any form), gives an element $\alpha$ in $\var{nf}$ such that for
! 3520: all prime ideals $\p$ such that the valuation of $x$ at $\p$ is non-zero, we
! 3521: have $v_{\p}(\alpha)=v_{\p}(x)$, and. $v_{\p}(\alpha)\ge0$ for all other
! 3522: ${\p}$.
! 3523:
! 3524: If $\fl$ is non-zero, $x$ must be given as a prime ideal factorization, as
! 3525: output by \kbd{idealfactor}, but possibly with zero or negative exponents.
! 3526: This yields an element $\alpha$ such that for all prime ideals $\p$ occurring
! 3527: in $x$, $v_{\p}(\alpha)$ is equal to the exponent of $\p$ in $x$, and for all
! 3528: other prime ideals, $v_{\p}(\alpha)\ge0$. This generalizes
! 3529: $\kbd{idealappr}(\var{nf},x,0)$ since zero exponents are allowed. Note that
! 3530: the algorithm used is slightly different, so that
! 3531: \kbd{idealappr(\var{nf},idealfactor(\var{nf},x))} may not be the same as
! 3532: \kbd{idealappr(\var{nf},x,1)}.
! 3533:
! 3534: \syn{idealappr0}{\var{nf},x,\fl}.
! 3535:
! 3536: \subsecidx{idealchinese}$(\var{nf},x,y)$: $x$ being a prime ideal factorization
! 3537: (i.e.~a 2 by 2 matrix whose first column contain prime ideals, and the second
! 3538: column integral exponents), $y$ a vector of elements in $\var{nf}$ indexed by
! 3539: the ideals in $x$, computes an element $b$ such that
! 3540:
! 3541: $v_\p(b - y_\p) \geq v_\p(x)$ for all prime ideals in $x$ and $v_\p(b)\geq 0$
! 3542: for all other $\p$.
! 3543:
! 3544: \syn{idealchinese}{\var{nf},x,y}.
! 3545:
! 3546: \subsecidx{idealcoprime}$(\var{nf},x,y)$: given two integral ideals $x$ and $y$
! 3547: in the number field $\var{nf}$, finds a $\beta$ in the field, expressed on the
! 3548: integral basis $\var{nf}[7]$, such that $\beta\cdot y$ is an integral ideal
! 3549: coprime to $x$.
! 3550:
! 3551: \syn{idealcoprime}{\var{nf},x}.
! 3552:
! 3553: \subsecidx{idealdiv}$(\var{nf},x,y,\{\fl=0\})$: quotient $x\cdot y^{-1}$ of the
! 3554: two ideals $x$ and $y$ in the number field $\var{nf}$. The result is given in
! 3555: HNF.
! 3556:
! 3557: If $\fl$ is non-zero, the quotient $x \cdot y^{-1}$ is assumed to be an
! 3558: integral ideal. This can be much faster when the norm of the quotient is
! 3559: small even though the norms of $x$ and $y$ are large.
! 3560:
! 3561: \syn{idealdiv0}{\var{nf},x,y,\fl}. Also available
! 3562: are $\teb{idealdiv}(\var{nf},x,y)$ ($\fl=0$) and
! 3563: $\teb{idealdivexact}(\var{nf},x,y)$ ($\fl=1$).
! 3564:
! 3565: \subsecidx{idealfactor}$(\var{nf},x)$: factors into prime ideal powers the
! 3566: ideal $x$ in the number field $\var{nf}$. The output format is similar to the
! 3567: \kbd{factor} function, and the prime ideals are represented in the form
! 3568: output by the \kbd{idealprimedec} function, i.e.~as 5-element vectors.
! 3569:
! 3570: \syn{idealfactor}{\var{nf},x}.
! 3571:
! 3572: \subsecidx{idealhnf}$(\var{nf},a,\{b\})$: gives the \idx{Hermite normal form}
! 3573: matrix of the ideal $a$. The ideal can be given in any form whatsoever
! 3574: (typically by an algebraic number if it is principal, by a $\Z_K$-system of
! 3575: generators, as a prime ideal as given by \kbd{idealprimedec}, or by a
! 3576: $\Z$-basis).
! 3577:
! 3578: If $b$ is not omitted, assume the ideal given was $a\Z_K+b\Z_K$, where $a$
! 3579: and $b$ are elements of $K$ given either as vectors on the integral basis
! 3580: $\var{nf}[7]$ or as algebraic numbers.
! 3581:
! 3582: \syn{idealhnf0}{\var{nf},a,b} where an omitted $b$ is coded as \kbd{NULL}.
! 3583: Also available is $\teb{idealhermite}(\var{nf},a)$ ($b$ omitted).
! 3584:
! 3585: \subsecidx{idealintersect}$(\var{nf},x,y)$: intersection of the two ideals
! 3586: $x$ and $y$ in the number field $\var{nf}$. When $x$ and $y$ are given by
! 3587: $\Z$-bases, this does not depend on $\var{nf}$ and can be used to compute the
! 3588: intersection of any two $\Z$-modules. The result is given in HNF.
! 3589:
! 3590: \syn{idealintersect}{\var{nf},x,y}.
! 3591:
! 3592: \subsecidx{idealinv}$(\var{nf},x)$: inverse of the ideal $x$ in the
! 3593: number field $\var{nf}$. The result is the Hermite normal form of the inverse
! 3594: of the ideal, together with the opposite of the Archimedean information if it
! 3595: is given.
! 3596:
! 3597: \syn{idealinv}{\var{nf},x}.
! 3598:
! 3599: \subsecidx{ideallist}$(\var{nf},\var{bound},\{\fl=4\})$: computes the list
! 3600: of all ideals of norm less or equal to \var{bound} in the number field
! 3601: \var{nf}. The result is a row vector with exactly \var{bound} components.
! 3602: Each component is itself a row vector containing the information about
! 3603: ideals of a given norm, in no specific order. This information can be
! 3604: either the HNF of the ideal or the \kbd{idealstar} with possibly some
! 3605: additional information.
! 3606:
! 3607: If $\fl$ is present, its binary digits are toggles meaning
! 3608:
! 3609: \quad 1: give also the generators in the \kbd{idealstar}.
! 3610:
! 3611: \quad 2: output $[L,U]$, where $L$ is as before and $U$ is a vector of
! 3612: \kbd{zinternallog}s of the units.
! 3613:
! 3614: \quad 4: give only the ideals and not the \kbd{idealstar} or the \kbd{ideallog}
! 3615: of the units.
! 3616:
! 3617: \syn{ideallist0}{\var{nf},\var{bound},\fl}, where \var{bound} must
! 3618: be a C long integer. Also available is $\teb{ideallist}(\var{nf},\var{bound})$,
! 3619: corresponding to the case $\fl=0$.
! 3620:
! 3621: \subsecidx{ideallistarch}$(\var{nf},\var{list},\{\var{arch}=[\,]\},\{\fl=0\})$:
! 3622: vector of vectors of all \kbd{idealstarinit} (see \kbd{idealstar}) of all
! 3623: modules in \var{list}, with Archimedean part \var{arch} added (void if
! 3624: omitted). \var{list} is a vector of big ideals, as output by
! 3625: \kbd{ideallist}$(\ldots, \fl)$ for instance. $\fl$ is optional; its binary
! 3626: digits are toggles meaning: 1: give generators as well, 2: list format is
! 3627: $[L,U]$ (see \kbd{ideallist}).
! 3628:
! 3629: \syn{ideallistarch0}{\var{nf},\var{list},\var{arch},\fl}, where an omitted
! 3630: \var{arch} is coded as \kbd{NULL}.
! 3631:
! 3632: \subsecidx{ideallog}$(\var{nf},x,\var{bid})$: $\var{nf}$ being a number field,
! 3633: \var{bid} being a ``big ideal'' as output by \kbd{idealstar} and $x$ being a
! 3634: non-necessarily integral element of \var{nf} which must have valuation
! 3635: equal to 0 at all prime ideals dividing $I=\var{bid}[1]$, computes the
! 3636: ``discrete logarithm'' of $x$ on the generators given in $\var{bid}[2]$.
! 3637: In other words, if $g_i$ are these generators, of orders $d_i$ respectively,
! 3638: the result is a column vector of integers $(x_i)$ such that $0\le x_i<d_i$ and
! 3639: $$x\equiv\prod_ig_i^{x_i}\pmod{\ ^*I}\enspace.$$
! 3640: Note that when $I$ is a module, this implies also sign conditions on the
! 3641: embeddings.
! 3642:
! 3643: \syn{zideallog}{\var{nf},x,\var{bid}}.
! 3644:
! 3645: \subsecidx{idealmin}$(\var{nf},x,\{\var{vdir}\})$: computes a minimum of
! 3646: the ideal $x$ in the direction \var{vdir} in the number field \var{nf}.
! 3647:
! 3648: \syn{minideal}{\var{nf},x,\var{vdir},\var{prec}}, where an omitted
! 3649: \var{vdir} is coded as \kbd{NULL}.
! 3650:
! 3651: \subsecidx{idealmul}$(\var{nf},x,y,\{\fl=0\})$: ideal multiplication of the
! 3652: ideals $x$ and $y$ in the number field \var{nf}. The result is a generating
! 3653: set for the ideal product with at most $n$ elements, and is in Hermite normal
! 3654: form if either $x$ or $y$ is in HNF or is a prime ideal as output by
! 3655: \kbd{idealprimedec}, and this is given together with the sum of the
! 3656: Archimedean information in $x$ and $y$ if both are given.
! 3657:
! 3658: If $\fl$ is non-zero, reduce the result using \kbd{idealred}.
! 3659:
! 3660: \syn{idealmul}{\var{nf},x,y} ($\fl=0$) or
! 3661: $\teb{idealmulred}(\var{nf},x,y,\var{prec})$ ($\fl\neq0$), where as usual,
! 3662: $\var{prec}$ is a C long integer representing the precision.
! 3663:
! 3664: \subsecidx{idealnorm}$(\var{nf},x)$: computes the norm of the ideal~$x$
! 3665: in the number field~$\var{nf}$.
! 3666:
! 3667: \syn{idealnorm}{\var{nf}, x}.
! 3668:
! 3669: \subsecidx{idealpow}$(\var{nf},x,k,\{\fl=0\})$: computes the $k$-th power of
! 3670: the ideal $x$ in the number field $\var{nf}$. $k$ can be positive, negative
! 3671: or zero. The result is NOT reduced, it is really the $k$-th ideal power, and
! 3672: is given in HNF.
! 3673:
! 3674: If $\fl$ is non-zero, reduce the result using \kbd{idealred}. Note however
! 3675: that this is NOT the same as as $\kbd{idealpow}(\var{nf},x,k)$ followed by
! 3676: reduction, since the reduction is performed throughout the powering process.
! 3677:
! 3678: The library syntax corresponding to $\fl=0$ is
! 3679: $\teb{idealpow}(\var{nf},x,k)$. If $k$ is a \kbd{long}, you can use
! 3680: $\teb{idealpows}(\var{nf},x,k)$. Corresponding to $\fl=1$ is
! 3681: $\teb{idealpowred}(\var{nf},vp,k,\var{prec})$, where $\var{prec}$ is a
! 3682: \kbd{long}.
! 3683:
! 3684: \subsecidx{idealprimedec}$(\var{nf},p)$: computes the prime ideal
! 3685: decomposition of the prime number $p$ in the number field $\var{nf}$. $p$
! 3686: must be a (positive) prime number. Note that the fact that $p$ is prime is
! 3687: not checked, so if a non-prime number $p$ is given it may lead to
! 3688: unpredictable results.
! 3689:
! 3690: The result is a vector of 5-component vectors, each representing one of the
! 3691: prime ideals above $p$ in the number field $\var{nf}$. The representation
! 3692: $vp=[p,a,e,f,b]$ of a prime ideal means the following. The prime ideal is
! 3693: equal to $p\Z_K+\alpha\Z_K$ where $\Z_K$ is the ring of integers of the field
! 3694: and $\alpha=\sum_i a_i\omega_i$ where the $\omega_i$ form the integral basis
! 3695: \kbd{\var{nf}.zk}, $e$ is the ramification index, $f$ is the residual index,
! 3696: and $b$ is an $n$-component column vector representing a $\beta\in\Z_K$ such
! 3697: that $vp^{-1}=\Z_K+\beta/p\Z_K$ which will be useful for computing
! 3698: valuations, but which the user can ignore. The number $\alpha$ is guaranteed
! 3699: to have a valuation equal to 1 at the prime ideal (this is automatic if
! 3700: $e>1$).
! 3701:
! 3702: \syn{idealprimedec}{\var{nf},p}.
! 3703:
! 3704: \subsecidx{idealprincipal}$(\var{nf},x)$: creates the principal ideal
! 3705: generated by the algebraic number $x$ (which must be of type integer,
! 3706: rational or polmod) in the number field $\var{nf}$. The result is a
! 3707: one-column matrix.
! 3708:
! 3709: \syn{principalideal}{\var{nf},x}.
! 3710:
! 3711: \subsecidx{idealred}$(\var{nf},I,\{\var{vdir}=0\})$: \idx{LLL} reduction of
! 3712: the ideal $I$ in the number field \var{nf}, along the direction \var{vdir}.
! 3713: If \var{vdir} is present, it must be an $r1+r2$-component vector ($r1$ and
! 3714: $r2$ number of real and complex places of \var{nf} as usual).
! 3715:
! 3716: This function finds a ``small'' $a$ in $I$ (it is an LLL pseudo-minimum
! 3717: along direction \var{vdir}). The result is the \idx{Hermite normal form} of
! 3718: the LLL-reduced ideal $r I/a$, where $r$ is a rational number such that the
! 3719: resulting ideal is integral and primitive. This is often, but not always, a
! 3720: reduced ideal in the sense of \idx{Buchmann}. If $I$ is an idele, the
! 3721: logarithmic embeddings of $a$ are subtracted to the Archimedean part.
! 3722:
! 3723: More often than not, a \idx{principal ideal} will yield the identity
! 3724: matrix. This is a quick and dirty way to check if ideals are principal
! 3725: without computing a full \kbd{bnf} structure, but it's not a necessary
! 3726: condition; hence, a non-trivial result doesn't prove the ideal is
! 3727: non-trivial in the class group.
! 3728:
! 3729: Note that this is \var{not} the same as the LLL reduction of the lattice
! 3730: $I$ since ideal operations are involved.
! 3731:
! 3732: \syn{ideallllred}{\var{nf},x,\var{vdir},\var{prec}}, where an omitted
! 3733: \var{vdir} is coded as \kbd{NULL}.
! 3734:
! 3735: \subsecidx{idealstar}$(\var{nf},I,\{\fl=1\})$: \var{nf} being a number
! 3736: field, and $I$
! 3737: either and ideal in any form, or a row vector whose first component is an
! 3738: ideal and whose second component is a row vector of $r_1$ 0 or 1, outputs
! 3739: necessary data for computing in the group $(\Z_K/I)^*$.
! 3740:
! 3741: If $\fl=2$, the result is a 5-component vector $w$. $w[1]$ is the ideal
! 3742: or module $I$ itself. $w[2]$ is the structure of the group. The other
! 3743: components are difficult to describe and are used only in conjunction with
! 3744: the function \kbd{ideallog}.
! 3745:
! 3746: If $\fl=1$ (default), as $\fl=2$, but do not compute explicit generators
! 3747: for the cyclic components, which saves time.
! 3748:
! 3749: If $\fl=0$, computes the structure of $(\Z_K/I)^*$ as a 3-component vector
! 3750: $v$. $v[1]$ is the order, $v[2]$ is the vector of SNF\sidx{Smith normal form}
! 3751: cyclic components and
! 3752: $v[3]$ the corresponding generators. When the row vector is explicitly
! 3753: included, the
! 3754: non-zero elements of this vector are considered as real embeddings of
! 3755: \var{nf} in the order given by \kbd{polroots}, i.e.~in \var{nf}[6]
! 3756: (\kbd{\var{nf}.roots}), and then $I$ is a module with components at infinity.
! 3757:
! 3758: To solve discrete logarithms (using \kbd{ideallog}), you have to choose
! 3759: $\fl=2$.
! 3760:
! 3761: \syn{idealstar0}{\var{nf},I,\fl}.
! 3762:
! 3763: \subsecidx{idealtwoelt}$(\var{nf},x,\{a\})$: computes a two-element
! 3764: representation of the ideal $x$ in the number field $\var{nf}$, using a
! 3765: straightforward (exponential time) search. $x$ can be an ideal in any form,
! 3766: (including perhaps an Archimedean part, which is ignored) and the result is a
! 3767: row vector $[a,\alpha]$ with two components such that $x=a\Z_K+\alpha\Z_K$
! 3768: and $a\in\Z$, where $a$ is the one passed as argument if any. If $x$ is given
! 3769: by at least two generators, $a$ is chosen to be the positive generator of
! 3770: $x\cap\Z$.
! 3771:
! 3772: Note that when an explicit $a$ is given, we use an asymptotically faster
! 3773: method, however in practice it is usually slower.
! 3774:
! 3775: \syn{ideal_two_elt0}{\var{nf},x,a}, where an omitted $a$ is entered as
! 3776: \kbd{NULL}.
! 3777:
! 3778: \subsecidx{idealval}$(\var{nf},x,\var{vp})$: gives the valuation of the
! 3779: ideal $x$ at the prime ideal \var{vp} in the number field $\var{nf}$,
! 3780: where \var{vp} must be a
! 3781: 5-component vector as given by \kbd{idealprimedec}.
! 3782:
! 3783: \syn{idealval}{\var{nf},x,\var{vp}}, and the result is a \kbd{long}
! 3784: integer.
! 3785:
! 3786: \subsecidx{ideleprincipal}$(\var{nf},x)$: creates the principal idele
! 3787: generated by the algebraic number $x$ (which must be of type integer,
! 3788: rational or polmod) in the number field $\var{nf}$. The result is a
! 3789: two-component vector, the first being a one-column matrix representing the
! 3790: corresponding principal ideal, and the second being the vector with $r_1+r_2$
! 3791: components giving the complex logarithmic embedding of $x$.
! 3792:
! 3793: \syn{principalidele}{\var{nf},x}.
! 3794:
! 3795: \subsecidx{matalgtobasis}$(\var{nf},x)$: $\var{nf}$ being a number field in
! 3796: \kbd{nfinit} format, and $x$ a matrix whose coefficients are expressed as
! 3797: polmods in $\var{nf}$, transforms this matrix into a matrix whose
! 3798: coefficients are expressed on the integral basis of $\var{nf}$. This is the
! 3799: same as applying \kbd{nfalgtobasis} to each entry, but it would be dangerous
! 3800: to use the same name.
! 3801:
! 3802: \syn{matalgtobasis}{\var{nf},x}.
! 3803:
! 3804: \subsecidx{matbasistoalg}$(\var{nf},x)$: $\var{nf}$ being a number field in
! 3805: \kbd{nfinit} format, and $x$ a matrix whose coefficients are expressed as
! 3806: column vectors on the integral basis of $\var{nf}$, transforms this matrix
! 3807: into a matrix whose coefficients are algebraic numbers expressed as
! 3808: polmods. This is the same as applying \kbd{nfbasistoalg} to each entry, but
! 3809: it would be dangerous to use the same name.
! 3810:
! 3811: \syn{matbasistoalg}{\var{nf},x}.
! 3812:
! 3813: \subsecidx{modreverse}$(a)$: $a$ being a polmod $A(X)$ modulo $T(X)$, finds
! 3814: the ``reverse polmod'' $B(X)$ modulo $Q(X)$, where $Q$ is the minimal
! 3815: polynomial of $a$, which must be equal to the degree of $T$, and such that if
! 3816: $\theta$ is a root of $T$ then $\theta=B(\alpha)$ for a certain root $\alpha$
! 3817: of $Q$.
! 3818:
! 3819: This is very useful when one changes the generating element in algebraic
! 3820: extensions.
! 3821:
! 3822: \syn{polmodrecip}{x}.
! 3823:
! 3824: \subsecidx{newtonpoly}$(x,p)$: gives the vector of the slopes of the Newton
! 3825: polygon of the polynomial $x$ with respect to the prime number $p$. The $n$
! 3826: components of the vector are in decreasing order, where $n$ is equal to the
! 3827: degree of $x$. Vertical slopes occur iff the constant coefficient of $x$ is
! 3828: zero and are denoted by \kbd{VERYBIGINT}, the biggest single precision
! 3829: integer representable on the machine ($2^{31}-1$ (resp.~$2^{63}-1$) on 32-bit
! 3830: (resp.~64-bit) machines), see \secref{se:valuation}.
! 3831:
! 3832: \syn{newtonpoly}{x,p}.
! 3833:
! 3834: \subsecidx{nfalgtobasis}$(\var{nf},x)$: this is the inverse function of
! 3835: \kbd{nfbasistoalg}. Given an object $x$ whose entries are expressed as
! 3836: algebraic numbers in the number field $\var{nf}$, transforms it so that the
! 3837: entries are expressed as a column vector on the integral basis
! 3838: \kbd{\var{nf}.zk}.
! 3839:
! 3840: \syn{algtobasis}{\var{nf},x}.
! 3841:
! 3842: \subsecidx{nfbasis}$(x,\{\fl=0\},\{p\})$: \idx{integral basis} of the number
! 3843: field defined by the irreducible, preferably monic, polynomial $x$,
! 3844: using a modified version of the \idx{round 4} algorithm by
! 3845: default. The binary digits of $\fl$ have the following meaning:
! 3846:
! 3847: 1: assume that no square of a prime greater than the default \kbd{primelimit}
! 3848: divides the discriminant of $x$, i.e.~that the index of $x$ has only small
! 3849: prime divisors.
! 3850:
! 3851: 2: use \idx{round 2} algorithm. For small degrees and coefficient size, this is
! 3852: sometimes a little faster. (This program is the translation into C of a program
! 3853: written by David \idx{Ford} in Algeb.)
! 3854:
! 3855: Thus for instance, if $\fl=3$, this uses the round 2 algorithm and outputs
! 3856: an order which will be maximal at all the small primes.
! 3857:
! 3858: If $p$ is present, we assume (without checking!) that it is the two-column
! 3859: matrix of the factorization of the discriminant of the polynomial $x$. Note
! 3860: that it does \var{not} have to be a complete factorization. This is
! 3861: especially useful if only a local integral basis for some small set of places
! 3862: is desired: only factors with exponents greater or equal to 2 will be
! 3863: considered.
! 3864:
! 3865: \syn{nfbasis0}{x,\fl,p}. An extended version
! 3866: is $\teb{nfbasis}(x,\&d,\fl,p)$, where $d$ will receive the discriminant of
! 3867: the number field (\var{not} of the polynomial $x$), and an omitted $p$ should
! 3868: be input as \kbd{gzero}. Also available are $\teb{base}(x,\&d)$ ($\fl=0$),
! 3869: $\teb{base2}(x,\&d)$ ($\fl=2$) and $\teb{factoredbase}(x,p,\&d)$.
! 3870:
! 3871: \subsecidx{nfbasistoalg}$(\var{nf},x)$: this is the inverse function of
! 3872: \kbd{nfalgtobasis}. Given an object $x$ whose entries are expressed on the
! 3873: integral basis \kbd{\var{nf}.zk}, transforms it into an object whose entries
! 3874: are algebraic numbers (i.e.~polmods).
! 3875:
! 3876: \syn{basistoalg}{\var{nf},x}.
! 3877:
! 3878: \subsecidx{nfdetint}$(\var{nf},x)$: given a pseudo-matrix $x$, computes a
! 3879: non-zero ideal contained in (i.e.~multiple of) the determinant of $x$. This
! 3880: is particularly useful in conjunction with \kbd{nfhnfmod}.
! 3881:
! 3882: \syn{nfdetint}{\var{nf},x}.
! 3883:
! 3884: \subsecidx{nfdisc}$(x,\{\fl=0\},\{p\})$: \idx{field discriminant} of the
! 3885: number field defined by the integral, preferably monic, irreducible
! 3886: polynomial $x$. $\fl$ and $p$ are exactly as in \kbd{nfbasis}. That is, $p$
! 3887: provides the matrix of a partial factorization of the discriminant of $x$,
! 3888: and binary digits of $\fl$ are as follows:
! 3889:
! 3890: 1: assume that no square of a prime greater than \kbd{primelimit}
! 3891: divides the discriminant.
! 3892:
! 3893: 2: use the round 2 algorithm, instead of the default \idx{round 4}.
! 3894: This should be
! 3895: slower except maybe for polynomials of small degree and coefficients.
! 3896:
! 3897: \syn{nfdiscf0}{x,\fl,p} where, to omit $p$, you should input \kbd{gzero}. You
! 3898: can also use $\teb{discf}(x)$ ($\fl=0$).
! 3899:
! 3900: \subsecidx{nfeltdiv}$(\var{nf},x,y)$: given two elements $x$ and $y$ in
! 3901: \var{nf}, computes their quotient $x/y$ in the number field $\var{nf}$.
! 3902:
! 3903: \syn{element_div}{\var{nf},x,y}.
! 3904:
! 3905: \subsecidx{nfeltdiveuc}$(\var{nf},x,y)$: given two elements $x$ and $y$ in
! 3906: \var{nf}, computes an algebraic integer $q$ in the number field $\var{nf}$
! 3907: such that the components of $x-qy$ are reasonably small. In fact, this is
! 3908: functionally identical to \kbd{round(nfeltdiv(\var{nf},x,y))}.
! 3909:
! 3910: \syn{nfdiveuc}{\var{nf},x,y}.
! 3911:
! 3912: \subsecidx{nfeltdivmodpr}$(\var{nf},x,y,\var{pr})$: given two elements $x$
! 3913: and $y$ in \var{nf} and \var{pr} a prime ideal in \kbd{modpr} format (see
! 3914: \tet{nfmodprinit}), computes their quotient $x / y$ modulo the prime ideal
! 3915: \var{pr}.
! 3916:
! 3917: \syn{element_divmodpr}{\var{nf},x,y,\var{pr}}.
! 3918:
! 3919: \subsecidx{nfeltdivrem}$(\var{nf},x,y)$: given two elements $x$ and $y$ in
! 3920: \var{nf}, gives a two-element row vector $[q,r]$ such that $x=qy+r$, $q$ is
! 3921: an algebraic integer in $\var{nf}$, and the components of $r$ are
! 3922: reasonably small.
! 3923:
! 3924: \syn{nfdivres}{\var{nf},x,y}.
! 3925:
! 3926: \subsecidx{nfeltmod}$(\var{nf},x,y)$: given two elements $x$ and $y$ in
! 3927: \var{nf}, computes an element $r$ of $\var{nf}$ of the form $r=x-qy$ with
! 3928: $q$ and algebraic integer, and such that $r$ is small. This is functionally
! 3929: identical to
! 3930: $$\kbd{x - nfeltmul(\var{nf},round(nfeltdiv(\var{nf},x,y)),y)}.$$
! 3931:
! 3932: \syn{nfmod}{\var{nf},x,y}.
! 3933:
! 3934: \subsecidx{nfeltmul}$(\var{nf},x,y)$: given two elements $x$ and $y$ in
! 3935: \var{nf}, computes their product $x*y$ in the number field $\var{nf}$.
! 3936:
! 3937: \syn{element_mul}{\var{nf},x,y}.
! 3938:
! 3939: \subsecidx{nfeltmulmodpr}$(\var{nf},x,y,\var{pr})$: given two elements $x$ and
! 3940: $y$ in \var{nf} and \var{pr} a prime ideal in \kbd{modpr} format (see
! 3941: \tet{nfmodprinit}), computes their product $x*y$ modulo the prime ideal
! 3942: \var{pr}.
! 3943:
! 3944: \syn{element_mulmodpr}{\var{nf},x,y,\var{pr}}.
! 3945:
! 3946: \subsecidx{nfeltpow}$(\var{nf},x,k)$: given an element $x$ in \var{nf},
! 3947: and a positive or negative integer $k$, computes $x^k$ in the number field
! 3948: $\var{nf}$.
! 3949:
! 3950: \syn{element_pow}{\var{nf},x,k}.
! 3951:
! 3952: \subsecidx{nfeltpowmodpr}$(\var{nf},x,k,\var{pr})$: given an element $x$ in
! 3953: \var{nf}, an integer $k$ and a prime ideal \var{pr} in \kbd{modpr} format
! 3954: (see \tet{nfmodprinit}), computes $x^k$ modulo the prime ideal \var{pr}.
! 3955:
! 3956: \syn{element_powmodpr}{\var{nf},x,k,\var{pr}}.
! 3957:
! 3958: \subsecidx{nfeltreduce}$(\var{nf},x,\var{ideal})$: given an ideal in
! 3959: Hermite normal form and an element $x$ of the number field $\var{nf}$,
! 3960: finds an element $r$ in $\var{nf}$ such that $x-r$ belongs to the ideal
! 3961: and $r$ is small.
! 3962:
! 3963: \syn{element_reduce}{\var{nf},x,\var{ideal}}.
! 3964:
! 3965: \subsecidx{nfeltreducemodpr}$(\var{nf},x,\var{pr})$: given
! 3966: an element $x$ of the number field $\var{nf}$ and a prime ideal \var{pr} in
! 3967: \kbd{modpr} format compute a canonical representative for the class of $x$
! 3968: modulo \var{pr}.
! 3969:
! 3970: \syn{nfreducemodpr2}{\var{nf},x,\var{pr}}.
! 3971:
! 3972: \subsecidx{nfeltval}$(\var{nf},x,\var{pr})$: given an element $x$ in
! 3973: \var{nf} and a prime ideal \var{pr} in the format output by
! 3974: \kbd{idealprimedec}, computes their the valuation at \var{pr} of the
! 3975: element $x$. The same result could be obtained using
! 3976: \kbd{idealval(\var{nf},x,\var{pr})} (since $x$ would then be converted to a
! 3977: principal ideal), but it would be less efficient.
! 3978:
! 3979: \syn{element_val}{\var{nf},x,\var{pr}}, and the result is a \kbd{long}.
! 3980:
! 3981: \subsecidx{nffactor}$(\var{nf},x)$: factorization of the univariate
! 3982: polynomial $x$ over the number field $\var{nf}$ given by \kbd{nfinit}. $x$
! 3983: has coefficients in $\var{nf}$ (i.e.~either scalar, polmod, polynomial or
! 3984: column vector). The main variable of $\var{nf}$ must be of \var{lower}
! 3985: priority than that of $x$ (in other words, the variable number of $\var{nf}$
! 3986: must be \var{greater} than that of $x$). However if the polynomial defining
! 3987: the number field occurs explicitly in the coefficients of $x$ (as modulus of
! 3988: a \typ{POLMOD}), its main variable must be \var{the same} as the main
! 3989: variable of $x$. For example,
! 3990: \bprog
! 3991: ? nf = nfinit(y^2 + 1);
! 3992: ? nffactor(nf, x^2 + y); \\@com OK
! 3993: ? nffactor(nf, x^2 + Mod(y, y^2+1)); \\ @com OK
! 3994: ? nffactor(nf, x^2 + Mod(z, z^2+1)); \\ @com WRONG
! 3995: @eprog
! 3996:
! 3997: \syn{nffactor}{\var{nf},x}.
! 3998:
! 3999: \subsecidx{nffactormod}$(\var{nf},x,\var{pr})$: factorization of the
! 4000: univariate polynomial $x$ modulo the prime ideal \var{pr} in the number
! 4001: field $\var{nf}$. $x$ can have coefficients in the number field (scalar,
! 4002: polmod, polynomial, column vector) or modulo the prime ideal (integermod
! 4003: modulo the rational prime under \var{pr}, polmod or polynomial with
! 4004: integermod coefficients, column vector of integermod). The prime ideal
! 4005: \var{pr} \var{must} be in the format output by \kbd{idealprimedec}. The
! 4006: main variable of $\var{nf}$ must be of lower priority than that of $x$ (in
! 4007: other words the variable number of $\var{nf}$ must be greater than that of
! 4008: $x$). However if the coefficients of the number field occur explicitly (as
! 4009: polmods) as coefficients of $x$, the variable of these polmods \var{must}
! 4010: be the same as the main variable of $t$ (see \kbd{nffactor}).
! 4011:
! 4012: \syn{nffactormod}{\var{nf},x,\var{pr}}.
! 4013:
! 4014: \subsecidx{nfgaloisapply}$(\var{nf},\var{aut},x)$: $\var{nf}$ being a
! 4015: number field as output by \kbd{nfinit}, and \var{aut} being a \idx{Galois}
! 4016: automorphism of $\var{nf}$ expressed either as a polynomial or a polmod
! 4017: (such automorphisms being found using for example one of the variants of
! 4018: \kbd{nfgaloisconj}), computes the action of the automorphism \var{aut} on
! 4019: the object $x$ in the number field. $x$ can be an element (scalar, polmod,
! 4020: polynomial or column vector) of the number field, an ideal (either given by
! 4021: $\Z_K$-generators or by a $\Z$-basis), a prime ideal (given as a 5-element
! 4022: row vector) or an idele (given as a 2-element row vector). Because of
! 4023: possible confusion with elements and ideals, other vector or matrix
! 4024: arguments are forbidden.
! 4025:
! 4026: \syn{galoisapply}{\var{nf},\var{aut},x}.
! 4027:
! 4028: \subsecidx{nfgaloisconj}$(\var{nf},\{\fl=0\},\{d\})$: $\var{nf}$ being a
! 4029: number field as output by \kbd{nfinit}, computes the conjugates of a root
! 4030: $r$ of the non-constant polynomial $x=\var{nf}[1]$ expressed as
! 4031: polynomials in $r$. This can be used even if the number field $\var{nf}$ is
! 4032: not \idx{Galois} since some conjugates may lie in the field. As a note to
! 4033: old-timers of PARI, starting with version 2.0.17 this function works much
! 4034: better than in earlier versions.
! 4035:
! 4036: $\var{nf}$ can simply be a polynomial if $\fl\neq 1$.
! 4037:
! 4038: If no flags or $\fl=0$, if $\var{nf}$ is a number field use a
! 4039: combination of flag $4$ and $1$ and the result is always complete,
! 4040: else use a combination of flag $4$ and $2$ and the result is subject
! 4041: to the restriction of $\fl=2$, but a warning is issued when it is not
! 4042: proven complete.
! 4043:
! 4044: If $\fl=1$, use \kbd{nfroots} (require a number field).
! 4045:
! 4046: If $\fl=2$, use complex approximations to the roots and an integral
! 4047: \idx{LLL}. The result is not guaranteed to be complete: some
! 4048: conjugates may be missing (no warning issued), especially so if the
! 4049: corresponding polynomial has a huge index. In that case, increasing
! 4050: the default precision may help.
! 4051:
! 4052: If $\fl=4$, use Allombert's algorithm and permutation testing. If the
! 4053: field is Galois with ``weakly'' super solvable Galois group, return
! 4054: the complete list of automorphisms, else only the identity element. If
! 4055: present, $d$ is assumed to be a multiple of the least common
! 4056: denominator of the conjugates expressed as polynomial in a root of
! 4057: \var{pol}.
! 4058:
! 4059: A group G is ``weakly'' super solvable if it contains a super solvable
! 4060: normal subgroup $H$ such that $G=H$ , or $G/H \simeq A_4$ , or $G/H \simeq
! 4061: S_4$. Abelian and nilpotent groups are ``weakly'' super solvable. In
! 4062: practice, almost all groups of small order are ``weakly'' super solvable, the
! 4063: exceptions having order 36(1 exception), 48(2), 56(1), 60(1), 72(5), 75(1),
! 4064: 80(1), 96(10) and $\geq 108$.
! 4065:
! 4066: Hence $\fl = 4$ permits to quickly check whether a polynomial of order
! 4067: strictly less than $36$ is Galois or not. This method is much faster than
! 4068: \kbd{nfroots} and can be applied to polynomials of degree larger than $50$.
! 4069:
! 4070: \syn{galoisconj0}{\var{nf},\fl,d,\var{prec}}. Also available are
! 4071: $\teb{galoisconj}(\var{nf})$ for $\fl=0$,
! 4072: $\teb{galoisconj2}(\var{nf},n,\var{prec})$ for $\fl=2$ where $n$ is a bound
! 4073: on the number of conjugates, and $\teb{galoisconj4}(\var{nf},d)$
! 4074: corresponding to $\fl=4$.
! 4075:
! 4076: \subsecidx{nfhilbert}$(\var{nf},a,b,\{\var{pr}\})$: if \var{pr} is omitted,
! 4077: compute the global \idx{Hilbert symbol} $(a,b)$ in $\var{nf}$, that is $1$
! 4078: if $x^2 - a y^2 - b z^2$ has a non trivial solution $(x,y,z)$ in $\var{nf}$,
! 4079: and $-1$ otherwise. Otherwise compute the local symbol modulo the prime ideal
! 4080: \var{pr} (as output by \kbd{idealprimedec}).
! 4081:
! 4082: \syn{nfhilbert}{\var{nf},a,b,\var{pr}}, where an omitted \var{pr} is coded
! 4083: as \kbd{NULL}.
! 4084:
! 4085: \subsecidx{nfhnf}$(\var{nf},x)$: given a pseudo-matrix $(A,I)$, finds a
! 4086: pseudo-basis in \idx{Hermite normal form} of the module it generates.
! 4087:
! 4088: \syn{nfhermite}{\var{nf},x}.
! 4089:
! 4090: \subsecidx{nfhnfmod}$(\var{nf},x,\var{detx})$: given a pseudo-matrix $(A,I)$
! 4091: and an ideal \var{detx} which is contained in (read integral multiple of) the
! 4092: determinant of $(A,I)$, finds a pseudo-basis in \idx{Hermite normal form}
! 4093: of the module generated by $(A,I)$. This avoids coefficient explosion.
! 4094: \var{detx} can be computed using the function \kbd{nfdetint}.
! 4095:
! 4096: \syn{nfhermitemod}{\var{nf},x,\var{detx}}.
! 4097:
! 4098: \subsecidx{nfinit}$(\var{pol},\{\fl=0\})$: \var{pol} being a non-constant,
! 4099: preferably monic, irreducible polynomial in $\Z[X]$, initializes a
! 4100: \var{number field} structure (\kbd{nf}) associated to the field $K$ defined
! 4101: by \var{pol}. As such, it's a technical object passed as the first argument
! 4102: to most \kbd{nf}\var{xxx} functions, but it contains some information which
! 4103: may be directly useful. Access to this information via \var{member
! 4104: functions} is prefered since the specific data organization specified below
! 4105: may change in the future. Currently, \kbd{nf} is a row vector with 9
! 4106: components:
! 4107:
! 4108: $\var{nf}[1]$ contains the polynomial \var{pol} (\kbd{\var{nf}.pol}).
! 4109:
! 4110: $\var{nf}[2]$ contains $[r1,r2]$ (\kbd{\var{nf}.sign}), the number of real
! 4111: and complex places of $K$.
! 4112:
! 4113: $\var{nf}[3]$ contains the discriminant $d(K)$ (\kbd{\var{nf}.disc}) of $K$.
! 4114:
! 4115: $\var{nf}[4]$ contains the index of $\var{nf}[1]$,
! 4116: i.e.~$[\Z_K : \Z[\theta]]$, where $\theta$ is any root of $\var{nf}[1]$.
! 4117:
! 4118: $\var{nf}[5]$ is a vector containing 7 matrices $M$, $MC$, $T2$, $T$,
! 4119: $MD$, $TI$, $MDI$ useful for certain computations in the number field $K$.
! 4120:
! 4121: \quad$\bullet$ $M$ is the $(r1+r2)\times n$ matrix whose columns represent
! 4122: the numerical values of the conjugates of the elements of the integral
! 4123: basis.
! 4124:
! 4125: \quad$\bullet$ $MC$ is essentially the conjugate of the transpose of $M$,
! 4126: except that the last $r2$ columns are also multiplied by 2.
! 4127:
! 4128: \quad$\bullet$ $T2$ is an $n\times n$ matrix equal to the real part of the
! 4129: product $MC\cdot M$ (which is a real positive definite symmetric matrix), the
! 4130: so-called $T_2$-matrix (\kbd{\var{nf}.t2}).
! 4131:
! 4132: \quad$\bullet$ $T$ is the $n\times n$ matrix whose coefficients are
! 4133: $\text{Tr}(\omega_i\omega_j)$ where the $\omega_i$ are the elements of the
! 4134: integral basis. Note that $T=\overline{MC}\cdot M$ and in particular that
! 4135: $T=T_2$ if the field is totally real (in practice $T_2$ will have real
! 4136: approximate entries and $T$ will have integer entries). Note also that
! 4137: $\det(T)$ is equal to the discriminant of the field $K$.
! 4138:
! 4139: \quad$\bullet$ The columns of $MD$ (\kbd{\var{nf}.diff}) express a $\Z$-basis
! 4140: of the different of $K$ on the integral basis.
! 4141:
! 4142: \quad$\bullet$ $TI$ is equal to $d(K)T^{-1}$, which has integral
! 4143: coefficients. Note that, understood as as ideal, the matrix $T^{-1}$
! 4144: generates the codifferent ideal.
! 4145:
! 4146: \quad$\bullet$ Finally, $MDI$ is a two-element representation (for faster
! 4147: ideal product) of $d(K)$ times the codifferent ideal
! 4148: (\kbd{\var{nf}.disc$*$\var{nf}.codiff}, which is an integral ideal). $MDI$
! 4149: is only used in \tet{idealinv}.
! 4150:
! 4151: $\var{nf}[6]$ is the vector containing the $r1+r2$ roots
! 4152: (\kbd{\var{nf}.roots}) of $\var{nf}[1]$ corresponding to the $r1+r2$
! 4153: embeddings of the number field into $\C$ (the first $r1$ components are real,
! 4154: the next $r2$ have positive imaginary part).
! 4155:
! 4156: $\var{nf}[7]$ is an integral basis in Hermite normal form for $\Z_K$
! 4157: (\kbd{\var{nf}.zk}) expressed on the powers of~$\theta$.
! 4158:
! 4159: $\var{nf}[8]$ is the $n\times n$ integral matrix expressing the power
! 4160: basis in terms of the integral basis, and finally
! 4161:
! 4162: $\var{nf}[9]$ is the $n\times n^2$ matrix giving the multiplication table
! 4163: of the integral basis.
! 4164:
! 4165: If a non monic polynomial is input, \kbd{nfinit} will transform it into a
! 4166: monic one, then reduce it (see $\fl=3$). It is allowed, though not very
! 4167: useful given the existence of \tet{nfnewprec}, to input a \kbd{nf} or a
! 4168: \kbd{bnf} instead of a polynomial.
! 4169:
! 4170: The special input format $[x,B]$ is also accepted where $x$ is a polynomial
! 4171: as above and $B$ is the integer basis, as computed by \tet{nfbasis}. This can
! 4172: be useful since \kbd{nfinit} uses the round 4 algorithm by default, which can
! 4173: be very slow in pathological cases where round 2 (\kbd{nfbasis(x,2)}) would
! 4174: succeed very quickly.
! 4175:
! 4176: If $\fl=2$: \var{pol} is changed into another polynomial $P$ defining the same
! 4177: number field, which is as simple as can easily be found using the
! 4178: \kbd{polred} algorithm, and all the subsequent computations are done using
! 4179: this new polynomial. In particular, the first component of the result is the
! 4180: modified polynomial.
! 4181:
! 4182: If $\fl=3$, does a \kbd{polred} as in case 2, but outputs
! 4183: $[\var{nf},\kbd{Mod}(a,P)]$, where $\var{nf}$ is as before and
! 4184: $\kbd{Mod}(a,P)=\kbd{Mod}(x,\var{pol})$ gives the change of
! 4185: variables. This is implicit when \var{pol} is not monic: first a linear change
! 4186: of variables is performed, to get a monic polynomial, then a \kbd{polred}
! 4187: reduction.
! 4188:
! 4189: If $\fl=4$, as $2$ but uses a partial \kbd{polred}.
! 4190:
! 4191: If $\fl=5$, as $3$ using a partial \kbd{polred}.
! 4192:
! 4193: \syn{nfinit0}{x,\fl,\var{prec}}.
! 4194:
! 4195: \subsecidx{nfisideal}$(\var{nf},x)$: returns 1 if $x$ is an ideal in
! 4196: the number field $\var{nf}$, 0 otherwise.
! 4197:
! 4198: \syn{isideal}{x}.
! 4199:
! 4200: \subsecidx{nfisincl}$(x,y)$: tests whether the number field $K$ defined
! 4201: by the polynomial $x$ is conjugate to a subfield of the field $L$ defined
! 4202: by $y$ (where $x$ and $y$ must be in $\Q[X]$). If they are not, the output
! 4203: is the number 0. If they are, the output is a vector of polynomials, each
! 4204: polynomial $a$ representing an embedding of $K$ into $L$, i.e.~being such
! 4205: that $y\mid x\circ a$.
! 4206:
! 4207: If $y$ is a number field (\var{nf}), a much faster algorithm is used
! 4208: (factoring $x$ over $y$ using \tet{nffactor}). Before version 2.0.14, this
! 4209: wasn't guaranteed to return all the embeddings, hence was triggered by a
! 4210: special flag. This is no more the case.
! 4211:
! 4212: \syn{nfisincl}{x,y,\fl}.
! 4213:
! 4214: \subsecidx{nfisisom}$(x,y)$: as \tet{nfisincl}, but tests
! 4215: for isomorphism. If either $x$ or $y$ is a number field, a much faster
! 4216: algorithm will be used.
! 4217:
! 4218: \syn{nfisisom}{x,y,\fl}.
! 4219:
! 4220: \subsecidx{nfnewprec}$(\var{nf})$: transforms the number field $\var{nf}$
! 4221: into the corresponding data using current (usually larger) precision. This
! 4222: function works as expected if $\var{nf}$ is in fact a $\var{bnf}$ (update
! 4223: $\var{bnf}$ to current precision) but may be quite slow (many generators of
! 4224: principal ideals have to be computed).
! 4225:
! 4226: \syn{nfnewprec}{\var{nf},\var{prec}}.
! 4227:
! 4228: \subsecidx{nfkermodpr}$(\var{nf},a,\var{pr})$: kernel of the matrix $a$ in
! 4229: $\Z_K/\var{pr}$, where \var{pr} is in \key{modpr} format
! 4230: (see \kbd{nfmodprinit}).
! 4231:
! 4232: \syn{nfkermodpr}{\var{nf},a,\var{pr}}.
! 4233:
! 4234: \subsecidx{nfmodprinit}$(\var{nf},\var{pr})$: transforms the prime ideal
! 4235: \var{pr} into \tet{modpr} format necessary for all operations modulo
! 4236: \var{pr} in the number field \var{nf}. Returns a two-component vector
! 4237: $[P,a]$, where $P$ is the \idx{Hermite normal form} of \var{pr}, and $a$ is
! 4238: an integral element congruent to $1$ modulo \var{pr}, and congruent to $0$
! 4239: modulo $p / pr^e$. Here $p = \Z \cap \var{pr}$ and $e$
! 4240: is the absolute ramification index.\label{se:nfmodprinit}
! 4241:
! 4242: \syn{nfmodprinit}{\var{nf},\var{pr}}.
! 4243:
! 4244: \subsecidx{nfsubfields}$(\var{pol},\{d=0\})$: finds all subfields of degree
! 4245: $d$ of the number field defined by the (monic, integral) polynomial
! 4246: \var{pol} (all subfields if $d$ is null or omitted). The result is a vector
! 4247: of subfields, each being given by $[g,h]$, where $g$ is an absolute equation
! 4248: and $h$ expresses one of the roots of $g$ in terms of the root $x$ of the
! 4249: polynomial defining $\var{nf}$. This routine uses J.~Kl\"uners's algorithm,
! 4250: our naïve implementation would be very slow when no sufficiently inert primes
! 4251: can be found, e.g.~when \var{nf} is a compositum of many quadratic fields. So
! 4252: it may abort with an error message (\kbd{too many block systems}) if it looks
! 4253: like the computation is hopeless. This shall eventually be
! 4254: corrected, using the ideas from \kbd{nfgaloisconj}.\sidx{Galois}\sidx{subfield}
! 4255:
! 4256: %If the field is abelian, you can circonvene the problem by using
! 4257: %\tet{galoisinit} and \tet{galoisfixedfield}, as in
! 4258: %\bprog
! 4259: % subf(pol) =
! 4260: % {
! 4261: % local(gal,G,H,h,l,gen, L = []);
! 4262: % gl = galoisinit(pol);
! 4263: % G = matdiagonal(Vec(g.orders));
! 4264: % l = length(G); gen = Mat(vectorv(l,i, g.gen[i]));
! 4265: % forsubgroup(H = G,,
! 4266: % h = mathnf(concat(H,G));
! 4267: % perm = vector(l,i, factorback(concat(gen, h[,i])));
! 4268: % L = concat(L, [galoisfixedfield(g, perm)])
! 4269: % ); L
! 4270: % }
! 4271: %@eprog
! 4272: %which returns the same output as \kbd{nfsubfields(pol)}. For non-abelian
! 4273: %Galois fields, you can still use \tet{galoisinit} and \teb{galoisfixedfield},
! 4274: %but you will have to use another package than PARI to compute the subgroup
! 4275: %lattice, since \tet{forsubgroup} is restricted to the abelian case.
! 4276:
! 4277: \syn{subfields}{\var{nf},d}.
! 4278:
! 4279: \subsecidx{nfroots}$(\var{nf},x)$: roots of the polynomial $x$ in the number
! 4280: field $\var{nf}$ given by \kbd{nfinit} without multiplicity. $x$ has
! 4281: coefficients in the number field (scalar, polmod, polynomial, column
! 4282: vector). The main variable of $\var{nf}$ must be of lower priority than that
! 4283: of $x$ (in other words the variable number of $\var{nf}$ must be greater than
! 4284: that of $x$). However if the coefficients of the number field occur
! 4285: explicitly (as polmods) as coefficients of $x$, the variable of these
! 4286: polmods \var{must} be the same as the main variable of $t$ (see
! 4287: \kbd{nffactor}).
! 4288:
! 4289: \syn{nfroots}{\var{nf},x}.
! 4290:
! 4291: \subsecidx{nfrootsof1}$(\var{nf})$: computes the number of roots of unity
! 4292: $w$ and a primitive $w$-th root of unity (expressed on the integral basis)
! 4293: belonging to the number field $\var{nf}$. The result is a two-component
! 4294: vector $[w,z]$ where $z$ is a column vector expressing a primitive $w$-th
! 4295: root of unity on the integral basis \kbd{\var{nf}.zk}.
! 4296:
! 4297: \syn{rootsof1}{\var{nf}}.
! 4298:
! 4299: \subsecidx{nfsnf}$(\var{nf},x)$: given a torsion module $x$ as a 3-component
! 4300: row
! 4301: vector $[A,I,J]$ where $A$ is a square invertible $n\times n$ matrix, $I$ and
! 4302: $J$ are two ideal lists, outputs an ideal list $d_1,\dots,d_n$ which is the
! 4303: \idx{Smith normal form} of $x$. In other words, $x$ is isomorphic to
! 4304: $\Z_K/d_1\oplus\cdots\oplus\Z_K/d_n$ and $d_i$ divides $d_{i-1}$ for $i\ge2$.
! 4305: The link between $x$ and $[A,I,J]$ is as follows: if $e_i$ is the canonical
! 4306: basis of $K^n$, $I=[b_1,\dots,b_n]$ and $J=[a_1,\dots,a_n]$, then $x$ is
! 4307: isomorphic to
! 4308: $$ (b_1e_1\oplus\cdots\oplus b_ne_n) / (a_1A_1\oplus\cdots\oplus a_nA_n)
! 4309: \enspace, $$
! 4310: where the $A_j$ are the columns of the matrix $A$. Note that every finitely
! 4311: generated torsion module can be given in this way, and even with $b_i=Z_K$
! 4312: for all $i$.
! 4313:
! 4314: \syn{nfsmith}{\var{nf},x}.
! 4315:
! 4316: \subsecidx{nfsolvemodpr}$(\var{nf},a,b,\var{pr})$: solution of $a\cdot x = b$
! 4317: in $\Z_K/\var{pr}$, where $a$ is a matrix and $b$ a column vector, and where
! 4318: \var{pr} is in \key{modpr} format (see \kbd{nfmodprinit}).
! 4319:
! 4320: \syn{nfsolvemodpr}{\var{nf},a,b,\var{pr}}.
! 4321:
! 4322: \subsecidx{polcompositum}$(x,y,\{\fl=0\})$: $x$ and $y$ being polynomials
! 4323: in $\Z[X]$ in the same variable, outputs a vector giving the list of all
! 4324: possible composita of the number fields defined by $x$ and $y$, if $x$ and
! 4325: $y$ are irreducible, or of the corresponding \'etale algebras, if they are
! 4326: only squarefree. Returns an error if one of the polynomials is not
! 4327: squarefree. When one of the polynomials is irreducible (say $x$), it is
! 4328: often \var{much} faster to use \kbd{nffactor(nfinit($x$), $y$)} then
! 4329: \tet{rnfequation}.
! 4330:
! 4331: If $\fl=1$, outputs a vector of 4-component vectors $[z,a,b,k]$, where $z$
! 4332: ranges through the list of all possible compositums as above, and $a$
! 4333: (resp. $b$) expresses the root of $x$ (resp. $y$) as a polmod in a root of
! 4334: $z$, and $k$ is a small integer k such that $a+kb$ is the chosen root of
! 4335: $z$.
! 4336:
! 4337: The compositum will quite often be defined by a complicated polynomial,
! 4338: which it is advisable to reduce before further work. Here is a simple
! 4339: example involving the field $\Q(\zeta_5, 5^{1/5})$:
! 4340: \bprog
! 4341: ? z = polcompositum(x^5 - 5, polcyclo(5), 1)[1];
! 4342: ? pol = z[1] \\@com \kbd{pol} defines the compositum
! 4343: %2 = x^20 + 5*x^19 + 15*x^18 + 35*x^17 + 70*x^16 + 141*x^15 + 260*x^14 \
! 4344: + 355*x^13 + 95*x^12 - 1460*x^11 - 3279*x^10 - 3660*x^9 - 2005*x^8 \
! 4345: + 705*x^7 + 9210*x^6 + 13506*x^5 + 7145*x^4 - 2740*x^3 + 1040*x^2 \
! 4346: - 320*x + 256
! 4347: ? a = z[2]; a^5 - 5 \\@com \kbd{a} is a fifth root of $5$
! 4348: %3 = 0
! 4349: ? z = polredabs(pol, 1); \\@com look for a simpler polynomial
! 4350: ? pol = z[1]
! 4351: %5 = x^20 + 25*x^10 + 5
! 4352: ? a = subst(a.pol, x, z[2]) \\@com \kbd{a} in the new coordinates
! 4353: %6 = Mod(-5/22*x^19 + 1/22*x^14 - 123/22*x^9 + 9/11*x^4, x^20 + 25*x^10 + 5)
! 4354: @eprog
! 4355:
! 4356: \syn{polcompositum0}{x,y,\fl}.
! 4357:
! 4358: \subsecidx{polgalois}$(x)$: \idx{Galois} group of the non-constant polynomial
! 4359: $x\in\Q[X]$. In the present version \vers, $x$ must be irreducible and
! 4360: the degree of $x$ must be less than or equal to 7. On certain versions for
! 4361: which the data file of Galois resolvents has been installed (available
! 4362: in the Unix distribution as a separate package), degrees 8, 9, 10 and 11
! 4363: are also implemented.
! 4364:
! 4365: The output is a 3-component vector $[n,s,k]$ with the following meaning: $n$
! 4366: is the cardinality of the group, $s$ is its signature ($s=1$ if the group is
! 4367: a subgroup of the alternating group $A_n$, $s=-1$ otherwise), and $k$ is the
! 4368: number of the group corresponding to a given pair $(n,s)$ ($k=1$ except in 2
! 4369: cases). Specifically, the groups are coded as follows, using standard
! 4370: notations (see GTM 138, quoted at the beginning of this section; see also
! 4371: ``The transitive groups of degree up to eleven'', by G.~Butler and J.~McKay
! 4372: in Communications in Algebra, vol.~11, 1983, pp.~863--911):
! 4373: \smallskip
! 4374: In degree 1: $S_1=[1,-1,1]$.
! 4375: \smallskip
! 4376: In degree 2: $S_2=[2,-1,1]$.
! 4377: \smallskip
! 4378: In degree 3: $A_3=C_3=[3,1,1]$, $S_3=[6,-1,1]$.
! 4379: \smallskip
! 4380: In degree 4: $C_4=[4,-1,1]$, $V_4=[4,1,1]$, $D_4=[8,-1,1]$, $A_4=[12,1,1]$,
! 4381: $S_4=[24,-1,1]$.
! 4382: \smallskip
! 4383: In degree 5: $C_5=[5,1,1]$, $D_5=[10,1,1]$, $M_{20}=[20,-1,1]$,
! 4384: $A_5=[60,1,1]$, $S_5=[120,-1,1]$.
! 4385: \smallskip
! 4386: In degree 6: $C_6=[6,-1,1]$, $S_3=[6,-1,2]$, $D_6=[12,-1,1]$, $A_4=[12,1,1]$,
! 4387: $G_{18}=[18,-1,1]$, $S_4^-=[24,-1,1]$, $A_4\times C_2=[24,-1,2]$,
! 4388: $S_4^+=[24,1,1]$, $G_{36}^-=[36,-1,1]$, $G_{36}^+=[36,1,1]$,
! 4389: $S_4\times C_2=[48,-1,1]$, $A_5=PSL_2(5)=[60,1,1]$, $G_{72}=[72,-1,1]$,
! 4390: $S_5=PGL_2(5)=[120,-1,1]$, $A_6=[360,1,1]$, $S_6=[720,-1,1]$.
! 4391: \smallskip
! 4392: In degree 7: $C_7=[7,1,1]$, $D_7=[14,-1,1]$, $M_{21}=[21,1,1]$,
! 4393: $M_{42}=[42,-1,1]$, $PSL_2(7)=PSL_3(2)=[168,1,1]$, $A_7=[2520,1,1]$,
! 4394: $S_7=[5040,-1,1]$.
! 4395: \smallskip
! 4396: The method used is that of resolvent polynomials and is sensitive to the
! 4397: current precision. The precision is updated internally but, in very rare
! 4398: cases, a wrong result may be returned if the initial precision was not
! 4399: sufficient.
! 4400:
! 4401: \syn{galois}{x,\var{prec}}.
! 4402:
! 4403: \subsecidx{polred}$(x,\{\fl=0\},\{p\})$: finds polynomials with reasonably
! 4404: small coefficients defining subfields of the number field defined by $x$.
! 4405: One of the polynomials always defines $\Q$ (hence is equal to $x-1$),
! 4406: and another always defines the same number field as $x$ if $x$ is irreducible.
! 4407: All $x$ accepted by \tet{nfinit} are also allowed here (e.g. non-monic
! 4408: polynomials, \kbd{nf}, \kbd{bnf}, \kbd{[x,Z\_K\_basis]}).
! 4409:
! 4410: The following binary digits of $\fl$ are significant:
! 4411:
! 4412: 1: does a partial reduction only. This means that only a suborder of the
! 4413: maximal order may be used.
! 4414:
! 4415: 2: gives also elements. The result is a two-column matrix, the first column
! 4416: giving the elements defining these subfields, the second giving the
! 4417: corresponding minimal polynomials.
! 4418:
! 4419: If $p$ is given, it is assumed that it is the two-column matrix of the
! 4420: factorization of the discriminant of the polynomial $x$.
! 4421:
! 4422: \syn{polred0}{x,\fl,p,\var{prec}}, where an omitted $p$ is
! 4423: coded by $gzero$. Also available are $\teb{polred}(x,\var{prec})$ and
! 4424: $\teb{factoredpolred}(x,p,\var{prec})$, both corresponding to $\fl=0$.
! 4425:
! 4426: \subsecidx{polredabs}$(x,\{\fl=0\})$: finds one of the polynomial defining
! 4427: the same number field as the one defined by $x$, and such that the sum of the
! 4428: squares of the modulus of the roots (i.e.~the $T_2$-norm) is minimal.
! 4429: All $x$ accepted by \tet{nfinit} are also allowed here (e.g. non-monic
! 4430: polynomials, \kbd{nf}, \kbd{bnf}, \kbd{[x,Z\_K\_basis]}).
! 4431:
! 4432: The binary digits of $\fl$ mean
! 4433:
! 4434: 1: outputs a two-component row vector $[P,a]$, where $P$ is the default
! 4435: output and $a$ is an element expressed on a root of the polynomial $P$,
! 4436: whose minimal polynomial is equal to $x$.
! 4437:
! 4438: 4: gives \var{all} polynomials of minimal $T_2$ norm (of the two polynomials
! 4439: $P(x)$ and $P(-x)$, only one is given).
! 4440:
! 4441: \syn{polredabs0}{x,\fl,\var{prec}}.
! 4442:
! 4443: \subsecidx{polredord}$(x)$: finds polynomials with reasonably small
! 4444: coefficients and of the same degree as that of $x$ defining suborders of the
! 4445: order defined by $x$. One of the polynomials always defines $\Q$ (hence
! 4446: is equal to $(x-1)^n$, where $n$ is the degree), and another always defines
! 4447: the same order as $x$ if $x$ is irreducible.
! 4448:
! 4449: \syn{ordred}{x}.
! 4450:
! 4451: \subsecidx{poltschirnhaus}$(x)$: applies a random Tschirnhausen
! 4452: transformation to the polynomial $x$, which is assumed to be non-constant
! 4453: and separable, so as to obtain a new equation for the \'etale algebra
! 4454: defined by $x$. This is for instance useful when computing resolvents,
! 4455: hence is used by the \kbd{polgalois} function.
! 4456:
! 4457: \syn{tschirnhaus}{x}.
! 4458:
! 4459: \subsecidx{rnfalgtobasis}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
! 4460: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an element of
! 4461: $L$ expressed as a polynomial or polmod with polmod coefficients, expresses
! 4462: $x$ on the relative integral basis.
! 4463:
! 4464: \syn{rnfalgtobasis}{\var{rnf},x}.
! 4465:
! 4466: \subsecidx{rnfbasis}$(\var{bnf},x)$: given a big number field $\var{bnf}$ as
! 4467: output by \kbd{bnfinit}, and either a polynomial $x$ with coefficients in
! 4468: $\var{bnf}$ defining a relative extension $L$ of $\var{bnf}$, or a
! 4469: pseudo-basis $x$ of such an extension, gives either a true $\var{bnf}$-basis
! 4470: of $L$ if it exists, or an $n+1$-element generating set of $L$ if not, where
! 4471: $n$ is the rank of $L$ over $\var{bnf}$.
! 4472:
! 4473: \syn{rnfbasis}{\var{bnf},x}.
! 4474:
! 4475: \subsecidx{rnfbasistoalg}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
! 4476: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an element of
! 4477: $L$ expressed on the relative integral basis, computes the representation of
! 4478: $x$ as a polmod with polmods coefficients.
! 4479:
! 4480: \syn{rnfbasistoalg}{\var{rnf},x}.
! 4481:
! 4482: \subsecidx{rnfcharpoly}$(\var{nf},T,a,\{v=x\})$: characteristic polynomial of
! 4483: $a$ over $\var{nf}$, where $a$ belongs to the algebra defined by $T$ over
! 4484: $\var{nf}$, i.e.~$\var{nf}[X]/(T)$. Returns a polynomial in variable $v$
! 4485: ($x$ by default).
! 4486:
! 4487: \syn{rnfcharpoly}{\var{nf},T,a,v}, where $v$ is a variable number.
! 4488:
! 4489: \subsecidx{rnfconductor}$(\var{bnf},\var{pol},\{\fl=0\})$: $\var{bnf}$
! 4490: being a big number field as output by \kbd{bnfinit}, and \var{pol} a
! 4491: relative polynomial defining an \idx{Abelian extension}, computes the
! 4492: class field theory conductor of this Abelian extension. The result is
! 4493: a 3-component vector $[\var{conductor},\var{rayclgp},\var{subgroup}]$,
! 4494: where \var{conductor} is the conductor of the extension given as a
! 4495: 2-component row vector $[f_0,f_\infty]$, \var{rayclgp} is the full ray
! 4496: class group corresponding to the conductor given as a 3-component
! 4497: vector [h,cyc,gen] as usual for a group, and \var{subgroup} is a
! 4498: matrix in HNF defining the subgroup of the ray class group on the
! 4499: given generators gen. If $\fl$ is non-zero, check under GRH that
! 4500: \var{pol} indeed defines an Abelian extension, return 0 if it does not.
! 4501:
! 4502: \syn{rnfconductor}{\var{rnf},\var{pol},\fl}.
! 4503:
! 4504: \subsecidx{rnfdedekind}$(\var{nf},\var{pol},\var{pr})$: given a number field
! 4505: $\var{nf}$ as output by \kbd{nfinit} and a polynomial \var{pol} with
! 4506: coefficients in $\var{nf}$ defining a relative extension $L$ of $\var{nf}$,
! 4507: evaluates the relative \idx{Dedekind} criterion over the order defined by a
! 4508: root of \var{pol} for the prime ideal \var{pr} and outputs a 3-component
! 4509: vector as the result. The first component is a flag equal to 1 if the
! 4510: enlarged order could be proven to be \var{pr}-maximal and to 0 otherwise (it
! 4511: may be maximal in the latter case if \var{pr} is ramified in $L$), the second
! 4512: component is a pseudo-basis of the enlarged order and the third component is
! 4513: the valuation at \var{pr} of the order discriminant.
! 4514:
! 4515: \syn{rnfdedekind}{\var{nf},\var{pol},\var{pr}}.
! 4516:
! 4517: \subsecidx{rnfdet}$(\var{nf},M)$: given a pseudomatrix $M$ over the maximal
! 4518: order of $\var{nf}$, computes its pseudodeterminant.
! 4519:
! 4520: \syn{rnfdet}{\var{nf},M}.
! 4521:
! 4522: \subsecidx{rnfdisc}$(\var{nf},\var{pol})$: given a number field $\var{nf}$ as
! 4523: output by \kbd{nfinit} and a polynomial \var{pol} with coefficients in
! 4524: $\var{nf}$ defining a relative extension $L$ of $\var{nf}$, computes
! 4525: the relative
! 4526: discriminant of $L$. This is a two-element row vector $[D,d]$, where $D$ is
! 4527: the relative ideal discriminant and $d$ is the relative discriminant
! 4528: considered as an element of $\var{nf}^*/{\var{nf}^*}^2$. The main variable of
! 4529: $\var{nf}$ \var{must} be of lower priority than that of \var{pol}.
! 4530:
! 4531: Note: As usual, $\var{nf}$ can be a $\var{bnf}$ as output by \kbd{nfinit}.
! 4532:
! 4533: \syn{rnfdiscf}{\var{bnf},\var{pol}}.
! 4534:
! 4535: \subsecidx{rnfeltabstorel}$(\var{rnf},x)$: $\var{rnf}$ being a relative
! 4536: number field
! 4537: extension $L/K$ as output by \kbd{rnfinit} and $x$ being an element of $L$
! 4538: expressed as a polynomial modulo the absolute equation $\var{rnf}[11][1]$,
! 4539: computes $x$ as an element of the relative extension $L/K$ as a polmod with
! 4540: polmod coefficients.
! 4541:
! 4542: \syn{rnfelementabstorel}{\var{rnf},x}.
! 4543:
! 4544: \subsecidx{rnfeltdown}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
! 4545: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an element of
! 4546: $L$ expressed as a polynomial or polmod with polmod coefficients, computes
! 4547: $x$ as an element of $K$ as a polmod, assuming $x$ is in $K$ (otherwise an
! 4548: error will occur). If $x$ is given on the relative integral basis, apply
! 4549: \kbd{rnfbasistoalg} first, otherwise PARI will believe you are dealing with a
! 4550: vector.
! 4551:
! 4552: \syn{rnfelementdown}{\var{rnf},x}.
! 4553:
! 4554: \subsecidx{rnfeltreltoabs}$(\var{rnf},x)$: $\var{rnf}$ being a relative
! 4555: number field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an
! 4556: element of $L$ expressed as a polynomial or polmod with polmod
! 4557: coefficients, computes $x$ as an element of the absolute extension $L/\Q$ as
! 4558: a polynomial modulo the absolute equation $\var{rnf}[11][1]$. If $x$ is
! 4559: given on the relative integral basis, apply \kbd{rnfbasistoalg} first,
! 4560: otherwise PARI will believe you are dealing with a vector.
! 4561:
! 4562: \syn{rnfelementreltoabs}{\var{rnf},x}.
! 4563:
! 4564: \subsecidx{rnfeltup}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
! 4565: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an element of
! 4566: $K$ expressed as a polynomial or polmod, computes $x$ as an element of the
! 4567: absolute extension $L/\Q$ as a polynomial modulo the absolute equation
! 4568: $\var{rnf}[11][1]$. Note that it is unnecessary to compute $x$ as an
! 4569: element of the relative extension $L/K$ (its expression would be identical to
! 4570: itself). If $x$ is given on the integral basis of $K$, apply
! 4571: \kbd{nfbasistoalg} first, otherwise PARI will believe you are dealing with a
! 4572: vector.
! 4573:
! 4574: \syn{rnfelementup}{\var{rnf},x}.
! 4575:
! 4576: \subsecidx{rnfequation}$(\var{nf},\var{pol},\{\fl=0\})$: given a number field
! 4577: $\var{nf}$ as output by \kbd{nfinit} (or simply a polynomial) and a
! 4578: polynomial \var{pol} with coefficients in $\var{nf}$ defining a relative
! 4579: extension $L$ of $\var{nf}$, computes the absolute equation of $L$ over
! 4580: $\Q$.
! 4581:
! 4582: If $\fl$ is non-zero, outputs a 3-component row vector $[z,a,k]$, where
! 4583: $z$ is the absolute equation of $L$ over $\Q$, as in the default behaviour,
! 4584: $a$ expresses as an element of $L$ a root $\alpha$ of the polynomial
! 4585: defining the base field $\var{nf}$, and $k$ is a small integer such that
! 4586: $\theta = \beta+k\alpha$ where $\theta$ is a root of $z$ and $\beta$ a root
! 4587: of $\var{pol}$.
! 4588:
! 4589: The main variable of $\var{nf}$ \var{must} be of lower priority than that
! 4590: of \var{pol}. Note that for efficiency, this does not check whether the
! 4591: relative equation is irreducible over $\var{nf}$, but only if it is
! 4592: squarefree. If it is reducible but squarefree, the result will be the
! 4593: absolute equation of the \'etale algebra defined by \var{pol}. If \var{pol}
! 4594: is not squarefree, an error message will be issued.
! 4595:
! 4596: \syn{rnfequation0}{\var{nf},\var{pol},\fl}.
! 4597:
! 4598: \subsecidx{rnfhnfbasis}$(\var{bnf},x)$: given a big number field $\var{bnf}$
! 4599: as output by \kbd{bnfinit}, and either a polynomial $x$ with coefficients in
! 4600: $\var{bnf}$ defining a relative extension $L$ of $\var{bnf}$, or a
! 4601: pseudo-basis $x$ of such an extension, gives either a true $\var{bnf}$-basis
! 4602: of $L$ in upper triangular Hermite normal form, if it exists,
! 4603: zero otherwise.
! 4604:
! 4605: \syn{rnfhermitebasis}{\var{nf},x}.
! 4606:
! 4607: \subsecidx{rnfidealabstorel}$(\var{rnf},x)$: $\var{rnf}$ being a relative
! 4608: number field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an
! 4609: ideal of the absolute extension $L/\Q$ given in HNF\sidx{Hermite normal form}
! 4610: (if it is not, apply \kbd{idealhnf} first), computes the relative pseudomatrix
! 4611: in HNF giving the ideal $x$ considered as an ideal of the relative extension
! 4612: $L/K$.
! 4613:
! 4614: \syn{rnfidealabstorel}{\var{rnf},x}.
! 4615:
! 4616: \subsecidx{rnfidealdown}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
! 4617: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an ideal of
! 4618: the absolute extension $L/\Q$ given in HNF (if it is not, apply
! 4619: \kbd{idealhnf} first), gives the ideal of $K$ below $x$, i.e.~the
! 4620: intersection of $x$ with $K$. Note that, if $x$ is given as a relative ideal
! 4621: (i.e.~a pseudomatrix in HNF), then it is not necessary to use this function
! 4622: since the result is simply the first ideal of the ideal list of the
! 4623: pseudomatrix.
! 4624:
! 4625: \syn{rnfidealdown}{\var{rnf},x}.
! 4626:
! 4627: \subsecidx{rnfidealhnf}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
! 4628: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being a relative
! 4629: ideal (which can be, as in the absolute case, of many different types,
! 4630: including of course elements), computes as a 2-component row vector the
! 4631: relative Hermite normal form of $x$, the first component being the HNF matrix
! 4632: (with entries on the integral basis), and the second component the ideals.
! 4633:
! 4634: \syn{rnfidealhermite}{\var{rnf},x}.
! 4635:
! 4636: \subsecidx{rnfidealmul}$(\var{rnf},x,y)$: $\var{rnf}$ being a relative number
! 4637: field extension $L/K$ as output by \kbd{rnfinit} and $x$ and $y$ being ideals
! 4638: of the relative extension $L/K$ given by pseudo-matrices, outputs the ideal
! 4639: product, again as a relative ideal.
! 4640:
! 4641: \syn{rnfidealmul}{\var{rnf},x,y}.
! 4642:
! 4643: \subsecidx{rnfidealnormabs}$(\var{rnf},x)$: $\var{rnf}$ being a relative
! 4644: number field extension $L/K$ as output by \kbd{rnfinit} and $x$ being a
! 4645: relative ideal (which can be, as in the absolute case, of many different
! 4646: types, including of course elements), computes the norm of the ideal $x$
! 4647: considered as an ideal of the absolute extension $L/\Q$. This is identical to
! 4648: \kbd{idealnorm(rnfidealnormrel(\var{rnf},x))}, only faster.
! 4649:
! 4650: \syn{rnfidealnormabs}{\var{rnf},x}.
! 4651:
! 4652: \subsecidx{rnfidealnormrel}$(\var{rnf},x)$: $\var{rnf}$ being a relative
! 4653: number field
! 4654: extension $L/K$ as output by \kbd{rnfinit} and $x$ being a relative ideal
! 4655: (which can be, as in the absolute case, of many different types, including
! 4656: of course elements), computes the relative norm of $x$ as a ideal of $K$
! 4657: in HNF.
! 4658:
! 4659: \syn{rnfidealnormrel}{\var{rnf},x}.
! 4660:
! 4661: \subsecidx{rnfidealreltoabs}$(\var{rnf},x)$: $\var{rnf}$ being a relative
! 4662: number field
! 4663: extension $L/K$ as output by \kbd{rnfinit} and $x$ being a relative ideal
! 4664: (which can be, as in the absolute case, of many different types, including
! 4665: of course elements), computes the HNF matrix of the ideal $x$ considered
! 4666: as an ideal of the absolute extension $L/\Q$.
! 4667:
! 4668: \syn{rnfidealreltoabs}{\var{rnf},x}.
! 4669:
! 4670: \subsecidx{rnfidealtwoelt}$(\var{rnf},x)$: $\var{rnf}$ being a relative
! 4671: number field
! 4672: extension $L/K$ as output by \kbd{rnfinit} and $x$ being an ideal of the
! 4673: relative extension $L/K$ given by a pseudo-matrix, gives a vector of
! 4674: two generators of $x$ over $\Z_L$ expressed as polmods with polmod
! 4675: coefficients.
! 4676:
! 4677: \syn{rnfidealtwoelement}{\var{rnf},x}.
! 4678:
! 4679: \subsecidx{rnfidealup}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
! 4680: field
! 4681: extension $L/K$ as output by \kbd{rnfinit} and $x$ being an ideal of
! 4682: $K$, gives the ideal $x\Z_L$ as an absolute ideal of $L/\Q$ (the relative
! 4683: ideal representation is trivial: the matrix is the identity matrix, and
! 4684: the ideal list starts with $x$, all the other ideals being $\Z_K$).
! 4685:
! 4686: \syn{rnfidealup}{\var{rnf},x}.
! 4687:
! 4688: \subsecidx{rnfinit}$(\var{nf},\var{pol})$: $\var{nf}$ being a number field in
! 4689: \kbd{nfinit}
! 4690: format considered as base field, and \var{pol} a polynomial defining a relative
! 4691: extension over $\var{nf}$, this computes all the necessary data to work in the
! 4692: relative extension. The main variable of \var{pol} must be of higher priority
! 4693: (i.e.~lower number) than that of $\var{nf}$, and the coefficients of \var{pol}
! 4694: must be in $\var{nf}$.
! 4695:
! 4696: The result is an 11-component row vector as follows (most of the components
! 4697: are technical), the numbering being very close to that of \kbd{nfinit}. In
! 4698: the following description, we let $K$ be the base field defined by
! 4699: $\var{nf}$, $m$ the degree of the base field, $n$ the relative degree, $L$
! 4700: the large field (of relative degree $n$ or absolute degree $nm$), $r_1$ and
! 4701: $r_2$ the number of real and complex places of $K$.
! 4702:
! 4703: $\var{rnf}[1]$ contains the relative polynomial \var{pol}.
! 4704:
! 4705: $\var{rnf}[2]$ is a row vector with $r_1+r_2$ entries, entry $j$ being
! 4706: a 2-component row vector $[r_{j,1},r_{j,2}]$ where $r_{j,1}$ and $r_{j,2}$
! 4707: are the number of real and complex places of $L$ above the $j$-th place of
! 4708: $K$ so that $r_{j,1}=0$ and $r_{j,2}=n$ if $j$ is a complex place, while if
! 4709: $j$ is a real place we have $r_{j,1}+2r_{j,2}=n$.
! 4710:
! 4711: $\var{rnf}[3]$ is a two-component row vector $[\d(L/K),s]$ where $\d(L/K)$
! 4712: is the relative ideal discriminant of $L/K$ and $s$ is the discriminant of
! 4713: $L/K$ viewed as an element of $K^*/(K^*)^2$, in other words it is the output
! 4714: of \kbd{rnfdisc}.
! 4715:
! 4716: $\var{rnf}[4]$ is the ideal index $\f$, i.e.~such that
! 4717: $d(pol)\Z_K=\f^2\d(L/K)$.
! 4718:
! 4719: $\var{rnf}[5]$ is a vector \var{vm} with 7 entries useful for certain
! 4720: computations in the relative extension $L/K$. $\var{vm}[1]$ is a vector of
! 4721: $r_1+r_2$ matrices, the $j$-th matrix being an $(r_{1,j}+r_{2,j})\times n$
! 4722: matrix $M_j$ representing the numerical values of the conjugates of the
! 4723: $j$-th embedding of the elements of the integral basis, where $r_{i,j}$ is as
! 4724: in $\var{rnf}[2]$. $\var{vm}[2]$ is a vector of $r_1+r_2$ matrices, the
! 4725: $j$-th matrix $MC_j$ being essentially the conjugate of the matrix $M_j$
! 4726: except that the last $r_{2,j}$ columns are also multiplied by 2.
! 4727: $\var{vm}[3]$ is a vector of $r_1+r_2$ matrices $T2_j$, where $T2_j$ is
! 4728: an $n\times n$ matrix equal to the real part of the product $MC_j\cdot M_j$
! 4729: (which is a real positive definite matrix). $\var{vm}[4]$ is the $n\times n$
! 4730: matrix $T$ whose entries are the relative traces of $\omega_i\omega_j$
! 4731: expressed as polmods in $\var{nf}$, where the $\omega_i$ are the elements
! 4732: of the relative integral basis. Note that the $j$-th embedding of $T$ is
! 4733: equal to $\overline{MC_j}\cdot M_j$, and in particular will be equal to
! 4734: $T2_j$ if $r_{2,j}=0$. Note also that the relative ideal discriminant of
! 4735: $L/K$ is equal to $\det(T)$ times the square of the product of the ideals
! 4736: in the relative pseudo-basis (in $\var{rnf}[7][2]$). The last 3 entries
! 4737: $\var{vm}[5]$, $\var{vm}[6]$ and $\var{vm}[7]$ are linked to the different
! 4738: as in \kbd{nfinit}, but have not yet been implemented.
! 4739:
! 4740: $\var{rnf}[6]$ is a row vector with $r_1+r_2$ entries, the $j$-th entry
! 4741: being the
! 4742: row vector with $r_{1,j}+r_{2,j}$ entries of the roots of the $j$-th embedding
! 4743: of the relative polynomial \var{pol}.
! 4744:
! 4745: $\var{rnf}[7]$ is a two-component row vector, where the first component is
! 4746: the relative integral pseudo basis expressed as polynomials (in the variable of
! 4747: $pol$) with polmod coefficients in $\var{nf}$, and the second component is the
! 4748: ideal list of the pseudobasis in HNF.
! 4749:
! 4750: $\var{rnf}[8]$ is the inverse matrix of the integral basis matrix, with
! 4751: coefficients polmods in $\var{nf}$.
! 4752:
! 4753: $\var{rnf}[9]$ may be the multiplication table of the integral basis, but
! 4754: is not implemented at present.
! 4755:
! 4756: $\var{rnf}[10]$ is $\var{nf}$.
! 4757:
! 4758: $\var{rnf}[11]$ is a vector \var{vabs} with 5 entries describing the
! 4759: \var{absolute} extension $L/\Q$. $\var{vabs}[1]$ is an absolute equation.
! 4760: $\var{vabs}[2]$ expresses the generator $\alpha$ of the number field
! 4761: $\var{nf}$ as a polynomial modulo the absolute equation $\var{vabs}[1]$.
! 4762: $\var{vabs}[3]$ is a small integer $k$ such that, if $\beta$ is an abstract
! 4763: root of \var{pol} and $\alpha$ the generator of $\var{nf}$, the generator
! 4764: whose root is \var{vabs} will be $\beta + k \alpha$. Note that one must
! 4765: be very careful if $k\neq0$ when dealing simultaneously with absolute and
! 4766: relative quantities since the generator chosen for the absolute extension
! 4767: is not the same as for the relative one. If this happens, one can of course
! 4768: go on working, but we strongly advise to change the relative polynomial so
! 4769: that its root will be $\beta + k \alpha$. Typically, the GP instruction would
! 4770: be
! 4771:
! 4772: \kbd{pol = subst(pol, x, x - k*Mod(y,\var{nf}.pol))}
! 4773:
! 4774: Finally, $\var{vabs}[4]$ is the absolute integral basis of $L$ expressed in HNF
! 4775: (hence as would be output by \kbd{nfinit(vabs[1])}), and $\var{vabs}[5]$ the
! 4776: inverse matrix of the integral basis, allowing to go from polmod to integral
! 4777: basis representation.
! 4778:
! 4779: \syn{rnfinitalg}{\var{nf},\var{pol},\var{prec}}.
! 4780:
! 4781: \subsecidx{rnfisfree}$(\var{bnf},x)$: given a big number field $\var{bnf}$ as
! 4782: output by \kbd{bnfinit}, and either a polynomial $x$ with coefficients in
! 4783: $\var{bnf}$ defining a relative extension $L$ of $\var{bnf}$, or a
! 4784: pseudo-basis $x$ of such an extension, returns true (1) if $L/\var{bnf}$ is
! 4785: free, false (0) if not.
! 4786:
! 4787: \syn{rnfisfree}{\var{bnf},x}, and the result is a \kbd{long}.
! 4788:
! 4789: \subsecidx{rnfisnorm}$(\var{bnf},\var{ext},\var{el},\{\fl=1\})$: similar to
! 4790: \kbd{bnfisnorm} but in the relative case. This tries to decide whether the
! 4791: element \var{el} in \var{bnf} is the norm of some $y$ in \var{ext}.
! 4792: $\var{bnf}$ is as output by \kbd{bnfinit}.
! 4793:
! 4794: $\var{ext}$ is a relative extension which has to be a row vector whose
! 4795: components are:
! 4796:
! 4797: $\var{ext}[1]$: a relative equation of the number field \var{ext} over
! 4798: \var{bnf}. As usual, the priority of the variable of the polynomial
! 4799: defining the ground field \var{bnf} (say $y$) must be lower than the
! 4800: main variable of $\var{ext}[1]$, say $x$.
! 4801:
! 4802: $\var{ext}[2]$: the generator $y$ of the base field as a polynomial in $x$ (as
! 4803: given by \kbd{rnfequation} with $\fl = 1$).
! 4804:
! 4805: $\var{ext}[3]$: is the \kbd{bnfinit} of the absolute extension $\var{ext}/\Q$.
! 4806:
! 4807: This returns a vector $[a,b]$, where $\var{el}=\var{Norm}(a)*b$. It looks for a
! 4808: solution which is an $S$-integer, with $S$ a list of places (of \var{bnf})
! 4809: containing the ramified primes, the generators of the class group of
! 4810: \var{ext}, as well as those primes dividing \var{el}. If $\var{ext}/\var{bnf}$
! 4811: is known to be \idx{Galois}, set $\fl=0$ (here \var{el} is a norm iff $b=1$).
! 4812: If $\fl$ is non zero add to $S$ all the places above the primes which: divide
! 4813: $\fl$ if $\fl<0$, or are less than $\fl$ if $\fl>0$. The answer is guaranteed
! 4814: (i.e.~\var{el} is a norm iff $b=1$) under \idx{GRH}, if $S$ contains all
! 4815: primes less than $12\log^2\left|\text{disc}(\var{Ext})\right|$, where
! 4816: \var{Ext} is the normal closure of $\var{ext} / \var{bnf}$. Example:
! 4817:
! 4818: \bprog
! 4819: bnf = bnfinit(y^3 + y^2 - 2*y - 1);
! 4820: p = x^2 + Mod(y^2 + 2*y + 1, bnf.pol);
! 4821: rnf = rnfequation(bnf,p,1);
! 4822: ext = [p, rnf[2], bnfinit(rnf[1])];
! 4823: rnfisnorm(bnf,ext,17, 1)
! 4824: @eprog
! 4825: \noindent checks whether $17$ is a norm in the Galois extension $\Q(\beta) /
! 4826: \Q(\alpha)$, where $\alpha^3 + \alpha^2 - 2\alpha - 1 = 0$ and $\beta^2 +
! 4827: \alpha^2 + 2*\alpha + 1 = 0$ (it is).
! 4828:
! 4829: \syn{rnfisnorm}{\var{bnf},ext,x,\fl,\var{prec}}.
! 4830:
! 4831: \subsecidx{rnfkummer}$(\var{bnr},\var{subgroup},\{deg=0\})$: \var{bnr}
! 4832: being as output by \kbd{bnrinit}, finds a relative equation for the
! 4833: class field corresponding to the module in \var{bnr} and the given
! 4834: congruence subgroup. If \var{deg} is positive, outputs the list of all
! 4835: relative equations of degree \var{deg} contained in the ray class field
! 4836: defined by \var{bnr}.
! 4837:
! 4838: (THIS PROGRAM IS STILL IN DEVELOPMENT STAGE)
! 4839:
! 4840: \syn{rnfkummer}{\var{bnr},\var{subgroup},\var{deg},\var{prec}},
! 4841: where \var{deg} is a \kbd{long}.
! 4842:
! 4843: \subsecidx{rnflllgram}$(\var{nf},\var{pol},\var{order})$: given a polynomial
! 4844: \var{pol} with coefficients in \var{nf} defining a relative extension $L$ and
! 4845: a suborder \var{order} of $L$ (of maximal rank), as output by
! 4846: \kbd{rnfpseudobasis}$(\var{nf},\var{pol})$ or similar, gives
! 4847: $[[\var{neworder}],U]$, where \var{neworder} is a reduced order and $U$ is
! 4848: the unimodular transformation matrix.
! 4849:
! 4850: \syn{rnflllgram}{\var{nf},\var{pol},\var{order},\var{prec}}.
! 4851:
! 4852: \subsecidx{rnfnormgroup}$(\var{bnr},\var{pol})$: \var{bnr} being a big ray
! 4853: class field as output by \kbd{bnrinit} and \var{pol} a relative polynomial
! 4854: defining an \idx{Abelian extension}, computes the norm group (alias Artin
! 4855: or Takagi group) corresponding to the Abelian extension of $\var{bnf}=bnr[1]$
! 4856: defined by \var{pol}, where the module corresponding to \var{bnr} is assumed
! 4857: to be a multiple of the conductor (i.e.~polrel defines a subextension of
! 4858: bnr). The result is the HNF defining the norm group on the given generators
! 4859: of $\var{bnr}[5][3]$. Note that neither the fact that \var{pol} defines an
! 4860: Abelian extension nor the fact that the module is a multiple of the conductor
! 4861: is checked. The result is undefined if the assumption is not correct.
! 4862:
! 4863: \syn{rnfnormgroup}{\var{bnr},\var{pol}}.
! 4864:
! 4865: \subsecidx{rnfpolred}$(\var{nf},\var{pol})$: relative version of \kbd{polred}.
! 4866: Given a monic polynomial \var{pol} with coefficients in $\var{nf}$, finds a
! 4867: list of relative polynomials defining some subfields, hopefully simpler and
! 4868: containing the original field. In the present version \vers, this is slower
! 4869: than \kbd{rnfpolredabs}.
! 4870:
! 4871: \syn{rnfpolred}{\var{nf},\var{pol},\var{prec}}.
! 4872:
! 4873: \subsecidx{rnfpolredabs}$(\var{nf},\var{pol},\{\fl=0\})$: relative version of
! 4874: \kbd{polredabs}. Given a monic polynomial \var{pol} with coefficients in
! 4875: $\var{nf}$, finds a simpler relative polynomial defining the same field. If
! 4876: $\fl=1$, returns $[P,a]$ where $P$ is the default output and $a$ is an
! 4877: element expressed on a root of $P$ whose characteristic polynomial is
! 4878: \var{pol}, if $\fl=2$, returns an absolute polynomial (same as
! 4879:
! 4880: {\tt rnfequation(\var{nf},rnfpolredabs(\var{nf},\var{pol}))}
! 4881:
! 4882: \noindent but faster).
! 4883:
! 4884: \misctitle{Remark.} In the present implementation, this is both faster and
! 4885: much more efficient than \kbd{rnfpolred}, the difference being more
! 4886: dramatic than in the absolute case. This is because the implementation of
! 4887: \kbd{rnfpolred} is based on (a partial implementation of) an incomplete
! 4888: reduction theory of lattices over number fields (i.e.~the function
! 4889: \kbd{rnflllgram}) which deserves to be improved.
! 4890:
! 4891: \syn{rnfpolredabs}{\var{nf},\var{pol},\fl,\var{prec}}.
! 4892:
! 4893: \subsecidx{rnfpseudobasis}$(\var{nf},\var{pol})$: given a number field
! 4894: $\var{nf}$ as output by \kbd{nfinit} and a polynomial \var{pol} with
! 4895: coefficients in $\var{nf}$ defining a relative extension $L$ of $\var{nf}$,
! 4896: computes a pseudo-basis $(A,I)$ and the relative discriminant of $L$.
! 4897: This is output as
! 4898: a four-element row vector $[A,I,D,d]$, where $D$ is the relative ideal
! 4899: discriminant and $d$ is the relative discriminant considered as an element of
! 4900: $\var{nf}^*/{\var{nf}^*}^2$.
! 4901:
! 4902: Note: As usual, $\var{nf}$ can be a $\var{bnf}$ as output by \kbd{bnfinit}.
! 4903:
! 4904: \syn{rnfpseudobasis}{\var{nf},\var{pol}}.
! 4905:
! 4906: \subsecidx{rnfsteinitz}$(\var{nf},x)$: given a number field $\var{nf}$ as
! 4907: output by \kbd{nfinit} and either a polynomial $x$ with coefficients in
! 4908: $\var{nf}$ defining a relative extension $L$ of $\var{nf}$, or a pseudo-basis
! 4909: $x$ of such an extension as output for example by \kbd{rnfpseudobasis},
! 4910: computes another pseudo-basis $(A,I)$ (not in HNF in general) such that all
! 4911: the ideals of $I$ except perhaps the last one are equal to the ring of
! 4912: integers of $\var{nf}$, and outputs the four-component row vector $[A,I,D,d]$
! 4913: as in \kbd{rnfpseudobasis}. The name of this function comes from the fact
! 4914: that the ideal class of the last ideal of $I$ (which is well defined) is
! 4915: called the \idx{Steinitz class} of the module $\Z_L$.
! 4916:
! 4917: Note: $\var{nf}$ can be a $\var{bnf}$ as output by \kbd{bnfinit}.
! 4918:
! 4919: \syn{rnfsteinitz}{\var{nf},x}.
! 4920:
! 4921: \subsecidx{subgrouplist}$(\var{bnr},\{\var{bound}\},\{\fl=0\})$:
! 4922: \var{bnr} being as output by \kbd{bnrinit} or a list of cyclic components
! 4923: of a finite Abelian group $G$, outputs the list of subgroups of $G$
! 4924: (of index bounded by \var{bound}, if not omitted). Subgroups are given
! 4925: as HNF\sidx{Hermite normal form} left divisors of the
! 4926: SNF\sidx{Smith normal form} matrix corresponding to $G$. If $\fl=0$
! 4927: (default) and \var{bnr} is as output by
! 4928: \kbd{bnrinit}, gives only the subgroups whose modulus is the conductor.
! 4929:
! 4930: \syn{subgrouplist0}{\var{bnr},\var{bound},\fl}, where \var{bound} and $\fl$
! 4931: are long integers.
! 4932:
! 4933: \subsecidx{zetak}$(\var{znf},x,\{\fl=0\})$: \var{znf} being a number
! 4934: field initialized by \kbd{zetakinit} (\var{not} by \kbd{nfinit}),
! 4935: computes the value of the \idx{Dedekind} zeta function of the number
! 4936: field at the complex number $x$. If $\fl=1$ computes Dedekind $\Lambda$
! 4937: function instead (i.e.~the product of the
! 4938: Dedekind zeta function by its gamma and exponential factors).
! 4939:
! 4940: The accuracy of the result depends in an essential way on the accuracy of
! 4941: both the \kbd{zetakinit} program and the current accuracy, but even so the
! 4942: result may be off by up to 5 or 10 decimal digits.
! 4943:
! 4944: \syn{glambdak}{\var{znf},x,\var{prec}} or
! 4945: $\teb{gzetak}(\var{znf},x,\var{prec})$.
! 4946:
! 4947: \subsecidx{zetakinit}$(x)$: computes a number of initialization data
! 4948: concerning the number field defined by the polynomial $x$ so as to be able
! 4949: to compute the \idx{Dedekind} zeta and lambda functions (respectively
! 4950: $\kbd{zetak}(x)$ and $\kbd{zetak}(x,1)$). This function calls in particular
! 4951: the \kbd{bnfinit} program. The result is a 9-component vector $v$ whose
! 4952: components are very technical and cannot really be used by the user except
! 4953: through the \kbd{zetak} function. The only component which can be used if
! 4954: it has not been computed already is $v[1][4]$ which is the result of the
! 4955: \kbd{bnfinit} call.
! 4956:
! 4957: This function is very inefficient and should be rewritten. It needs to
! 4958: computes millions of coefficients of the corresponding Dirichlet series if
! 4959: the precision is big. Unless the discriminant is small it will not be able
! 4960: to handle more than 9 digits of relative precision
! 4961: (e.g~\kbd{zetakinit(x\pow 8 - 2)} needs 440MB of memory at default
! 4962: precision).
! 4963:
! 4964: \syn{initzeta}{x}.
! 4965:
! 4966: \section{Polynomials and power series}
! 4967:
! 4968: We group here all functions which are specific to polynomials or power
! 4969: series. Many other functions which can be applied on these objects are
! 4970: described in the other sections. Also, some of the functions described here
! 4971: can be applied to other types.
! 4972:
! 4973: \subsecidx{O}$(a$\kbd{\pow}$b)$: $p$-adic (if $a$ is an integer greater or
! 4974: equal to 2) or power series zero (in all other cases), with precision given
! 4975: by $b$.
! 4976:
! 4977: \syn{ggrandocp}{a,b}, where $b$ is a \kbd{long}.
! 4978:
! 4979: \subsecidx{deriv}$(x,\{v\})$: derivative of $x$ with respect to the main
! 4980: variable if $v$ is omitted, and with respect to $v$ otherwise. $x$ can be any
! 4981: type except polmod. The derivative of a scalar type is zero, and the
! 4982: derivative of a vector or matrix is done componentwise. One can use $x'$ as a
! 4983: shortcut if the derivative is with respect to the main variable of $x$.
! 4984:
! 4985: \syn{deriv}{x,v}, where $v$ is a \kbd{long}, and an omitted $v$ is coded as
! 4986: $-1$. When $x$ is a \typ{POL}, $\tet{derivpol}(x)$ is a shortcut for
! 4987: $\kbd{deriv}(x, -1)$.
! 4988:
! 4989: \subsecidx{eval}$(x)$: replaces in $x$ the formal variables by the values that
! 4990: have been assigned to them after the creation of $x$. This is mainly useful
! 4991: in GP, and not in library mode. Do not confuse this with substitution (see
! 4992: \kbd{subst}). Applying this function to a character string yields the
! 4993: output from the corresponding GP command, as if directly input from the
! 4994: keyboard (see \secref{se:strings}).\label{se:eval}
! 4995:
! 4996: \syn{geval}{x}. The more basic functions $\teb{poleval}(q,x)$,
! 4997: $\teb{qfeval}(q,x)$, and $\teb{hqfeval}(q,x)$ evaluate $q$ at $x$, where $q$
! 4998: is respectively assumed to be a polynomial, a quadratic form (a symmetric
! 4999: matrix), or an Hermitian form (an Hermitian complex matrix).
! 5000:
! 5001: \subsecidx{factorpadic}$(\var{pol},p,r,\{\fl=0\})$: $p$-adic factorization
! 5002: of the polynomial \var{pol} to precision $r$, the result being a
! 5003: two-column matrix as in \kbd{factor}. The factors are normalized so that
! 5004: their leading coefficient is a power of $p$. $r$ must be strictly larger than
! 5005: the $p$-adic valuation of the discriminant of \var{pol} for the result to
! 5006: make any sense. The method used is a modified version of the \idx{round 4}
! 5007: algorithm of \idx{Zassenhaus}.
! 5008:
! 5009: If $\fl=1$, use an algorithm due to \idx{Buchmann} and \idx{Lenstra}, which is
! 5010: usually less efficient.
! 5011:
! 5012: \syn{factorpadic4}{\var{pol},p,r}, where $r$ is a \kbd{long} integer.
! 5013:
! 5014: \subsecidx{intformal}$(x,\{v\})$: \idx{formal integration} of $x$ with
! 5015: respect to the main variable if $v$ is omitted, with respect to the variable
! 5016: $v$ otherwise. Since PARI does not know about ``abstract'' logarithms (they
! 5017: are immediately evaluated, if only to a power series), logarithmic terms in
! 5018: the result will yield an error. $x$ can be of any type. When $x$ is a
! 5019: rational function, it is assumed that the base ring is an integral domain of
! 5020: characteristic zero.
! 5021:
! 5022: \syn{integ}{x,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded
! 5023: as $-1$.
! 5024:
! 5025: \subsecidx{padicappr}$(\var{pol},a)$: vector of $p$-adic roots of the
! 5026: polynomial
! 5027: $pol$ congruent to the $p$-adic number $a$ modulo $p$ (or modulo 4 if $p=2$),
! 5028: and with the same $p$-adic precision as $a$. The number $a$ can be an
! 5029: ordinary $p$-adic number (type \typ{PADIC}, i.e.~an element of $\Q_p$) or
! 5030: can be an element of a finite extension of $\Q_p$, in which case it is of
! 5031: type \typ{POLMOD}, where at least one of the coefficients of the polmod is a
! 5032: $p$-adic number. In this case, the result is the vector of roots belonging to
! 5033: the same extension of $\Q_p$ as $a$.
! 5034:
! 5035: \syn{apprgen9}{\var{pol},a}, but if $a$ is known to be simply a $p$-adic number
! 5036: (type \typ{PADIC}), the syntax $\teb{apprgen}(\var{pol},a)$ can be used.
! 5037:
! 5038: \subsecidx{polcoeff}$(x,s,\{v\})$: coefficient of degree $s$ of the
! 5039: polynomial $x$, with respect to the main variable if $v$ is omitted, with
! 5040: respect to $v$ otherwise.
! 5041:
! 5042: \syn{polcoeff0}{x,s,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded
! 5043: as $-1$. Also available is \teb{truecoeff}$(x,v)$.
! 5044:
! 5045: \subsecidx{poldegree}$(x,\{v\})$: degree of the polynomial $x$ in the main
! 5046: variable if $v$ is omitted, in the variable $v$ otherwise. This is to be
! 5047: understood as follows. When $x$ is a polynomial or a rational function, it
! 5048: gives the degree of $x$, the degree of $0$ being $-1$ by convention. When $x$
! 5049: is a non-zero scalar, it gives 0, and when $x$ is a zero scalar, it gives
! 5050: $-1$. Return an error otherwise.
! 5051:
! 5052: \syn{poldegree}{x,v}, where $v$ and the result are \kbd{long}s (and an
! 5053: omitted $v$ is coded as $-1$). Also available is \teb{degree}$(x)$, which is
! 5054: equivalent to \kbd{poldegree($x$,-1)}.
! 5055:
! 5056: \subsecidx{polcyclo}$(n,\{v=x\})$: $n$-th cyclotomic polynomial, in variable
! 5057: $v$ ($x$ by default). The integer $n$ must be positive.
! 5058:
! 5059: \syn{cyclo}{n,v}, where $n$ and $v$ are \kbd{long}
! 5060: integers ($v$ is a variable number, usually obtained through \kbd{varn}).
! 5061:
! 5062: \subsecidx{poldisc}$(\var{pol},\{v\})$: discriminant of the polynomial
! 5063: \var{pol} in the main variable is $v$ is omitted, in $v$ otherwise. The
! 5064: algorithm used is the \idx{subresultant algorithm}.
! 5065:
! 5066: \syn{poldisc0}{x,v}. Also available is \teb{discsr}$(x)$, equivalent
! 5067: to \kbd{poldisc0(x,-1)}.
! 5068:
! 5069: \subsecidx{poldiscreduced}$(f)$: reduced discriminant vector of the
! 5070: (integral, monic) polynomial $f$. This is the vector of elementary divisors
! 5071: of $\Z[\alpha]/f'(\alpha)\Z[\alpha]$, where $\alpha$ is a root of the
! 5072: polynomial $f$. The components of the result are all positive, and their
! 5073: product is equal to the absolute value of the discriminant of~$f$.
! 5074:
! 5075: \syn{reduceddiscsmith}{x}.
! 5076:
! 5077: \subsecidx{polhensellift}$(x, y, p, e)$: given a prime $p$, an integral
! 5078: polynomial $x$ whose leading coefficient is a $p$-unit, a vector $y$ of
! 5079: integral polynomials that are pairwise relatively prime modulo $p$, and whose
! 5080: product is congruent to $x$ modulo $p$, lift the elements of $y$ to
! 5081: polynomials whose product is congruent to $x$ modulo $p^e$.
! 5082:
! 5083: \syn{polhensellift}{x,y,p,e} where $e$ must be a \kbd{long}.
! 5084:
! 5085: \subsecidx{polinterpolate}$(xa,\{ya\},\{v=x\},\{\&e\})$: given the data vectors
! 5086: $xa$ and $ya$ of the same length $n$ ($xa$ containing the $x$-coordinates,
! 5087: and $ya$ the corresponding $y$-coordinates), this function finds the
! 5088: \idx{interpolating polynomial} passing through these points and evaluates it
! 5089: at~$v$. If $ya$ is omitted, return the polynomial interpolating the
! 5090: $(i,xa[i])$. If present, $e$ will contain an error estimate on the returned
! 5091: value.
! 5092:
! 5093: \syn{polint}{xa,ya,v,\&e}, where $e$ will contain an error estimate on the
! 5094: returned value.
! 5095:
! 5096: \subsecidx{polisirreducible}$(\var{pol})$: \var{pol} being a polynomial
! 5097: (univariate in the present version \vers), returns 1 if \var{pol} is
! 5098: non-constant and irreducible, 0 otherwise. Irreducibility is checked over
! 5099: the smallest base field over which \var{pol} seems to be defined.
! 5100:
! 5101: \syn{gisirreducible}{\var{pol}}.
! 5102:
! 5103: \subsecidx{pollead}$(x,\{v\})$: leading coefficient of the polynomial or
! 5104: power series $x$. This is computed with respect to the main variable of $x$
! 5105: if $v$ is omitted, with respect to the variable $v$ otherwise.
! 5106:
! 5107: \syn{pollead}{x,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded as
! 5108: $-1$. Also available is \teb{leadingcoeff}$(x)$.
! 5109:
! 5110: \subsecidx{pollegendre}$(n,\{v=x\})$: creates the $n^{\text{th}}$
! 5111: \idx{Legendre polynomial}, in variable $v$.
! 5112:
! 5113: \syn{legendre}{n}, where $x$ is a \kbd{long}.
! 5114:
! 5115: \subsecidx{polrecip}$(\var{pol})$: reciprocal polynomial of \var{pol},
! 5116: i.e.~the coefficients are in reverse order. \var{pol} must be a polynomial.
! 5117:
! 5118: \syn{polrecip}{x}.
! 5119:
! 5120: \subsecidx{polresultant}$(x,y,\{v\},\{\fl=0\})$: resultant of the two
! 5121: polynomials $x$ and $y$ with exact entries, with respect to the main
! 5122: variables of $x$ and $y$ if $v$ is omitted, with respect to the variable $v$
! 5123: otherwise. The algorithm used is the \idx{subresultant algorithm} by default.
! 5124:
! 5125: If $\fl=1$, uses the determinant of Sylvester's matrix instead (here $x$ and
! 5126: $y$ may have non-exact coefficients).
! 5127:
! 5128: If $\fl=2$, uses Ducos's modified subresultant algorithm. It should be much
! 5129: faster than the default if the coefficient ring is complicated (e.g
! 5130: multivariate polynomials or huge coefficients), and slightly slower
! 5131: otherwise.
! 5132:
! 5133: \syn{polresultant0}{x,y,v,\fl}, where $v$ is a \kbd{long} and an omitted $v$
! 5134: is coded as $-1$. Also available are $\teb{subres}(x,y)$ ($\fl=0$) and
! 5135: $\teb{resultant2}(x,y)$ ($\fl=1$).
! 5136:
! 5137: \subsecidx{polroots}$(\var{pol},\{\fl=0\})$: complex roots of the polynomial
! 5138: \var{pol}, given as a column vector where each root is repeated according to
! 5139: its multiplicity. The precision is given as for transcendental functions: under
! 5140: GP it is kept in the variable \kbd{realprecision} and is transparent to the
! 5141: user, but it must be explicitly given as a second argument in library mode.
! 5142:
! 5143: The algorithm used is a modification of A.~Sch\"onhage\sidx{Sch\"onage}'s
! 5144: remarkable root-finding algorithm, due to and implemented by X.~Gourdon.
! 5145: Barring bugs, it is guaranteed to converge and to give the roots to the
! 5146: required accuracy.
! 5147:
! 5148: If $\fl=1$, use a variant of the Newton-Raphson method, which is \var{not}
! 5149: guaranteed to converge, but is rather fast. If you get the messages ``too
! 5150: many iterations in roots'' or ``INTERNAL ERROR: incorrect result in roots'',
! 5151: use the default function (i.e.~no flag or $\fl=0$). This used to be the
! 5152: default root-finding function in PARI until version 1.39.06.
! 5153:
! 5154: \syn{roots}{\var{pol},\var{prec}} or $\teb{rootsold}(\var{pol},\var{prec})$.
! 5155:
! 5156: \subsecidx{polrootsmod}$(\var{pol},p,\{\fl=0\})$: row vector of roots modulo
! 5157: $p$ of the polynomial \var{pol}. The particular non-prime value $p=4$ is
! 5158: accepted, mainly for $2$-adic computations. Multiple roots are \var{not}
! 5159: repeated.
! 5160:
! 5161: If $p<100$, you may try setting $\fl=1$, which uses a naive search. In this
! 5162: case, multiple roots \var{are} repeated with their order of multiplicity.
! 5163:
! 5164: \syn{rootmod}{\var{pol},p} ($\fl=0$) or
! 5165: $\teb{rootmod2}(\var{pol},p)$ ($\fl=1$).
! 5166:
! 5167: \subsecidx{polrootspadic}$(\var{pol},p,r)$: row vector of $p$-adic roots of the
! 5168: polynomial \var{pol} with $p$-adic precision equal to $r$. Multiple roots are
! 5169: \var{not} repeated. $p$ is assumed to be a prime.
! 5170:
! 5171: \syn{rootpadic}{\var{pol},p,r}, where $r$ is a \kbd{long}.
! 5172:
! 5173: \subsecidx{polsturm}$(\var{pol},\{a\},\{b\})$: number of real roots of the real
! 5174: polynomial \var{pol} in the interval $]a,b]$, using Sturm's algorithm. $a$
! 5175: (resp.~$b$) is taken to be $-\infty$ (resp.~$+\infty$) if omitted.
! 5176:
! 5177: \syn{sturmpart}{\var{pol},a,b}. Use \kbd{NULL} to omit an argument.
! 5178: \teb{sturm}\kbd{(\var{pol})} is equivalent to
! 5179: \key{sturmpart}\kbd{(\var{pol},NULL,NULL)}. The result is a \kbd{long}.
! 5180:
! 5181: \subsecidx{polsubcyclo}$(n,d,\{v=x\})$: gives a polynomial (in variable
! 5182: $v$) defining the sub-Abelian extension of degree $d$ of the cyclotomic
! 5183: field $\Q(\zeta_n)$, where $d\mid \phi(n)$. $(\Z/n\Z)^*$ has to be cyclic
! 5184: (i.e.~$n=2$, $4$, $p^k$ or $2p^k$ for an odd prime $p$). The function
! 5185: \tet{galoissubcyclo} covers the general case.
! 5186:
! 5187: \syn{subcyclo}{n,d,v}, where $v$ is a variable number.
! 5188:
! 5189: \subsecidx{polsylvestermatrix}$(x,y)$: forms the Sylvester matrix
! 5190: corresponding to the two polynomials $x$ and $y$, where the coefficients of
! 5191: the polynomials are put in the columns of the matrix (which is the natural
! 5192: direction for solving equations afterwards). The use of this matrix can be
! 5193: essential when dealing with polynomials with inexact entries, since
! 5194: polynomial Euclidean division doesn't make much sense in this case.
! 5195:
! 5196: \syn{sylvestermatrix}{x,y}.
! 5197:
! 5198: \subsecidx{polsym}$(x,n)$: creates the vector of the \idx{symmetric powers}
! 5199: of the roots of the polynomial $x$ up to power $n$, using Newton's
! 5200: formula.
! 5201:
! 5202: \syn{polsym}{x}.
! 5203:
! 5204: \subsecidx{poltchebi}$(n,\{v=x\})$: creates the $n^{\text{th}}$
! 5205: \idx{Chebyshev} polynomial, in variable $v$.
! 5206:
! 5207: \syn{tchebi}{n,v}, where $n$ and $v$ are \kbd{long}
! 5208: integers ($v$ is a variable number).
! 5209:
! 5210: \subsecidx{polzagier}$(n,m)$: creates Zagier's polynomial $P_{n,m}$ used in
! 5211: the functions \kbd{sumalt} and \kbd{sumpos} (with $\fl=1$). The exact
! 5212: definition can be found in a forthcoming paper. One must have $m\le n$.
! 5213:
! 5214: \syn{polzagreel}{n,m,\var{prec}} if the result is only wanted as a polynomial
! 5215: with real coefficients to the precision $\var{prec}$, or $\teb{polzag}(n,m)$
! 5216: if the result is wanted exactly, where $n$ and $m$ are \kbd{long}s.
! 5217:
! 5218: \subsecidx{serconvol}$(x,y)$: convolution (or \idx{Hadamard product}) of the
! 5219: two power series $x$ and $y$; in other words if $x=\sum a_k*X^k$ and $y=\sum
! 5220: b_k*X^k$ then $\kbd{serconvol}(x,y)=\sum a_k*b_k*X^k$.
! 5221:
! 5222: \syn{convol}{x,y}.
! 5223:
! 5224: \subsecidx{serlaplace}$(x)$: $x$ must be a power series with only
! 5225: non-negative exponents. If $x=\sum (a_k/k!)*X^k$ then the result is $\sum
! 5226: a_k*X^k$.
! 5227:
! 5228: \syn{laplace}{x}.
! 5229:
! 5230: \subsecidx{serreverse}$(x)$: reverse power series (i.e.~$x^{-1}$, not $1/x$)
! 5231: of $x$. $x$ must be a power series whose valuation is exactly equal to one.
! 5232:
! 5233: \syn{recip}{x}.
! 5234:
! 5235: \subsecidx{subst}$(x,y,z)$:
! 5236: replace the simple variable $y$ by the argument $z$ in the ``polynomial''
! 5237: expression $x$. Every type is allowed for $x$, but if it is not a genuine
! 5238: polynomial (or power series, or rational function), the substitution will be
! 5239: done as if the scalar components were polynomials of degree one. In
! 5240: particular, beware that:
! 5241:
! 5242: \bprog
! 5243: ? subst(1, x, [1,2; 3,4])
! 5244: %1 =
! 5245: [1 0]
! 5246:
! 5247: [0 1]
! 5248:
! 5249: ? subst(1, x, Mat([0,1]))
! 5250: *** forbidden substitution by a non square matrix
! 5251: @eprog
! 5252:
! 5253: If $x$ is a power series, $z$ must be either a polynomial, a power series, or
! 5254: a rational function. $y$ must be a simple variable name, or a monome of the
! 5255: form $t^k$ for some simple variable $t$. In the latter case, substitution
! 5256: may not always be possible since PARI doesn't know about algebraic functions.
! 5257:
! 5258: \syn{gsubst}{x,v,z}, where $v$ is the number of the variable $y$ for regular
! 5259: usage. Also available is \tet{gsubst0}$(x,y,z)$ where $y$ is a \kbd{GEN}
! 5260: monomial of the form $t^k$.
! 5261:
! 5262: \subsecidx{taylor}$(x,y)$: Taylor expansion around $0$ of $x$ with respect
! 5263: to\label{se:taylor}
! 5264: the simple variable $y$. $x$ can be of any reasonable type, for example a
! 5265: rational function. The number of terms of the expansion is transparent to the
! 5266: user under GP, but must be given as a second argument in library mode.
! 5267:
! 5268: \syn{tayl}{x,y,n}, where the \kbd{long} integer $n$ is the desired number of
! 5269: terms in the expansion.
! 5270:
! 5271: \subsecidx{thue}$(\var{tnf},a,\{\var{sol}\})$: solves the equation
! 5272: $P(x,y)=a$ in integers $x$ and $y$, where \var{tnf} was created with
! 5273: $\kbd{thueinit}(P)$. \var{sol}, if present, contains the solutions of
! 5274: $\text{Norm}(x)=a$ modulo units of positive norm in the number field
! 5275: defined by $P$ (as computed by \kbd{bnfisintnorm}). If \var{tnf} was
! 5276: computed without assuming \idx{GRH} ($\fl=1$ in \kbd{thueinit}), the
! 5277: result is unconditional. For instance, here's how to solve the Thue
! 5278: equation $x^{13} - 5y^{13} = - 4$:
! 5279:
! 5280: \bprog
! 5281: ? tnf = thueinit(x^13 - 5);
! 5282: ? thue(tnf, -4)
! 5283: %1 = [[1, 1]]
! 5284: @eprog
! 5285: Hence, assuming GRH, the only solution is $x = 1$, $y = 1$.
! 5286:
! 5287: \syn{thue}{\var{tnf},a,\var{sol}}, where an omitted \var{sol} is coded
! 5288: as \kbd{NULL}.
! 5289:
! 5290: \subsecidx{thueinit}$(P,\{\fl=0\})$: initializes the \var{tnf}
! 5291: corresponding to $P$. It is meant to be used in conjunction with \tet{thue}
! 5292: to solve Thue equations $P(x,y) = a$, where $a$ is an integer. If $\fl$ is
! 5293: non-zero, certify the result unconditionnaly, Otherwise, assume \idx{GRH},
! 5294: this being much faster of course.
! 5295:
! 5296: \syn{thueinit}{P,\fl,\var{prec}}.
! 5297:
! 5298: \section{Vectors, matrices, linear algebra and sets}
! 5299: \label{se:linear_algebra}
! 5300:
! 5301: Note that most linear algebra functions operating on subspaces defined by
! 5302: generating sets (such as \tet{mathnf}, \tet{qflll}, etc.) take matrices as
! 5303: arguments. As usual, the generating vectors are taken to be the
! 5304: \var{columns} of the given matrix.
! 5305:
! 5306: \subsecidx{algdep}$(x,k,\{\fl=0\})$:\sidx{algebraic dependence} $x$ being
! 5307: real, complex, or $p$-adic, finds a polynomial of degree at most $k$ with
! 5308: integer coefficients having $x$ as approximate root. Note that the polynomial
! 5309: which is obtained is not necessarily the ``correct'' one (it's not even
! 5310: guaranteed to be irreducible!). One can check the closeness either by a
! 5311: polynomial evaluation or substitution, or by computing the roots of the
! 5312: polynomial given by algdep.
! 5313:
! 5314: If $x$ is padic, $\fl$ is meaningless and the algorithm LLL-reduces the
! 5315: ``dual lattice'' corresponding to the powers of $x$.
! 5316:
! 5317: Otherwise, if $\fl$ is zero, the algorithm used is a variant of the \idx{LLL}
! 5318: algorithm due to Hastad, Lagarias and Schnorr (STACS 1986). If the precision
! 5319: is too low, the routine may enter an infinite loop.
! 5320:
! 5321: If $\fl$ is non-zero, use a standard LLL. $\fl$ then indicates a precision,
! 5322: which should be between $0.5$ and $1.0$ times the number of decimal digits
! 5323: to which $x$ was computed.
! 5324:
! 5325: \syn{algdep0}{x,k,\fl,\var{prec}}, where $k$ and $\fl$ are \kbd{long}s.
! 5326: Also available is $\teb{algdep}(x,k,\var{prec})$ ($\fl=0$).
! 5327:
! 5328: \subsecidx{charpoly}$(A,\{v=x\},\{\fl=0\})$: \idx{characteristic polynomial}
! 5329: of $A$ with respect to the variable $v$, i.e.~determinant of $v*I-A$ if $A$
! 5330: is a square matrix, determinant of the map ``multiplication by $A$'' if $A$
! 5331: is a scalar, in particular a polmod (e.g.~\kbd{charpoly(I,x)=x\pow2+1}).
! 5332: Note that in the latter case, the \idx{minimal polynomial} can be obtained
! 5333: as
! 5334: \bprog
! 5335: minpoly(A)=
! 5336: {
! 5337: local(y);
! 5338: y = charpoly(A);
! 5339: y / gcd(y,y')
! 5340: }
! 5341: @eprog
! 5342: \noindent The value of $\fl$ is only significant for matrices.
! 5343:
! 5344: If $\fl=0$, the method used is essentially the same as for computing the
! 5345: adjoint matrix, i.e.~computing the traces of the powers of $A$.
! 5346:
! 5347: If $\fl=1$, uses Lagrange interpolation which is almost always slower.
! 5348:
! 5349: If $\fl=2$, uses the Hessenberg form. This is faster than the default when
! 5350: the coefficients are integermod a prime or real numbers, but is usually
! 5351: slower in other base rings.
! 5352:
! 5353: \syn{charpoly0}{A,v,\fl}, where $v$ is the variable number. Also available
! 5354: are the functions $\teb{caract}(A,v)$ ($\fl=1$), $\teb{carhess}(A,v)$
! 5355: ($\fl=2$), and $\teb{caradj}(A,v,\var{pt})$ where, in this last case,
! 5356: \var{pt} is a \kbd{GEN*} which, if not equal to \kbd{NULL}, will receive
! 5357: the address of the adjoint matrix of $A$ (see \kbd{matadjoint}), so both
! 5358: can be obtained at once.
! 5359:
! 5360: \subsecidx{concat}$(x,\{y\})$: concatenation of $x$ and $y$. If $x$ or $y$ is
! 5361: not a vector or matrix, it is considered as a one-dimensional vector. All
! 5362: types are allowed for $x$ and $y$, but the sizes must be compatible. Note
! 5363: that matrices are concatenated horizontally, i.e.~the number of rows stays
! 5364: the same. Using transpositions, it is easy to concatenate them vertically.
! 5365:
! 5366: To concatenate vectors sideways (i.e.~to obtain a two-row or two-column
! 5367: matrix), first transform the vector into a one-row or one-column matrix using
! 5368: the function \tet{Mat}. Concatenating a row vector to a matrix having the
! 5369: same number of columns will add the row to the matrix (top row if the vector
! 5370: is $x$, i.e.~comes first, and bottom row otherwise).
! 5371:
! 5372: The empty matrix \kbd{[;]} is considered to have a number of rows compatible
! 5373: with any operation, in particular concatenation. (Note that this is
! 5374: definitely \var{not} the case for empty vectors \kbd{[~]} or \kbd{[~]\til}.)
! 5375:
! 5376: If $y$ is omitted, $x$ has to be a row vector or a list, in which case its
! 5377: elements are concatenated, from left to right, using the above rules.
! 5378:
! 5379: \bprog
! 5380: ? concat([1,2], [3,4])
! 5381: %1 = [1, 2, 3, 4]
! 5382: ? a = [[1,2]~, [3,4]~]; concat(a)
! 5383: %2 = [1, 2, 3, 4]~
! 5384: ? a[1] = Mat(a[1]); concat(a)
! 5385: %3 =
! 5386: [1 3]
! 5387:
! 5388: [2 4]
! 5389:
! 5390: ? concat([1,2; 3,4], [5,6]~)
! 5391: %4 =
! 5392: [1 2 5]
! 5393:
! 5394: [3 4 6]
! 5395: ? concat([%, [7,8]~, [1,2,3,4]])
! 5396: %5 =
! 5397: [1 2 5 7]
! 5398:
! 5399: [3 4 6 8]
! 5400:
! 5401: [1 2 3 4]
! 5402: @eprog
! 5403:
! 5404: \syn{concat}{x,y}.
! 5405:
! 5406: \subsecidx{lindep}$(x,\{\fl=0\})$:\sidx{linear dependence}$x$ being a
! 5407: vector with real or complex coefficients, finds a small integral linear
! 5408: combination among these coefficients.
! 5409:
! 5410: If $\fl=0$, uses a variant of the \idx{LLL} algorithm due to Hastad, Lagarias
! 5411: and Schnorr (STACS 1986).
! 5412:
! 5413: If $\fl>0$, uses the LLL algorithm. $\fl$ is a parameter which should be
! 5414: between one half the number of decimal digits of precision and that number
! 5415: (see \kbd{algdep}).
! 5416:
! 5417: If $\fl<0$, returns as soon as one relation has been found.
! 5418:
! 5419: \syn{lindep0}{x,\fl,\var{prec}}. Also available is
! 5420: $\teb{lindep}(x,\var{prec})$ ($\fl=0$).
! 5421:
! 5422: \subsecidx{listcreate}$(n)$: creates an empty list of maximal length $n$.
! 5423:
! 5424: This function is useless in library mode.
! 5425:
! 5426: \subsecidx{listinsert}$(\var{list},x,n)$: inserts the object $x$ at
! 5427: position $n$ in \var{list} (which must be of type \typ{LIST}). All the
! 5428: remaining elements of \var{list} (from position $n+1$ onwards) are shifted
! 5429: to the right. This and \kbd{listput} are the only commands which enable
! 5430: you to increase a list's effective length (as long as it remains under
! 5431: the maximal length specified at the time of the \kbd{listcreate}).
! 5432:
! 5433: This function is useless in library mode.
! 5434:
! 5435: \subsecidx{listkill}$(\var{list})$: kill \var{list}. This deletes all
! 5436: elements from \var{list} and sets its effective length to $0$. The maximal
! 5437: length is not affected.
! 5438:
! 5439: This function is useless in library mode.
! 5440:
! 5441: \subsecidx{listput}$(\var{list},x,\{n\})$: sets the $n$-th element of the list
! 5442: \var{list} (which must be of type \typ{LIST}) equal to $x$. If $n$ is omitted,
! 5443: or greater than the list current effective length, just appends $x$. This and
! 5444: \kbd{listinsert} are the only commands which enable you to increase a list's
! 5445: effective length (as long as it remains under the maximal length specified at
! 5446: the time of the \kbd{listcreate}).
! 5447:
! 5448: If you want to put an element into an occupied cell, i.e.~if you don't want to
! 5449: change the effective length, you can consider the list as a vector and use
! 5450: the usual \kbd{list[n] = x} construct.
! 5451:
! 5452: This function is useless in library mode.
! 5453:
! 5454: \subsecidx{listsort}$(\var{list},\{\fl=0\})$: sorts \var{list} (which must
! 5455: be of type \typ{LIST}) in place. If $\fl$ is non-zero, suppresses all repeated
! 5456: coefficients. This is much faster than the \kbd{vecsort} command since no
! 5457: copy has to be made.
! 5458:
! 5459: This function is useless in library mode.
! 5460:
! 5461: \subsecidx{matadjoint}$(x)$: \idx{adjoint matrix} of $x$, i.e.~the matrix $y$
! 5462: of cofactors of $x$, satisfying $x*y=\det(x)*\text{Id}$. $x$ must be a
! 5463: (non-necessarily invertible) square matrix.
! 5464:
! 5465: \syn{adj}{x}.
! 5466:
! 5467: \subsecidx{matcompanion}$(x)$: the left companion matrix to the polynomial $x$.
! 5468:
! 5469: \syn{assmat}{x}.
! 5470:
! 5471: \subsecidx{matdet}$(x,\{\fl=0\})$: determinant of $x$. $x$ must be a
! 5472: square matrix.
! 5473:
! 5474: If $\fl=0$, uses Gauss-Bareiss.
! 5475:
! 5476: If $\fl=1$, uses classical Gaussian elimination, which is better when the
! 5477: entries of the matrix are reals or integers for example, but usually much
! 5478: worse for more complicated entries like multivariate polynomials.
! 5479:
! 5480: \syn{det}{x} ($\fl=0$) and $\teb{det2}(x)$
! 5481: ($\fl=1$).
! 5482:
! 5483: \subsecidx{matdetint}$(x)$: $x$ being an $m\times n$ matrix with integer
! 5484: coefficients, this function computes a \var{multiple} of the determinant of the
! 5485: lattice generated by the columns of $x$ if it is of rank $m$, and returns
! 5486: zero otherwise. This function can be useful in conjunction with the function
! 5487: \kbd{mathnfmod} which needs to know such a multiple. To obtain the
! 5488: exact determinant (assuming the rank is maximal), you can compute
! 5489: \kbd{matdet(mathnfmod(x, matdetint(x)))}.
! 5490:
! 5491: Note that as soon as one of the dimensions gets large ($m$ or $n$ is larger
! 5492: than 20, say), it will often be much faster to use \kbd{mathnf(x, 1)} or
! 5493: \kbd{mathnf(x, 4)} directly.
! 5494:
! 5495: \syn{detint}{x}.
! 5496:
! 5497: \subsecidx{matdiagonal}$(x)$: $x$ being a vector, creates the diagonal matrix
! 5498: whose diagonal entries are those of $x$.
! 5499:
! 5500: \syn{diagonal}{x}.
! 5501:
! 5502: \subsecidx{mateigen}$(x)$: gives the eigenvectors of $x$ as columns of a
! 5503: matrix.
! 5504:
! 5505: \syn{eigen}{x}.
! 5506:
! 5507: \subsecidx{mathess}$(x)$: Hessenberg form of the square matrix $x$.
! 5508:
! 5509: \syn{hess}{x}.
! 5510:
! 5511: \subsecidx{mathilbert}$(x)$: $x$ being a \kbd{long}, creates the \idx{Hilbert
! 5512: matrix} of order $x$, i.e.~the matrix whose coefficient ($i$,$j$) is $1/
! 5513: (i+j-1)$.
! 5514:
! 5515: \syn{mathilbert}{x}.
! 5516:
! 5517: \subsecidx{mathnf}$(x,\{\fl=0\})$: if $x$ is a (not necessarily square)
! 5518: matrix, finds the \var{upper triangular} \idx{Hermite normal form} of $x$. If
! 5519: the rank of $x$ is equal to its number of rows, the result is a square
! 5520: matrix. In general, the columns of the result form a basis of the lattice
! 5521: spanned by the columns of $x$.
! 5522:
! 5523: If $\fl=0$, uses the naive algorithm. This should never be used if the
! 5524: dimension is at all large (larger than 10, say). It is recommanded to use
! 5525: either \kbd{mathnfmod(x, matdetint(x))} (when $x$ has maximal rank) or
! 5526: \kbd{mathnf(x, 1)}. Note that the latter is in general faster than
! 5527: \kbd{mathnfmod}, and also provides a base change matrix.
! 5528:
! 5529: If $\fl=1$, uses Batut's algorithm, which is much faster than the default.
! 5530: Outputs a two-component row vector $[H,U]$, where $H$ is the \var{upper
! 5531: triangular} Hermite normal form of $x$ defined as above, and $U$ is the
! 5532: unimodular transformation matrix such that $xU=[0|H]$. $U$ has in general
! 5533: huge coefficients, in particular when the kernel is large.
! 5534:
! 5535: If $\fl=3$, uses Batut's algorithm, but outputs $[H,U,P]$, such that $H$ and
! 5536: $U$ are as before and $P$ is a permutation of the rows such that $P$ applied
! 5537: to $xU$ gives $H$. The matrix $U$ is smaller than with $\fl=1$, but may still
! 5538: be large.
! 5539:
! 5540: If $\fl=4$, as in case 1 above, but uses a heuristic variant of \idx{LLL}
! 5541: reduction along the way. The matrix $U$ is in general close to optimal (in
! 5542: terms of smallest $L_2$ norm), but the reduction is slower than in case $1$.
! 5543:
! 5544: \syn{mathnf0}{x,\fl}. Also available are $\teb{hnf}(x)$ ($\fl=0$) and
! 5545: $\teb{hnfall}(x)$ ($\fl=1$). To reduce \var{huge} (say $400 \times 400$ and
! 5546: more) relation matrices (sparse with small entries), you can use the pair
! 5547: \kbd{hnfspec} / \kbd{hnfadd}. Since this is rather technical and the
! 5548: calling interface may change, they are not documented yet. Look at the code
! 5549: in \kbd{basemath/alglin1.c}.
! 5550:
! 5551: \subsecidx{mathnfmod}$(x,d)$: if $x$ is a (not necessarily square) matrix of
! 5552: maximal rank with integer entries, and $d$ is a multiple of the (non-zero)
! 5553: determinant of the lattice spanned by the columns of $x$, finds the
! 5554: \var{upper triangular} \idx{Hermite normal form} of $x$.
! 5555:
! 5556: If the rank of $x$ is equal to its number of rows, the result is a square
! 5557: matrix. In general, the columns of the result form a basis of the lattice
! 5558: spanned by the columns of $x$. This is much faster than \kbd{mathnf} when $d$
! 5559: is known.
! 5560:
! 5561: \syn{hnfmod}{x,d}.
! 5562:
! 5563: \subsecidx{mathnfmodid}$(x,d)$: outputs the (upper triangular)
! 5564: \idx{Hermite normal form} of $x$ concatenated with $d$ times
! 5565: the identity matrix.
! 5566:
! 5567: \syn{hnfmodid}{x,d}.
! 5568:
! 5569: \subsecidx{matid}$(n)$: creates the $n\times n$ identity matrix.
! 5570:
! 5571: \syn{idmat}{n} where $n$ is a \kbd{long}.
! 5572:
! 5573: Related functions are $\teb{gscalmat}(x,n)$, which creates $x$ times the
! 5574: identity matrix ($x$ being a \kbd{GEN} and $n$ a \kbd{long}), and
! 5575: $\teb{gscalsmat}(x,n)$ which is the same when $x$ is a \kbd{long}.
! 5576:
! 5577: \subsecidx{matimage}$(x,\{\fl=0\})$: gives a basis for the image of the
! 5578: matrix $x$ as columns of a matrix. A priori the matrix can have entries of
! 5579: any type. If $\fl=0$, use standard Gauss pivot. If $\fl=1$, use
! 5580: \kbd{matsupplement}.
! 5581:
! 5582: \syn{matimage0}{x,\fl}. Also available is $\teb{image}(x)$ ($\fl=0$).
! 5583:
! 5584: \subsecidx{matimagecompl}$(x)$: gives the vector of the column indices which
! 5585: are not extracted by the function \kbd{matimage}. Hence the number of
! 5586: components of \kbd{matimagecompl(x)} plus the number of columns of
! 5587: \kbd{matimage(x)} is equal to the number of columns of the matrix $x$.
! 5588:
! 5589: \syn{imagecompl}{x}.
! 5590:
! 5591: \subsecidx{matindexrank}$(x)$: $x$ being a matrix of rank $r$, gives two
! 5592: vectors $y$ and $z$ of length $r$ giving a list of rows and columns
! 5593: respectively (starting from 1) such that the extracted matrix obtained from
! 5594: these two vectors using $\tet{vecextract}(x,y,z)$ is invertible.
! 5595:
! 5596: \syn{indexrank}{x}.
! 5597:
! 5598: \subsecidx{matintersect}$(x,y)$: $x$ and $y$ being two matrices with the same
! 5599: number of rows each of whose columns are independent, finds a basis of the
! 5600: $\Q$-vector space equal to the intersection of the spaces spanned by the
! 5601: columns of $x$ and $y$ respectively. See also the function
! 5602: \tet{idealintersect}, which does the same for free $\Z$-modules.
! 5603:
! 5604: \syn{intersect}{x,y}.
! 5605:
! 5606: \subsecidx{matinverseimage}$(x,y)$: gives a column vector belonging to the
! 5607: inverse image of the column vector $y$ by the matrix $x$ if one exists, the
! 5608: empty vector otherwise. To get the complete inverse image, it suffices to add
! 5609: to the result any element of the kernel of $x$ obtained for example by
! 5610: \kbd{matker}.
! 5611:
! 5612: \syn{inverseimage}{x,y}.
! 5613:
! 5614: \subsecidx{matisdiagonal}$(x)$: returns true (1) if $x$ is a diagonal matrix,
! 5615: false (0) if not.
! 5616:
! 5617: \syn{isdiagonal}{x}, and this returns a \kbd{long}
! 5618: integer.
! 5619:
! 5620: \subsecidx{matker}$(x,\{\fl=0\})$: gives a basis for the kernel of the
! 5621: matrix $x$ as columns of a matrix. A priori the matrix can have entries of
! 5622: any type.
! 5623:
! 5624: If $x$ is known to have integral entries, set $\fl=1$.
! 5625:
! 5626: \noindent Note: The library function $\tet{ker_mod_p}(x, p)$, where $x$ has
! 5627: integer entries and $p$ is prime, which is equivalent to but many orders of
! 5628: magnitude faster than \kbd{matker(x*Mod(1,p))} and needs much less stack
! 5629: space. To use it under GP, type \kbd{install(ker\_mod\_p, GG)} first.
! 5630:
! 5631: \syn{matker0}{x,\fl}. Also available are $\teb{ker}(x)$ ($\fl=0$),
! 5632: $\teb{keri}(x)$ ($\fl=1$) and $\kbd{ker\_mod\_p}(x,p)$.
! 5633:
! 5634: \subsecidx{matkerint}$(x,\{\fl=0\})$: gives an \idx{LLL}-reduced $\Z$-basis
! 5635: for the lattice equal to the kernel of the matrix $x$ as columns of the
! 5636: matrix $x$ with integer entries (rational entries are not permitted).
! 5637:
! 5638: If $\fl=0$, uses a modified integer LLL algorithm.
! 5639:
! 5640: If $\fl=1$, uses $\kbd{matrixqz}(x,-2)$. If LLL reduction of the final result
! 5641: is not desired, you can save time using \kbd{matrixqz(matker(x),-2)} instead.
! 5642:
! 5643: If $\fl=2$, uses another modified LLL. In the present version \vers, only
! 5644: independent rows are allowed in this case.
! 5645:
! 5646: \syn{matkerint0}{x,\fl}. Also available is
! 5647: $\teb{kerint}(x)$ ($\fl=0$).
! 5648:
! 5649: \subsecidx{matmuldiagonal}$(x,d)$: product of the matrix $x$ by the diagonal
! 5650: matrix whose diagonal entries are those of the vector $d$. Equivalent to,
! 5651: but much faster than $x*\kbd{matdiagonal}(d)$.
! 5652:
! 5653: \syn{matmuldiagonal}{x,d}.
! 5654:
! 5655: \subsecidx{matmultodiagonal}$(x,y)$: product of the matrices $x$ and $y$
! 5656: knowing that the result is a diagonal matrix. Much faster than $x*y$ in
! 5657: that case.
! 5658:
! 5659: \syn{matmultodiagonal}{x,y}.
! 5660:
! 5661: \subsecidx{matpascal}$(x,\{q\})$: creates as a matrix the lower triangular
! 5662: \idx{Pascal triangle} of order $x+1$ (i.e.~with binomial coefficients
! 5663: up to $x$). If $q$ is given, compute the $q$-Pascal triangle (i.e.~using
! 5664: $q$-binomial coefficients).
! 5665:
! 5666: \syn{matqpascal}{x,q}, where $x$ is a \kbd{long} and $q=\kbd{NULL}$ is used
! 5667: to omit $q$. Also available is $\teb{matpascal}(x)$.
! 5668:
! 5669: \subsecidx{matrank}$(x)$: rank of the matrix $x$.
! 5670:
! 5671: \syn{rank}{x}, and the result is a \kbd{long}.
! 5672:
! 5673: \subsecidx{matrix}$(m,n,\{X\},\{Y\},\{\var{expr}=0\})$: creation of the
! 5674: $m\times n$ matrix whose coefficients are given by the expression
! 5675: \var{expr}. There are two formal parameters in \var{expr}, the first one
! 5676: ($X$) corresponding to the rows, the second ($Y$) to the columns, and $X$
! 5677: goes from 1 to $m$, $Y$ goes from 1 to $n$. If one of the last 3 parameters
! 5678: is omitted, fill the matrix with zeroes.
! 5679:
! 5680: \synt{matrice}{GEN nlig,GEN ncol,entree *e1,entree *e2,char *expr}.
! 5681:
! 5682: \subsecidx{matrixqz}$(x,p)$: $x$ being an $m\times n$ matrix with $m\ge n$
! 5683: with rational or integer entries, this function has varying behaviour
! 5684: depending on the sign of $p$:
! 5685:
! 5686: If $p\geq 0$, $x$ is assumed to be of maximal rank. This function returns a
! 5687: matrix having only integral entries, having the same image as $x$, such that
! 5688: the GCD of all its $n\times n$ subdeterminants is equal to 1 when $p$ is
! 5689: equal to 0, or not divisible by $p$ otherwise. Here $p$ must be a prime
! 5690: number (when it is non-zero). However, if the function is used when $p$ has
! 5691: no small prime factors, it will either work or give the message ``impossible
! 5692: inverse modulo'' and a non-trivial divisor of $p$.
! 5693:
! 5694: If $p=-1$, this function returns a matrix whose columns form a basis of the
! 5695: lattice equal to $\Z^n$ intersected with the lattice generated by the
! 5696: columns of $x$.
! 5697:
! 5698: If $p=-2$, returns a matrix whose columns form a basis of the lattice equal
! 5699: to $\Z^n$ intersected with the $\Q$-vector space generated by the
! 5700: columns of $x$.
! 5701:
! 5702: \syn{matrixqz0}{x,p}.
! 5703:
! 5704: \subsecidx{matsize}$(x)$: $x$ being a vector or matrix, returns a row vector
! 5705: with two components, the first being the number of rows (1 for a row vector),
! 5706: the second the number of columns (1 for a column vector).
! 5707:
! 5708: \syn{matsize}{x}.
! 5709:
! 5710: \subsecidx{matsnf}$(X,\{\fl=0\})$: if $X$ is a (singular or non-singular)
! 5711: square matrix outputs the vector of elementary divisors of $X$ (i.e.~the
! 5712: diagonal of the \idx{Smith normal form} of $X$).
! 5713:
! 5714: The binary digits of \fl\ mean:
! 5715:
! 5716: 1 (complete output): if set, outputs $[U,V,D]$, where $U$ and $V$ are two
! 5717: unimodular matrices such that $UXV$ is the diagonal matrix $D$. Otherwise
! 5718: output only the diagonal of $D$.
! 5719:
! 5720: 2 (generic input): if set, allows polynomial entries. Otherwise, assume
! 5721: that $X$ has integer coefficients.
! 5722:
! 5723: 4 (cleanup): if set, cleans up the output. This means that elementary
! 5724: divisors equal to $1$ will be deleted, i.e.~outputs a shortened vector $D'$
! 5725: instead of $D$. If complete output was required, returns $[U',V',D']$ so
! 5726: that $U'XV' = D'$ holds. If this flag is set, $X$ is allowed to be of the
! 5727: form $D$ or $[U,V,D]$ as would normally be output with the cleanup flag
! 5728: unset.
! 5729:
! 5730: \syn{matsnf0}{X,\fl}. Also available is $\teb{smith}(X)$ ($\fl=0$).
! 5731:
! 5732: \subsecidx{matsolve}$(x,y)$: $x$ being an invertible matrix and $y$ a column
! 5733: vector, finds the solution $u$ of $x*u=y$, using Gaussian elimination. This
! 5734: has the same effect as, but is a bit faster, than $x^{-1}*y$.
! 5735:
! 5736: \syn{gauss}{x,y}.
! 5737:
! 5738: \subsecidx{matsolvemod}$(m,d,y,\{\fl=0\})$: $m$ being any integral matrix,
! 5739: $d$ a vector of positive integer moduli, and $y$ an integral
! 5740: column vector, gives a small integer solution to the system of congruences
! 5741: $\sum_i m_{i,j}x_j\equiv y_i\pmod{d_i}$ if one exists, otherwise returns
! 5742: zero. Shorthand notation: $y$ (resp.~$d$) can be given as a single integer,
! 5743: in which case all the $y_i$ (resp.~$d_i$) above are taken to be equal to $y$
! 5744: (resp.~$d$).
! 5745:
! 5746: If $\fl=1$, all solutions are returned in the form of a two-component row
! 5747: vector $[x,u]$, where $x$ is a small integer solution to the system of
! 5748: congruences and $u$ is a matrix whose columns give a basis of the homogeneous
! 5749: system (so that all solutions can be obtained by adding $x$ to any linear
! 5750: combination of columns of $u$). If no solution exists, returns zero.
! 5751:
! 5752: \syn{matsolvemod0}{m,d,y,\fl}. Also available
! 5753: are $\teb{gaussmodulo}(m,d,y)$ ($\fl=0$)
! 5754: and $\teb{gaussmodulo2}(m,d,y)$ ($\fl=1$).
! 5755:
! 5756: \subsecidx{matsupplement}$(x)$: assuming that the columns of the matrix $x$
! 5757: are linearly independent (if they are not, an error message is issued), finds
! 5758: a square invertible matrix whose first columns are the columns of $x$,
! 5759: i.e.~supplement the columns of $x$ to a basis of the whole space.
! 5760:
! 5761: \syn{suppl}{x}.
! 5762:
! 5763: \subsecidx{mattranspose}$(x)$ or $x\til$: transpose of $x$.
! 5764: This has an effect only on vectors and matrices.
! 5765:
! 5766: \syn{gtrans}{x}.
! 5767:
! 5768: \subsecidx{qfgaussred}$(q)$: \idx{decomposition into squares} of the
! 5769: quadratic form represented by the symmetric matrix $q$. The result is a
! 5770: matrix whose diagonal entries are the coefficients of the squares, and the
! 5771: non-diagonal entries represent the bilinear forms. More precisely, if
! 5772: $(a_{ij})$ denotes the output, one has
! 5773: $$ q(x) = \sum_i a_{ii} (x_i + \sum_{j>i} a_{ij} x_j)^2 $$
! 5774:
! 5775: \syn{sqred}{x}.
! 5776:
! 5777: \subsecidx{qfjacobi}$(x)$: $x$ being a real symmetric matrix, this gives a
! 5778: vector having two components: the first one is the vector of eigenvalues of
! 5779: $x$, the second is the corresponding orthogonal matrix of eigenvectors of
! 5780: $x$. The method used is Jacobi's method for symmetric matrices.
! 5781:
! 5782: \syn{jacobi}{x}.
! 5783:
! 5784: \subsecidx{qflll}$(x,\{\fl=0\})$: \idx{LLL} algorithm applied to the
! 5785: \var{columns} of the (not necessarily square) matrix $x$. The columns of $x$
! 5786: must however be linearly independent, unless specified otherwise below. The
! 5787: result is a transformation matrix $T$ such that $x\cdot T$ is an LLL-reduced
! 5788: basis of the lattice generated by the column vectors of $x$.
! 5789:
! 5790: If $\fl=0$ (default), the computations are done with real numbers (i.e.~not
! 5791: with rational numbers) hence are fast but as presently programmed (version
! 5792: \vers) are numerically unstable.
! 5793:
! 5794: If $\fl=1$, it is assumed that the corresponding Gram matrix is integral.
! 5795: The computation is done entirely with integers and the algorithm is both
! 5796: accurate and quite fast. In this case, $x$ needs not be of maximal rank, but
! 5797: if it is not, $T$ will not be square.
! 5798:
! 5799: If $\fl=2$, similar to case 1, except $x$ should be an integer matrix whose
! 5800: columns are linearly independent. The lattice generated by the columns of
! 5801: $x$ is first partially reduced before applying the LLL algorithm. [A basis
! 5802: is said to be \var{partially reduced} if $|v_i \pm v_j| \geq |v_i|$ for any
! 5803: two distinct basis vectors $v_i, \, v_j$.]
! 5804:
! 5805: This can be significantly faster than $\fl=1$ when one row is huge compared
! 5806: to the other rows.
! 5807:
! 5808: If $\fl=3$, all computations are done in rational numbers. This does not
! 5809: incur numerical instability, but is extremely slow. This function is
! 5810: essentially superseded by case 1, so will soon disappear.
! 5811:
! 5812: If $\fl=4$, $x$ is assumed to have integral entries, but needs not be of
! 5813: maximal rank. The result is a two-component vector of matrices~: the
! 5814: columns of the first matrix represent a basis of the integer kernel of $x$
! 5815: (not necessarily LLL-reduced) and the second matrix is the transformation
! 5816: matrix $T$ such that $x\cdot T$ is an LLL-reduced $\Z$-basis of the image
! 5817: of the matrix $x$.
! 5818:
! 5819: If $\fl=5$, case as case $4$, but $x$ may have polynomial coefficients.
! 5820:
! 5821: If $\fl=7$, uses an older version of case $0$ above.
! 5822:
! 5823: If $\fl=8$, same as case $0$, where $x$ may have polynomial coefficients.
! 5824:
! 5825: If $\fl=9$, variation on case $1$, using content.
! 5826:
! 5827: \syn{qflll0}{x,\fl,\var{prec}}. Also available are
! 5828: $\teb{lll}(x,\var{prec})$ ($\fl=0$), $\teb{lllint}(x)$ ($\fl=1$), and
! 5829: $\teb{lllkerim}(x)$ ($\fl=4$).
! 5830:
! 5831: \subsecidx{qflllgram}$(x,\{\fl=0\})$: same as \kbd{qflll} except that the
! 5832: matrix $x$ which must now be a square symmetric real matrix is the Gram
! 5833: matrix of the lattice vectors, and not the coordinates of the vectors
! 5834: themselves. The result is again the transformation matrix $T$ which gives (as
! 5835: columns) the coefficients with respect to the initial basis vectors. The
! 5836: flags have more or less the same meaning, but some are missing. In brief:
! 5837:
! 5838: $\fl=0$: numerically unstable in the present version \vers.
! 5839:
! 5840: $\fl=1$: $x$ has integer entries, the computations are all done in integers.
! 5841:
! 5842: $\fl=4$: $x$ has integer entries, gives the kernel and reduced image.
! 5843:
! 5844: $\fl=5$: same as $4$ for generic $x$.
! 5845:
! 5846: $\fl=7$: an older version of case $0$.
! 5847:
! 5848: \syn{qflllgram0}{x,\fl,\var{prec}}. Also available are
! 5849: $\teb{lllgram}(x,\var{prec})$ ($\fl=0$), $\teb{lllgramint}(x)$ ($\fl=1$), and
! 5850: $\teb{lllgramkerim}(x)$ ($\fl=4$).
! 5851:
! 5852: \subsecidx{qfminim}$(x,b,m,\{\fl=0\})$: $x$ being a square and symmetric
! 5853: matrix representing a positive definite quadratic form, this function
! 5854: deals with the minimal vectors of $x$, depending on $\fl$.
! 5855:
! 5856: If $\fl=0$ (default), seeks vectors of square norm less than or equal to $b$
! 5857: (for the norm defined by $x$), and at most $2m$ of these vectors. The result
! 5858: is a three-component vector, the first component being the number of vectors,
! 5859: the second being the maximum norm found, and the last vector is a matrix
! 5860: whose columns are the vectors found, only one being given for each
! 5861: pair $\pm v$ (at most $m$ such pairs).
! 5862:
! 5863: If $\fl=1$, ignores $m$ and returns the first vector whose norm is less than
! 5864: $b$.
! 5865:
! 5866: In both these cases, $x$ {\it is assumed to have integral entries}, and the
! 5867: function searches for the minimal non-zero vectors whenever $b=0$.
! 5868:
! 5869: If $\fl=2$, $x$ can have non integral real entries, but $b=0$ is now
! 5870: meaningless (uses Fincke-Pohst algorithm).
! 5871:
! 5872: \syn{qfminim0}{x,b,m,\fl,\var{prec}}, also available are \funs{minim}{x,b,m}
! 5873: ($\fl=0$), \funs{minim2}{x,b,m} ($\fl=1$), and finally
! 5874: \funs{fincke_pohst}{x,b,m,\var{prec}} ($\fl=2$).
! 5875:
! 5876: \subsecidx{qfperfection}$(x)$: $x$ being a square and symmetric matrix with
! 5877: integer entries representing a positive definite quadratic form, outputs the
! 5878: perfection rank of the form. That is, gives the rank of the family of the $s$
! 5879: symmetric matrices $v_iv_i^t$, where $s$ is half the number of minimal
! 5880: vectors and the $v_i$ ($1\le i\le s$) are the minimal vectors.
! 5881:
! 5882: As a side note to old-timers, this used to fail bluntly when $x$ had more
! 5883: than $5000$ minimal vectors. Beware that the computations can now be very
! 5884: lengthy when $x$ has many minimal vectors.
! 5885:
! 5886: \syn{perf}{x}.
! 5887:
! 5888: \subsecidx{qfsign}$(x)$: signature of the quadratic form represented by the
! 5889: symmetric matrix $x$. The result is a two-component vector.
! 5890:
! 5891: \syn{signat}{x}.
! 5892:
! 5893: \subsecidx{setintersect}$(x,y)$: intersection of the two sets $x$ and $y$.
! 5894:
! 5895: \syn{setintersect}{x,y}.
! 5896:
! 5897: \subsecidx{setisset}$(x)$: returns true (1) if $x$ is a set, false (0) if
! 5898: not. In PARI, a set is simply a row vector whose entries are strictly
! 5899: increasing. To convert any vector (and other objects) into a set, use the
! 5900: function \kbd{Set}.
! 5901:
! 5902: \syn{setisset}{x}, and this returns a \kbd{long}.
! 5903:
! 5904: \subsecidx{setminus}$(x,y)$: difference of the two sets $x$ and $y$,
! 5905: i.e.~set of elements of $x$ which do not belong to $y$.
! 5906:
! 5907: \syn{setminus}{x,y}.
! 5908:
! 5909: \subsecidx{setsearch}$(x,y,\{\fl=0\})$: searches if $y$ belongs to the set
! 5910: $x$. If it does and $\fl$ is zero or omitted, returns the index $j$ such that
! 5911: $x[j]=y$, otherwise returns 0. If $\fl$ is non-zero returns the index $j$
! 5912: where $y$ should be inserted, and $0$ if it already belongs to $x$ (this is
! 5913: meant to be used in conjunction with \kbd{listinsert}).
! 5914:
! 5915: This function works also if $x$ is a \var{sorted} list (see \kbd{listsort}).
! 5916:
! 5917: \syn{setsearch}{x,y,\fl} which returns a \kbd{long}
! 5918: integer.
! 5919:
! 5920: \subsecidx{setunion}$(x,y)$: union of the two sets $x$ and $y$.
! 5921:
! 5922: \syn{setunion}{x,y}.
! 5923:
! 5924: \subsecidx{trace}$(x)$: this applies to quite general $x$. If $x$ is not a
! 5925: matrix, it is equal to the sum of $x$ and its conjugate, except for polmods
! 5926: where it is the trace as an algebraic number.
! 5927:
! 5928: For $x$ a square matrix, it is the ordinary trace. If $x$ is a
! 5929: non-square matrix (but not a vector), an error occurs.
! 5930:
! 5931: \syn{gtrace}{x}.
! 5932:
! 5933: \subsecidx{vecextract}$(x,y,\{z\})$: extraction of components of the
! 5934: vector or matrix $x$ according to $y$. In case $x$ is a matrix, its
! 5935: components are as usual the \var{columns} of $x$. The parameter $y$ is a
! 5936: component specifier, which is either an integer, a string describing a
! 5937: range, or a vector.
! 5938:
! 5939: If $y$ is an integer, it is considered as a mask: the binary bits of $y$ are
! 5940: read from right to left, but correspond to taking the components from left to
! 5941: right. For example, if $y=13=(1101)_2$ then the components 1,3 and 4 are
! 5942: extracted.
! 5943:
! 5944: If $y$ is a vector, which must have integer entries, these entries correspond
! 5945: to the component numbers to be extracted, in the order specified.
! 5946:
! 5947: If $y$ is a string, it can be
! 5948:
! 5949: $\bullet$ a single (non-zero) index giving a component number (a negative
! 5950: index means we start counting from the end).
! 5951:
! 5952: $\bullet$ a range of the form \kbd{"$a$..$b$"}, where $a$ and $b$ are
! 5953: indexes as above. Any of $a$ and $b$ can be omitted; in this case, we take
! 5954: as default values $a = 1$ and $b = -1$, i.e.~ the first and last components
! 5955: respectively. We then extract all components in the interval $[a,b]$, in
! 5956: reverse order if $b < a$.
! 5957:
! 5958: In addition, if the first character in the string is \kbd{\pow}, the
! 5959: complement of the given set of indices is taken.
! 5960:
! 5961: If $z$ is not omitted, $x$ must be a matrix. $y$ is then the \var{line}
! 5962: specifier, and $z$ the \var{column} specifier, where the component specifier
! 5963: is as explained above.
! 5964:
! 5965: \bprog
! 5966: ? v = [a, b, c, d, e];
! 5967: ? vecextract(v, 5) \\@com mask
! 5968: %1 = [a, c]
! 5969: ? vecextract(v, [4, 2, 1]) \\@com component list
! 5970: %2 = [d, b, a]
! 5971: ? vecextract(v, "2..4") \\@com interval
! 5972: %3 = [b, c, d]
! 5973: ? vecextract(v, "-1..-3") \\@com interval + reverse order
! 5974: %4 = [e, d, c]
! 5975: ? vecextract([1,2,3], "^2") \\@com complement
! 5976: %5 = [1, 3]
! 5977: ? vecextract(matid(3), "2..", "..")
! 5978: %6 =
! 5979: [0 1 0]
! 5980:
! 5981: [0 0 1]
! 5982: @eprog
! 5983:
! 5984: \syn{extract}{x,y} or $\teb{matextract}(x,y,z)$.
! 5985:
! 5986: \subsecidx{vecsort}$(x,\{k\},\{\fl=0\})$: sorts the vector $x$ in ascending
! 5987: order, using the heapsort method. $x$ must be a vector, and its components
! 5988: integers, reals, or fractions.
! 5989:
! 5990: If $k$ is present and is an integer, sorts according to the value of the
! 5991: $k$-th subcomponents of the components of~$x$. $k$ can also be a vector,
! 5992: in which case the
! 5993: sorting is done lexicographically according to the components listed in the
! 5994: vector $k$. For example, if $k=[2,1,3]$, sorting will be done with respect
! 5995: to the second component, and when these are equal, with respect to the
! 5996: first, and when these are equal, with respect to the third.
! 5997:
! 5998: \noindent The binary digits of \fl\ mean:
! 5999:
! 6000: $\bullet$ 1: indirect sorting of the vector $x$, i.e.~if $x$ is an
! 6001: $n$-component vector, returns a permutation of $[1,2,\dots,n]$ which
! 6002: applied to the components of $x$ sorts $x$ in increasing order.
! 6003: For example, \kbd{vecextract(x, vecsort(x,,1))} is equivalent to
! 6004: \kbd{vecsort(x)}.
! 6005:
! 6006: $\bullet$ 2: sorts $x$ by ascending lexicographic order (as per the
! 6007: \kbd{lex} comparison function).
! 6008:
! 6009: $\bullet$ 4: use decreasing instead of ascending order.
! 6010:
! 6011: \syn{vecsort0}{x,k,flag}. To omit $k$, use \kbd{NULL} instead. You can also
! 6012: use the simpler functions
! 6013:
! 6014: $\teb{sort}(x)$ (= $\kbd{vecsort0}(x,\text{NULL},0)$).
! 6015:
! 6016: $\teb{indexsort}(x)$ (= $\kbd{vecsort0}(x,\text{NULL},1)$).
! 6017:
! 6018: $\teb{lexsort}(x)$ (= $\kbd{vecsort0}(x,\text{NULL},2)$).
! 6019:
! 6020: Also available are \teb{sindexsort} and \teb{sindexlexsort} which return a
! 6021: vector of C-long integers (private type \typ{VECSMALL}) $v$, where
! 6022: $v[1]\dots v[n]$ contain the indices. Note that the resulting $v$ is
! 6023: \var{not} a generic PARI object, but is in general easier to use in C
! 6024: programs!
! 6025:
! 6026: \subsecidx{vector}$(n,\{X\},\{\var{expr}=0\})$: creates a row vector (type
! 6027: \typ{VEC}) with $n$ components whose components are the expression
! 6028: \var{expr} evaluated at the integer points between 1 and $n$. If one of the
! 6029: last two arguments is omitted, fill the vector with zeroes.
! 6030:
! 6031: \synt{vecteur}{GEN nmax, entree *ep, char *expr}.
! 6032:
! 6033: \subsecidx{vectorv}$(n,X,\var{expr})$: as \tet{vector}, but returns a
! 6034: column vector (type \typ{COL}).
! 6035:
! 6036: \synt{vvecteur}{GEN nmax, entree *ep, char *expr}.
! 6037:
! 6038: \section{Sums, products, integrals and similar functions}
! 6039: \label{se:sums}
! 6040:
! 6041: Although the GP calculator is programmable, it is useful to have
! 6042: preprogrammed a number of loops, including sums, products, and a certain
! 6043: number of recursions. Also, a number of functions from numerical analysis
! 6044: like numerical integration and summation of series will be described here.
! 6045:
! 6046: One of the parameters in these loops must be the control variable, hence a
! 6047: simple variable name. The last parameter can be any legal PARI expression,
! 6048: including of course expressions using loops. Since it is much easier to
! 6049: program directly the loops in library mode, these functions are mainly
! 6050: useful for GP programming. The use of these functions in library mode is a
! 6051: little tricky and its explanation will be mostly omitted, although the
! 6052: reader can try and figure it out by himself by checking the example given
! 6053: for the \tet{sum} function. In this section we only give the library
! 6054: syntax, with no semantic explanation.
! 6055:
! 6056: The letter $X$ will always denote any simple variable name, and represents
! 6057: the formal parameter used in the function.
! 6058:
! 6059: \misctitle{(numerical) integration}:\sidx{numerical integration} A number
! 6060: of Romberg-like integration methods are implemented (see \kbd{intnum} as
! 6061: opposed to \kbd{intformal} which we already described). The user should not
! 6062: require too much accuracy: 18 or 28 decimal digits is OK, but not much more.
! 6063: In addition, analytical cleanup of the integral must have been done: there
! 6064: must be no singularities in the interval or at the boundaries. In practice
! 6065: this can be accomplished with a simple change of variable. Furthermore, for
! 6066: improper integrals, where one or both of the limits of integration are plus
! 6067: or minus infinity, the function must decrease sufficiently rapidly at
! 6068: infinity. This can often be accomplished through integration by parts.
! 6069: Finally, the function to be integrated should not be very small
! 6070: (compared to the current precision) on the entire interval. This can
! 6071: of course be accomplished by just multiplying by an appropriate
! 6072: constant.
! 6073:
! 6074: Note that \idx{infinity} can be represented with essentially no loss of
! 6075: accuracy by 1e4000. However beware of real underflow when dealing with
! 6076: rapidly decreasing functions. For example, if one wants to compute the
! 6077: $\int_0^\infty e^{-x^2}\,dx$ to 28 decimal digits, then one should set
! 6078: infinity equal to 10 for example, and certainly not to 1e4000.
! 6079:
! 6080: The integrand may have values belonging to a vector space over the real
! 6081: numbers; in particular, it can be complex-valued or vector-valued.
! 6082:
! 6083: See also the discrete summation methods below (sharing the prefix \kbd{sum}).
! 6084:
! 6085: \subsecidx{intnum}$(X=a,b,\var{expr},\{\fl=0\})$: numerical integration of
! 6086: \var{expr} (smooth in $]a,b[$), with respect to $X$.
! 6087:
! 6088: Set $\fl=0$ (or omit it altogether) when $a$ and $b$ are not too large, the
! 6089: function is smooth, and can be evaluated exactly everywhere on the interval
! 6090: $[a,b]$.
! 6091:
! 6092: If $\fl=1$, uses a general driver routine for doing numerical integration,
! 6093: making no particular assumption (slow).
! 6094:
! 6095: $\fl=2$ is tailored for being used when $a$ or $b$ are infinite. One
! 6096: \var{must} have $ab>0$, and in fact if for example $b=+\infty$, then it is
! 6097: preferable to have $a$ as large as possible, at least $a\ge1$.
! 6098:
! 6099: If $\fl=3$, the function is allowed to be undefined (but continuous) at $a$
! 6100: or $b$, for example the function $\sin(x)/x$ at $x=0$.
! 6101:
! 6102: \synt{intnum0}{entree$\,$*e,GEN a,GEN b,char$\,$*expr,long \fl,long prec}.
! 6103:
! 6104: \subsecidx{prod}$(X=a,b,\var{expr},\{x=1\})$: product of expression \var{expr},
! 6105: initialized at $x$, the formal parameter $X$ going from $a$ to $b$. As for
! 6106: \kbd{sum}, the main purpose of the initialization parameter $x$ is to force
! 6107: the type of the operations being performed. For example if it is set equal to
! 6108: the integer 1, operations will start being done exactly. If it is set equal
! 6109: to the real $1.$, they will be done using real numbers having the default
! 6110: precision. If it is set equal to the power series $1+O(X^k)$ for a certain
! 6111: $k$, they will be done using power series of precision at most $k$. These
! 6112: are the three most common initializations.
! 6113:
! 6114: \noindent As an extreme example, compare
! 6115:
! 6116: \bprog
! 6117: ? prod(i=1, 100, 1 - X^i); \\@com this has degree $5050$ !!
! 6118: time = 3,335 ms.
! 6119: ? prod(i=1, 100, 1 - X^i, 1 + O(X^101))
! 6120: time = 43 ms.
! 6121: %2 = 1 - X - X^2 + X^5 + X^7 - X^12 - X^15 + X^22 + X^26 - X^35 - X^40 + \
! 6122: X^51 + X^57 - X^70 - X^77 + X^92 + X^100 + O(X^101)
! 6123: @eprog
! 6124:
! 6125: \synt{produit}{entree *ep, GEN a, GEN b, char *expr, GEN x}.
! 6126:
! 6127: \subsecidx{prodeuler}$(X=a,b,\var{expr})$: product of expression \var{expr},
! 6128: initialized at 1. (i.e.~to a \var{real} number equal to 1 to the current
! 6129: \kbd{realprecision}), the formal parameter $X$ ranging over the prime numbers
! 6130: between $a$ and $b$.\sidx{Euler product}
! 6131:
! 6132: \synt{prodeuler}{entree *ep, GEN a, GEN b, char *expr, long prec}.
! 6133:
! 6134: \subsecidx{prodinf}$(X=a,\var{expr},\{\fl=0\})$: \idx{infinite product} of
! 6135: expression \var{expr}, the formal parameter $X$ starting at $a$. The evaluation
! 6136: stops when the relative error of the expression minus 1 is less than the
! 6137: default precision. The expressions must always evaluate to an element of
! 6138: $\C$.
! 6139:
! 6140: If $\fl=1$, do the product of the ($1+\var{expr}$) instead.
! 6141:
! 6142: \synt{prodinf}{entree *ep, GEN a, char *expr, long prec} ($\fl=0$), or
! 6143: \teb{prodinf1} with the same arguments ($\fl=1$).
! 6144:
! 6145: \subsecidx{solve}$(X=a,b,\var{expr})$: find a real root of expression
! 6146: \var{expr} between $a$ and $b$, under the condition
! 6147: $\var{expr}(X=a) * \var{expr}(X=b) \le 0$.
! 6148: This routine uses Brent's method and can fail miserably if \var{expr} is
! 6149: not defined in the whole of $[a,b]$ (try \kbd{solve(x=1, 2, tan(x)}).
! 6150:
! 6151: \synt{zbrent}{entree *ep, GEN a, GEN b, char *expr, long prec}.
! 6152:
! 6153: \subsecidx{sum}$(X=a,b,\var{expr},\{x=0\})$: sum of expression \var{expr},
! 6154: initialized at $x$, the formal parameter going from $a$ to $b$. As for
! 6155: \kbd{prod}, the initialization parameter $x$ may be given to force the type
! 6156: of the operations being performed.
! 6157:
! 6158: \noindent As an extreme example, compare
! 6159:
! 6160: \bprog
! 6161: ? sum(i=1, 5000, 1/i); \\@com rational number: denominator has $2166$ digits.
! 6162: time = 1,241 ms.
! 6163: ? sum(i=1, 5000, 1/i, 0.)
! 6164: time = 158 ms.
! 6165: %2 = 9.094508852984436967261245533
! 6166: @eprog
! 6167:
! 6168: \synt{somme}{entree *ep, GEN a, GEN b, char *expr, GEN x}. This is to be
! 6169: used as follows: \kbd{ep} represents the dummy variable used in the
! 6170: expression \kbd{expr}
! 6171: \bprog
! 6172: /* compute a^2 + @dots + b^2 */
! 6173: {
! 6174: /* define the dummy variable "i" */
! 6175: entree *ep = is_entry("i");
! 6176: /* sum for a <= i <= b */
! 6177: return somme(ep, a, b, "i^2", gzero);
! 6178: }
! 6179: @eprog
! 6180:
! 6181: \subsecidx{sumalt}$(X=a,\var{expr},\{\fl=0\})$: numerical summation of the
! 6182: series \var{expr}, which should be an \idx{alternating series}, the formal
! 6183: variable $X$ starting at $a$.
! 6184:
! 6185: If $\fl=0$, use an algorithm of F.~Villegas as modified by D.~Zagier. This
! 6186: is much better than \idx{Euler}-Van Wijngaarden's method which was used
! 6187: formerly.
! 6188: Beware that the stopping criterion is that the term gets small enough, hence
! 6189: terms which are equal to 0 will create problems and should be removed.
! 6190:
! 6191: If $\fl=1$, use a variant with slightly different polynomials. Sometimes
! 6192: faster.
! 6193:
! 6194: Divergent alternating series can sometimes be summed by this method, as well
! 6195: as series which are not exactly alternating (see for example
! 6196: \secref{se:user_defined}).
! 6197:
! 6198: \misctitle{Important hint:} a significant speed gain can be obtained by
! 6199: writing the $(-1)^X$ which may occur in the expression as
! 6200: \kbd{(1.~- X\%2*2)}.
! 6201:
! 6202: \synt{sumalt}{entree *ep, GEN a, char *expr, long \fl, long prec}.
! 6203:
! 6204: \subsecidx{sumdiv}$(n,X,\var{expr})$: sum of expression \var{expr} over
! 6205: the positive divisors of $n$.
! 6206:
! 6207: Arithmetic functions like \tet{sigma} use the multiplicativity of the
! 6208: underlying expression to speed up the computation. In the present version
! 6209: \vers, there is no way to indicate that \var{expr} is multiplicative in
! 6210: $n$, hence specialized functions should be prefered whenever possible.
! 6211:
! 6212: \synt{divsum}{entree *ep, GEN num, char *expr}.
! 6213:
! 6214: \subsecidx{suminf}$(X=a,\var{expr})$: \idx{infinite sum} of expression
! 6215: \var{expr}, the formal parameter $X$ starting at $a$. The evaluation stops
! 6216: when the relative error of the expression is less than the default precision.
! 6217: The expressions must always evaluate to a complex number.
! 6218:
! 6219: \synt{suminf}{entree *ep, GEN a, char *expr, long prec}.
! 6220:
! 6221: \subsecidx{sumpos}$(X=a,\var{expr},\{\fl=0\})$: numerical summation of the
! 6222: series \var{expr}, which must be a series of terms having the same sign,
! 6223: the formal
! 6224: variable $X$ starting at $a$. The algorithm used is Van Wijngaarden's trick
! 6225: for converting such a series into an alternating one, and is quite slow.
! 6226: Beware that the stopping criterion is that the term gets small enough, hence
! 6227: terms which are equal to 0 will create problems and should be removed.
! 6228:
! 6229: If $\fl=1$, use slightly different polynomials. Sometimes faster.
! 6230:
! 6231: \synt{sumpos}{entree *ep, GEN a, char *expr, long \fl, long prec}.
! 6232:
! 6233: \section{Plotting functions}
! 6234:
! 6235: Although plotting is not even a side purpose of PARI, a number of plotting
! 6236: functions are provided. Moreover, a lot of people felt like suggesting
! 6237: ideas or submitting huge patches for this section of the code. Among these,
! 6238: special thanks go to Klaus-Peter Nischke who suggested the recursive plotting
! 6239: and the forking/resizing stuff under X11, and Ilya Zakharevich who
! 6240: undertook a complete rewrite of the graphic code, so that most of it is now
! 6241: platform-independent and should be relatively easy to port or expand.
! 6242:
! 6243: These graphic functions are either
! 6244:
! 6245: $\bullet$ high-level plotting functions (all the functions starting with
! 6246: \kbd{ploth}) in which the user has little to do but explain what type of plot
! 6247: he wants, and whose syntax is similar to the one used in the preceding
! 6248: section (with somewhat more complicated flags).
! 6249:
! 6250: $\bullet$ low-level plotting functions, where every drawing primitive (point,
! 6251: line, box, etc.) must be specified by the user. These low-level functions
! 6252: (called \var{rectplot} functions, sharing the prefix \kbd{plot}) work as
! 6253: follows. You have at your disposal 16 virtual windows which are filled
! 6254: independently, and can then be physically ORed on a single window at
! 6255: user-defined positions. These windows are numbered from 0 to 15, and must be
! 6256: initialized before being used by the function \kbd{plotinit}, which specifies
! 6257: the height and width of the virtual window (called a \var{rectwindow} in the
! 6258: sequel). At all times, a virtual cursor (initialized at $[0,0]$) is
! 6259: associated to the window, and its current value can be obtained using the
! 6260: function \kbd{plotcursor}.
! 6261:
! 6262: A number of primitive graphic objects (called \var{rect} objects) can then
! 6263: be drawn in these windows, using a default color associated to that window
! 6264: (which can be changed under X11, using the \kbd{plotcolor} function, black
! 6265: otherwise) and only the part of the object which is inside the window will be
! 6266: drawn, with the exception of polygons and strings which are drawn entirely
! 6267: (but the virtual cursor can move outside of the window). The ones sharing the
! 6268: prefix \kbd{plotr} draw relatively to the current position of the virtual
! 6269: cursor, the others use absolute coordinates. Those having the prefix
! 6270: \kbd{plotrecth} put in the rectwindow a large batch of rect objects
! 6271: corresponding to the output of the related \kbd{ploth} function.
! 6272:
! 6273: Finally, the actual physical drawing is done using the function
! 6274: \kbd{plotdraw}. Note that the windows are preserved so that further drawings
! 6275: using the same windows at different positions or different windows can be
! 6276: done without extra work. If you want to erase a window (and free the
! 6277: corresponding memory), use the function \kbd{plotkill}. It is not possible to
! 6278: partially erase a window. Erase it completely, initialize it again and then
! 6279: fill it with the graphic objects that you want to keep.
! 6280:
! 6281: In addition to initializing the window, you may want to have a scaled
! 6282: window to avoid unnecessary conversions. For this, use the function
! 6283: \kbd{plotscale} below. As long as this function is not called, the scaling is
! 6284: simply the number of pixels, the origin being at the upper left and the
! 6285: $y$-coordinates going downwards.
! 6286:
! 6287: Note that in the present version \vers\ all these plotting functions
! 6288: (both low and high level) have been written for the X11-window system
! 6289: (hence also for GUI's based on X11 such as Openwindows and Motif) only,
! 6290: though very little code remains which is actually platform-dependent. A
! 6291: Suntools/Sunview, Macintosh, and an Atari/Gem port were provided for
! 6292: previous versions. These \var{may} be adapted in future releases.
! 6293:
! 6294: Under X11/Suntools, the physical window (opened by \kbd{plotdraw} or any
! 6295: of the \kbd{ploth*} functions) is completely separated from GP (technically,
! 6296: a \kbd{fork} is done, and the non-graphical memory is immediately freed in
! 6297: the child process), which means you can go on working in the current GP
! 6298: session, without having to kill the window first. Under X11, this window can
! 6299: be closed, enlarged or reduced using the standard window manager functions.
! 6300: No zooming procedure is implemented though (yet).
! 6301:
! 6302: $\bullet$ Finally, note that in the same way that \kbd{printtex} allows you
! 6303: to have a \TeX\ output corresponding to printed results, the functions
! 6304: starting with \kbd{ps} allow you to have \tet{PostScript} output of the
! 6305: plots. This will not be absolutely identical with the screen output, but will
! 6306: be sufficiently close. Note that you can use PostScript output even if you do
! 6307: not have the plotting routines enabled. The PostScript output is written in a
! 6308: file whose name is derived from the \tet{psfile} default (\kbd{./pari.ps} if
! 6309: you did not tamper with it). Each time a new PostScript output is asked for,
! 6310: the PostScript output is appended to that file. Hence the user must remove
! 6311: this file, or change the value of \kbd{psfile}, first if he does not want
! 6312: unnecessary drawings from preceding sessions to appear. On the other hand, in
! 6313: this manner as many plots as desired can be kept in a single file. \smallskip
! 6314:
! 6315: {\it None of the graphic functions are available within the PARI library, you
! 6316: must be under GP to use them}. The reason for that is that you really should
! 6317: not use PARI for heavy-duty graphical work, there are much better specialized
! 6318: alternatives around. This whole set of routines was only meant as a
! 6319: convenient, but simple-minded, visual aid. If you really insist on using
! 6320: these in your program (we warned you), the source (\kbd{plot*.c}) should be
! 6321: readable enough for you to achieve something.
! 6322:
! 6323: \subsecidx{plot}$(X=a,b,\var{expr},\{\var{Ymin}\},\{\var{Ymax}\})$: crude
! 6324: (ASCII) plot of the function represented by expression \var{expr} from
! 6325: $a$ to $b$, with \var{Y} ranging from \var{Ymin} to \var{Ymax}. If
! 6326: \var{Ymin} (resp. \var{Ymax}) is not given, the minima (resp. the
! 6327: maxima) of the computed values of the expression is used instead.
! 6328:
! 6329: \subsecidx{plotbox}$(w,x2,y2)$: let $(x1,y1)$ be the current position of the
! 6330: virtual cursor. Draw in the rectwindow $w$ the outline of the rectangle which
! 6331: is such that the points $(x1,y1)$ and $(x2,y2)$ are opposite corners. Only
! 6332: the part of the rectangle which is in $w$ is drawn. The virtual cursor does
! 6333: \var{not} move.
! 6334:
! 6335: \subsecidx{plotclip}$(w)$: `clips' the content of rectwindow $w$, i.e
! 6336: remove all parts of the drawing that would not be visible on the screen.
! 6337: Together with \tet{plotcopy} this function enables you to draw on a
! 6338: scratchpad before commiting the part you're interested in to the final
! 6339: picture.
! 6340:
! 6341: \subsecidx{plotcolor}$(w,c)$: set default color to $c$ in rectwindow $w$.
! 6342: In present version \vers, this is only implemented for X11 window system,
! 6343: and you only have the following palette to choose from:
! 6344:
! 6345: 1=black, 2=blue, 3=sienna, 4=red, 5=cornsilk, 6=grey, 7=gainsborough.
! 6346:
! 6347: Note that it should be fairly easy for you to hardwire some more colors by
! 6348: tweaking the files \kbd{rect.h} and \kbd{plotX.c}. User-defined
! 6349: colormaps would be nice, and \var{may} be available in future versions.
! 6350:
! 6351: \subsecidx{plotcopy}$(w1,w2,dx,dy)$: copy the contents of rectwindow
! 6352: $w1$ to rectwindow $w2$, with offset $(dx,dy)$.
! 6353:
! 6354: \subsecidx{plotcursor}$(w)$: give as a 2-component vector the current
! 6355: (scaled) position of the virtual cursor corresponding to the rectwindow $w$.
! 6356:
! 6357: \subsecidx{plotdraw}$(list)$: physically draw the rectwindows given in $list$
! 6358: which must be a vector whose number of components is divisible by 3. If
! 6359: $list=[w1,x1,y1,w2,x2,y2,\dots]$, the windows $w1$, $w2$, etc.~are
! 6360: physically placed with their upper left corner at physical position
! 6361: $(x1,y1)$, $(x2,y2)$,\dots\ respectively, and are then drawn together.
! 6362: Overlapping regions will thus be drawn twice, and the windows are considered
! 6363: transparent. Then display the whole drawing in a special window on your
! 6364: screen.
! 6365:
! 6366: \subsecidx{plotfile}$(s)$: set the output file for plotting output. Special
! 6367: filename \kbd{-} redirects to the same place as PARI output.
! 6368:
! 6369: \subsecidx{ploth}$(X=a,b,\var{expr},\{\fl=0\},\{n=0\})$: high precision
! 6370: plot of the function $y=f(x)$ represented by the expression \var{expr}, $x$
! 6371: going from $a$ to $b$. This opens a specific window (which is killed
! 6372: whenever you click on it), and returns a four-component vector giving the
! 6373: coordinates of the bounding box in the form
! 6374: $[\var{xmin},\var{xmax},\var{ymin},\var{ymax}]$.
! 6375:
! 6376: \misctitle{Important note}: Since this may involve a lot of function calls,
! 6377: it is advised to keep the current precision to a minimum (e.g.~9) before
! 6378: calling this function.
! 6379:
! 6380: $n$ specifies the number of reference point on the graph (0 means use the
! 6381: hardwired default values, that is: 1000 for general plot, 1500 for
! 6382: parametric plot, and 15 for recursive plot).
! 6383:
! 6384: If no $\fl$ is given, \var{expr} is either a scalar expression $f(X)$, in which
! 6385: case the plane curve $y=f(X)$ will be drawn, or a vector
! 6386: $[f_1(X),\dots,f_k(X)]$, and then all the curves $y=f_i(X)$ will be drawn in
! 6387: the same window.
! 6388:
! 6389: \noindent The binary digits of $\fl$ mean:
! 6390:
! 6391: $\bullet$ 1: \tev{parametric plot}. Here \var{expr} must be a vector with
! 6392: an even number of components. Successive pairs are then understood as the
! 6393: parametric coordinates of a plane curve. Each of these are then drawn.
! 6394:
! 6395: For instance:
! 6396:
! 6397: \kbd{ploth(X=0,2*Pi,[sin(X),cos(X)],1)} will draw a circle.
! 6398:
! 6399: \kbd{ploth(X=0,2*Pi,[sin(X),cos(X)])} will draw two entwined sinusoidal
! 6400: curves.
! 6401:
! 6402: \kbd{ploth(X=0,2*Pi,[X,X,sin(X),cos(X)],1)} will draw a circle and the line
! 6403: $y=x$.
! 6404:
! 6405:
! 6406: $\bullet$ 2: \tev{recursive plot}. If this flag is set, only \var{one}
! 6407: curve can be drawn at time, i.e.~\var{expr} must be either a two-component
! 6408: vector (for a single parametric curve, and the parametric flag \var{has} to
! 6409: be set), or a scalar function. The idea is to choose pairs of successive
! 6410: reference points, and if their middle point is not too far away from the
! 6411: segment joining them, draw this as a local approximation to the curve.
! 6412: Otherwise, add the middle point to the reference points. This is very fast,
! 6413: and usually more precise than usual plot. Compare the results of
! 6414: $$\kbd{ploth(X=-1,1,sin(1/X),2)}\quad
! 6415: \text{and}\quad\kbd{ploth(X=-1,1,sin(1/X))}$$
! 6416: for instance. But beware that if you are extremely unlucky, or choose too few
! 6417: reference points, you may draw some nice polygon bearing little resemblance
! 6418: to the original curve. For instance you should \var{never} plot recursively
! 6419: an odd function in a symmetric interval around 0. Try
! 6420: \bprog
! 6421: ploth(x = -20, 20, sin(x), 2)
! 6422: @eprog
! 6423: \noindent to see why. Hence, it's usually a good idea to try and plot the same
! 6424: curve with slightly different parameters.
! 6425:
! 6426: The other values toggle various display options:
! 6427:
! 6428: $\bullet$ 4: do not rescale plot according to the computed extrema. This is
! 6429: meant to be used when graphing multiple functions on a rectwindow (as a
! 6430: \tet{plotrecth} call), in conjuction with \tet{plotscale}.
! 6431:
! 6432: $\bullet$ 8: do not print the $x$-axis.
! 6433:
! 6434: $\bullet$ 16: do not print the $y$-axis.
! 6435:
! 6436: $\bullet$ 32: do not print frame.
! 6437:
! 6438: $\bullet$ 64: only plot reference points, do not join them.
! 6439:
! 6440: $\bullet$ 256: use splines to interpolate the points.
! 6441:
! 6442: $\bullet$ 512: plot no $x$-ticks.
! 6443:
! 6444: $\bullet$ 1024: plot no $y$-ticks.
! 6445:
! 6446: $\bullet$ 2048: plot all ticks with the same length.
! 6447:
! 6448: \subsecidx{plothraw}$(\var{listx},\var{listy},\{\fl=0\})$: given
! 6449: \var{listx} and \var{listy} two vectors of equal length, plots (in high
! 6450: precision) the points whose $(x,y)$-coordinates are given in \var{listx}
! 6451: and \var{listy}. Automatic positioning and scaling is done, but with the
! 6452: same scaling factor on $x$ and $y$. If $\fl$ is 1, join points, other non-0
! 6453: flags toggle display options and should be combinations of bits $2^k$, $k
! 6454: \geq 3$ as in \kbd{ploth}.
! 6455:
! 6456: \subsecidx{plothsizes}$()$: return data corresponding to the output window
! 6457: in the form of a 6-component vector: window width and height, sizes for ticks
! 6458: in horizontal and vertical directions (this is intended for the \kbd{gnuplot}
! 6459: interface and is currently not significant), width and height of characters.
! 6460:
! 6461: \subsecidx{plotinit}$(w,x,y,\{\fl\})$: initialize the rectwindow $w$,
! 6462: destroying any rect objects you may have already drawn in $w$. The virtual
! 6463: cursor is set to $(0,0)$. The rectwindow size is set to width $x$ and height
! 6464: $y$. If $\fl=0$, $x$ and $y$ represent pixel units. Otherwise, $x$ and $y$
! 6465: are understood as fractions of the size of the current output device (hence
! 6466: must be between $0$ and $1$) and internally converted to pixels.
! 6467:
! 6468: The plotting device imposes an upper bound for $x$ and $y$, for instance the
! 6469: number of pixels for screen output. These bounds are available through the
! 6470: \tet{plothsizes} function. The following sequence initializes in a portable
! 6471: way (i.e independant of the output device) a window of maximal size, accessed
! 6472: through coordinates in the $[0,1000] \times [0,1000]$ range~:
! 6473:
! 6474: \bprog
! 6475: s = plothsizes();
! 6476: plotinit(0, s[1]-1, s[2]-1);
! 6477: plotscale(0, 0,1000, 0,1000);
! 6478: @eprog
! 6479:
! 6480: \subsecidx{plotkill}$(w)$: erase rectwindow $w$ and free the corresponding
! 6481: memory. Note that if you want to use the rectwindow $w$ again, you have to
! 6482: use \kbd{initrect} first to specify the new size. So it's better in this case
! 6483: to use \kbd{initrect} directly as this throws away any previous work in the
! 6484: given rectwindow.
! 6485:
! 6486: \subsecidx{plotlines}$(w,X,Y,\{\fl=0\})$: draw on the rectwindow $w$
! 6487: the polygon such that the (x,y)-coordinates of the vertices are in the
! 6488: vectors of equal length $X$ and $Y$. For simplicity, the whole
! 6489: polygon is drawn, not only the part of the polygon which is inside the
! 6490: rectwindow. If $\fl$ is non-zero, close the polygon. In any case, the
! 6491: virtual cursor does not move.
! 6492:
! 6493: $X$ and $Y$ are allowed to be scalars (in this case, both have to).
! 6494: There, a single segment will be drawn, between the virtual cursor current
! 6495: position and the point $(X,Y)$. And only the part thereof which
! 6496: actually lies within the boundary of $w$. Then \var{move} the virtual cursor
! 6497: to $(X,Y)$, even if it is outside the window. If you want to draw a
! 6498: line from $(x1,y1)$ to $(x2,y2)$ where $(x1,y1)$ is not necessarily the
! 6499: position of the virtual cursor, use \kbd{plotmove(w,x1,y1)} before using this
! 6500: function.
! 6501:
! 6502: \subsecidx{plotlinetype}$(w,\var{type})$: change the type of lines
! 6503: subsequently plotted in rectwindow $w$. \var{type} $-2$ corresponds to
! 6504: frames, $-1$ to axes, larger values may correspond to something else. $w =
! 6505: -1$ changes highlevel plotting. This is only taken into account by the
! 6506: \kbd{gnuplot} interface.
! 6507:
! 6508: \subsecidx{plotmove}$(w,x,y)$: move the virtual cursor of the rectwindow $w$
! 6509: to position $(x,y)$.
! 6510:
! 6511: \subsecidx{plotpoints}$(w,X,Y)$: draw on the rectwindow $w$ the
! 6512: points whose $(x,y)$-coordinates are in the vectors of equal length $X$ and
! 6513: $Y$ and which are inside $w$. The virtual cursor does \var{not} move. This
! 6514: is basically the same function as \kbd{plothraw}, but either with no scaling
! 6515: factor or with a scale chosen using the function \kbd{plotscale}.
! 6516:
! 6517: As was the case with the \kbd{plotlines} function, $X$ and $Y$ are allowed to
! 6518: be (simultaneously) scalar. In this case, draw the single point $(X,Y)$ on
! 6519: the rectwindow $w$ (if it is actually inside $w$), and in any case
! 6520: \var{move} the virtual cursor to position $(x,y)$.
! 6521:
! 6522: \subsecidx{plotpointsize}$(w,size)$: changes the ``size'' of following
! 6523: points in rectwindow $w$. If $w = -1$, change it in all rectwindows.
! 6524: This only works in the \kbd{gnuplot} interface.
! 6525:
! 6526: \subsecidx{plotpointtype}$(w,\var{type})$: change the type of
! 6527: points subsequently plotted in rectwindow $w$. $\var{type} = -1$
! 6528: corresponds to a dot, larger values may correspond to something else. $w = -1$
! 6529: changes highlevel plotting. This is only taken into account by the
! 6530: \kbd{gnuplot} interface.
! 6531:
! 6532: \subsecidx{plotrbox}$(w,dx,dy)$: draw in the rectwindow $w$ the outline of
! 6533: the rectangle which is such that the points $(x1,y1)$ and $(x1+dx,y1+dy)$ are
! 6534: opposite corners, where $(x1,y1)$ is the current position of the cursor.
! 6535: Only the part of the rectangle which is in $w$ is drawn. The virtual cursor
! 6536: does \var{not} move.
! 6537:
! 6538: \subsecidx{plotrecth}$(w,X=a,b,\var{expr},\{\fl=0\},\{n=0\})$: writes to
! 6539: rectwindow $w$ the curve output of \kbd{ploth}$(w,X=a,b,\var{expr},\fl,n)$.
! 6540:
! 6541: \subsecidx{plotrecthraw}$(w,\var{data},\{\fl=0\})$: plot graph(s) for
! 6542: \var{data} in rectwindow $w$. $\fl$ has the same significance here as in
! 6543: \kbd{ploth}, though recursive plot is no more significant.
! 6544:
! 6545: \var{data} is a vector of vectors, each corresponding to a list a coordinates.
! 6546: If parametric plot is set, there must be an even number of vectors, each
! 6547: successive pair corresponding to a curve. Otherwise, the first one containe
! 6548: the $x$ coordinates, and the other ones contain the $y$-coordinates
! 6549: of curves to plot.
! 6550:
! 6551: \subsecidx{plotrline}$(w,dx,dy)$: draw in the rectwindow $w$ the part of the
! 6552: segment $(x1,y1)-(x1+dx,y1+dy)$ which is inside $w$, where $(x1,y1)$ is the
! 6553: current position of the virtual cursor, and move the virtual cursor to
! 6554: $(x1+dx,y1+dy)$ (even if it is outside the window).
! 6555:
! 6556: \subsecidx{plotrmove}$(w,dx,dy)$: move the virtual cursor of the rectwindow
! 6557: $w$ to position $(x1+dx,y1+dy)$, where $(x1,y1)$ is the initial position of
! 6558: the cursor (i.e.~to position $(dx,dy)$ relative to the initial cursor).
! 6559:
! 6560: \subsecidx{plotrpoint}$(w,dx,dy)$: draw the point $(x1+dx,y1+dy)$ on the
! 6561: rectwindow $w$ (if it is inside $w$), where $(x1,y1)$ is the current position
! 6562: of the cursor, and in any case move the virtual cursor to position
! 6563: $(x1+dx,y1+dy)$.
! 6564:
! 6565: \subsecidx{plotscale}$(w,x1,x2,y1,y2)$: scale the local coordinates of the
! 6566: rectwindow $w$ so that $x$ goes from $x1$ to $x2$ and $y$ goes from $y1$ to
! 6567: $y2$ ($x2<x1$ and $y2<y1$ being allowed). Initially, after the initialization
! 6568: of the rectwindow $w$ using the function \kbd{plotinit}, the default scaling
! 6569: is the graphic pixel count, and in particular the $y$ axis is oriented
! 6570: downwards since the origin is at the upper left. The function \kbd{plotscale}
! 6571: allows to change all these defaults and should be used whenever functions are
! 6572: graphed.
! 6573:
! 6574: \subsecidx{plotstring}$(w,x,\{\fl=0\})$: draw on the rectwindow $w$ the
! 6575: String $x$ (see \secref{se:strings}), at the current position of the cursor.
! 6576:
! 6577: \fl\ is used for justification: bits 1 and 2 regulate horizontal alignment:
! 6578: left if 0, right if 2, center if 1. Bits 4 and 8 regulate vertical
! 6579: alignment: bottom if 0, top if 8, v-center if 4. Can insert additional
! 6580: small gap between point and string: horizontal if bit 16 is set, vertical
! 6581: if bit 32 is set (see the tutorial for an example).
! 6582:
! 6583: \subsecidx{plotterm}$(\var{term})$: sets terminal where high resolution
! 6584: plots go (this is currently only taken into account by the \kbd{gnuplot}
! 6585: graphical driver). Using the \kbd{gnuplot} driver, possible terminals are
! 6586: the same as in gnuplot. If \var{term} is "?", lists possible values.
! 6587:
! 6588: Terminal options can be appended to the terminal name and space; terminal
! 6589: size can be put immediately after the name, as in \kbd{"gif=300,200"}.
! 6590: Positive return value means success.
! 6591:
! 6592: \subsecidx{psdraw}$(\var{list})$: same as \kbd{plotdraw}, except that the
! 6593: output is a PostScript program appended to the \kbd{psfile}.
! 6594:
! 6595: \subsecidx{psploth}$(X=a,b,\var{expr})$: same as \kbd{ploth}, except that the
! 6596: output is a PostScript program appended to the \kbd{psfile}.
! 6597:
! 6598: \subsecidx{psplothraw}$(\var{listx},\var{listy})$: same as \kbd{plothraw},
! 6599: except that the output is a PostScript program appended to the \kbd{psfile}.
! 6600:
! 6601: \section{Programming under GP}
! 6602: \sidx{programming}\label{se:programming}
! 6603: \subsecidx{Control statements}.
! 6604:
! 6605: A number of control statements are available under GP. They are simpler and
! 6606: have a syntax slightly different from their C counterparts, but are quite
! 6607: powerful enough to write any kind of program. Some of them are specific to
! 6608: GP, since they are made for number theorists. As usual, $X$ will denote any
! 6609: simple variable name, and \var{seq} will always denote a sequence of
! 6610: expressions, including the empty sequence.
! 6611:
! 6612: \subsubsecidx{break}$(\{n=1\})$: interrupts execution of current \var{seq}, and
! 6613: immediately exits from the $n$ innermost enclosing loops, within the
! 6614: current function call (or the top level loop). $n$ must be bigger than 1.
! 6615: If $n$ is greater than the number of enclosing loops, all enclosing loops
! 6616: are exited.
! 6617:
! 6618: \subsubsecidx{for}$(X=a,b,\var{seq})$: the formal variable $X$ going from
! 6619: $a$ to $b$, the \var{seq} is evaluated. Nothing is done if $a>b$.
! 6620: $a$ and $b$ must be in $\R$.
! 6621:
! 6622: \subsubsecidx{fordiv}$(n,X,\var{seq})$: the formal variable $X$ ranging
! 6623: through the positive divisors of $n$, the sequence \var{seq} is evaluated.
! 6624: $n$ must be of type integer.
! 6625:
! 6626: \subsubsecidx{forprime}$(X=a,b,\var{seq})$: the formal variable $X$
! 6627: ranging over the prime numbers between $a$ to $b$ (including $a$ and $b$
! 6628: if they are prime), the \var{seq} is evaluated. More precisely, the value
! 6629: of $X$ is incremented to the smallest prime strictly larger than $X$ at the
! 6630: end of each iteration. Nothing is done if $a>b$. Note that $a$ and $b$ must
! 6631: be in $\R$.
! 6632:
! 6633: \bprog
! 6634: ? { forprime(p = 2, 12,
! 6635: print(p);
! 6636: if (p == 3, p = 6);
! 6637: )
! 6638: }
! 6639: 2
! 6640: 3
! 6641: 7
! 6642: 11
! 6643: @eprog
! 6644:
! 6645: \subsubsecidx{forstep}$(X=a,b,s,\var{seq})$: the formal variable $X$
! 6646: going from $a$ to $b$, in increments of $s$, the \var{seq} is evaluated.
! 6647: Nothing is done if $s>0$ and $a>b$ or if $s<0$ and $a<b$. $s$ must be in
! 6648: $\R^*$ or a vector of steps $[s_1,\dots,s_n]$. In the latter case, the
! 6649: successive steps are used in the order they appear in $s$.
! 6650:
! 6651: \bprog
! 6652: ? forstep(x=5, 20, [2,4], print(x))
! 6653: 5
! 6654: 7
! 6655: 11
! 6656: 13
! 6657: 17
! 6658: 19
! 6659: @eprog
! 6660:
! 6661: \subsubsecidx{forsubgroup}$(H=G,\{B\},\var{seq})$: executes \var{seq} for
! 6662: each subgroup $H$ of the \var{abelian} group $G$ (given in
! 6663: SNF\sidx{Smith normal form} form or as a vector of elementary divisors),
! 6664: whose index is bounded by $B$. The subgroups are not ordered in any
! 6665: obvious way, unless $G$ is a $p$-group in which case Birkhoff's algorithm
! 6666: produces them by decreasing index. A \idx{subgroup} is given as a matrix
! 6667: whose columns give its generators on the implicit generators of $G$. For
! 6668: example, the following prints all subgroups of index less than 2 in $G =
! 6669: \Z/2\Z g_1 \times \Z/2\Z g_2$~:
! 6670:
! 6671: \bprog
! 6672: ? G = [2,2]; forsubgroup(H=G, 2, print(H))
! 6673: [1; 1]
! 6674: [1; 2]
! 6675: [2; 1]
! 6676: [1, 0; 1, 1]
! 6677: @eprog
! 6678: The last one, for instance is generated by $(g_1, g_1 + g_2)$. This
! 6679: routine is intended to treat huge groups, when \tet{subgrouplist} is not an
! 6680: option due to the sheer size of the output.
! 6681:
! 6682: For maximal speed the subgroups have been left as produced by the algorithm.
! 6683: To print them in canonical form (as left divisors of $G$ in
! 6684: HNF\sidx{Hermite normal form} form), one can for instance use
! 6685: \bprog
! 6686: ? G = matdiagonal([2,2]); forsubgroup(H=G, 2, print(mathnf(concat(G,H))))
! 6687: [2, 1; 0, 1]
! 6688: [1, 0; 0, 2]
! 6689: [2, 0; 0, 1]
! 6690: [1, 0; 0, 1]
! 6691: @eprog
! 6692: Note that in this last representation, the index $[G:H]$ is given by the
! 6693: determinant. See \tet{galoissubcyclo} and \tet{galoisfixedfield} for
! 6694: \tet{nfsubfields} applications to \idx{Galois} theory.
! 6695:
! 6696: \subsubsecidx{forvec}$(X=v,\var{seq},\{\fl=0\})$: $v$ being an $n$-component
! 6697: vector (where $n$ is arbitrary) of two-component vectors $[a_i,b_i]$
! 6698: for $1\le i\le n$, the \var{seq} is evaluated with the formal variable
! 6699: $X[1]$ going from $a_1$ to $b_1$,\dots,$X[n]$ going from $a_n$ to $b_n$.
! 6700: The formal variable with the highest index moves the fastest. If $\fl=1$,
! 6701: generate only nondecreasing vectors $X$, and if $\fl=2$, generate only
! 6702: strictly increasing vectors $X$.
! 6703:
! 6704: \subsubsecidx{if}$(a,\{\var{seq1}\},\{\var{seq2}\})$: if $a$ is non-zero,
! 6705: the expression sequence \var{seq1} is evaluated, otherwise the expression
! 6706: \var{seq2} is evaluated. Of course, \var{seq1} or \var{seq2} may be empty,
! 6707: so \kbd{if ($a$,\var{seq})} evaluates \var{seq} if $a$ is not equal to zero
! 6708: (you don't have to write the second comma), and does nothing otherwise,
! 6709: whereas \kbd{if ($a$,,\var{seq})} evaluates \var{seq} if $a$ is equal to
! 6710: zero, and does nothing otherwise. You could get the same result using
! 6711: the \kbd{!} (\kbd{not}) operator: \kbd{if (!$a$,\var{seq})}.
! 6712:
! 6713: Note that the boolean operators \kbd{\&\&} and \kbd{||} are evaluated
! 6714: according to operator precedence as explained in \secref{se:operators}, but
! 6715: that, contrary to other operators, the evaluation of the arguments is
! 6716: stopped as soon as the final truth value has been determined. For instance
! 6717: \bprog
! 6718: if (reallydoit && longcomplicatedfunction(), ...)%
! 6719: @eprog
! 6720: \noindent is a perfectly safe statement.
! 6721:
! 6722: Recall that functions such as \kbd{break} and \kbd{next} operate on
! 6723: \var{loops} (such as \kbd{for$xxx$}, \kbd{while}, \kbd{until}). The \kbd{if}
! 6724: statement is \var{not} a loop (obviously!).
! 6725:
! 6726: \subsubsecidx{next}$(\{n=1\})$: interrupts execution of current $seq$,
! 6727: resume the next iteration of the innermost enclosing loop, within the
! 6728: current fonction call (or top level loop). If $n$ is specified, resume at
! 6729: the $n$-th enclosing loop. If $n$ is bigger than the number of enclosing
! 6730: loops, all enclosing loops are exited.
! 6731:
! 6732: \subsubsecidx{return}$(\{x=0\})$: returns from current subroutine, with
! 6733: result $x$.
! 6734:
! 6735: \subsubsecidx{until}$(a,\var{seq})$: evaluates expression sequence \var{seq}
! 6736: until $a$ is not equal to 0 (i.e.~until $a$ is true). If $a$ is initially
! 6737: not equal to 0, \var{seq} is evaluated once (more generally, the condition
! 6738: on $a$ is tested \var{after} execution of the \var{seq}, not before as in
! 6739: \kbd{while}).
! 6740:
! 6741: \subsubsecidx{while}$(a,\var{seq})$: while $a$ is non-zero evaluate the
! 6742: expression sequence \var{seq}. The test is made \var{before} evaluating
! 6743: the $seq$, hence in particular if $a$ is initially equal to zero the
! 6744: \var{seq} will not be evaluated at all.\smallskip
! 6745:
! 6746: \subsec{Specific functions used in GP programming}.
! 6747: \label{se:gp_program}
! 6748:
! 6749: In addition to the general PARI functions, it is necessary to have some
! 6750: functions which will be of use specifically for GP, though a few of these can
! 6751: be accessed under library mode. Before we start describing these, we recall
! 6752: the difference between \var{strings} and \var{keywords} (see
! 6753: \secref{se:strings}): the latter don't get expanded at all, and you can type
! 6754: them without any enclosing quotes. The former are dynamic objects, where
! 6755: everything outside quotes gets immediately expanded.
! 6756:
! 6757: We need an additional notation for this chapter. An argument between braces,
! 6758: followed by a star, like $\{\var{str}\}*$, means that any number of such
! 6759: arguments (possibly none) can be given.
! 6760:
! 6761: \subsubsecidx{addhelp}$(S,\var{str})$:\label{se:addhelp} changes the help
! 6762: message for the symbol $S$. The string \var{str} is expanded on the spot
! 6763: and stored as the online help for $S$. If $S$ is a function \var{you} have
! 6764: defined, its definition will still be printed before the message \var{str}.
! 6765: It is recommended that you document global variables and user functions in
! 6766: this way. Of course GP won't protest if you don't do it.
! 6767:
! 6768: There's nothing to prevent you from modifying the help of built-in PARI
! 6769: functions (but if you do, we'd like to hear why you needed to do it!).
! 6770:
! 6771: \subsubsecidx{alias}$(\var{newkey},\var{key})$: defines the keyword
! 6772: \var{newkey} as an alias for keyword \var{key}. \var{key} must correspond
! 6773: to an existing \var{function} name. This is different from the general user
! 6774: macros in that alias expansion takes place immediately upon execution,
! 6775: without having to look up any function code, and is thus much faster. A
! 6776: sample alias file \kbd{misc/gpalias} is provided with the standard
! 6777: distribution. Alias commands are meant to be read upon startup from the
! 6778: \kbd{.gprc} file, to cope with function names you are dissatisfied with, and
! 6779: should be useless in interactive usage.
! 6780:
! 6781: \subsubsecidx{allocatemem}$(\{x=0\})$: this is a very special operation which
! 6782: allows the user to change the stack size \var{after} initialization. $x$
! 6783: must be a non-negative integer. If $x!=0$, a new stack of size $16*\lceil
! 6784: x/16\rceil$ bytes will be allocated, all the PARI data on the old stack will
! 6785: be moved to the new one, and the old stack will be discarded. If $x=0$, the
! 6786: size of the new stack will be twice the size of the old one.
! 6787:
! 6788: Although it is a function, this must be the \var{last} instruction in any GP
! 6789: sequence. The technical reason is that this routine usually moves the stack,
! 6790: so objects from the current sequence might not be correct anymore. Hence, to
! 6791: prevent such problems, this routine terminates by a \kbd{longjmp} (just as an
! 6792: error would) and not by a return.
! 6793:
! 6794: \syn{allocatemoremem}{x}, where $x$ is an unsigned long, and the return type
! 6795: is void. GP uses a variant which ends by a \kbd{longjmp}.
! 6796:
! 6797: \subsubsecidx{default}$(\{\var{key}\},\{\var{val}\},\{\fl\})$: sets the default
! 6798: corresponding to keyword \var{key} to value \var{val}. \var{val} is a string
! 6799: (which of course accepts numeric arguments without adverse effects, due to the
! 6800: expansion mechanism). See \secref{se:defaults} for a list of available
! 6801: defaults, and \secref{se:meta} for some shortcut alternatives. Typing
! 6802: \kbd{default()} (or \b{d}) yields the complete default list as well as
! 6803: their current values.\label{se:default}
! 6804:
! 6805: If \var{val} is omitted, prints the current value of default \var{key}.
! 6806: If $\fl$ is set, returns the result instead of printing it.
! 6807:
! 6808: \subsubsecidx{error}$(\{\var{str}\}*)$: outputs its argument list (each of
! 6809: them interpreted as a string), then interrupts the running GP program,
! 6810: returning to the input prompt.
! 6811:
! 6812: Example: \kbd{error("n = ", n, " is not squarefree !")}.
! 6813:
! 6814: Note that, due to the automatic concatenation of strings, you could in fact
! 6815: use only one argument, just by suppressing the commas.
! 6816:
! 6817: \subsubsecidxunix{extern}$(\var{str})$: the string \var{str} is the name
! 6818: of an external command (i.e.~one you would type from your UNIX shell prompt).
! 6819: This command is immediately run and its input fed into GP, just as if read
! 6820: from a file.
! 6821:
! 6822: \subsubsecidx{getheap}$()$: returns a two-component row vector giving the
! 6823: number of objects on the heap and the amount of memory they occupy in long
! 6824: words. Useful mainly for debugging purposes.
! 6825:
! 6826: \syn{getheap}{}.
! 6827:
! 6828: \subsubsecidx{getrand}$()$: returns the current value of the random number
! 6829: seed. Useful mainly for debugging purposes.
! 6830:
! 6831: \syn{getrand}{}, returns a C long.
! 6832:
! 6833: \subsubsecidx{getstack}$()$: returns the current value of
! 6834: \kbd{top${}-{}$avma},
! 6835: i.e.~the number of bytes used up to now on the stack. Should be equal to 0
! 6836: in between commands. Useful mainly for debugging purposes.
! 6837:
! 6838: \syn{getstack}{}, returns a C long.
! 6839:
! 6840: \subsubsecidx{gettime}$()$: returns the time (in milliseconds) elapsed since
! 6841: either the last call to \kbd{gettime}, or to the beginning of the containing
! 6842: GP instruction (if inside GP), whichever came last.
! 6843:
! 6844: \syn{gettime}{}, returns a C long.
! 6845:
! 6846: \subsubsecidx{global}$(\{\hbox{\it list of variables}\})$: \label{se:global}
! 6847: declares the corresponding variables to be global. From now on, you will be
! 6848: forbidden to use them as formal parameters for function definitions or as
! 6849: loop indexes. This is especially useful when patching together various
! 6850: scripts, possibly written with different naming conventions. For instance the
! 6851: following situation is dangerous:
! 6852: %
! 6853: \bprog
! 6854: p = 3 \\@com fix characteristic
! 6855: ...
! 6856: forprime(p = 2, N, ...)
! 6857: f(p) = ...
! 6858: @eprog
! 6859: since within the loop or within the function's body (even worse: in the
! 6860: subroutines called in that scope), the true global value of \kbd{p} will be
! 6861: hidden. If the statement \kbd{global(p = 3)} appears at the beginning of
! 6862: the script, then both expressions will trigger syntax errors.
! 6863:
! 6864: Calling \kbd{global} without arguments prints the list of global variables in
! 6865: use. In particular, \kbd{eval(global)} will output the values of all local
! 6866: variables.
! 6867:
! 6868: \subsubsecidx{input}$()$: reads a string, interpreted as a GP expression,
! 6869: from the input file, usually standard input (i.e.~the keyboard). If a
! 6870: sequence of expressions is given, the result is the result of the last
! 6871: expression of the sequence. When using this instruction, it is useful to
! 6872: prompt for the string by using the \kbd{print1} function. Note that in the
! 6873: present version 2.19 of \kbd{pari.el}, when using GP under GNU Emacs (see
! 6874: \secref{se:emacs}) one \var{must} prompt for the string, with a string
! 6875: which ends with the same prompt as any of the previous ones (a \kbd{"? "}
! 6876: will do for instance).
! 6877:
! 6878: \subsubsecidxunix{install}$(\var{name},\var{code},\{\var{gpname}\},\{\var{lib}\})$:
! 6879: loads from dynamic library \var{lib} the function \var{name}. Assigns to it
! 6880: the name \var{gpname} in this GP session, with argument code \var{code} (see
! 6881: \secref{se:gp.interface} for an explanation of those). If \var{lib} is
! 6882: omitted, uses \kbd{libpari.so}. If \var{gpname} is omitted, uses
! 6883: \var{name}.\label{se:install}
! 6884:
! 6885: This function is useful for adding custom functions to the GP interpreter,
! 6886: or picking useful functions from unrelated libraries. For instance, it
! 6887: makes the function \tet{system} obsolete:
! 6888:
! 6889: \bprog
! 6890: ? install(system, vs, sys, "libc.so")
! 6891: ? sys("ls gp*")
! 6892: gp.c gp.h gp_rl.c
! 6893: @eprog
! 6894:
! 6895: But it also gives you access to all (non static) functions defined in the
! 6896: PARI library. For instance, the function \kbd{GEN addii(GEN x, GEN y)} adds
! 6897: two PARI integers, and is not directly accessible under GP (it's eventually
! 6898: called by the \kbd{+} operator of course):
! 6899:
! 6900: \bprog
! 6901: ? install("addii", "GG")
! 6902: ? addii(1, 2)
! 6903: %1 = 3
! 6904: @eprog
! 6905:
! 6906: \misctitle{Caution:} This function may not work on all systems, especially
! 6907: when GP has been compiled statically. In that case, the first use of an
! 6908: installed function will provoke a Segmentation Fault, i.e.~a major internal
! 6909: blunder (this should never happen with a dynamically linked executable).
! 6910: Hence, if you intend to use this function, please check first on some
! 6911: harmless example such as the ones above that it works properly on your
! 6912: machine.
! 6913:
! 6914: \subsubsecidx{kill}$(s)$:\label{se:kill} kills the present value of the
! 6915: variable, alias or user-defined function $s$. The corresponding identifier
! 6916: can now be used to name any GP object (variable or function). This is the
! 6917: only way to replace a variable by a function having the same name (or the
! 6918: other way round), as in the following example:
! 6919:
! 6920: \bprog
! 6921: ? f = 1
! 6922: %1 = 1
! 6923: ? f(x) = 0
! 6924: *** unused characters: f(x)=0
! 6925: ^----
! 6926: ? kill(f)
! 6927: ? f(x) = 0
! 6928: ? f()
! 6929: %2 = 0
! 6930: @eprog
! 6931:
! 6932: When you kill a variable, all objects that used it become invalid. You
! 6933: can still display them, even though the killed variable will be printed in a
! 6934: funny way (following the same convention as used by the library function
! 6935: \kbd{fetch\_var}, see~\secref{se:vars}). For example:
! 6936:
! 6937: \bprog
! 6938: ? a^2 + 1
! 6939: %1 = a^2 + 1
! 6940: ? kill(a)
! 6941: ? %1
! 6942: %2 = #<1>^2 + 1
! 6943: @eprog
! 6944:
! 6945: If you simply want to restore a variable to its ``undefined'' value
! 6946: (monomial of degree one), use the \idx{quote} operator: \kbd{a = 'a}.
! 6947: Predefined symbols (\kbd{x} and GP function names) cannot be killed.
! 6948:
! 6949: \subsubsecidx{print}$(\{\var{str}\}*)$: outputs its (string) arguments in raw
! 6950: format, ending with a newline.
! 6951:
! 6952: \subsubsecidx{print1}$(\{\var{str}\}*)$: outputs its (string) arguments in raw
! 6953: format, without ending with a newline (note that you can still embed newlines
! 6954: within your strings, using the \b{n} notation~!).
! 6955:
! 6956: \subsubsecidx{printp}$(\{\var{str}\}*)$: outputs its (string) arguments in
! 6957: prettyprint (beautified) format, ending with a newline.
! 6958:
! 6959: \subsubsecidx{printp1}$(\{\var{str}\}*)$: outputs its (string) arguments in
! 6960: prettyprint (beautified) format, without ending with a newline.
! 6961:
! 6962: \subsubsecidx{printtex}$(\{\var{str}\}*)$: outputs its (string) arguments in
! 6963: \TeX\ format. This output can then be used in a \TeX\ manuscript.
! 6964: The printing is done on the standard output. If you want to print it to a
! 6965: file you should use \kbd{writetex} (see there).
! 6966:
! 6967: Another possibility is to enable the \tet{log} default
! 6968: (see~\secref{se:defaults}).
! 6969: You could for instance do:\sidx{logfile}
! 6970: %
! 6971: \bprog
! 6972: default(logfile, "new.tex");
! 6973: default(log, 1);
! 6974: printtex(result);
! 6975: @eprog
! 6976: \noindent
! 6977: (You can use the automatic string expansion/concatenation process to have
! 6978: dynamic file names if you wish).
! 6979:
! 6980: \subsubsecidx{quit}$()$: exits GP.\label{se:quit}
! 6981:
! 6982: \subsubsecidx{read}$(\{\var{str}\})$: reads in the file whose name results
! 6983: from the expansion of the string \var{str}. If \var{str} is omitted,
! 6984: re-reads the last file that was fed into GP. The return value is the result of
! 6985: the last expression evaluated.\label{se:read} If a GP \tet{binary file} is
! 6986: read using this command (see \secref{se:writebin}), the file is loaded and
! 6987: the last object in the file is returned.
! 6988:
! 6989: \subsubsecidx{reorder}$(\{x=[\,]\})$: $x$ must be a vector. If $x$ is the
! 6990: empty vector, this gives the vector whose components are the existing
! 6991: variables in increasing order (i.e.~in decreasing importance). Killed
! 6992: variables (see \kbd{kill}) will be shown as \kbd{0}. If $x$ is
! 6993: non-empty, it must be a permutation of variable names, and this permutation
! 6994: gives a new order of importance of the variables, {\it for output only}. For
! 6995: example, if the existing order is \kbd{[x,y,z]}, then after
! 6996: \kbd{reorder([z,x])} the order of importance of the variables, with respect
! 6997: to output, will be \kbd{[z,y,x]}. The internal representation is unaffected.
! 6998: \label{se:reorder}
! 6999:
! 7000: \subsubsecidx{setrand}$(n)$: reseeds the random number generator to the value
! 7001: $n$. The initial seed is $n=1$.
! 7002:
! 7003: \syn{setrand}{n}, where $n$ is a \kbd{long}. Returns $n$.
! 7004:
! 7005: \subsubsecidxunix{system}$(\var{str})$: \var{str} is a string representing
! 7006: a system command. This command is executed, its output written to the
! 7007: standard output (this won't get into your logfile), and control returns
! 7008: to the PARI system. This simply calls the C \kbd{system} command.
! 7009:
! 7010: \subsubsecidx{trap}$(\{e\}, \{\var{rec}\}, \{\var{seq}\})$: tries to
! 7011: execute \var{seq}, trapping error $e$, that is effectively preventing it
! 7012: from aborting computations in the usual way; the recovery sequence
! 7013: \var{rec} is executed if the error occurs and the evaluation of \var{rec}
! 7014: becomes the result of the command. If $e$ is omitted, all exceptions are
! 7015: trapped. Note in particular that hitting \kbd{\pow C} (Control-C) raises an
! 7016: exception.
! 7017:
! 7018: \bprog
! 7019: ? \\@com trap division by 0
! 7020: ? inv(x) = trap (gdiver2, INFINITY, 1/x)
! 7021: ? inv(2)
! 7022: %1 = 1/2
! 7023: ? inv(0)
! 7024: %2 = INFINITY
! 7025: @eprog
! 7026:
! 7027: If \var{seq} is omitted, defines \var{rec} as a default action when
! 7028: encountering exception $e$. The error message is printed, as well as the
! 7029: result of the evaluation of \var{rec}, and the control is given back to the
! 7030: GP prompt. In particular, current computation is then lost.
! 7031:
! 7032: The following error handler prints the list of all user variables, then
! 7033: stores in a file their name and their values:
! 7034: \bprog
! 7035: ? { trap( ,
! 7036: print(reorder);
! 7037: write("crash", reorder);
! 7038: write("crash", eval(reorder))) }
! 7039: @eprog
! 7040:
! 7041: If no recovery code is given (\var{rec} is omitted) a so-called
! 7042: {\it\idx{break loop}} will be started. During a break loop, all commands are
! 7043: read and evaluated as during the main GP loop (except that no history of
! 7044: results is kept).
! 7045:
! 7046: To get out of the break loop, you can use \tet{next}, \tet{break} or
! 7047: \tet{return}; reading in a file by \b{r} will also terminate the loop once
! 7048: the file has been read (\kbd{read} will remain in the break loop). If the
! 7049: error is not fatal (\kbd{\pow C} is the only non-fatal error), \kbd{next}
! 7050: will continue the computation as if nothing had happened (except of course,
! 7051: you may have changed GP state during the break loop); otherwise control
! 7052: will come back to the GP prompt. After a user interrupt (\kbd{\pow C}),
! 7053: entering an empty input line (i.e hitting the return key) has the same
! 7054: effect as \kbd{next}.
! 7055:
! 7056: Break loops are useful as a debugging tool to inspect the values of GP
! 7057: variables to understand why a problem occurred, or to change GP behaviour
! 7058: (increase debugging level, start storing results in a logfile, modify
! 7059: parameters\dots) in the middle of a long computation (hit \kbd{\pow C}, type
! 7060: in your modifications, then type \kbd{next}).
! 7061:
! 7062: If \var{rec} is the empty string \kbd{""} the last default handler is popped
! 7063: out, and replaced by the previous one for that error.
! 7064:
! 7065: \misctitle{Note:} The interface is currently not adequate for trapping
! 7066: individual exceptions. In the current version \vers, the following keywords
! 7067: are recognized, but the name list will be expanded and changed in the
! 7068: future (all library mode errors can be trapped: it's a matter of defining
! 7069: the keywords to GP, and there are currently far too many useless ones):
! 7070:
! 7071: \kbd{accurer}: accuracy problem
! 7072:
! 7073: \kbd{gdiver2}: division by 0
! 7074:
! 7075: \kbd{invmoder}: impossible inverse modulo
! 7076:
! 7077: \kbd{archer}: not available on this architecture or operating system
! 7078:
! 7079: \kbd{typeer}: wrong type
! 7080:
! 7081: \kbd{errpile}: the PARI stack overflows
! 7082:
! 7083: \subsubsecidx{type}$(x,\{t\})$: this is useful only under GP. If $t$ is
! 7084: not present, returns the internal type number of the PARI object $x$.
! 7085: Otherwise, makes a copy of $x$ and sets its type equal to type $t$, which
! 7086: can be either a number or, preferably since internal codes may eventually
! 7087: change, a symbolic name such as \typ{FRACN} (you can skip the \typ{}
! 7088: part here, so that \kbd{FRACN} by itself would also be all right). Check out
! 7089: existing type names with the metacommand \b{t}.\label{se:gptype}
! 7090:
! 7091: GP won't let you create meaningless objects in this way where the internal
! 7092: structure doesn't match the type. This function can be useful to create
! 7093: reducible rationals (type \typ{FRACN}) or rational functions (type
! 7094: \typ{RFRACN}). In fact it's the only way to do so in GP. In this case, the
! 7095: created object, as well as the objects created from it, will not be reduced
! 7096: automatically, making some operations a bit faster.
! 7097:
! 7098: There is no equivalent library syntax, since the internal functions \kbd{typ}
! 7099: and \kbd{settyp} are available. Note that \kbd{settyp} does \var{not}
! 7100: create a copy of \kbd{x}, contrary to most PARI functions. It also doesn't
! 7101: check for consistency. \kbd{settyp} just changes the type in place and
! 7102: returns nothing. \kbd{typ} returns a C long integer. Note also the different
! 7103: spellings of the internal functions (\kbd{set})\kbd{typ} and of the GP
! 7104: function \kbd{type}, which is due to the fact that \kbd{type} is a reserved
! 7105: identifier for some C compilers.
! 7106:
! 7107: \subsubsecidx{whatnow}$(\var{key})$: if keyword \var{key} is the name
! 7108: of a function that was present in GP version 1.39.15 or lower, outputs
! 7109: the new function name and syntax, if it changed at all ($387$ out of $560$
! 7110: did).\label{se:whatnow}
! 7111:
! 7112: \subsubsecidx{write}$(\var{filename},\{\var{str}*\})$: writes (appends)
! 7113: to \var{filename} the remaining arguments, and appends a newline (same output
! 7114: as \kbd{print}).\label{se:write}
! 7115:
! 7116: \subsubsecidx{write1}$(\var{filename},\{\var{str}*\})$: writes (appends) to
! 7117: \var{filename} the remaining arguments without a trailing newline
! 7118: (same output as \kbd{print1}).
! 7119:
! 7120: \subsubsecidx{writebin}$(\var{filename},\{x\})$: writes (appends) to
! 7121: \var{filename} the object $x$ in binary format. This format is not human
! 7122: readable, but contains the exact internal structure of $x$, and is much
! 7123: faster to save/load than a string expression, as would be produced by
! 7124: \tet{write}. The binary file format includes a magic number, so that such a
! 7125: file can be recognized and correctly input by the regular \tet{read} or \b{r}
! 7126: function. If saved objects refer to (polynomial) variables that are not
! 7127: defined in the new session, they will be displayed in a funny way (see
! 7128: \secref{se:kill}).
! 7129:
! 7130: If $x$ is omitted, saves all user variables from the session, together with
! 7131: their names. Reading such a ``named object'' back in a GP session will set
! 7132: the corresponding user variable to the saved value. E.g after
! 7133: \bprog
! 7134: x = 1; writebin("log")
! 7135: @eprog
! 7136: \noindent reading \kbd{log} into a clean session will set \kbd{x} to $1$.
! 7137: The relative variables priorities of new variables set in this way remain the
! 7138: same (preset variables retain their former priority, but are set to the new
! 7139: value). In particular, reading such a session log into a clean session will
! 7140: restore all variables exactly as they were in the original one.
! 7141:
! 7142: User functions, installed functions and history objects can not be saved via
! 7143: this function. Just as a regular input file, a binary file can be compressed
! 7144: using \tet{gzip}, provided the file name has the standard \kbd{.gz}
! 7145: extension. \label{se:writebin}\sidx{binary file}
! 7146:
! 7147: \subsubsecidx{writetex}$(\var{filename},\{\var{str}*\})$: as \kbd{write},
! 7148: in \TeX\ format.\label{se:writetex}
! 7149:
! 7150: \vfill\eject
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to usersch3.tex CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM_contrib / pari-2.2 / doc