Annotation of OpenXM_contrib/pari/doc/usersch3.tex, Revision 1.1
1.1 ! maekawa 1: \chapter{Functions and Operations Available in PARI and GP}
! 2: \label{se:functions}
! 3:
! 4: The functions and operators available in PARI and in the GP/PARI calculator
! 5: are numerous and everexpanding. Here is a description of the ones available
! 6: in version \vers. It should be noted that many of these functions accept
! 7: quite different types as arguments, but others are more restricted. The list
! 8: of acceptable types will be given for each function or class of functions.
! 9: Except when stated otherwise, it is understood that a function or operation
! 10: which should make natural sense is legal. In this chapter, we will describe
! 11: the functions according to a rough classification. For the functions in
! 12: alphabetical order, see the general index. The general entry looks something
! 13: like:
! 14:
! 15: \key{foo}$(x,\{\fl=0\})$: short description.
! 16:
! 17: \syn{foo}{x,\fl}.
! 18:
! 19: \noindent
! 20: This means that the GP function \kbd{foo} has one mandatory argument $x$, and
! 21: an optional one, $\fl$, whose default value is 0 (the $\{\}$ should never be
! 22: typed, it is just a convenient notation we will use throughout to denote
! 23: optional arguments). That is, you can type \kbd{foo(x,2)}, or \kbd{foo(x)},
! 24: which is then understood to mean \kbd{foo(x,0)}. As well, a comma or closing
! 25: parenthesis, where an optional argument should have been, signals to GP it
! 26: should use the default. Thus, the syntax \kbd{foo(x,)} is also accepted as a
! 27: synonym for our last expression. When a function has more than one optional
! 28: argument, the argument list is filled with user supplied values, in order.
! 29: And when none are left, the defaults are used instead. Thus, assuming that
! 30: \kbd{foo}'s prototype had been
! 31: $$\hbox{%
! 32: \key{foo}$(\{x=1\},\{y=2\},\{z=3\})$,%
! 33: }$$
! 34: typing in \kbd{foo(6,4)} would give
! 35: you \kbd{foo(6,4,3)}. In the rare case when you want to set some far away
! 36: flag, and leave the defaults in between as they stand, you can use the
! 37: ``empty arg'' trick alluded to above: \kbd{foo(6,,1)} would yield
! 38: \kbd{foo(6,2,1)}. By the way, \kbd{foo()} by itself yields
! 39: \kbd{foo(1,2,3)} as was to be expected. In this rather special case of a
! 40: function having no mandatory argument, you can even omit the $()$: a
! 41: standalone \kbd{foo} would be enough (though we don't really recommend it for
! 42: your scripts, for the sake of clarity). In defining GP syntax, we strove
! 43: to put optional arguments at the end of the argument list (of course, since
! 44: they would not make sense otherwise), and in order of decreasing usefulness
! 45: so that, most of the time, you will be able to ignore them.
! 46:
! 47: For some of these optional flags, we adopted the customary binary notation as
! 48: a compact way to represent many toggles with just one number. Letting
! 49: $(p_0,\dots,p_n)$ be a list of switches (i.e.~of properties which can be
! 50: assumed to take either the value $0$ or~$1$), the number $2^3 + 2^5=40$
! 51: means that $p_3$ and $p_5$ have been set (that is, set to $1$), and none
! 52: of the others were (that is, they were set to 0). This will usually be
! 53: announced as ``The binary digits of $\fl$ mean 1: $p_0$, 2: $p_1$, 4:
! 54: $p_2$'', and so on, using the available consecutive powers of~$2$.
! 55:
! 56: To finish with our generic simple-minded example, the {\it library\/} function
! 57: \kbd{foo}, as defined above, is seen to have two mandatory arguments,
! 58: $x$ and \fl (no PARI mathematical function has been implemented so
! 59: as to accept a variable number of arguments). When not mentioned otherwise,
! 60: the result and arguments of a function are assumed implicitly to be of type
! 61: \kbd{GEN}. Most other functions return an object of type \kbd{long} integer
! 62: in C (see Chapter~4). The variable or parameter names \var{prec} and \fl\
! 63: always denote \kbd{long} integers.
! 64:
! 65: \misctitle{Pointers}. If a parameter in the function prototype is prefixed
! 66: with a \& sign, as in
! 67:
! 68: \key{foo}$(x,\&e)$
! 69:
! 70: \noindent it means that, besides the normal return value, the variable named
! 71: $e$ may be set as a side effect. When passing the argument, the \& sign has
! 72: to be typed in explicitly. As of version \vers{}, this \tet{pointer} argument
! 73: is optional for all documented functions, hence the \& will always appear
! 74: between brackets as in \kbd{issquare}$(x,\{\&e\})$.
! 75:
! 76: \section{Standard monadic or dyadic operators}
! 77:
! 78: \subseckbd{+$/$-}: The expressions \kbd{+}$x$ and \kbd{-}$x$ refer
! 79: to monadic operators (the first does nothing, the second negates $x$).
! 80:
! 81: \syn{gneg}{x} for \kbd{-}$x$.
! 82:
! 83: \subseckbd{+}, \kbd{-}: The expression $x$ \kbd{+} $y$ is the \idx{sum} and
! 84: $x$ \kbd{-} $y$ is the \idx{difference} of $x$ and $y$. Among the prominent
! 85: impossibilities are addition/subtraction between a scalar type and a vector
! 86: or a matrix, between vector/matrices of incompatible sizes and between an
! 87: integermod and a real number.
! 88:
! 89: \syn{gadd}{x,y} $x$ \kbd{+} $y$, $\teb{gsub}(x,y)$ for $x$ \kbd{-} $y$.
! 90:
! 91: \subseckbd{*}: The expression $x$ \kbd{*} $y$ is the \idx{product} of $x$
! 92: and $y$. Among the prominent impossibilities are multiplication between
! 93: vector/matrices of incompatible sizes, between an integermod and a real
! 94: number. Note that because of vector and matrix operations, \kbd{*} is not
! 95: necessarily commutative. Note also that since multiplication between two
! 96: column or two row vectors is not allowed, to obtain the \idx{scalar product}
! 97: of two vectors of the same length, you must multiply a line vector by a
! 98: column vector, if necessary by transposing one of the vectors (using
! 99: the operator \kbd{\til} or the function \kbd{mattranspose}, see
! 100: \secref{se:linear_algebra}).
! 101:
! 102: If $x$ and $y$ are binary quadratic forms, compose them. See also
! 103: \kbd{qfbnucomp} and \kbd{qfbnupow}.
! 104:
! 105: \syn{gmul}{x,y} for $x$ \kbd{*} $y$. Also available is
! 106: $\teb{gsqr}(x)$ for $x$ \kbd{*} $x$ (faster of course!).
! 107:
! 108: \subseckbd{/}: The expression $x$ \kbd{/} $y$ is the \idx{quotient} of $x$
! 109: and $y$. In addition to the impossibilities for multiplication, note that if
! 110: the divisor is a matrix, it must be an invertible square matrix, and in that
! 111: case the result is $x*y^{-1}$. Furthermore note that the result is as exact
! 112: as possible: in particular, division of two integers always gives a rational
! 113: number (which may be an integer if the quotient is exact) and {\it not\/} the
! 114: Euclidean quotient (see $x$ \kbd{\bs} $y$ for that), and similarly the
! 115: quotient of two polynomials is a rational function in general. To obtain the
! 116: approximate real value of the quotient of two integers, add \kbd{0.} to the
! 117: result; to obtain the approximate $p$-adic value of the quotient of two
! 118: integers, add \kbd{O(p\pow k)} to the result; finally, to obtain the
! 119: \idx{Taylor series} expansion of the quotient of two polynomials, add
! 120: \kbd{O(X\pow k)} to the result or use the \kbd{taylor} function
! 121: (see \secref{se:taylor}). \label{se:gdiv}
! 122:
! 123: \syn{gdiv}{x,y}for $x$ \kbd{/} $y$.
! 124:
! 125: \subseckbd{\bs}: The expression $x$ \kbd{\bs} $y$ is the
! 126: % keep "Euclidean" and "quotient" on same line for gphelp
! 127: \idx{Euclidean quotient} of $x$ and $y$. The types must be either both
! 128: integer or both polynomials. The result is the Euclidean quotient. In the
! 129: case of integer division, the quotient is such that the corresponding
! 130: remainder is non-negative.
! 131:
! 132: \syn{gdivent}{x,y} for $x$ \kbd{\bs} $y$.
! 133:
! 134: \subseckbd{\bs/}: The expression $x$ \b{/} $y$ is the Euclidean
! 135: quotient of $x$ and $y$. The types must be either both integer or both
! 136: polynomials. The result is the rounded Euclidean quotient. In the case of
! 137: integer division, the quotient is such that the corresponding remainder is
! 138: smallest in absolute value and in case of a tie the quotient closest to
! 139: $+\infty$ is chosen.
! 140:
! 141: \syn{gdivround}{x,y} for $x$ \b{/} $y$.
! 142:
! 143: \subseckbd{\%}: The expression $x$ \kbd{\%} $y$ is the
! 144: % keep "Euclidean" and "remainder" on same line for gphelp
! 145: \idx{Euclidean remainder} of $x$ and $y$. The modulus $y$ must be of type
! 146: integer or polynomial. The result is the remainder, always non-negative in
! 147: the case of integers. Allowed dividend types are scalar exact types when
! 148: the modulus is an integer, and polynomials, polmods and rational functions
! 149: when the modulus is a polynomial.
! 150:
! 151: \syn{gmod}{x,y} for $x$ \kbd{\%} $y$.
! 152:
! 153: \subsecidx{divrem}$(x,y)$: creates a column vector with two components,
! 154: the first being the Euclidean quotient, the second the Euclidean remainder,
! 155: of the division of $x$ by $y$. This avoids the need to do two divisions if
! 156: one needs both the quotient and the remainder. The arguments must be both
! 157: integers or both polynomials; in the case of integers, the remainder is
! 158: non-negative.
! 159:
! 160: \syn{gdiventres}{x,y}.
! 161:
! 162: \subseckbd{\pow}: The expression $x\hbox{\kbd{\pow}}y$ is \idx{powering}. If
! 163: the exponent is an integer, then exact operations are performed using binary
! 164: (left-shift) powering techniques. In particular, in this case the first
! 165: argument cannot be a vector or matrix unless it is a square matrix (and
! 166: moreover invertible if the exponent is negative). If the exponent is not of
! 167: type integer, this is treated as a transcendental function (see
! 168: \secref{se:trans}), and in particular has the effect of componentwise
! 169: powering on vector or matrices.
! 170:
! 171: \syn{gpow}{x,y,\var{prec}} for $x\hbox{\kbd{\pow}}y$.
! 172:
! 173: \subsecidx{shift}$(x,n)$ or $x$ \kbd{<<} $n$ (= $x$ \kbd{>>} $(-n)$): shifts
! 174: $x$ componentwise left by $n$ bits if $n\ge0$ and right by $|n|$ bits if
! 175: $n<0$. A left shift by $n$ corresponds to multiplication by $2^n$. A right
! 176: shift of an integer $x$ by $|n|$ corresponds to a Euclidean division of
! 177: $x$ by $2^{|n|}$ with a
! 178: remainder of the same sign as $x$, hence is not the same (in general) as
! 179: $x \kbd{\bs} 2^n$.
! 180:
! 181: \syn{gshift}{x,n} where $n$ is a \kbd{long}.
! 182:
! 183: \subsecidx{shiftmul}$(x,n)$: multiplies $x$ by $2^n$. The difference with
! 184: \kbd{shift} is that when $n<0$, ordinary division takes place, hence for
! 185: example if $x$ is an integer the result may be a fraction, while for
! 186: \kbd{shift} Euclidean division takes place when $n<0$ hence if $x$ is an
! 187: integer the result is still an integer.
! 188:
! 189: \syn{gmul2n}{x,n} where $n$ is a \kbd{long}.
! 190:
! 191: \subsec{Comparison and boolean operators}.\sidx{boolean operators}
! 192: The six standard \idx{comparison operators} \kbd{<=}, \kbd{<}, \kbd{>=},
! 193: \kbd{>}, \kbd{==}, \kbd{!=} are available in GP, and in library mode under
! 194: the names \teb{gle}, \teb{glt}, \teb{gge}, \teb{ggt}, \teb{geq}, \teb{gne}
! 195: respectively. The library syntax is ${\it co}(x,y)$, where {\it co} is the
! 196: comparison operator. The result is 1 (as a \kbd{GEN}) if the comparison is
! 197: true, 0 (as a \kbd{GEN}) if it is false.
! 198:
! 199: The standard boolean functions \kbd{||} (\idx{inclusive or}), \kbd{\&\&}
! 200: (\idx{and})\sidx{or} and \kbd{!} (\idx{not}) are also available, and the
! 201: library syntax is $\teb{gor}(x,y)$, $\teb{gand}(x,y)$ and $\teb{gnot}(x)$
! 202: respectively.
! 203:
! 204: In library mode, it is in fact usually preferable to use the two basic
! 205: functions which are $\teb{gcmp}(x,y)$ which gives the sign (1, 0, or -1) of
! 206: $x-y$, where $x$ and $y$ must be in $\R$, and $\teb{gegal}(x,y)$ which
! 207: can be applied to any two PARI objects $x$ and $y$ and gives 1 (i.e.~true) if
! 208: they are equal (but not necessarily identical), 0 (i.e.~false) otherwise.
! 209: Particular cases of \teb{gegal} which should be used are $\teb{gcmp0}(x)$
! 210: ($x==0$ ?), $\teb{gcmp1}(x)$ ($x==1$ ?), and\sidx{gcmp\string\_1}
! 211: \key{gcmp\_1}$(x)$ ($x==-1$ ?).
! 212:
! 213: Note that $\teb{gcmp0}(x)$ tests whether $x$ is equal to zero, even if $x$ is
! 214: not an exact object. To test whether $x$ is an exact object which is equal to
! 215: zero, one must use $\teb{isexactzero}$.
! 216:
! 217: Also note that the \kbd{gcmp} and \kbd{gegal} functions return a C-integer,
! 218: and {\it not\/} a \kbd{GEN} like \kbd{gle} etc.
! 219:
! 220: \smallskip
! 221: GP accepts the following synonyms for some of the above functions: since
! 222: there is no bitwise \kbd{and} or bitwise \kbd{or}, \kbd{|} and \kbd{\&} are
! 223: accepted as\sidx{bitwise and}\sidx{bitwise or} synonyms of \kbd{||} and
! 224: \kbd{\&\&} respectively. Also, \kbd{<>} is accepted as a synonym for
! 225: \kbd{!=}. On the other hand, \kbd{=} is definitely {\it not\/} a synonym for
! 226: \kbd{==} since it is the assignment statement.
! 227:
! 228: \subsecidx{lex}$(x,y)$: gives the result of a lexicographic comparison
! 229: between $x$ and $y$. This is to be interpreted in quite a wide sense. For
! 230: example, the vector $[1,3]$ will be considered smaller than the longer
! 231: vector $[1,3,-1]$ (but of course larger than $[1,2,5]$),
! 232: i.e.~\kbd{lex([1,3], [1,3,-1])} will return $-1$.
! 233:
! 234: \syn{lexcmp}{x,y}.
! 235:
! 236: \subsecidx{sign}$(x)$: \idx{sign} ($0$, $1$ or $-1$) of $x$, which must be of
! 237: type integer, real or fraction.
! 238:
! 239: \syn{gsigne}{x}. The result is a \kbd{long}.
! 240:
! 241: \subsecidx{max}$(x,y)$ and \teb{min}$(x,y)$: creates the
! 242: maximum and minimum of $x$ and $y$ when they can be compared.
! 243:
! 244: \syn{gmax}{x,y} and $\teb{gmin}(x,y)$.
! 245:
! 246: \subsecidx{vecmax}$(x)$: if $x$ is a vector or a matrix, returns the maximum
! 247: of the elements of $x$, otherwise returns a copy of $x$. Returns $-\infty$
! 248: in the form of $-(2^{31}-1)$ (or $-(2^{63}-1)$ for 64-bit machines) if $x$ is
! 249: empty.
! 250:
! 251: \syn{vecmax}{x}.
! 252:
! 253: \subsecidx{vecmin}$(x)$: if $x$ is a vector or a matrix, returns the minimum
! 254: of the elements of $x$, otherwise returns a copy of $x$. Returns $+\infty$
! 255: in the form of $2^{31}-1$ (or $2^{63}-1$ for 64-bit machines) if $x$ is empty.
! 256:
! 257: \syn{vecmin}{x}.
! 258:
! 259: \section{Conversions and similar elementary functions or commands}
! 260: \label{se:conversion}
! 261:
! 262: \noindent
! 263: Many of the conversion functions are rounding or truncating operations. In
! 264: this case, if the argument is a rational function, the result is the
! 265: Euclidean quotient of the numerator by the denominator, and if the argument
! 266: is a vector or a matrix, the operation is done componentwise. This will not
! 267: be restated for every function.
! 268:
! 269: \subsecidx{List}$({x=[\,]})$: transforms a (row or column) vector $x$
! 270: into a list. The only other way to create a \typ{LIST} is to use the
! 271: function \kbd{listcreate}.
! 272:
! 273: This is useless in library mode.
! 274:
! 275: \subsecidx{Mat}$({x=[\,]})$: transforms the object $x$ into a matrix.
! 276: If $x$ is not a vector or a matrix, this creates a $1\times 1$ matrix.
! 277: If $x$ is a row (resp. column) vector, this creates a 1-row (resp.
! 278: 1-column) matrix. If $x$ is already a matrix, a copy of $x$ is created.
! 279:
! 280: This function can be useful in connection with the function \kbd{concat}
! 281: (see there).
! 282:
! 283: \syn{gtomat}{x}.
! 284:
! 285: \subsecidx{Mod}$(x,y,\{\fl=0\})$:\label{se:Mod} creates the PARI object
! 286: $(x \mod y)$, i.e.~an integermod or a polmod. $y$ must be an integer or a
! 287: polynomial. If $y$ is an integer, $x$ must be an integer. If $y$ is a
! 288: polynomial, $x$ must be a scalar or a polynomial. The result is put on the
! 289: PARI stack.
! 290:
! 291: This function is not the same as $x$ \kbd{\%} $y$, the result of which is an
! 292: integer or a polynomial.
! 293:
! 294: If $\fl$ is equal to $1$, the modulus of the created result is put on the
! 295: heap and not on the stack, and hence becomes a permanent copy which cannot be
! 296: erased later by garbage collecting (see \secref{se:garbage}). In particular,
! 297: care should be taken to avoid creating too many such objects, since the heap
! 298: is very small (typically a few thousand objects at most).
! 299:
! 300: \syn{Mod0}{x,y,\fl}. Also available are
! 301:
! 302: $\bullet$ for $\fl=1$: $\teb{gmodulo}(x,y)$.
! 303:
! 304: $\bullet$ for $\fl=0$: $\teb{gmodulcp}(x,y)$.
! 305:
! 306: \subsecidx{Pol}$(x,\{v=x\})$: transforms the object $x$ into a polynomial with
! 307: main variable $v$. If $x$ is a scalar, this gives a constant polynomial. If
! 308: $x$ is a power series, the effect is identical to \kbd{truncate} (see there),
! 309: i.e.~it chops off the $O(X^k)$. If $x$ is a vector, this function creates
! 310: the polynomial whose coefficients are given in $x$, with $x[1]$ being the
! 311: leading coefficient (which can be zero).
! 312:
! 313: Warning: this is {\it not\/} a substitution function. It is intended to be
! 314: quick and dirty. So if you try \kbd{Pol(a,y)} on the polynomial \kbd{a = x+y},
! 315: you will get \kbd{y+y}, which is not a valid PARI object.
! 316:
! 317: \syn{gtopoly}{x,v}, where $v$ is a variable number.
! 318:
! 319: \subsecidx{Polrev}$(x,\{v=x\})$: transform the object $x$ into a polynomial
! 320: with main variable $v$. If $x$ is a scalar, this gives a constant polynomial.
! 321: If $x$ is a power series, the effect is identical to \kbd{truncate} (see
! 322: there), i.e.~it chops off the $O(X^k)$. If $x$ is a vector, this function
! 323: creates the polynomial whose coefficients are given in $x$, with $x[1]$ being
! 324: the constant term. Note that this is the reverse of \kbd{Pol} if $x$ is a
! 325: vector, otherwise it is identical to \kbd{Pol}.
! 326:
! 327: \syn{gtopolyrev}{x,v}, where $v$ is a variable number.
! 328:
! 329: \subsecidx{Ser}$(x,\{v=x\})$: transforms the object $x$ into a power series
! 330: with main variable $v$ ($x$ by default). If $x$ is a scalar, this gives a
! 331: constant power series with precision given by the default \kbd{serieslength}
! 332: (corresponding to the C global variable \kbd{precdl}). If $x$ is a
! 333: polynomial, the precision is the greatest of \kbd{precdl} and the degree of
! 334: the polynomial. If $x$ is a vector, the precision is similarly given, and the
! 335: coefficients of the vector are understood to be the coefficients of the power
! 336: series starting from the constant term (i.e.~the reverse of the function
! 337: \kbd{Pol}).
! 338:
! 339: The warning given for \kbd{Pol} applies here: this is not a substitution
! 340: function.
! 341:
! 342: \syn{gtoser}{x,v}, where $v$ is a variable number (i.e.~a C integer).
! 343:
! 344: \subsecidx{Set}$(\{x=[\,]\})$: converts $x$ into a set, i.e.~into a row vector
! 345: with strictly increasing entries. $x$ can be of any type, but is most useful
! 346: when $x$ is already a vector. The components of $x$ are put in canonical form
! 347: (type \typ{STR}) so as to be easily sorted. To recover an ordinary \kbd{GEN}
! 348: from such an element, you can apply \tet{eval} to it.
! 349:
! 350: \syn{gtoset}{x}.
! 351:
! 352: \subsecidx{Str}$(\{x=\hbox{\kbd{""}}\},\{\fl=0\})$: converts $x$ into a
! 353: character string (type \typ{STR}, the empty string if $x$ is omitted). To
! 354: recover an ordinary \kbd{GEN} from a string, apply \kbd{eval} to it. The
! 355: arguments of \kbd{Str} are evaluated in string context (see
! 356: \secref{se:strings}). If \fl\ is set, treat $x$ as a filename and perform
! 357: \idx{environment expansion} on the string. This feature can be used to read
! 358: \idx{environment variable} values.
! 359:
! 360: \bprog%
! 361: ? i = 1; Str("x" i)
! 362: \%1 = "x1"
! 363: ? eval(\%)
! 364: \%2 = x1;
! 365: ? Str("\$HOME", 1)
! 366: \%2 = "/home/pari"
! 367: \eprog
! 368:
! 369: \syn{strtoGENstr}{x,\fl}. This function is mostly useless in library mode. Use
! 370: the pair \tet{strtoGEN}/\tet{GENtostr} to convert between \kbd{char*} and
! 371: \kbd{GEN}.
! 372:
! 373: \subsecidx{Vec}$({x=[\,]})$: transforms the object $x$ into a row vector. The
! 374: vector will be with one component only, except when $x$ is a vector/matrix or
! 375: a quadratic form (in which case the resulting vector is simply the initial
! 376: object considered as a row vector), but more importantly when $x$ is a
! 377: polynomial or a power series. In the case of a polynomial, the coefficients
! 378: of the vector start with the leading coefficient of the polynomial, while
! 379: for power series only the significant coefficients are taken into account,
! 380: but this time by increasing order of degree.
! 381:
! 382: \syn{gtovec}{x}.
! 383:
! 384: \subsecidx{binary}$(x)$: outputs the vector of the binary digits of $|x|$.
! 385: Here $x$ can be an integer, a real number (in which case the result has two
! 386: components, one for the integer part, one for the fractional part) or a
! 387: vector/matrix.
! 388:
! 389: \syn{binaire}{x}.
! 390:
! 391: \subsecidx{bittest}$(x,n)$: outputs the $n^{\text{th}}$ bit of $|x|$ starting
! 392: from the right (i.e.~the coefficient of $2^n$ in the binary expansion of $x$).
! 393: The result is 0 or 1. To extract several bits at once as a vector, pass a
! 394: vector for $n$.
! 395:
! 396: \syn{bittest}{x,n}, where $n$ and the result are \kbd{long}s.
! 397:
! 398: \subsecidx{ceil}$(x)$: ceiling of $x$. When $x$ is in $\R$,
! 399: the result is the smallest integer greater than or equal to $x$.
! 400:
! 401: \syn{gceil}{x}.
! 402:
! 403: \subsecidx{centerlift}$(x,\{v\})$: lifts an element $x=a \bmod n$ of $\Z/n\Z$
! 404: to $a$ in $\Z$, and similarly lifts a polmod to a polynomial. This is the
! 405: same as \kbd{lift} except that in the particular case of elements of
! 406: $\Z/n\Z$, the lift $y$ is such that $-n/2<y\le n/2$. If $x$ is of type
! 407: fraction, complex, quadratic, polynomial, power series, rational function,
! 408: vector or matrix, the lift is done for each coefficient. Real and $p$-adics
! 409: are forbidden.
! 410:
! 411: \syn{centerlift0}{x,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded
! 412: as $-1$. Also available is \teb{centerlift}$(x)$ = \kbd{centerlift0($x$,-1)}.
! 413:
! 414: \subsecidx{changevar}$(x,y)$: creates a copy of the object $x$ where its
! 415: variables are modified according to the permutation specified by the vector
! 416: $y$. For example, assume that the variables have been introduced in the
! 417: order \kbd{x}, \kbd{a}, \kbd{b}, \kbd{c}. Then, if $y$ is the vector
! 418: \kbd{[x,c,a,b]}, the variable \kbd{a} will be replaced by \kbd{c}, \kbd{b} by
! 419: \kbd{a}, and \kbd{c} by \kbd{b}, \kbd{x} being unchanged. Note that the
! 420: permutation must be completely specified, e.g.~\kbd{[c,a,b]} would not work,
! 421: since this would replace \kbd{x} by \kbd{c}, and leave \kbd{a} and \kbd{b}
! 422: unchanged (as well as \kbd{c} which is the fourth variable of the initial
! 423: list). In particular, the new variable names must be distinct.
! 424:
! 425: \syn{changevar}{x,y}.
! 426:
! 427: \subsec{components of a PARI object}:
! 428:
! 429: There are essentially three ways to extract the \idx{components} from a PARI
! 430: object.
! 431:
! 432: The first and most general, is the function $\teb{component}(x,n)$ which
! 433: extracts the $n^{\text{th}}$-component of $x$. This is to be understood as
! 434: follows: every PARI type has one or two initial \idx{code words}. The
! 435: components are counted, starting at 1, after these code words. In particular
! 436: if $x$ is a vector, this is indeed the $n^{\text{th}}$-component of $x$, if
! 437: $x$ is a matrix, the $n^{\text{th}}$ column, if $x$ is a polynomial, the
! 438: $n^{\text{th}}$ coefficient (i.e.~of degree $n-1$), and for power series, the
! 439: $n^{\text{th}}$ significant coefficient. The use of the function
! 440: \kbd{component} implies the knowledge of the structure of the different PARI
! 441: types, which can be recalled by typing \b{t} under GP.
! 442:
! 443: \syn{compo}{x,n}, where $n$ is a \kbd{long}.
! 444:
! 445: The two other methods are more natural but more restricted. First, the
! 446: function $\teb{polcoeff}(x,n)$ gives the coefficient of degree $n$ of the
! 447: polynomial or power series $x$, with respect to the main variable of $x$ (to
! 448: see the order of the variables or to change it, use the function
! 449: \tet{reorder}, see \secref{se:reorder}). In particular if $n$ is less than
! 450: the valuation of $x$ or in the case of a polynomial, greater than the degree,
! 451: the result is zero (contrary to \kbd{compo} which would send an error
! 452: message). If $x$ is a power series and $n$ is greater than the largest
! 453: significant degree, then an error message is issued.
! 454:
! 455: For greater flexibility, vector or matrix types are also accepted for $x$,
! 456: and the meaning is then identical with that of \kbd{compo}.
! 457:
! 458: Finally note that a scalar type is considered by \kbd{polcoeff} as a
! 459: polynomial of degree zero.
! 460:
! 461: \syn{truecoeff}{x,n}.
! 462:
! 463: The third method is specific to vectors or matrices under GP. If $x$ is a
! 464: (row or column) vector, then \tet{x[n]} represents the $n^{\text{th}}$
! 465: component of $x$, i.e.~\kbd{compo(x,n)}. It is more natural and shorter to
! 466: write. If $x$ is a matrix, \tet{x[m,n]} represents the coefficient of
! 467: row \kbd{m} and column \kbd{n} of the matrix, \tet{x[m,]} represents
! 468: the $m^{\text{th}}$ {\it row\/} of $x$, and \tet{x[,n]} represents
! 469: the $n^{\text{th}}$ {\it column\/} of $x$.
! 470:
! 471: Finally note that in library mode, the macros \teb{coeff} and \teb{mael}
! 472: are available to deal with the non-recursivity of the \kbd{GEN} type from the
! 473: compiler's point of view. See the discussion on typecasts in Chapter 4.
! 474:
! 475: \subsecidx{conj}$(x)$: conjugate of $x$. The meaning of this
! 476: is clear, except that for real quadratic numbers, it means conjugation in the
! 477: real quadratic field. This function has no effect on integers, reals,
! 478: integermods, fractions or $p$-adics. The only forbidden type is polmod
! 479: (see \kbd{conjvec} for this).
! 480:
! 481: \syn{gconj}{x}.
! 482:
! 483: \subsecidx{conjvec}$(x)$: conjugate vector representation of $x$. If $x$ is a
! 484: polmod, equal to \kbd{Mod}$(a,q)$, this gives a vector of length
! 485: $\text{degree}(q)$ containing the complex embeddings of the polmod if $q$ has
! 486: integral or rational coefficients, and the conjugates of the polmod if $q$
! 487: has some integermod coefficients. The order is the same as that of the
! 488: \kbd{polroots} functions. If $x$ is an integer or a rational number, the
! 489: result is~$x$. If $x$ is a (row or column) vector, the result is a matrix
! 490: whose columns are the conjugate vectors of the individual elements of $x$.
! 491:
! 492: \syn{conjvec}{x,\var{prec}}.
! 493:
! 494: \subsecidx{denominator}$(x)$: lowest denominator of $x$. The meaning of this
! 495: is clear when $x$ is a rational number or function. When $x$ is an integer
! 496: or a polynomial, the result is equal to $1$. When $x$ is a vector or a matrix,
! 497: the lowest common denominator of the components of $x$ is computed. All other
! 498: types are forbidden.
! 499:
! 500: \syn{denom}{x}.
! 501:
! 502: \subsecidx{floor}$(x)$: floor of $x$. When $x$ is in $\R$,
! 503: the result is the largest integer smaller than or equal to $x$.
! 504:
! 505: \syn{gfloor}{x}.
! 506:
! 507: \subsecidx{frac}$(x)$: fractional part of $x$. Identical to
! 508: $x-\text{floor}(x)$. If $x$ is real, the result is in $[0,1[$.
! 509:
! 510: \syn{gfrac}{x}.
! 511:
! 512: \subsecidx{imag}$(x)$: imaginary part of $x$. When
! 513: $x$ is a quadratic number, this is the coefficient of $\omega$ in
! 514: the ``canonical'' integral basis $(1,\omega)$.
! 515:
! 516: \syn{gimag}{x}.
! 517:
! 518: \subsecidx{length}$(x)$: number of non-code words in $x$ really used (i.e.~the
! 519: effective length minus 2 for integers and polynomials). In particular,
! 520: the degree of a polynomial is equal to its length minus 1. If $x$ has type
! 521: \typ{STR}, output number of letters.
! 522:
! 523: \syn{glength}{x} and the result is a C long.
! 524:
! 525: \subsecidx{lift}$(x,\{v\})$: lifts an element $x=a \bmod n$ of $\Z/n\Z$ to
! 526: $a$ in $\Z$, and similarly lifts a polmod to a polynomial if $v$ is omitted.
! 527: Otherwise, lifts only polmods with main variable $v$ (if $v$ does not occur
! 528: in $x$, lifts only intmods). If $x$ is of type fraction, complex, quadratic,
! 529: polynomial, power series, rational function, vector or matrix, the lift is
! 530: done for each coefficient. Forbidden types for $x$ are reals and $p$-adics.
! 531:
! 532: \syn{lift0}{x,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded as
! 533: $-1$. Also available is \teb{lift}$(x)$ = \kbd{lift0($x$,-1)}.
! 534:
! 535: \subsecidx{norm}$(x)$: algebraic norm of $x$, i.e.~the product of $x$ with
! 536: its conjugate (no square roots are taken), or conjugates for polmods. For
! 537: vectors and matrices, the norm is taken componentwise and hence is not the
! 538: $L^2$-norm (see \kbd{norml2}). Note that the norm of an element of
! 539: $\R$ is its square, so as to be compatible with the complex norm.
! 540:
! 541: \syn{gnorm}{x}.
! 542:
! 543: \subsecidx{norml2}$(x)$: square of the $L^2$-norm of $x$. $x$ must
! 544: be a (row or column) vector.
! 545:
! 546: \syn{gnorml2}{x}.
! 547:
! 548: \subsecidx{numerator}$(x)$: numerator of $x$. When $x$ is a rational number
! 549: or function, the meaning is clear. When $x$ is an integer or a polynomial,
! 550: the result is $x$ itself. When $x$ is a vector or a matrix, then
! 551: \kbd{numerator(x)} is defined to be \kbd{denominator(x)*x}. All other types
! 552: are forbidden.
! 553:
! 554: \syn{numer}{x}.
! 555:
! 556: \subsecidx{numtoperm}$(n,k)$: generates the $k$-th permutation (as a
! 557: row vector of length $n$) of the numbers $1$ to $n$. The number $k$ is taken
! 558: modulo $n!\,$, i.e.~inverse function of \tet{permtonum}.
! 559:
! 560: \syn{permute}{n,k}, where $n$ is a \kbd{long}.
! 561:
! 562: \subsecidx{padicprec}$(x,p)$: absolute $p$-adic precision of the object $x$.
! 563: This is the minimum precision of the components of $x$. The result is
! 564: \kbd{VERYBIGINT} ($2^{31}-1$ for 32-bit machines or $2^{63}-1$ for 64-bit
! 565: machines) if $x$ is an exact object.
! 566:
! 567: \syn{padicprec}{x,p} and the result is a \kbd{long}
! 568: integer.
! 569:
! 570: \subsecidx{permtonum}$(x)$: given a permutation $x$ on $n$ elements,
! 571: gives the number $k$ such that $x=\kbd{numtoperm(n,k)}$, i.e.~inverse
! 572: function of \tet{numtoperm}.
! 573:
! 574: \syn{permuteInv}{x}.
! 575:
! 576: \subsecidx{precision}$(x,\{n\})$: gives the precision in decimal digits of the
! 577: PARI object $x$. If $x$ is an exact object, the largest single precision
! 578: integer is returned. If $n$ is not omitted, creates a new object equal to $x$
! 579: with a new precision $n$. This is to be understood as follows:
! 580:
! 581: For exact types, no change. For $x$ a vector or a matrix, the operation
! 582: is done componentwise.
! 583:
! 584: For real $x$, $n$ is the number of desired significant {\it decimal} digits.
! 585: If $n$ is smaller than the precision of $x$, $x$ is truncated, otherwise $x$
! 586: is extended with zeros.
! 587:
! 588: For $x$ a $p$-adic or a power series, $n$ is the desired number of
! 589: significant $p$-adic or $X$-adic digits, where $X$ is the main variable of
! 590: $x$.
! 591:
! 592: Note that the function \kbd{precision} never changes the type of the result.
! 593: In particular it is not possible to use it to obtain a polynomial from a
! 594: power series. For that, see \kbd{truncate}.
! 595:
! 596: \syn{precision0}{x,n}, where $n$ is a \kbd{long}. Also available are
! 597: $\teb{ggprecision}(x)$ (result is a \kbd{GEN}) and $\teb{gprec}(x,n)$, where
! 598: $n$ is a \kbd{long}.
! 599:
! 600: \subsecidx{random}$(\{N=2^{31}\})$: gives a random integer between 0 and
! 601: $N-1$. $N$ can be arbitrary large. This is an internal PARI function and does
! 602: not depend on the system's random number generator. Note that the resulting
! 603: integer is obtained by means of linear congruences and will not be well
! 604: distributed in arithmetic progressions.
! 605:
! 606: \syn{genrand}{N}.
! 607:
! 608: \subsecidx{real}$(x)$: real part of $x$. In the case where $x$ is a quadratic
! 609: number, this is the coefficient of $1$ in the ``canonical'' integral basis
! 610: $(1,\omega)$.
! 611:
! 612: \syn{greal}{x}.
! 613:
! 614: \subsecidx{round}$(x,\{\&e\})$: If $x$ is in $\R$, rounds $x$ to the nearest
! 615: integer and set $e$ to the number of error bits, that is the binary exponent
! 616: of the difference between the original and the rounded value (the
! 617: ``fractional part''). If the exponent of $x$ is too large compared to its
! 618: precision (i.e.~$e>0$), the result is undefined and an error occurs if $e$
! 619: was not given.
! 620:
! 621: \misctitle{Important remark:} note that, contrary to the other truncation
! 622: functions, this function operates on every coefficient at every level of a
! 623: PARI object. For example
! 624: $$\text{truncate}\left(\dfrac{2.4*X^2-1.7}{X}\right)=2.4*X,$$ whereas
! 625: $$\text{round}\left(\dfrac{2.4*X^2-1.7}{X}\right)=\dfrac{2*X^2-2}{X}.$$
! 626: An important use of \kbd{round} is to get exact results after a long
! 627: approximate computation, when theory tells you that the coefficients
! 628: must be integers.
! 629:
! 630: \syn{grndtoi}{x,\&e}, where $e$ is a \kbd{long} integer. Also available is
! 631: $\teb{ground}(x)$.
! 632:
! 633: \subsecidx{simplify}$(x)$: this function tries to simplify the object $x$ as
! 634: much as it can. The simplifications do not concern rational functions (which
! 635: PARI automatically tries to simplify), but type changes. Specifically, a
! 636: complex or quadratic number whose imaginary part is exactly equal to 0
! 637: (i.e.~not a real zero) is converted to its real part, and a polynomial of
! 638: degree zero is converted to its constant term. For all types, this of course
! 639: occurs recursively. This function is useful in any case, but in particular
! 640: before the use of arithmetic functions which expect integer arguments, and
! 641: not for example a complex number of 0 imaginary part and integer real part
! 642: (which is however printed as an integer).
! 643:
! 644: \syn{simplify}{x}.
! 645:
! 646: \subsecidx{sizebyte}$(x)$: outputs the total number of bytes occupied by the
! 647: tree representing the PARI object $x$.
! 648:
! 649: \syn{taille2}{x} which returns a \kbd{long}. The
! 650: function \teb{taille} returns the number of {\it words} instead.
! 651:
! 652: \subsecidx{sizedigit}$(x)$: outputs a quick bound for the number of decimal
! 653: digits of (the components of) $x$, off by at most $1$. If you want the
! 654: exact value, you an use \kbd{length(Str(x))}, which is much slower.
! 655:
! 656: \syn{gsize}{x} which returns a \kbd{long}.
! 657:
! 658: \subsecidx{truncate}$(x,\{\&e\})$: truncate $x$ and set $e$ to the number of
! 659: error bits. When $x$ is in $\R$, this means that the part after the decimal
! 660: point is chopped away, integer and set $e$ to the number of error bits that
! 661: is the binary exponent of the difference between the original and the
! 662: truncated value (the ``fractional part''). If the exponent of $x$ is too
! 663: large compared to its precision (i.e.~$e>0$), the result is undefined and an
! 664: error occurs if $e$ was not given.
! 665:
! 666: Note a very special use of \kbd{truncate}: when applied to a power series, it
! 667: transforms it into a polynomial or a rational function with denominator
! 668: a power of $X$, by chopping away the $O(X^k)$. Similarly, when applied to
! 669: a $p$-adic number, it transforms it into an integer or a rational number
! 670: by chopping away the $O(p^k)$.
! 671:
! 672: \syn{gcvtoi}{x,\&e}, where $e$ is a \kbd{long} integer. Also available is
! 673: \teb{gtrunc}$(x)$.
! 674:
! 675: \subsecidx{valuation}$(x,p)$:\label{se:valuation} computes the highest
! 676: exponent of $p$ dividing $x$. If $p$ is of type integer, $x$ must be an
! 677: integer, an integermod whose modulus is divisible by $p$, a fraction, a
! 678: $q$-adic number with $q=p$, or a polynomial or power series in which case the
! 679: valuation is the minimum of the valuation of the coefficients.
! 680:
! 681: If $p$ is of type polynomial, $x$ must be of type polynomial or rational
! 682: function, and also a power series if $x$ is a monomial. Finally, the
! 683: valuation of a vector, complex or quadratic number is the minimum of the
! 684: component valuations.
! 685:
! 686: If $x=0$, the result is \kbd{VERYBIGINT} ($2^{31}-1$ for 32-bit machines or
! 687: $2^{63}-1$ for 64-bit machines) if $x$ is an exact object. If $x$ is a
! 688: $p$-adic numbers or power series, the result is the exponent of the zero.
! 689: Any other type combinations gives an error.
! 690:
! 691: \syn{ggval}{x,p}, and the result is a \kbd{long}.
! 692:
! 693: \subsecidx{variable}$(x)$: gives the main variable of the object $x$, and
! 694: $p$ if $x$ is a $p$-adic number. Gives an error if $x$ has no variable
! 695: associated to it. Note that this function is useful only in GP, since in
! 696: library mode the function \kbd{gvar} is more appropriate.
! 697:
! 698: \syn{gpolvar}{x}. However, in library mode, this function should not be used.
! 699: Instead, test whether $x$ is a $p$-adic (type \typ{PADIC}), in which case $p$
! 700: is in $x[2]$, or call the function $\key{gvar}(x)$ which returns the variable
! 701: {\it number\/} of $x$ if it exists, \kbd{BIGINT} otherwise.
! 702:
! 703: \section{Transcendental functions}\label{se:trans}
! 704:
! 705: As a general rule, which of course in some cases may have exceptions,
! 706: transcendental functions operate in the following way:
! 707:
! 708: $\bullet$ If the argument is either an integer, a real, a rational, a complex
! 709: or a quadratic number, it is, if necessary, first converted to a real (or
! 710: complex) number using the current \idx{precision} held in the default
! 711: \kbd{realprecision}. Note that only exact arguments are converted, while
! 712: inexact arguments such as reals are not.
! 713:
! 714: Under GP this is transparent to the user, but when programming in library
! 715: mode, care must be taken to supply a meaningful parameter \var{prec} as the
! 716: last argument of the function if the first argument is an exact object.
! 717: This parameter is ignored if the argument is inexact.
! 718:
! 719: Note that in library mode the precision argument \var{prec} is a word
! 720: count including codewords, i.e.~represents the length in words of a real
! 721: number, while under GP the precision (which is changed by the metacommand
! 722: \b{p} or using \kbd{default(realprecision,...)}) is the number of significant
! 723: decimal digits.
! 724:
! 725: Note that some accuracies attainable on 32-bit machines cannot be attained
! 726: on 64-bit machines for parity reasons. For example the default GP accuracy
! 727: is 28 decimal digits on 32-bit machines, corresponding to \var{prec} having
! 728: the value 5, but this cannot be attained on 64-bit machines.\smallskip
! 729:
! 730: After possible conversion, the function is computed. Note that even if the
! 731: argument is real, the result may be complex (e.g.~$\text{acos}(2.0)$ or
! 732: $\text{acosh}(0.0)$). Note also that the principal branch is always chosen.
! 733:
! 734: $\bullet$ If the argument is an integermod or a $p$-adic, at present only a
! 735: few functions like \kbd{sqrt} (square root), \kbd{sqr} (square), \kbd{log},
! 736: \kbd{exp}, powering, \kbd{teichmuller} (Teichm\"uller character) and
! 737: \kbd{agm} (arithmetic-geometric mean) are implemented. Note that in the case
! 738: of a $2$-adic number, $\kbd{sqr}(x)$ is not identical to $x*x$: for example
! 739: if $x = 1+O(2^5)$ then $x*x = 1+O(2^5)$ while $\kbd{sqr}(x) = 1+O(2^6)$.
! 740: (Remark: note that if we wanted to be strictly consistent with the PARI
! 741: philosophy, we should have $x*y= (4 \mod 8)$ when both $x$ and $y$ are
! 742: congruent to $2$ modulo $4$, or $\kbd{sqr}(x)=(4\mod 32)$ when $x$ is
! 743: congruent to $2$ modulo $4$. However, since an integermod is an exact object,
! 744: PARI assumes that the modulus must not change, and the result is hence $0\,
! 745: \mod\, 4$ in both cases. On the other hand, $p$-adics are not exact objects,
! 746: hence are treated differently.)
! 747:
! 748: $\bullet$ If the argument is a polynomial, power series or rational function,
! 749: it is, if necessary, first converted to a power series using the current
! 750: precision held in the variable \tet{precdl}. Under GP this again is
! 751: transparent to the user. When programming in library mode, however, the
! 752: global variable \kbd{precdl} must be set before calling the function if the
! 753: argument has an exact type (i.e.~not a power series). Here \kbd{precdl} is
! 754: not an argument of the function, but a global variable.
! 755:
! 756: Then the Taylor series expansion of the function around $X=0$ (where $X$ is
! 757: the main variable) is computed to a number of terms depending on the number
! 758: of terms of the argument and the function being computed.
! 759:
! 760: $\bullet$ If the argument is a vector or a matrix, the result is the
! 761: componentwise evaluation of the function. In particular, transcendental
! 762: functions on square matrices, which are not implemented in the present
! 763: version \vers{} (see Appendix~B however), will have a slightly different name
! 764: if they are implemented some day.
! 765:
! 766: \subseckbd{\pow}: If $y$ is not of type integer, \kbd{x\pow y} has the same
! 767: effect as \kbd{exp(y*ln(x))}. It can be applied to $p$-adic numbers as
! 768: well as to the more usual types.\sidx{powering}
! 769:
! 770: \syn{gpow}{x,y,\var{prec}}.
! 771:
! 772: \subsecidx{Euler}: Euler's constant $0.57721\cdots$. Note that \kbd{Euler}
! 773: is one of the few special reserved names which cannot be used for variables
! 774: (the others are \kbd{I} and \kbd{Pi}, as well as all function names).
! 775: \label{se:euler}
! 776:
! 777: \syn{mpeuler}{\var{prec}} where $\var{prec}$ {\it must\/} be
! 778: given. Note that this creates $\gamma$ on the PARI stack. If one does not
! 779: want to create it on the stack but stash it for later use under the global
! 780: name \teb{geuler} (with no parentheses), use instead
! 781: $\teb{consteuler}(\var{prec})$.
! 782:
! 783: \subsecidx{I}: the complex number $\sqrt{-1}$.
! 784:
! 785: The library syntax is the global variable \kbd{gi} (of type \kbd{GEN}).
! 786:
! 787: \subsecidx{Pi}: the constant $\pi$ ($3.14159\cdots$).\label{se:pi}
! 788:
! 789: \syn{mppi}{\var{prec}} where $\var{prec}$ {\it must\/} be given.
! 790: Note that this creates $\pi$ on the PARI stack. If one does not want to
! 791: create it on the stack but stash it for later use under the global
! 792: name \teb{gpi} (with no parentheses), use instead $\teb{constpi}(\var{prec})$.
! 793:
! 794: \subsecidx{abs}$(x)$: absolute value of $x$ (modulus if $x$ is complex).
! 795: Polynomials, power series and rational functions are not allowed.
! 796: Contrary to most transcendental functions, an integer is {\it not\/}
! 797: converted to a real number before applying \kbd{abs}.
! 798:
! 799: \syn{gabs}{x,\var{prec}}.
! 800:
! 801: \subsecidx{acos}$(x)$: principal branch of $\text{cos}^{-1}(x)$,
! 802: i.e.~such that $\text{Re(acos}(x))\in [0,\pi]$. If
! 803: $x\in \R$ and $|x|>1$, then $\text{acos}(x)$ is complex.
! 804:
! 805: \syn{gacos}{x,\var{prec}}.
! 806:
! 807: \subsecidx{acosh}$(x)$: principal branch of $\text{cosh}^{-1}(x)$,
! 808: i.e.~such that $\text{Im(acosh}(x))\in [0,\pi]$. If
! 809: $x\in \R$ and $x<1$, then $\text{acosh}(x)$ is complex.
! 810:
! 811: \syn{gach}{x,\var{prec}}.
! 812:
! 813: \subsecidx{agm}$(x,y)$: arithmetic-geometric mean of $x$ and $y$. In the
! 814: case of complex or negative numbers, the principal square root is always
! 815: chosen. $p$-adic or power series arguments are also allowed. Note that
! 816: a $p$-adic agm exists only if $x/y$ is congruent to 1 modulo $p$ (modulo
! 817: 16 for $p=2$). $x$ and $y$ cannot both be vectors or matrices.
! 818:
! 819: \syn{agm}{x,y,\var{prec}}.
! 820:
! 821: \subsecidx{arg}$(x)$: argument of the complex number $x$, such that
! 822: $-\pi<\text{arg}(x)\le\pi$.
! 823:
! 824: \syn{garg}{x,\var{prec}}.
! 825:
! 826: \subsecidx{asin}$(x)$: principal branch of $\text{sin}^{-1}(x)$, i.e.~such
! 827: that $\text{Re(asin}(x))\in [-\pi/2,\pi/2]$. If $x\in \R$ and $|x|>1$ then
! 828: $\text{asin}(x)$ is complex.
! 829:
! 830: \syn{gasin}{x,\var{prec}}.
! 831:
! 832: \subsecidx{asinh}$(x)$: principal branch of $\text{sinh}^{-1}(x)$, i.e.~such
! 833: that $\text{Im(asinh}(x))\in [-\pi/2,\pi/2]$.
! 834:
! 835: \syn{gash}{x,\var{prec}}.
! 836:
! 837: \subsecidx{atan}$(x)$: principal branch of $\text{tan}^{-1}(x)$, i.e.~such
! 838: that $\text{Re(atan}(x))\in{} ]-\pi/2,\pi/2[$.
! 839:
! 840: \syn{gatan}{x,\var{prec}}.
! 841:
! 842: \subsecidx{atanh}$(x)$: principal branch of $\text{tanh}^{-1}(x)$, i.e.~such
! 843: that $\text{Im(atanh}(x))\in{} ]-\pi/2,\pi/2]$. If $x\in \R$ and $|x|>1$ then
! 844: $\text{atanh}(x)$ is complex.
! 845:
! 846: \syn{gath}{x,\var{prec}}.
! 847:
! 848: \subsecidx{bernfrac}$(x)$: Bernoulli number\sidx{Bernoulli numbers} $B_x$,
! 849: where $B_0=1$, $B_1=-1/2$, $B_2=1/6$,\dots, expressed as a rational number.
! 850: The argument $x$ should be of type integer.
! 851:
! 852: \syn{bernfrac}{x}.
! 853:
! 854: \subsecidx{bernreal}$(x)$: Bernoulli number\sidx{Bernoulli numbers}
! 855: $B_x$, as \kbd{bernfrac}, but $B_x$ is returned as a real number
! 856: (with the current precision).
! 857:
! 858: \syn{bernreal}{x,\var{prec}}.
! 859:
! 860: \subsecidx{bernvec}$(x)$: creates a vector containing, as rational numbers,
! 861: the \idx{Bernoulli numbers} $B_0$, $B_2$,\dots, $B_{2x}$. These Bernoulli
! 862: numbers can then be used as follows. Assume that this vector has been put
! 863: into a variable, say \kbd{bernint}. Then you can define under GP:
! 864:
! 865: \bprog
! 866: bern(x) =
! 867: \obr
! 868: \q if (x==1, return(-1/2));
! 869: \q if ((x<0) || (x\%2), return(0));
! 870: \q bernint[x/2+1]
! 871: \cbr
! 872: \eprog
! 873: \noindent and then \kbd{bern(k)} gives the Bernoulli number of index $k$ as a
! 874: rational number, exactly as \kbd{bernreal(k)} gives it as a real number. If
! 875: you need only a few values, calling \kbd{bernfrac(k)} each time will be much
! 876: more efficient than computing the huge vector above.
! 877:
! 878:
! 879: \syn{bernvec}{x}.
! 880:
! 881: \subsecidx{besseljh}$(n,x)$: $J$-Bessel function of half integral index.
! 882: More precisely, $\kbd{besseljh}(n,x)$ computes $J_{n+1/2}(x)$ where $n$
! 883: must be of type integer, and $x$ is any element of $\C$. In the
! 884: present version \vers, this function is not very accurate when $x$ is
! 885: small.
! 886:
! 887: \syn{jbesselh}{n,x,\var{prec}}.
! 888:
! 889: \subsecidx{besselk}$(\var{nu},x,\{\fl=0\})$: $K$-Bessel function of index
! 890: \var{nu} (which can be complex) and argument $x$. Only real and positive
! 891: arguments
! 892: $x$ are allowed in the present version \vers. If $\fl$ is equal to 1,
! 893: uses another implementation of this function which is often faster.
! 894:
! 895: \syn{kbessel}{\var{nu},x,\var{prec}} and
! 896: $\teb{kbessel2}(\var{nu},x,\var{prec})$ respectively.
! 897:
! 898: \subsecidx{cos}$(x)$: cosine of $x$.
! 899:
! 900: \syn{gcos}{x,\var{prec}}.
! 901:
! 902: \subsecidx{cosh}$(x)$: hyperbolic cosine of $x$.
! 903:
! 904: \syn{gch}{x,\var{prec}}.
! 905:
! 906: \subsecidx{cotan}$(x)$: cotangent of $x$.
! 907:
! 908: \syn{gcotan}{x,\var{prec}}.
! 909:
! 910: \subsecidx{dilog}$(x)$: principal branch of the dilogarithm of $x$,
! 911: i.e.~analytic continuation of the power series $\log_2(x)=\sum_{n\ge1}x^n/n^2$.
! 912:
! 913: \syn{dilog}{x,\var{prec}}.
! 914:
! 915: \subsecidx{eint1}$(x,\{n\})$: exponential integral
! 916: $\int_x^\infty \dfrac{e^{-t}}{t}\,dt$ ($x\in\R$)
! 917:
! 918: If $n$ is present, outputs the $n$-dimensional vector
! 919: $[\kbd{eint1}(x),\dots,\kbd{eint1}(nx)]$ ($x \geq 0$). This is faster than
! 920: repeatedly calling \kbd{eint1($i$ * x)}.
! 921:
! 922: \syn{veceint1}{x,n,\var{prec}}. Also available is
! 923: $\teb{eint1}(x,\var{prec})$.
! 924:
! 925: \subsecidx{erfc}$(x)$: complementary error function
! 926: $(2/\sqrt\pi)\int_x^\infty e^{-t^2}\,dt$.
! 927:
! 928: \syn{erfc}{x,\var{prec}}.
! 929:
! 930: \subsecidx{eta}$(x,\{\fl=0\})$: \idx{Dedekind}'s $\eta$ function, without the
! 931: $q^{1/24}$. This means the following: if $x$ is a complex number with positive
! 932: imaginary part, the result is $\prod_{n=1}^\infty(1-q^n)$, where
! 933: $q=e^{2i\pi x}$. If $x$ is a power series (or can be converted to a power
! 934: series) with positive valuation, the result is $\prod_{n=1}^\infty(1-x^n)$.
! 935:
! 936: If $\fl=1$ and $x$ can be converted to a complex number (i.e.~is not a power
! 937: series), computes the true $\eta$ function, including the leading $q^{1/24}$.
! 938:
! 939: \syn{eta}{x,\var{prec}}.
! 940:
! 941: \subsecidx{exp}$(x)$: exponential of $x$.
! 942: $p$-adic arguments with positive valuation are accepted.
! 943:
! 944: \syn{gexp}{x,\var{prec}}.
! 945:
! 946: \subsecidx{gammah}$(x)$: gamma function evaluated at the argument
! 947: $x+1/2$. When $x$ is an integer, this is much faster than using
! 948: $\kbd{gamma}(x+1/2)$.
! 949:
! 950: \syn{ggamd}{x,\var{prec}}.
! 951:
! 952: \subsecidx{gamma}$(x)$: gamma function of $x$. In the present version
! 953: \vers{} the $p$-adic gamma function is not implemented.
! 954:
! 955: \syn{ggamma}{x,\var{prec}}.
! 956:
! 957: \subsecidx{hyperu}$(a,b,x)$: $U$-confluent hypergeometric function with
! 958: parameters $a$ and $b$.
! 959:
! 960: \syn{hyperu}{a,b,x,\var{prec}}.
! 961:
! 962: \subsecidx{incgam}$(s,x,{y})$: incomplete gamma function.
! 963:
! 964: The arguments $s$ and $x$ must be positive. The result returned is
! 965: $\int_x^\infty e^{-t}t^{s-1}\,dt$. When $y$ is given, assume (of course
! 966: without checking!) that $y=\Gamma(s)$. For small $x$, this will tremendously
! 967: speed up the computation.
! 968:
! 969: \syn{incgam}{s,x,\var{prec}} and $\teb{incgam4}(s,x,y,\var{prec})$,
! 970: respectively. There exist also the functions \teb{incgam1} and
! 971: \teb{incgam2} which are used for internal purposes.
! 972:
! 973: \subsecidx{incgamc}$(s,x)$: complementary incomplete gamma function.
! 974:
! 975: The arguments $s$ and $x$ must be positive. The result returned is
! 976: $\int_0^x e^{-t}t^{s-1}\,dt$, when $x$ is not too large.
! 977:
! 978: \syn{incgam3}{s,x,\var{prec}}.
! 979:
! 980: \subsecidx{log}$(x,\{\fl=0\})$: principal branch of the natural logarithm of
! 981: $x$, i.e.~such that $\text{Im(ln}(x))\in{} ]-\pi,\pi]$. The result is complex
! 982: (with imaginary part equal to $\pi$) if $x\in \R$ and $x<0$.
! 983:
! 984: $p$-adic arguments are also accepted for $x$, with the convention that
! 985: $\ln(p)=0$. Hence in particular $\exp(\ln(x))/x$ will not in general be
! 986: equal to 1 but to a $(p-1)$-th root of unity (or $\pm1$ if $p=2$)
! 987: times a power of $p$.
! 988:
! 989: If $\fl$ is equal to 1, use an agm formula suggested by Mestre, when $x$ is
! 990: real, otherwise identical to \kbd{log}.
! 991:
! 992: \syn{glog}{x,\var{prec}} or $\teb{glogagm}(x,\var{prec})$.
! 993:
! 994: \subsecidx{lngamma}$(x)$: principal branch of the logarithm of the gamma
! 995: function of $x$. Can have much larger arguments than \kbd{gamma} itself.
! 996: In the present version \vers, the $p$-adic \kbd{lngamma} function is not
! 997: implemented.
! 998:
! 999: \syn{glngamma}{x,\var{prec}}.
! 1000:
! 1001: \subsecidx{polylog}$(m,x,{\fl=0})$: one of the different polylogarithms,
! 1002: depending on \fl:
! 1003:
! 1004: If $\fl=0$ or is omitted: $m^\text{th}$ polylogarithm of $x$, i.e.~analytic
! 1005: continuation of the power series $\text{Li}_m(x)=\sum_{n\ge1}x^n/n^m$. The
! 1006: program uses the power series when $|x|^2\le1/2$, and the power series
! 1007: expansion in $\log(x)$ otherwise. It is valid in a large domain (at least
! 1008: $|x|<230$), but should not be used too far away from the unit circle since it
! 1009: is then better to use the functional equation linking the value at $x$ to the
! 1010: value at $1/x$, which takes a trivial form for the variant below. Power
! 1011: series, polynomial, rational and vector/matrix arguments are allowed.
! 1012:
! 1013: For the variants to follow we need a notation: let $\Re_m$
! 1014: denotes $\Re$ or $\Im$ depending whether $m$ is odd or even.
! 1015:
! 1016: If $\fl=1$: modified $m^\text{th}$ polylogarithm of $x$, called
! 1017: $\tilde D_m(x)$ in Zagier, defined for $|x|\le1$ by
! 1018: $$\Re_m\left(\sum_{k=0}^{m-1} \dfrac{(-\log|x|)^k}{k!}\text{Li}_{m-k}(x)
! 1019: +\dfrac{(-\log|x|)^{m-1}}{m!}\log|1-x|\right).$$
! 1020:
! 1021: If $\fl=2$: modified $m^\text{th}$ polylogarithm of $x$,
! 1022: called $D_m(x)$ in Zagier, defined for $|x|\le1$ by
! 1023: $$\Re_m\left(\sum_{k=0}^{m-1}\dfrac{(-\log|x|)^k}{k!}\text{Li}_{m-k}(x)
! 1024: -\dfrac{1}{2}\dfrac{(-\log|x|)^m}{m!}\right).$$
! 1025:
! 1026: If $\fl=3$: another modified $m^\text{th}$
! 1027: polylogarithm of $x$, called $P_m(x)$ in Zagier, defined for $|x|\le1$ by
! 1028: $$\Re_m\left(\sum_{k=0}^{m-1}\dfrac{2^kB_k}{k!}(\log|x|)^k\text{Li}_{m-k}(x)
! 1029: -\dfrac{2^{m-1}B_m}{m!}(\log|x|)^m\right).$$
! 1030:
! 1031: These three functions satisfy the functional equation
! 1032: $f_m(1/x)=(-1)^{m-1}f_m(x)$.
! 1033:
! 1034: \syn{polylog0}{m,x,\fl,\var{prec}}.
! 1035:
! 1036: \subsecidx{psi}$(x)$: the $\psi$-function of $x$, i.e.~the
! 1037: logarithmic derivative $\Gamma'(x)/\Gamma(x)$.
! 1038:
! 1039: \syn{gpsi}{x,\var{prec}}.
! 1040:
! 1041: \subsecidx{sin}$(x)$: sine of $x$.
! 1042:
! 1043: \syn{gsin}{x,\var{prec}}.
! 1044:
! 1045: \subsecidx{sinh}$(x)$: hyperbolic sine of $x$.
! 1046:
! 1047: \syn{gsh}{x,\var{prec}}.
! 1048:
! 1049: \subsecidx{sqr}$(x)$: square of $x$. Not identical to $x*x$ in
! 1050: the case of $2$-adics, where it returns a more precise result.
! 1051:
! 1052: \syn{gsqr}{x}.
! 1053:
! 1054: \subsecidx{sqrt}$(x)$: principal branch of the square root of $x$,
! 1055: i.e.~such that $\text{Arg}(\text{sqrt}(x))\in{} ]-\pi/2, \pi/2]$, or in other
! 1056: words such that $\Re(\text{sqrt}(x))>0$ or $\Re(\text{sqrt}(x))=0$ and
! 1057: $\Im(\text{sqrt}(x))\ge 0$. If $x\in \R$ and $x<0$, then the result is
! 1058: complex with positive imaginary part.
! 1059:
! 1060: Integermod a prime and $p$-adics are allowed as arguments. In that case,
! 1061: the square root (if it exists) which is returned is the one whose
! 1062: first $p$-adic digit (or its unique $p$-adic digit in the case of
! 1063: integermods) is in the interval $[0,p/2]$. When the argument is an
! 1064: integermod a non-prime (or a non-prime-adic), the result is undefined
! 1065: (and the function may not even return).
! 1066:
! 1067: \syn{gsqrt}{x,\var{prec}}.
! 1068:
! 1069: \subsecidx{tan}$(x)$: tangent of $x$.
! 1070:
! 1071: \syn{gtan}{x,\var{prec}}.
! 1072:
! 1073: \subsecidx{tanh}$(x)$: hyperbolic tangent of $x$.
! 1074:
! 1075: \syn{gth}{x,\var{prec}}.
! 1076:
! 1077: \subsecidx{teichmuller}$(x)$: Teichm\"uller character of the $p$-adic number
! 1078: $x$.
! 1079:
! 1080: \syn{teich}{x}.
! 1081:
! 1082: \subsecidx{theta}$(q,z)$: Jacobi sine theta-function.
! 1083:
! 1084: \syn{theta}{q,z,\var{prec}}.
! 1085:
! 1086: \subsecidx{thetanullk}$(q,k)$: $k$-th derivative at $z=0$ of
! 1087: $\kbd{theta}(q,z)$.
! 1088:
! 1089: \syn{thetanullk}{q,k,\var{prec}}, where $k$ is a \kbd{long}.
! 1090:
! 1091: \subsecidx{weber}$(x,\{\fl=0\})$: one of Weber's three $f$ functions.
! 1092: If $\fl=0$, returns
! 1093: $$f(x)=\exp(-i\pi/24)\cdot\eta((x+1)/2)\,/\,\eta(x) \quad\hbox{such that}\quad
! 1094: j=(f^{24}-16)^3/f^{24}\,,$$
! 1095: where $j$ is the elliptic $j$-invariant (see the function \kbd{ellj}).
! 1096: If $\fl=1$, returns
! 1097: $$f_1(x)=\eta(x/2)\,/\,\eta(x)\quad\hbox{such that}\quad
! 1098: j=(f_1^{24}+16)^3/f_1^{24}\,.$$
! 1099: Finally, if $\fl=2$, returns
! 1100: $$f_2(x)=\sqrt{2}\eta(2x)\,/\,\eta(x)\quad\hbox{such that}\quad
! 1101: j=(f_2^{24}+16)^3/f_2^{24}.$$
! 1102: Note the identities $f^8=f_1^8+f_2^8$ and $ff_1f_2=\sqrt2$.
! 1103:
! 1104: \syn{weber0}{x,\fl,\var{prec}}, or
! 1105: $\teb{wf}(x,\var{prec})$, $\teb{wf1}(x,\var{prec})$ or
! 1106: $\teb{wf2}(x,\var{prec})$.
! 1107:
! 1108: \subsecidx{zeta}$(s)$: Riemann's zeta function\sidx{Riemann zeta-function}
! 1109: $\zeta(s)=\sum_{n\ge1}n^{-s}$, computed using the \idx{Euler-Maclaurin}
! 1110: summation formula, except when $s$ is of type integer, in which case it
! 1111: is computed using \idx{Bernoulli numbers} for
! 1112: $s\le0$ or $s>0$ and even, and using modular forms for $s>0$ and odd.
! 1113:
! 1114: \syn{gzeta}{s,\var{prec}}.
! 1115:
! 1116: \section{Arithmetic functions}\label{se:arithmetic}
! 1117:
! 1118: These functions are by definition functions whose natural domain of
! 1119: definition is either $\Z$ (or $\Z_{>0}$), or sometimes polynomials
! 1120: over a base ring. Functions which concern polynomials exclusively will be
! 1121: explained in the next section. The way these functions are used is
! 1122: completely different from transcendental functions: in general only the types
! 1123: integer and polynomial are accepted as arguments. If a vector or matrix type
! 1124: is given, the function will be applied on each coefficient independently.
! 1125:
! 1126: In the present version \vers{}, all arithmetic functions in the narrow
! 1127: sense of the word~--- Euler's totient\sidx{Euler totient function}
! 1128: function, the M\"obius\sidx{moebius} function, the sums over divisors or
! 1129: powers of divisors etc.--- call, after trial division by small primes, the
! 1130: same versatile factoring machinery described under \kbd{factorint}.
! 1131: It includes \idx{Pollard Rho}, \idx{ECM} and \idx{MPQS}
! 1132: stages, and has an early exit option for the functions \teb{moebius} and (the
! 1133: integer function underlying) \teb{issquarefree}.
! 1134: Note that it relies on a (fairly strong) probabilistic primality test:
! 1135: numbers found to be strong pseudo-primes after 10 successful trials of
! 1136: the \idx{Rabin-Miller} test are declared primes.
! 1137:
! 1138: \bigskip
! 1139: \subsecidx{Qfb}$(a,b,c,\{D=0.\})$: creates the binary quadratic form
! 1140: $ax^2+bxy+cy^2$. If $b^2-4ac>0$, initialize \idx{Shanks}' distance
! 1141: function to $D$.
! 1142:
! 1143: \syn{Qfb0}{a,b,c,D,\var{prec}}. Also available are
! 1144: $\teb{qfi}(a,b,c)$ (when $b^2-4ac<0$), and
! 1145: $\teb{qfr}(a,b,c,d)$ (when $b^2-4ac>0$).\sidx{binary quadratic form}
! 1146:
! 1147:
! 1148: \subsecidx{addprimes}$(\{x=[\,]\})$: adds the primes contained in the vector
! 1149: $x$ (or the single integer $x$) to the table computed upon GP initialization
! 1150: (by \kbd{pari\_init} in library mode), and returns a row vector whose first
! 1151: entries contain all primes added by the user and whose last entries have been
! 1152: filled up with 1's. In total the returned row vector has 100 components.
! 1153: Whenever \kbd{factor} or \kbd{smallfact} is subsequently called, first the
! 1154: primes in the table computed by \kbd{pari\_init} will be checked, and then
! 1155: the additional primes in this table. If $x$ is empty or omitted, just returns
! 1156: the current list of extra primes.
! 1157:
! 1158: The entries in $x$ are not checked for primality. They need only be positive
! 1159: integers not divisible by any of the pre-computed primes. It's in fact a nice
! 1160: trick to add composite numbers, which for example the function
! 1161: $\kbd{factor}(x,0)$ was not able to factor. In case the message ``impossible
! 1162: inverse modulo $\langle${\it some integermod}$\rangle$'' shows up afterwards,
! 1163: you have just stumbled over a non-trivial factor. Note that the arithmetic
! 1164: functions in the narrow sense, like \teb{eulerphi}, do {\it not\/} use this
! 1165: extra table.
! 1166:
! 1167: The present PARI version \vers{} allows up to 100 user-specified
! 1168: primes to be appended to the table. This limit may be changed
! 1169: by altering \kbd{NUMPRTBELT} in file \kbd{init.c}. To remove primes from the
! 1170: list use \kbd{removeprimes}.
! 1171:
! 1172: \syn{addprimes}{x}.
! 1173:
! 1174: \subsecidx{bestappr}$(x,k)$: if $x\in\R$, finds the best rational
! 1175: approximation to $x$ with denominator at most equal to $k$ using continued
! 1176: fractions.
! 1177:
! 1178: \syn{bestappr}{x,k}.
! 1179:
! 1180: \subsecidx{bezout}$(x,y)$: finds $u$ and $v$ minimal in a
! 1181: natural sense such that $x*u+y*v=\text{gcd}(x,y)$. The arguments
! 1182: must be both integers or both polynomials, and the result is a
! 1183: row vector with three components $u$, $v$, and $\text{gcd}(x,y)$.
! 1184:
! 1185: \syn{vecbezout}{x,y} to get the vector, or $\teb{gbezout}(x,y, \&u, \&v)$
! 1186: which gives as result the address of the created gcd, and puts
! 1187: the addresses of the corresponding created objects into $u$ and $v$.
! 1188:
! 1189: \subsecidx{bezoutres}$(x,y)$: as \kbd{bezout}, with the resultant of $x$ and
! 1190: $y$ replacing the gcd.
! 1191:
! 1192: \syn{vecbezoutres}{x,y} to get the vector, or $\teb{subresext}(x,y, \&u,
! 1193: \&v)$ which gives as result the address of the created gcd, and puts the
! 1194: addresses of the corresponding created objects into $u$ and $v$.
! 1195:
! 1196: \subsecidx{bigomega}$(x)$: number of prime divisors of $x$ counted with
! 1197: multiplicity. $x$ must be an integer.
! 1198:
! 1199: \syn{bigomega}{x}, the result is a \kbd{long}.
! 1200:
! 1201: \subsecidx{binomial}$(x,y)$: \idx{binomial coefficient} $\binom x y$.
! 1202: Here $y$ must be an integer, but $x$ can be any PARI object.
! 1203:
! 1204: \syn{binome}{x,y}, where $y$ must be a \kbd{long}.
! 1205:
! 1206: \subsecidx{chinese}$(x,y)$: if $x$ and $y$ are both integermods or both
! 1207: polmods, creates (with the same type) a $z$ in the same residue class
! 1208: as $x$ and in the same residue class as $y$, if it is possible.
! 1209:
! 1210: This function also allows vector and matrix arguments, in which case the
! 1211: operation is recursively applied to each component of the vector or matrix.
! 1212: For polynomial arguments, it is applied to each coefficient. Finally
! 1213: $\kbd{chinese}(x,x) = x$ regardless of the type of $x$; this allows vector
! 1214: arguments to contain other data, so long as they are identical in both
! 1215: vectors.
! 1216:
! 1217: \syn{chinois}{x,y}.
! 1218:
! 1219: \subsecidx{content}$(x)$: computes the gcd of all the coefficients of $x$,
! 1220: when this gcd makes sense. If $x$ is a scalar, this simply returns $x$. If $x$
! 1221: is a polynomial (and by extension a power series), it gives the usual content
! 1222: of $x$. If $x$ is a rational function, it gives the ratio of the contents of
! 1223: the numerator and the denominator. Finally, if $x$ is a vector or a matrix,
! 1224: it gives the gcd of all the entries.
! 1225:
! 1226: \syn{content}{x}.
! 1227:
! 1228: \subsecidx{contfrac}$(x,\{b\},\{lmax\})$: creates the row vector whose
! 1229: components are the partial quotients of the \idx{continued fraction}
! 1230: expansion of $x$, the number of partial quotients being limited to $lmax$.
! 1231: If $x$ is a real number, the expansion stops at the last significant partial
! 1232: quotient if $lmax$ is omitted. $x$ can also be a rational function or a power
! 1233: series.
! 1234:
! 1235: If a vector $b$ is supplied, the numerators will be equal to the coefficients
! 1236: of $b$. The length of the result is then equal to the length of $b$, unless a
! 1237: partial remainder is encountered which is equal to zero. In which case the
! 1238: expansion stops. In the case of real numbers, the stopping criterion is thus
! 1239: different from the one mentioned above since, if $b$ is too long, some partial
! 1240: quotients may not be significant.
! 1241:
! 1242: \syn{contfrac0}{x,b,lmax}. Also available are
! 1243: $\teb{gboundcf}(x,lmax)$, $\teb{gcf}(x)$, or $\teb{gcf2}(b,x)$, where $lmax$
! 1244: is a C integer.
! 1245:
! 1246: \subsecidx{contfracpnqn}$(x)$: when $x$ is a vector or a one-row matrix, $x$
! 1247: is considered as the list of partial quotients $[a_0,a_1,\dots,a_n]$ of a
! 1248: rational number, and the result is the 2 by 2 matrix
! 1249: $[p_n,p_{n-1};q_n,q_{n-1}]$ in the standard notation of continued fractions,
! 1250: so $p_n/q_n=a_0+1/(a_1+\dots+1/a_n)\dots)$. If $x$ is a matrix with two rows
! 1251: $[b_0,b_1,\dots,b_n]$ and $[a_0,a_1,\dots,a_n]$, this is then considered as a
! 1252: generalized continued fraction and we have similarly
! 1253: $p_n/q_n=1/b_0(a_0+b_1/(a_1+\dots+b_n/a_n)\dots)$. Note that in this case one
! 1254: usually has $b_0=1$.
! 1255:
! 1256: \syn{pnqn}{x}.
! 1257:
! 1258: \subsecidx{core}$(n,\{\fl=0\})$: if $n$ is a non-zero integer written as
! 1259: $n=df^2$ with $d$ squarefree, returns $d$. If $\fl$ is non-zero,
! 1260: returns the two-element row vector $[d,f]$.
! 1261:
! 1262: \syn{core0}{n,\fl}.
! 1263: Also available are
! 1264: $\teb{core}(n)$ (= \teb{core}$(n,0)$) and
! 1265: $\teb{core2}(n)$ (= \teb{core}$(n,1)$).
! 1266:
! 1267: \subsecidx{coredisc}$(n,\{\fl\})$: if $n$ is a non-zero integer written as
! 1268: $n=df^2$ with $d$ fundamental discriminant (including 1), returns $d$. If
! 1269: $\fl$ is non-zero, returns the two-element row vector $[d,f]$. Note that if
! 1270: $n$ is not congruent to 0 or 1 modulo 4, $f$ will be a half integer and not
! 1271: an integer.
! 1272:
! 1273: \syn{coredisc0}{n,\fl}.
! 1274: Also available are
! 1275: $\teb{coredisc}(n)$ (= \teb{coredisc}$(n,0)$) and
! 1276: $\teb{coredisc2}(n)$ (= \teb{coredisc}$(n,1)$).
! 1277:
! 1278: \subsecidx{dirdiv}$(x,y)$: $x$ and $y$ being vectors of perhaps different
! 1279: lengths but with $y[1]\neq 0$ considered as \idx{Dirichlet series}, computes
! 1280: the quotient of $x$ by $y$, again as a vector.
! 1281:
! 1282: \syn{dirdiv}{x,y}.
! 1283:
! 1284: \subsecidx{direuler}$(p=a,b,\var{expr})$: computes the \idx{Dirichlet series}
! 1285: to $b$ terms of the \idx{Euler product} of expression \var{expr} as $p$ ranges
! 1286: through the primes from $a$ to $b$. \var{expr} must be a polynomial or
! 1287: rational function in
! 1288: another variable than $p$ (say $X$) and $\var{expr}(X)$ is understood as the
! 1289: Dirichlet series (or more precisely the local factor) $\var{expr}(p^{-s})$.
! 1290:
! 1291: \synt{direuler}{entree *ep, GEN a, GEN b, char *expr}
! 1292: (see the section on sums and products for explanations of this).
! 1293:
! 1294: \subsecidx{dirmul}$(x,y)$: $x$ and $y$ being vectors of perhaps different
! 1295: lengths considered as \idx{Dirichlet series}, computes the product of
! 1296: $x$ by $y$, again as a vector.
! 1297:
! 1298: \syn{dirmul}{x,y}.
! 1299:
! 1300: \subsecidx{divisors}$(x)$: creates a row vector whose components are the
! 1301: positive divisors of the integer $x$ in increasing order. The factorization
! 1302: of $x$ (as output by \tet{factor}) can be used instead.
! 1303:
! 1304: \syn{divisors}{x}.
! 1305:
! 1306: \subsecidx{eulerphi}$(x)$: Euler's $\phi$
! 1307: (totient)\sidx{Euler totient function} function of $x$.
! 1308: $x$ must be of type integer.
! 1309:
! 1310: \syn{phi}{x}.
! 1311:
! 1312: \subsecidx{factor}$(x,\{\var{lim}=-1\})$: general factorization function.
! 1313: If $x$ is of type integer, rational, polynomial or rational function,
! 1314: the result is a
! 1315: two-column matrix, the first column being the irreducibles dividing $x$
! 1316: (prime numbers or polynomials), and the second the exponents. If $x$ is a
! 1317: vector or a matrix, the factoring is done componentwise (hence the result is
! 1318: a vector or matrix of two-column matrices).
! 1319:
! 1320: If $x$ is of type integer or rational, an argument \var{lim} can be added,
! 1321: meaning that we look only for factors up to \var{lim}, or to \kbd{primelimit},
! 1322: whichever is lowest (except when $\var{lim}=0$ where the effect is identical
! 1323: to setting $\var{lim}=\kbd{primelimit}$). Hence in this case, the remaining
! 1324: part is not necessarily prime. See \teb{factorint} for more information about
! 1325: the algorithms used.
! 1326:
! 1327: The polynomials or rational functions to be factored must have scalar
! 1328: coefficients. In particular PARI does {\it not\/} know how to factor
! 1329: multivariate polynomials.
! 1330:
! 1331: Note that PARI tries to guess in a sensible way over which ring you want to
! 1332: factor. Note also that factorization of polynomials is done up to
! 1333: multiplication by a constant. In particular, the factors of rational
! 1334: polynomials will have integer coefficients, and the content of a polynomial or
! 1335: rational function is discarded and not included in the factorization. If
! 1336: you need to, you can always ask for the content explicitly:
! 1337:
! 1338: \bprog%
! 1339: ? factor(t\pow2 + 5/2*t + 1)
! 1340: \%1 =
! 1341: [2*t + 1 1]
! 1342: \smallskip%
! 1343: [t + 2 1]
! 1344: \smallskip%
! 1345: ? content(t\pow2 + 5/2*t + 1)
! 1346: \%2 = 1/2%
! 1347: \eprog
! 1348:
! 1349: \noindent See also \teb{factornf}.
! 1350:
! 1351: \syn{factor0}{x,\var{lim}}, where \var{lim} is a C integer.
! 1352: Also available are
! 1353: $\teb{factor}(x)$ (= $\teb{factor0}(x,-1)$),
! 1354: $\teb{smallfact}(x)$ (= $\teb{factor0}(x,0)$).
! 1355:
! 1356: \subsecidx{factorback}$(f,\{nf\})$: $f$ being any factorization, gives back
! 1357: the factored object. If a second argument $\var{nf}$ is supplied, $f$ is
! 1358: assumed to be a prime ideal factorization in the number field $\var{nf}$.
! 1359: The resulting ideal is given in HNF\sidx{Hermite normal form} form.
! 1360:
! 1361: \syn{factorback}{f,\var{nf\/}}, where an omitted
! 1362: $\var{nf}$ is entered as \kbd{NULL}.
! 1363:
! 1364: \subsecidx{factorcantor}$(x,p)$: factors the polynomial $x$ modulo the
! 1365: prime $p$, using distinct degree plus
! 1366: \idx{Cantor-Zassenhaus}\sidx{Zassenhaus}. The coefficients of $x$ must be
! 1367: operation-compatible with $\Z/p\Z$. The result is a two-column matrix, the
! 1368: first column being the irreducible polynomials dividing $x$, and the second
! 1369: the exponents. If you want only the {\it degrees\/} of the irreducible
! 1370: polynomials (for example for computing an $L$-function), use
! 1371: $\kbd{factormod}(x,p,1)$. Note that the \kbd{factormod} algorithm is
! 1372: usually faster than \kbd{factorcantor}.
! 1373:
! 1374: \syn{factcantor}{x,p}.
! 1375:
! 1376: \subsecidx{factorff}$(x,p,a)$: factors the polynomial $x$ in the field
! 1377: $\F_q$ defined by the irreducible polynomial $a$ over $\F_p$. The
! 1378: coefficients of $x$ must be operation-compatible with $\Z/p\Z$. The result
! 1379: is a two-column matrix, the first column being the irreducible polynomials
! 1380: dividing $x$, and the second the exponents. It is recommended to use for
! 1381: the variable of $a$ (which will be used as variable of a polmod) a name
! 1382: distinct from the other variables used, so that a \kbd{lift()} of the
! 1383: result will be legible.
! 1384:
! 1385: \syn{factmod9}{x,p,a}.
! 1386:
! 1387: \subsecidx{factorial}$(x)$ or $x!$: factorial of $x$. The expression $x!$
! 1388: gives a result which is an integer, while $\kbd{fact}(x)$ gives a real
! 1389: number.
! 1390:
! 1391: \syn{mpfact}{x} for $x!$ and
! 1392: $\teb{mpfactr}(x,\var{prec})$ for $\kbd{fact}(x)$. $x$ must be a \kbd{long}
! 1393: integer and not a PARI integer.
! 1394:
! 1395: \subsecidx{factorint}$(n,\{\fl=0\})$: factors the integer n using a
! 1396: combination of the \idx{Pollard Rho} method (with modifications due to
! 1397: Brent), \idx{Lenstra}'s \idx{ECM} (with modifications by Montgomery),
! 1398: and \idx{MPQS} (the latter adapted from the \idx{LiDIA} code with the kind
! 1399: permission of the LiDIA
! 1400: maintainers), as well as a search for pure powers with exponents$\le 10$.
! 1401: The output is a two-column matrix as for \kbd{factor}.
! 1402:
! 1403: This gives direct access to the integer factoring engine called by most
! 1404: arithmetical functions. \fl\ is optional; its binary digits mean 1: avoid
! 1405: MPQS, 2: skip first stage ECM (we may still fall back to it later), 4: avoid
! 1406: Rho, 8: don't run final ECM (as a result, a huge composite may be declared
! 1407: to be prime). Note that a (strong) probabilistic primality test is used;
! 1408: thus composites might (very rarely) not be detected.
! 1409:
! 1410: The machinery underlying this function is still in a somewhat experimental
! 1411: state, but should be much faster on average than pure ECM as used by all
! 1412: PARI versions up to 2.0.8, at the expense of heavier memory use. You are
! 1413: invited to play with the flag settings and watch the internals at work by
! 1414: using GP's \tet{debuglevel} default parameter (level 3 shows just the
! 1415: outline, 4 turns on time keeping, 5 and above show an increasing amount
! 1416: of internal details). If you see anything funny happening, please let
! 1417: us know.
! 1418:
! 1419: \syn{factorint}{n,\fl}.
! 1420:
! 1421: \subsecidx{factormod}$(x,p,\{\fl=0\})$: factors the polynomial $x$ modulo
! 1422: the prime integer $p$, using \idx{Berlekamp}. The coefficients of $x$ must be
! 1423: operation-compatible with $\Z/p\Z$. The result is a two-column matrix, the
! 1424: first column being the irreducible polynomials dividing $x$, and the second
! 1425: the exponents. If $\fl$ is non-zero, outputs only the {\it degrees} of the
! 1426: irreducible polynomials (for example, for computing an $L$-function). A
! 1427: different algorithm for computing the mod $p$ factorization is
! 1428: \kbd{factorcantor} which is sometimes faster.
! 1429:
! 1430: \syn{factormod}{x,p,\fl}. Also available are
! 1431: $\teb{factmod}(x,p)$ (which is equivalent to $\teb{factormod}(x,p,0)$) and
! 1432: $\teb{simplefactmod}(x,p)$ (= $\teb{factormod}(x,p,1)$).
! 1433:
! 1434: \subsecidx{fibonacci}$(x)$: $x^{\text{th}}$ Fibonacci number.
! 1435:
! 1436: \syn{fibo}{x}. $x$ must be a \kbd{long}.
! 1437:
! 1438: \subsecidx{gcd}$(x,y,\{\fl=0\})$: creates the greatest common divisor of $x$
! 1439: and $y$. $x$ and $y$ can be of quite general types, for instance both
! 1440: rational numbers. Vector/matrix types are also accepted, in which case
! 1441: the GCD is taken recursively on each component. Note that for these
! 1442: types, \kbd{gcd} is not commutative.
! 1443:
! 1444: If $\fl=0$, use \idx{Euclid}'s algorithm.
! 1445:
! 1446: If $\fl=1$, use the modular gcd algorithm ($x$ and $y$ have to be
! 1447: polynomials, with integer coefficients).
! 1448:
! 1449: If $\fl=2$, use the \idx{subresultant algorithm}.
! 1450:
! 1451: \syn{gcd0}{x,y,\fl}. Also available are
! 1452: $\teb{ggcd}(x,y)$, $\teb{modulargcd}(x,y)$, and $\teb{srgcd}(x,y)$
! 1453: corresponding to $\fl=0$, $1$ and $2$ respectively.
! 1454:
! 1455: \subsecidx{hilbert}$(x,y,\{p\})$: \idx{Hilbert symbol} of $x$ and $y$ modulo
! 1456: $p$. If $x$ and $y$ are of type integer or fraction, an explicit third
! 1457: parameter $p$ must be supplied, $p=0$ meaning the place at infinity.
! 1458: Otherwise, $p$ needs not be given, and $x$ and $y$ can be of compatible types
! 1459: integer, fraction, real, integermod or $p$-adic.
! 1460:
! 1461: \syn{hil}{x,y,p}.
! 1462:
! 1463: \subsecidx{isfundamental}$(x)$: true (1) if $x$ is equal to 1 or to the
! 1464: discriminant of a quadratic field, false (0) otherwise.
! 1465:
! 1466: \syn{gisfundamental}{x}, but the
! 1467: simpler function $\teb{isfundamental}(x)$ which returns a \kbd{long}
! 1468: should be used if $x$ is known to be of type integer.
! 1469:
! 1470: \subsecidx{isprime}$(x)$: true (1) if $x$ is a strong pseudo-prime
! 1471: for 10 randomly chosen bases, false (0) otherwise.
! 1472:
! 1473: \syn{gisprime}{x}, but the
! 1474: simpler function $\teb{isprime}(x)$ which returns a \kbd{long}
! 1475: should be used if $x$ is known to be of type integer.
! 1476:
! 1477: \subsecidx{ispseudoprime}$(x)$: true (1) if $x$ is a strong
! 1478: pseudo-prime for a randomly chosen base, false (0) otherwise.
! 1479:
! 1480: \syn{gispsp}{x}, but the
! 1481: simpler function $\teb{ispsp}(x)$ which returns a \kbd{long}
! 1482: should be used if $x$ is known to be of type integer.
! 1483:
! 1484: \subsecidx{issquare}$(x,\{\&n\})$: true (1) if $x$ is square, false (0) if
! 1485: not. $x$ can be of any type. If $n$ is given and an exact square root had to
! 1486: be computed in the checking process, puts that square root in $n$. This is in
! 1487: particular the case when $x$ is an integer or a polynomial. This is {\it not}
! 1488: the case for intmods (use quadratic reciprocity) or series (only check the
! 1489: leading coefficient).
! 1490:
! 1491: \syn{gcarrecomplet}{x,\&n}. Also available is $\teb{gcarreparfait}(x)$.
! 1492:
! 1493: \subsecidx{issquarefree}$(x)$: true (1) if $x$ is squarefree, false (0) if not.
! 1494: Here $x$ can be an integer or a polynomial.
! 1495:
! 1496: \syn{gissquarefree}{x}, but the
! 1497: simpler function $\teb{issquarefree}(x)$ which returns a \kbd{long}
! 1498: should be used if $x$ is known to be of type integer. This \teb{issquarefree}
! 1499: is just the square of the M\"obius\sidx{moebius} function, and is computed
! 1500: as a multiplicative arithmetic function much like the latter.
! 1501:
! 1502: \subsecidx{kronecker}$(x,y)$:
! 1503: Kronecker\sidx{Kronecker symbol}\sidx{Legendre symbol}
! 1504: (i.e.~generalized Legendre) symbol $\left(\dfrac{x}{y}\right)$. $x$ and $y$
! 1505: must be of type integer.
! 1506:
! 1507: \syn{kronecker}{x,y}, the result ($0$ or $\pm 1$) is a \kbd{long}.
! 1508:
! 1509: \subsecidx{lcm}$(x,y)$: least common multiple of $x$ and $y$, i.e.~such
! 1510: that $\text{lcm}(x,y)*\text{gcd}(x,y)=\text{abs}(x*y)$.
! 1511:
! 1512: \syn{glcm}{x,y}.
! 1513:
! 1514: \subsecidx{moebius}$(x)$: M\"obius $\mu$-function of $x$. $x$ must be of type
! 1515: integer.
! 1516:
! 1517: \syn{mu}{x}, the result ($0$ or $\pm 1$) is a \kbd{long}.
! 1518:
! 1519: \subsecidx{nextprime}$(x)$: finds the smallest prime greater than or
! 1520: equal to $x$. $x$ can be of any real type. Note that if $x$ is a prime,
! 1521: this function returns $x$ and not the smallest prime strictly larger than $x$.
! 1522:
! 1523: \syn{nextprime}{x}.
! 1524:
! 1525: \subsecidx{numdiv}$(x)$: number of divisors of $x$. $x$ must be of type
! 1526: integer, and the result is a \kbd{long}.
! 1527:
! 1528: \syn{numbdiv}{x}.
! 1529:
! 1530: \subsecidx{omega}$(x)$: number of distinct prime divisors of $x$. $x$ must be
! 1531: of type integer.
! 1532:
! 1533: \syn{omega}{x}, the result is a \kbd{long}.
! 1534:
! 1535: \subsecidx{precprime}$(x)$: finds the largest prime less than or equal to
! 1536: $x$. $x$ can be of any real type. Returns 0 if $x\le1$.
! 1537: Note that if $x$ is a prime, this function returns $x$ and not the largest
! 1538: prime strictly smaller than $x$.
! 1539:
! 1540: \syn{precprime}{x}.
! 1541:
! 1542: \subsecidx{prime}$(x)$: the $x^{\text{th}}$ prime number, which must be among
! 1543: the precalculated primes.
! 1544:
! 1545: \syn{prime}{x}. $x$ must be a \kbd{long}.
! 1546:
! 1547: \subsecidx{primes}$(x)$: creates a row vector whose components
! 1548: are the first $x$ prime numbers, which must be among the precalculated primes.
! 1549:
! 1550: \syn{primes}{x}. $x$ must be a \kbd{long}.
! 1551:
! 1552: \subsecidx{qfbclassno}$(x,\{\fl=0\})$: class number of the quadratic field
! 1553: of discriminant $x$. In the present version \vers, a simple algorithm is used
! 1554: for $x>0$, so $x$ should not be too large (say $x<10^7$) for the time to be
! 1555: reasonable. On the other hand, for $x<0$ one can reasonably compute
! 1556: classno($x$) for $|x|<10^{25}$, since the method used is \idx{Shanks}' method
! 1557: which is in $O(|x|^{1/4})$. For larger values of $|D|$, see
! 1558: \kbd{quadclassunit}.
! 1559:
! 1560: If $\fl=1$, compute the class number using \idx{Euler product}s and the
! 1561: functional equation. However, it is in $O(|x|^{1/2})$.
! 1562:
! 1563: \misctitle{Important warning.} For $D<0$, this function often gives
! 1564: incorrect results when the class group is non-cyclic, because the authors
! 1565: were too lazy to implement \idx{Shanks}' method completely. It is therefore
! 1566: strongly recommended to use either the version with $\fl=1$, the function
! 1567: $\kbd{qfhclassno}(-x)$ if $x$ is known to be a fundamental discriminant, or
! 1568: the function \kbd{quadclassunit}.
! 1569:
! 1570: \syn{qfbclassno0}{x,\fl}. Also available are
! 1571: $\teb{classno}(x)$ (= $\teb{qfbclassno}(x)$),
! 1572: $\teb{classno2}(x)$ (= $\teb{qfbclassno}(x,1)$), and finally
! 1573: there exists the function $\teb{hclassno}(x)$ which computes the class
! 1574: number of an imaginary quadratic field by counting reduced forms, an $O(|x|)$
! 1575: algorithm. See also \kbd{qfbhclassno}.
! 1576:
! 1577: \subsecidx{qfbcompraw}$(x,y)$ \idx{composition} of the binary quadratic forms
! 1578: $x$ and $y$, without \idx{reduction} of the result. This is useful e.g.~to
! 1579: compute a generating element of an ideal.
! 1580:
! 1581: \syn{compraw}{x,y}.
! 1582:
! 1583: \subsecidx{qfbhclassno}$(x)$: \idx{Hurwitz class number} of $x$, where $x$ is
! 1584: non-negative and congruent to 0 or 3 modulo 4. See also \kbd{qfbclassno}.
! 1585:
! 1586: \syn{hclassno}{x}.
! 1587:
! 1588: \subsecidx{qfbnucomp}$(x,y,l)$: \idx{composition} of the primitive positive
! 1589: definite binary quadratic forms $x$ and $y$ using the NUCOMP and NUDUPL
! 1590: algorithms of \idx{Shanks} (\`a la Atkin). $l$ is any positive constant,
! 1591: but for optimal speed, one should take $l=|D|^{1/4}$, where $D$ is the common
! 1592: discriminant of $x$ and $y$.
! 1593:
! 1594: \syn{nucomp}{x,y,l}. The auxiliary function
! 1595: $\teb{nudupl}(x,l)$ should be used instead for speed when $x=y$.
! 1596:
! 1597: \subsecidx{qfbnupow}$(x,n)$: $n$-th power of the primitive positive definite
! 1598: binary quadratic form $x$ using the NUCOMP and NUDUPL algorithms (see
! 1599: \kbd{qfbnucomp}).
! 1600:
! 1601: \syn{nupow}{x,n}.
! 1602:
! 1603: \subsecidx{qfbpowraw}$(x,n)$: $n$-th power of the binary quadratic form
! 1604: $x$, computed without doing any \idx{reduction} (i.e.~using \kbd{qfbcompraw}).
! 1605: Here $n$ must be non-negative and $n<2^{31}$.
! 1606:
! 1607: \syn{powraw}{x,n} where $n$ must be a \kbd{long}
! 1608: integer.
! 1609:
! 1610: \subsecidx{qfbprimeform}$(x,p)$: prime binary quadratic form of discriminant
! 1611: $x$ whose first coefficient is the prime number $p$. Returns an error if $x$ is not a
! 1612: quadratic residue mod $p$. In the case where $x>0$, the ``distance''
! 1613: component of the form is set equal to zero according to the current
! 1614: precision.
! 1615:
! 1616: \subsecidx{qfbred}$(x,\{\fl=0\},\{D\},\{\var{isqrtD}\},\{\var{sqrtD}\})$:
! 1617: reduces the binary quadratic form $x$. $\fl$ can be any of $0$:
! 1618: default behaviour, uses \idx{Shanks}' distance function $d$,
! 1619: $1$: uses $d$, but performs only a single \idx{reduction} step,
! 1620: $2$: does not compute the distance function $d$, or $3$:
! 1621: does not use $d$, single reduction step.
! 1622:
! 1623: $D$, \var{isqrtD}, \var{sqrtD}, if present, supply the values of the
! 1624: discriminant, $\lfloor \sqrt{D}\rfloor$, and $\sqrt{D}$ respectively
! 1625: (no checking is done of these facts). If $D<0$ these values are useless,
! 1626: and all references to Shanks's distance are irrelevant.
! 1627:
! 1628: \syn{qfbred0}{x,\fl,D,\var{isqrtD},\var{sqrtD\/}}. Use \kbd{NULL}
! 1629: to omit any of $D$, \var{isqrtD}, \var{sqrtD}.
! 1630:
! 1631: \noindent Also available are
! 1632:
! 1633: $\teb{redimag}(x)$ (= $\teb{qfbred}(x)$ where $x$ is definite),
! 1634:
! 1635: \noindent and for indefinite forms:
! 1636:
! 1637: $\teb{redreal}(x)$ (= $\teb{qfbred}(x)$),
! 1638:
! 1639: $\teb{rhoreal}(x)$ (= $\teb{qfbred}(x,1)$),
! 1640:
! 1641: $\teb{redrealnod}(x,sq)$ (= $\teb{qfbred}(x,2,,isqrtD)$),
! 1642:
! 1643: $\teb{rhorealnod}(x,sq)$ (= $\teb{qfbred}(x,3,,isqrtD)$).
! 1644:
! 1645: \syn{primeform}{x,p,\var{prec}}, where the third variable $\var{prec}$ is a
! 1646: \kbd{long}, but is only taken into account when $x>0$.
! 1647:
! 1648: \subsecidx{quadclassunit}$(D,\{\fl=0\},\{\var{tech}=[]\})$:
! 1649: \idx{Buchmann-McCurley}'s sub-exponential algorithm for computing the class
! 1650: group of a quadratic field of discriminant $D$. If $D$ is not fundamental,
! 1651: the function may or may not be defined, but usually is, and often gives the
! 1652: right answer (a warning is issued). The more general function \tet{bnrinit}
! 1653: should be used to compute the class group of an order.
! 1654:
! 1655: This function should be used instead of \kbd{qfbclassno} or \kbd{quadregula}
! 1656: when $D<-10^{25}$, $D>10^{10}$, or when the {\it structure\/} is wanted.
! 1657:
! 1658: If $\fl$ is non-zero {\it and\/} $D>0$, computes the narrow class group and
! 1659: regulator, instead of the ordinary (or wide) ones. In the current version
! 1660: \vers, this doesn't work at all~: use the general function \tet{bnfnarrow}.
! 1661:
! 1662: \var{tech} is a row vector of the form $[c_1,c_2]$, where $c_1$ and $c_2$
! 1663: are positive real numbers which control the execution time and the stack
! 1664: size. To get maximum speed, set $c_2=c$. To get a rigorous result (under
! 1665: \idx{GRH}) you must take $c_2=6$. Reasonable values for $c$ are between
! 1666: $0.1$ and $2$.
! 1667:
! 1668: The result of this function is a vector $v$ with 4 components if $D<0$, and
! 1669: $5$ otherwise. The correspond respectively to
! 1670:
! 1671: $\bullet$ $v[1]$~: the class number
! 1672:
! 1673: $\bullet$ $v[2]$~: a vector giving the structure of the class group as a
! 1674: product of cyclic groups;
! 1675:
! 1676: $\bullet$ $v[3]$~: a vector giving generators of those cyclic groups (as
! 1677: binary quadratic forms).
! 1678:
! 1679: $\bullet$ $v[4]$~: (omitted if $D < 0$) the regulator, computed to an
! 1680: accuracy which is the maximum of an internal accuracy determined by the
! 1681: program and the current default (note that once the regulator is known to a
! 1682: small accuracy it is trivial to compute it to very high accuracy, see the
! 1683: tutorial).
! 1684:
! 1685: $\bullet$ $v[5]$~: a measure of the correctness of the result. If it is
! 1686: close to 1, the result is correct (under \idx{GRH}). If it is close to a
! 1687: larger integer, this shows that the class number is off by a factor equal
! 1688: to this integer, and you must start again with a larger value for $c_1$ or
! 1689: a different random seed. In this case, a warning message is printed.
! 1690:
! 1691: \syn{quadclassunit0}{D,\fl,tech}. Also available are
! 1692: $\teb{buchimag}(D,c_1,c_2)$ and $\teb{buchreal}(D,\fl,c_1,c_2)$.
! 1693:
! 1694: \subsecidx{quaddisc}$(x)$: discriminant of the quadratic field
! 1695: $\Q(\sqrt{x})$, where $x\in\Q$.
! 1696:
! 1697: \syn{quaddisc}{x}.
! 1698:
! 1699: \subsecidx{quadhilbert}$(D,\{\fl=0\})$: relative equation defining the
! 1700: \idx{Hilbert class field} of the quadratic field of discriminant $D$.
! 1701: If $\fl$ is non-zero
! 1702: and $D<0$, outputs $[\var{form},\var{root}(\var{form})]$ (to be used for
! 1703: constructing subfields).
! 1704: Uses complex multiplication in the imaginary case and \idx{Stark units}
! 1705: in the real case.
! 1706:
! 1707: \syn{quadhilbert}{D,\fl,\var{prec}}.
! 1708:
! 1709: \subsecidx{quadgen}$(x)$: creates the quadratic number\sidx{omega}
! 1710: $\omega=(a+\sqrt{x})/2$ where $a=0$ if $x\equiv0\mod4$,
! 1711: $a=1$ if $x\equiv1\mod4$, so that $(1,\omega)$ is an integral basis for
! 1712: the quadratic order of discriminant $x$. $x$ must be an integer congruent to
! 1713: 0 or 1 modulo 4.
! 1714:
! 1715: \syn{quadgen}{x}.
! 1716:
! 1717: \subsecidx{quadpoly}$(D,\{v=x\})$: creates the ``canonical'' quadratic
! 1718: polynomial (in the variable $v$) corresponding to the discriminant $D$,
! 1719: i.e.~the minimal polynomial of $\kbd{quadgen}(x)$. $D$ must be an integer
! 1720: congruent to 0 or 1 modulo 4.
! 1721:
! 1722: \syn{quadpoly0}{x,v}.
! 1723:
! 1724: \subsecidx{quadray}$(D,f,\{\fl=0\})$: relative equation for the ray class
! 1725: field of conductor $f$ for the quadratic field of discriminant $D$ (which
! 1726: can also be a \kbd{bnf}). \fl\ is only meaningful when $D<0$. If it's an odd
! 1727: integer, outputs instead the vector of $[\var{ideal},
! 1728: \var{corresponding root}]$.
! 1729:
! 1730: If $\fl=0$ or 1, uses the $\sigma$ function, while if $\fl>1$, uses the
! 1731: Weierstrass $\wp$ function, which is less efficient and may disappear in
! 1732: future versions (not all special cases have been implemented in this case).
! 1733: Finally, \fl\ can also be a two-component vector $[\lambda,\fl]$, where
! 1734: \fl\ is as above and $\lambda$ is the technical element of bnf necessary
! 1735: for Schertz's method using $\sigma$. In that case, returns 0 if $\lambda$
! 1736: is not suitable.
! 1737:
! 1738: If $D>0$, the function may fail with the following message
! 1739: \bprog%
! 1740: "Cannot find a suitable modulus in FindModulus"
! 1741: \eprog
! 1742: See the comments in \tet{bnrstark} about this problem.
! 1743:
! 1744: \syn{quadray}{D,f,\fl}.
! 1745:
! 1746: \subsecidx{quadregulator}$(x)$: regulator of the quadratic field of positive
! 1747: discriminant $x$. Returns an error if $x$ is not a discriminant (fundamental or not) or
! 1748: if $x$ is a square. See also \kbd{quadclassunit} if $x$ is large.
! 1749:
! 1750: \syn{regula}{x,\var{prec}}.
! 1751:
! 1752: \subsecidx{quadunit}$(x)$: fundamental unit\sidx{fundamental units} of the
! 1753: real quadratic field $\Q(\sqrt x)$ where $x$ is the positive discriminant
! 1754: of the field. If $x$ is not a fundamental discriminant, this probably gives
! 1755: the fundamental unit of the corresponding order. $x$ must be of type
! 1756: integer, and the result is a quadratic number.
! 1757:
! 1758: \syn{fundunit}{x}.
! 1759:
! 1760: \subsecidx{removeprimes}$(\{x=[\,]\})$: removes the primes listed in $x$ from
! 1761: the prime number table. $x$ can also be a single integer. List the current
! 1762: extra primes if $x$ is omitted.
! 1763:
! 1764: \syn{removeprimes}{x}.
! 1765:
! 1766: \subsecidx{sigma}$(x,\{k=1\})$: sum of the $k^{\text{th}}$ powers of the
! 1767: positive divisors of $x$. $x$ must be of type integer.
! 1768:
! 1769: \syn{sumdiv}{x} (= $\teb{sigma}(x)$) or
! 1770: $\teb{gsumdivk}(x,k)$ (= $\teb{sigma}(x,k)$), where $k$ is a C long integer.
! 1771:
! 1772: \subsecidx{sqrtint}$(x)$: integer square root of $x$, which must be of PARI
! 1773: type integer. The result is non-negative and rounded towards zero. A
! 1774: negative $x$ is allowed, and the result in that case is \kbd{I*sqrtint(-x)}.
! 1775:
! 1776: \syn{racine}{x}.
! 1777:
! 1778: \subsecidx{znlog}$(x,g)$: $g$ must be a primitive root mod a prime $p$, and
! 1779: the result is the discrete log of $x$ in the multiplicative group
! 1780: $(\Z/p\Z)^*$. This function using a simple-minded baby-step/giant-step
! 1781: approach and requires $O(\sqrt{p})$ storage, hence it cannot be used for
! 1782: $p$ greater than about $10^13$.
! 1783:
! 1784: \syn{znlog}{x,g}.
! 1785:
! 1786: \subsecidx{znorder}$(x)$: $x$ must be an integer mod $n$, and the result is the
! 1787: order of $x$ in the multiplicative group $(\Z/n\Z)^*$. Returns an error if $x$
! 1788: is not invertible.
! 1789:
! 1790: \syn{order}{x}.
! 1791:
! 1792: \subsecidx{znprimroot}$(x)$: returns a primitive root of $x$, where $x$
! 1793: is a prime power.
! 1794:
! 1795: \syn{gener}{x}.
! 1796:
! 1797: \subsecidx{znstar}$(n)$: gives the structure of the multiplicative group
! 1798: $(\Z/n\Z)^*$ as a 3-component row vector $v$, where $v[1]=\phi(n)$ is the
! 1799: order of that group, $v[2]$ is a $k$-component row-vector $d$ of integers
! 1800: $d[i]$ such that $d[i]>1$ and $d[i]\mid d[i-1]$ for $i \ge 2$ and
! 1801: $(\Z/n\Z)^* \simeq \prod_{i=1}^k(\Z/d[i]\Z)$, and $v[3]$ is a $k$-component row
! 1802: vector giving generators of the image of the cyclic groups $\Z/d[i]\Z$.
! 1803:
! 1804: \syn{znstar}{n}.
! 1805:
! 1806: \section{Functions related to elliptic curves}
! 1807:
! 1808: We have implemented a number of functions which are useful for number
! 1809: theorists working on elliptic curves. We always use \idx{Tate}'s notations.
! 1810: The functions assume that the curve is given by a general Weierstrass
! 1811: model\sidx{Weierstrass equation}
! 1812: $$
! 1813: y^2+a_1xy+a_3y=x^3+a_2x^2+a_4x+a_6,
! 1814: $$
! 1815: where a priori the $a_i$ can be of any scalar type. This curve can be
! 1816: considered as a five-component vector \kbd{E=[a1,a2,a3,a4,a6]}. Points on
! 1817: \kbd{E} are represented as two-component vectors \kbd{[x,y]}, except for the
! 1818: point at infinity, i.e.~the identity element of the group law, represented by
! 1819: the one-component vector \kbd{[0]}.
! 1820:
! 1821: It is useful to have at one's disposal more information. This is given by
! 1822: the function \tet{ellinit} (see there), which usually gives a 19 component
! 1823: vector (which we will call a long vector in this section). If a specific flag
! 1824: is added, a vector with only 13 component will be output (which we will call
! 1825: a medium vector). A medium vector just gives the first 13 components of the
! 1826: long vector corresponding to the same curve, but is of course faster to
! 1827: compute. The following \idx{member functions} are available to deal with the
! 1828: output of \kbd{ellinit}:
! 1829: \settabs\+xxxxxxxxxxxxxxxxxx&: &\cr
! 1830:
! 1831: \+ \kbd{a1}--\kbd{a6}, \kbd{b2}--\kbd{b8}, \kbd{c4}--\kbd{c6} &: &
! 1832: coefficients of the elliptic curve.\cr
! 1833:
! 1834: \+ \tet{area} &: & volume of the complex lattice defining $E$.\cr
! 1835:
! 1836: \+ \tet{disc} &: & discriminant of the curve.\cr
! 1837:
! 1838: \+ \tet{j} &: & $j$-invariant of the curve.\cr
! 1839:
! 1840: \+ \tet{omega}&: & $[\omega_1,\omega_2]$, periods forming a basis of
! 1841: the complex lattice defining $E$ ($\omega_1$ is the\cr
! 1842:
! 1843: \+ & & real period, and $\omega_2/\omega_1$ belongs to
! 1844: Poincar\'e's half-plane).\cr
! 1845:
! 1846: \+ \tet{eta} &: & quasi-periods $[\eta_1, \eta_2]$, such that
! 1847: $\eta_1\omega_2-\eta_2\omega_1=i\pi$.\cr
! 1848:
! 1849: \+ \tet{roots}&: & roots of the associated Weierstrass equation.\cr
! 1850:
! 1851: \+ \tet{tate} &: & $[u^2,u,v]$ in the notation of Tate.\cr
! 1852:
! 1853: \+ \tet{w} &: & Mestre's $w$ (this is technical).\cr
! 1854:
! 1855: Their use is best described by an example: assume that $E$ was output by
! 1856: \kbd{ellinit}, then typing \kbd{$E$.disc} will retrieve the curve's
! 1857: discriminant. The member functions \kbd{area}, \kbd{eta} and \kbd{omega} are
! 1858: only available for curves over $\Q$. Conversely, \kbd{tate} and \kbd{w} are
! 1859: only available for curves defined over $\Q_p$.\smallskip
! 1860:
! 1861: Some functions, in particular those relative to height computations (see
! 1862: \kbd{ellheight}) require also that the curve be in minimal Weierstrass
! 1863: form. This is achieved by the function \kbd{ellglobalred}.
! 1864:
! 1865: All functions related to elliptic curves share the prefix \kbd{ell}, and the
! 1866: precise curve we are interested in is always the first argument, in either
! 1867: one of the three formats discussed above, unless otherwise specified. For
! 1868: instance, in functions which do not use the extra information given by long
! 1869: vectors, the curve can be given either as a five-component vector, or by one
! 1870: of the longer vectors computed by \kbd{ellinit}.
! 1871:
! 1872: \subsecidx{elladd}$(E,z1,z2)$: sum of the points $z1$ and $z2$ on the
! 1873: elliptic curve corresponding to the vector $E$.
! 1874:
! 1875: \syn{addell}{E,z1,z2}.
! 1876:
! 1877: \subsecidx{ellak}$(E,n)$: computes the coefficient $a_n$ of the $L$-function
! 1878: of the elliptic curve $E$, i.e.~in principle coefficients of a newform of
! 1879: weight 2 assuming \idx{Taniyama-Weil}. $E$ must be a medium or long vector
! 1880: of the type given by \kbd{ellinit}.
! 1881: For this function to work for every $n$ and not
! 1882: just those prime to the conductor, $E$ must be a minimal Weierstrass
! 1883: equation. If this is not the case, use the function \kbd{ellglobalred} first
! 1884: before using \kbd{ellak}.
! 1885:
! 1886: \syn{akell}{E,n}.
! 1887:
! 1888: \subsecidx{ellan}$(E,n)$: computes the vector of the first $n$ $a_k$
! 1889: corresponding to the elliptic curve $E$. All comments in \kbd{ellak}
! 1890: description remain valid.
! 1891:
! 1892: \syn{anell}{E,n}, where $n$ is a C integer.
! 1893:
! 1894: \subsecidx{ellap}$(E,p,\{\fl=0\})$: computes the $a_p$ corresponding to the
! 1895: elliptic curve $E$ and the prime number $p$. These are defined by the
! 1896: equation $\#E(\F_p) = p+1 - a_p$, where $\#E(\F_p)$ stands for the number
! 1897: of points of the curve $E$ over the finite field $\F_p$. When $\fl$ is $0$,
! 1898: this uses the baby-step giant-step method and a trick due to Mestre. This
! 1899: runs in time $O(p^{1/4})$ and requires $O(p^{1/4})$ storage, hence becomes
! 1900: unreasonable when $p$ has about 30 digits.
! 1901:
! 1902: If $\fl$ is $1$, computes the $a_p$ as a sum of Legendre symbols. This is
! 1903: slower than the previous method as soon as $p$ is greater than 100, say.
! 1904:
! 1905: No checking is done that $p$ is indeed prime. $E$ must be a medium or long
! 1906: vector of the type given by \kbd{ellinit}, defined over $\Q$, $\F_p$ or
! 1907: $\Q_p$.
! 1908:
! 1909: \syn{ellap0}{E,p,\fl}. Also available are $\teb{apell}(E,p)$, corresponding
! 1910: to $\fl=0$, and $\teb{apell2}(E,p)$ ($\fl=1$).
! 1911:
! 1912: \subsecidx{ellbil}$(E,z1,z2)$: if $z1$ and $z2$ are points on the elliptic
! 1913: curve $E$, this function computes the value of the canonical bilinear form on
! 1914: $z1$, $z2$:
! 1915: $$
! 1916: \kbd{ellheight}(E,z1\kbd{+}z2) - \kbd{ellheight}(E,z1) - \kbd{ellheight}(E,z2)
! 1917: $$
! 1918: where \kbd{+} denotes of course addition on $E$. In addition, $z1$ or $z2$
! 1919: (but not both) can be vectors or matrices. Note that this is equal to twice
! 1920: some normalizations. $E$ is assumed to be integral, given by a minimal model.
! 1921:
! 1922: \syn{bilhell}{E,z1,z2,\var{prec}}.
! 1923:
! 1924: \subsecidx{ellchangecurve}$(E,v)$: changes the data for the elliptic curve $E$
! 1925: by changing the coordinates using the vector \kbd{v=[u,r,s,t]}, i.e.~if $x'$
! 1926: and $y'$ are the new coordinates, then $x=u^2x'+r$, $y=u^3y'+su^2x'+t$.
! 1927: The vector $E$ must be a medium or long vector of the type given by
! 1928: \kbd{ellinit}.
! 1929:
! 1930: \syn{coordch}{E,v}.
! 1931:
! 1932: \subsecidx{ellchangepoint}$(x,v)$: changes the coordinates of the point or
! 1933: vector of points $x$ using the vector \kbd{v=[u,r,s,t]}, i.e.~if $x'$ and
! 1934: $y'$ are the new coordinates, then $x=u^2x'+r$, $y=u^3y'+su^2x'+t$ (see also
! 1935: \kbd{ellchangecurve}).
! 1936:
! 1937: \syn{pointch}{x,v}.
! 1938:
! 1939: \subsecidx{elleisnum}$(E,k,\{\fl=0\})$: $E$ being an elliptic curve as
! 1940: output by \kbd{ellinit} (or, alternatively, given by a 2-component vector
! 1941: $[\omega_1,\omega_2]$), and $k$ being an even positive integer, computes
! 1942: the numerical value of the Eisenstein series of weight $k$ at $E$. When
! 1943: \fl\ is non-zero and $k=4$ or 6, returns $g_2$ or $g_3$ with the correct
! 1944: normalization.
! 1945:
! 1946: \syn{elleisnum}{E,k,\fl}.
! 1947:
! 1948: \subsecidx{elleta}$(om)$: returns the two-component row vector
! 1949: $[\eta_1,\eta_2]$ of quasi-periods associated to $\kbd{om} = [\omega_1,
! 1950: \omega_2]$
! 1951:
! 1952: \syn{elleta}{om, \var{prec}}
! 1953:
! 1954: \subsecidx{ellglobalred}$(E)$: calculates the arithmetic conductor, the global
! 1955: minimal model of $E$ and the global \idx{Tamagawa number} $c$. Here $E$ is an
! 1956: elliptic curve given by a medium or long vector of the type given by
! 1957: \kbd{ellinit}, {\it and is supposed to have all its coefficients $a_i$ in}
! 1958: $\Q$. The result is a 3 component vector $[N,v,c]$. $N$ is the arithmetic
! 1959: conductor of the curve, $v$ is itself a vector $[u,r,s,t]$ with rational
! 1960: components. It gives a coordinate change for $E$ over $\Q$ such that the
! 1961: resulting model has integral coefficients, is everywhere minimal, $a_1$ is 0
! 1962: or 1, $a_2$ is 0, 1 or $-1$ and $a_3$ is 0 or 1. Such a model is unique, and
! 1963: the vector $v$ is unique if we specify that $u$ is positive. To get the new
! 1964: model, simply type \kbd{ellchangecurve(E,v)}. Finally $c$ is the product of
! 1965: the local Tamagawa numbers $c_p$, a quantity which enters in the
! 1966: \idx{Birch and Swinnerton-Dyer conjecture}.
! 1967:
! 1968: \syn{globalreduction}{E}.
! 1969:
! 1970: \subsecidx{ellheight}$(E,z,\{\fl=0\})$: global \idx{N\'eron-Tate height} of
! 1971: the point $z$ on the elliptic curve $E$. The vector $E$ must be a long vector
! 1972: of the type given by \kbd{ellinit}, with $\fl=1$. If $\fl=0$, this
! 1973: computation is done using sigma and theta-functions and a trick due to J.
! 1974: Silverman. If $\fl=1$, use Tate's $4^n$ algorithm, which is much slower.
! 1975:
! 1976: \syn{ellheight0}{E,z,\fl,\var{prec}}. The Archimedean
! 1977: contribution alone is given by the library function
! 1978: $\teb{hell}(E,z,\var{prec})$.
! 1979: Also available are $\teb{ghell}(E,z,\var{prec})$ ($\fl=0$) and
! 1980: $\teb{ghell2}(E,z,\var{prec})$ ($\fl=1$).
! 1981:
! 1982: \subsecidx{ellheightmatrix}$(E,x)$: $x$ being a vector of points, this
! 1983: function outputs the Gram matrix of $x$ with respect to the N\'eron-Tate
! 1984: height, in other words, the $(i,j)$ component of the matrix is equal to
! 1985: \kbd{ellbil($E$,x[$i$],x[$j$])}. The rank of this matrix, at least in some
! 1986: approximate sense, gives the rank of the set of points, and if $x$ is a
! 1987: basis of the \idx{Mordell-Weil group} of $E$, its determinant is equal to
! 1988: the regulator of $E$. Note that this matrix should be divided by 2 to be in
! 1989: accordance with certain normalizations. $E$ is assumed to be integral,
! 1990: given by a minimal model.
! 1991:
! 1992: \syn{mathell}{E,x,\var{prec}}.
! 1993:
! 1994: \subsecidx{ellinit}$(E,\{\fl=0\})$: computes some fixed data concerning the
! 1995: elliptic curve given by the five-component vector $E$, which will be
! 1996: essential for most further computations on the curve. The result is a
! 1997: 19-component vector E (called a long vector in this section), shortened
! 1998: to 13 components (medium vector) if $\fl=1$. Both contain the
! 1999: following information in the first 13 components:
! 2000: %
! 2001: $$ a_1,a_2,a_3,a_4,a_6,b_2,b_4,b_6,b_8,c_4,c_6,\Delta,j.$$
! 2002: %
! 2003: In particular, the discriminant is $E[12]$ (or \kbd{$E$.disc}), and the
! 2004: $j$-invariant is $E[13]$ (or \kbd{$E$.j}).
! 2005:
! 2006: The other six components are only present if $\fl$ is $0$ (or omitted!).
! 2007: Their content depends on whether the curve is defined over $\R$ or not:
! 2008: \smallskip
! 2009: $\bullet$ When $E$ is defined over $\R$, $E[14]$ (\kbd{$E$.roots}) is a
! 2010: vector whose three components contain the roots of the associated Weierstrass
! 2011: equation. If the roots are all real, then they are ordered by decreasing
! 2012: value. If only one is real, it is the first component of $E[14]$.
! 2013:
! 2014: $E[15]$ (\kbd{$E$.omega[1]}) is the real period of $E$ (integral of
! 2015: $dx/(2y+a_1x+a_3)$ over the connected component of the identity element of
! 2016: the real points of the curve), and $E[16]$ (\kbd{$E$.omega[2]}) is a complex
! 2017: period. In other words, $\omega_1=E[15]$ and $\omega_2=E[16]$ form a basis of
! 2018: the complex lattice defining $E$ (\kbd{$E$.omega}), with
! 2019: $\tau=\dfrac{\omega_2}{\omega_1}$ having positive imaginary part.
! 2020:
! 2021: $E[17]$ and $E[18]$ are the corresponding values $\eta_1$ and $\eta_2$ such
! 2022: that $\eta_1\omega_2-\eta_2\omega_1=i\pi$, and both can be retrieved by
! 2023: typing \kbd{$E$.eta} (as a row vector whose components are the $\eta_i$).
! 2024:
! 2025: Finally, $E[19]$ (\kbd{$E$.area}) is the volume of the complex lattice defining
! 2026: $E$.\smallskip
! 2027:
! 2028: $\bullet$ When $E$ is defined over $\Q_p$, the $p$-adic valuation of $j$
! 2029: must be negative. Then $E[14]$ (\kbd{$E$.roots}) is the vector with a single
! 2030: component equal to the $p$-adic root of the associated Weierstrass equation
! 2031: corresponding to $-1$ under the Tate parametrization.
! 2032:
! 2033: $E[15]$ is equal to the square of the $u$-value, in the notation of Tate.
! 2034:
! 2035: $E[16]$ is the $u$-value itself, if it belongs to $\Q_p$, otherwise zero.
! 2036:
! 2037: $E[17]$ is the value of Tate's $q$ for the curve $E$.
! 2038:
! 2039: \kbd{$E$.tate} will yield the three-component vector $[u^2,u,q]$.
! 2040:
! 2041: $E[18]$ (\kbd{$E$.w}) is the value of Mestre's $w$ (this is technical), and
! 2042: $E[19]$ is arbitrarily set equal to zero.
! 2043: \smallskip
! 2044: For all other base fields or rings, the last six components are arbitrarily
! 2045: set equal to zero (see also the description of member functions related to
! 2046: elliptic curves at the beginning of this section).
! 2047:
! 2048: \syn{ellinit0}{E,\fl,\var{prec}}. Also available are
! 2049: $\teb{initell}(E,\var{prec})$ ($\fl=0$) and
! 2050: $\teb{smallinitell}(E,\var{prec})$ ($\fl=1$).
! 2051:
! 2052: \subsecidx{ellisoncurve}$(E,z)$: gives 1 (i.e.~true) if the point $z$ is on
! 2053: the elliptic curve $E$, 0 otherwise. If $E$ or $z$ have imprecise coefficients,
! 2054: an attempt is made to take this into account, i.e.~an imprecise equality is
! 2055: checked, not a precise one.
! 2056:
! 2057: \syn{oncurve}{E,z}, and the result is a \kbd{long}.
! 2058:
! 2059: \subsecidx{ellj}$(x)$: elliptic $j$-invariant. $x$ must be a complex number
! 2060: with positive imaginary part, or convertible into a power series or a
! 2061: $p$-adic number with positive valuation.
! 2062:
! 2063: \syn{jell}{x,\var{prec}}.
! 2064:
! 2065: \subsecidx{elllocalred}$(E,p)$: calculates the \idx{Kodaira} type of the
! 2066: local fiber of the elliptic curve $E$ at the prime $p$.
! 2067: $E$ must be given by a medium or
! 2068: long vector of the type given by \kbd{ellinit}, and is assumed to have all
! 2069: its coefficients $a_i$ in $\Z$. The result is a 4-component vector
! 2070: $[f,kod,v,c]$. Here $f$ is the exponent of $p$ in the arithmetic conductor of
! 2071: $E$, and $kod$ is the Kodaira type which is coded as follows:
! 2072:
! 2073: 1 means good reduction (type I$_0$), 2, 3 and 4 mean types II, III and IV
! 2074: respectively, $4+\nu$ with $\nu>0$ means type I$_\nu$;
! 2075: finally the opposite values $-1$, $-2$, etc.~refer to the starred types
! 2076: I$_0^*$, II$^*$, etc. The third component $v$ is itself a vector $[u,r,s,t]$
! 2077: giving the coordinate changes done during the local reduction. Normally, this
! 2078: has no use if $u$ is 1, that is, if the given equation was already minimal.
! 2079: Finally, the last component $c$ is the local \idx{Tamagawa number} $c_p$.
! 2080:
! 2081: \syn{localreduction}{E,p}.
! 2082:
! 2083: \subsecidx{elllseries}$(E,s,\{A=1\})$: $E$ being a medium or long vector
! 2084: given by \kbd{ellinit}, this computes the value of the L-series of $E$ at
! 2085: $s$. It is assumed that $E$ is a minimal model over $\Z$ and that the curve
! 2086: is a modular elliptic curve. The optional parameter $A$ is a cutoff point for
! 2087: the integral, which must be chosen close to 1 for best speed. The result
! 2088: must be independent of $A$, so this allows some internal checking of the
! 2089: function.
! 2090:
! 2091: Note that if the conductor of the curve is large, say greater than $10^{12}$,
! 2092: this function will take an unreasonable amount of time since it uses an
! 2093: $O(N^{1/2})$ algorithm.
! 2094:
! 2095: \syn{lseriesell}{E,s,A,\var{prec}} where $\var{prec}$ is a \kbd{long} and an
! 2096: omitted $A$ is coded as \kbd{NULL}.
! 2097:
! 2098: \subsecidx{ellorder}$(E,z)$: gives the order of the point $z$ on the elliptic
! 2099: curve $E$ if it is a torsion point, zero otherwise. In the present version
! 2100: \vers{}, this is implemented only for elliptic curves defined over $\Q$.
! 2101:
! 2102: \syn{orderell}{E,z}.
! 2103:
! 2104: \subsecidx{ellordinate}$(E,x)$: gives a 0, 1 or 2-component vector containing
! 2105: the $y$-coordinates of the points of the curve $E$ having $x$ as
! 2106: $x$-coordinate.
! 2107:
! 2108: \syn{ordell}{E,x}.
! 2109:
! 2110: \subsecidx{ellpointtoz}$(E,z)$: if $E$ is an elliptic curve with coefficients
! 2111: in $\R$, this computes a complex number $t$ (modulo the lattice defining
! 2112: $E$) corresponding to the point $z$, i.e.~such that, in the standard
! 2113: Weierstrass model, $\wp(t)=z[1],\wp'(t)=z[2]$. In other words, this is the
! 2114: inverse function of \kbd{ellztopoint}.
! 2115:
! 2116: If $E$ has coefficients in $\Q_p$, then either Tate's $u$ is in $\Q_p$, in
! 2117: which case the output is a $p$-adic number $t$ corresponding to the point $z$
! 2118: under the Tate parametrization, or only its square is, in which case the
! 2119: output is $t+1/t$. $E$ must be a long vector output by \kbd{ellinit}.
! 2120:
! 2121: \syn{zell}{E,z,\var{prec}}.
! 2122:
! 2123: \subsecidx{ellpow}$(E,z,n)$: computes $n$ times the point $z$ for the
! 2124: group law on the elliptic curve $E$. Here, $n$ can be in $\Z$, or $n$
! 2125: can be a complex quadratic integer if the curve $E$ has complex multiplication
! 2126: by $n$ (if not, an error message is issued).
! 2127:
! 2128: \syn{powell}{E,z,n}.
! 2129:
! 2130: \subsecidx{ellrootno}$(E,\{p=1\})$: $E$ being a medium or long vector given
! 2131: by \kbd{ellinit}, this computes the local (if $p\neq 1$) or global (if $p=1$)
! 2132: root number of the L-series of the elliptic curve $E$. Note that the global
! 2133: root number is the sign of the functional equation and conjecturally is the
! 2134: parity of the rank of the \idx{Mordell-Weil group}.
! 2135: The equation for $E$ must have
! 2136: coefficients in $\Q$ but need {\it not\/} be minimal.
! 2137:
! 2138: \syn{ellrootno}{E,p} and the result (equal to $\pm1$) is a \kbd{long}.
! 2139:
! 2140: \subsecidx{ellsigma}$(E,z,\{\fl=0\})$: value of the Weierstrass $\sigma$
! 2141: function of the lattice associated to $E$ as given by \kbd{ellinit}
! 2142: (alternatively, $E$ can be given as a lattice $[\omega_1,\omega_2]$).
! 2143:
! 2144: If $\fl=1$, computes an (arbitrary) determination of $\log(\sigma(z))$.
! 2145:
! 2146: If $\fl=2,3$, same using the product expansion instead of theta series.
! 2147: \syn{ellsigma}{E,z,\fl}
! 2148:
! 2149: \subsecidx{ellsub}$(E,z1,z2)$: difference of the points $z1$ and $z2$ on the
! 2150: elliptic curve corresponding to the vector $E$.
! 2151:
! 2152: \syn{subell}{E,z1,z2}.
! 2153:
! 2154: \subsecidx{elltaniyama}$(E)$: computes the modular parametrization of the
! 2155: elliptic curve $E$, where $E$ is given in the (long or medium) format output
! 2156: by \kbd{ellinit}, in the form of a two-component vector $[u,v]$ of power
! 2157: series, given to the current default series precision. This vector is
! 2158: characterized by the following two properties. First the point $(x,y)=(u,v)$
! 2159: satisfies the equation of the elliptic curve. Second, the differential
! 2160: $du/(2v+a_1u+a_3)$ is equal to $f(z)dz$, a differential form on
! 2161: $H/\Gamma_0(N)$ where $N$ is the conductor of the curve. The variable used in
! 2162: the power series for $u$ and $v$ is $x$, which is implicitly understood to be
! 2163: equal to $\exp(2i\pi z)$. It is assumed that the curve is a {\it strong\/}
! 2164: \idx{Weil curve}, and the Manin constant is equal to 1. The equation of
! 2165: the curve $E$ must be minimal (use \kbd{ellglobalred} to get a minimal
! 2166: equation).
! 2167:
! 2168: \syn{taniyama}{E}, and the precision of the result is determined by the
! 2169: global variable \kbd{precdl}.
! 2170:
! 2171: \subsecidx{elltors}$(E,\{\fl=0\})$: if $E$ is an elliptic curve {\it defined
! 2172: over $\Q$}, outputs the torsion subgroup of $E$ as a 3-component vector
! 2173: \kbd{[t,v1,v2]}, where \kbd{t} is the order of the torsion group, \kbd{v1}
! 2174: gives the structure of the torsion group as a product of cyclic groups
! 2175: (sorted by decreasing order), and \kbd{v2} gives generators for these cyclic
! 2176: groups. $E$ must be a long vector as output by \kbd{ellinit}.
! 2177:
! 2178: \bprog%
! 2179: ? E = ellinit([0,0,0,-1,0]);
! 2180: ? elltors(E)
! 2181: \%1 = [4, [2, 2], [[0, 0], [1, 0]]]
! 2182: \eprog
! 2183: Here, the torsion subgroup is isomorphic to $\Z/2\Z \times \Z/2\Z$, with
! 2184: generators $[0,0]$ and $[1,0]$.
! 2185:
! 2186: If $\fl = 0$, use Doud's algorithm~: bound torsion by computing $\#E(\F_p)$
! 2187: for small primes of good reduction, then look for torsion points using
! 2188: Weierstrass parametrization (and Mazur's classification).
! 2189:
! 2190: If $\fl = 1$, use Lutz--Nagell ({\it much} slower), $E$ is allowed to be a
! 2191: medium vector.
! 2192:
! 2193: \syn{elltors0}{E,flag}.
! 2194:
! 2195: \subsecidx{ellwp}$(E,\{z=x\},\{\fl=0\})$:
! 2196:
! 2197: Computes the value at $z$ of the Weierstrass $\wp$ function attached to the
! 2198: elliptic curve $E$ as given by \kbd{ellinit} (alternatively, $E$ can be
! 2199: given as a lattice $[\omega_1,\omega_2]$).
! 2200:
! 2201: If $z$ is omitted or is a simple variable, computes the {\it power
! 2202: series\/} expansion in $z$ (starting $z^{-2}+O(z^2)$). The number of terms
! 2203: to an {\it even\/} power in the expansion is the default serieslength in
! 2204: GP, and the second argument (C long integer) in library mode.
! 2205:
! 2206: Optional \fl\ is (for now) only taken into account when $z$ is numeric, and
! 2207: means 0: compute only $\wp(z)$, 1: compute $[\wp(z),\wp'(z)]$.
! 2208:
! 2209: \syn{ellwp0}{E,z,\fl,\var{prec},\var{precdl}}. Also available is
! 2210: \teb{weipell}$(E,\var{precdl})$ for the power series (in
! 2211: $x=\kbd{polx[0]}$).
! 2212:
! 2213: \subsecidx{ellzeta}$(E,z)$: value of the Weierstrass $\zeta$ function of the
! 2214: lattice associated to $E$ as given by \kbd{ellinit} (alternatively, $E$ can
! 2215: be given as a lattice $[\omega_1,\omega_2]$).
! 2216:
! 2217: \syn{ellzeta}{E,z}.
! 2218:
! 2219: \subsecidx{ellztopoint}$(E,z)$: $E$ being a long vector, computes the
! 2220: coordinates $[x,y]$ on the curve $E$ corresponding to the complex number $z$.
! 2221: Hence this is the inverse function of \kbd{ellpointtoz}. In other words, if
! 2222: the curve is put in Weierstrass form, $[x,y]$ represents the
! 2223: \idx{Weierstrass $\wp$-function} and its derivative.
! 2224: If $z$ is in the lattice defining $E$ over
! 2225: $\C$, the result is the point at infinity $[0]$.
! 2226:
! 2227: \syn{pointell}{E,z,\var{prec}}.
! 2228:
! 2229: \section{Functions related to general number fields}
! 2230:
! 2231: In this section can be found functions which are used almost exclusively for
! 2232: working in general number fields. Other less specific functions can be found
! 2233: in the next section on polynomials. Functions related to quadratic number
! 2234: fields can be found in the section \secref{se:arithmetic} (Arithmetic
! 2235: functions).
! 2236:
! 2237: \noindent We shall use the following conventions:
! 2238:
! 2239: $\bullet$ $\var{\idx{nf}}$ denotes a number field, i.e.~a 9-component vector
! 2240: in the format output by \tet{nfinit}. This contains the basic arithmetic data
! 2241: associated to the number field: signature, maximal order, discriminant, etc.
! 2242:
! 2243: $\bullet$ $\var{\idx{bnf}}$ denotes a big number field, i.e.~a 10-component
! 2244: vector in the format output by \tet{bnfinit}. This contains $\var{nf}$ and
! 2245: the deeper invariants of the field: units, class groups, as well as a lot of
! 2246: technical data necessary for some complex fonctions like \kbd{bnfisprincipal}.
! 2247:
! 2248: $\bullet$ $\var{\idx{bnr}}$ denotes a big ``ray number field'', i.e.~some data
! 2249: structure output by \kbd{bnrinit}, even more complicated than $\var{bnf}$,
! 2250: corresponding to the ray class group structure of the field, for some
! 2251: modulus.
! 2252:
! 2253: $\bullet$ $\var{\idx{rnf}}$ denotes a relative number field (see below).
! 2254: \smallskip
! 2255:
! 2256: $\bullet$ ${\it \idx{ideal}}$ can mean any of the following:
! 2257:
! 2258: \quad -- a $\Z$-basis, in \idx{Hermite normal form}
! 2259: (HNF) or not. In this case $x$ is a square matrix.
! 2260:
! 2261: \quad -- an {\it \idx{idele}}, i.e.~a 2-component vector, the first
! 2262: being an ideal given as a $\Z$--basis, the second being a $r_1+r_2$-component
! 2263: row vector giving the complex logarithmic Archimedean information.
! 2264:
! 2265: \quad -- a $\Z_K$-generating system for an ideal.
! 2266:
! 2267: \quad -- a {\it column} vector $x$ expressing an element of the number field
! 2268: on the integral basis, in which case the ideal is treated as being the
! 2269: principal idele (or ideal) generated by $x$.
! 2270:
! 2271: \quad -- a prime ideal, i.e.~a 5-component vector in the format output by
! 2272: \kbd{idealprimedec}.
! 2273:
! 2274: \quad -- a polmod $x$, i.e.~an algebraic integer, in which case the ideal
! 2275: is treated as being the principal idele generated by $x$.
! 2276:
! 2277: \quad -- an integer or a rational number, also treated as a principal idele.
! 2278:
! 2279: $\bullet$ a {\it\idx{character}} on the Abelian group
! 2280: $\bigoplus (\Z/N_i\Z) g_i$
! 2281: is given by a row vector $\chi = [a_1,\ldots,a_n]$ such that
! 2282: $\chi(\prod g_i^{n_i}) = exp(2i\pi\sum a_i n_i / N_i)$.
! 2283:
! 2284:
! 2285: \misctitle{Warnings:}
! 2286:
! 2287: 1) An element in $\var{nf}$ can be expressed either as a polmod or as a
! 2288: vector of components on the integral basis \kbd{\var{nf}.zk}. It is absolutely
! 2289: essential that all such vectors be {\it column\/} vectors.
! 2290:
! 2291: 2) When giving an ideal by a $\Z_K$ generating system to a function expecting
! 2292: an ideal, it must be ensured that the function understands that it is a
! 2293: $\Z_K$-generating system and not a $\Z$-generating system. When the number of
! 2294: generators is strictly less than the degree of the field, there is no
! 2295: ambiguity and the program assumes that one is giving a $\Z_K$-generating set.
! 2296: When the number of generators is greater than or equal to the degree of the
! 2297: field, however, the program assumes on the contrary that you are giving a
! 2298: $\Z$-generating set. If this is not the case, you {\it must\/} absolutely
! 2299: change it into a $\Z$-generating set, the simplest manner being to use
! 2300: \kbd{idealhnf(\var{nf},$x$)}.
! 2301:
! 2302: Concerning relative extensions, some additional definitions are necessary.
! 2303:
! 2304: $\bullet$ A {\it\idx{relative matrix}\/} will be a matrix whose entries are
! 2305: elements of a (given) number field $\var{nf}$, always expressed as column
! 2306: vectors on the integral basis \kbd{\var{nf}.zk}. Hence it is a matrix of
! 2307: vectors.
! 2308:
! 2309: $\bullet$ An {\it\idx{ideal list}\/} will be a row vector of (fractional)
! 2310: ideals of the number field $\var{nf}$.
! 2311:
! 2312: $\bullet$ A {\it\idx{pseudo-matrix}\/} will be a pair $(A,I)$ where $A$ is a
! 2313: relative matrix and $I$ an ideal list whose length is the same as the number
! 2314: of columns of $A$. This pair will be represented by a 2-component row vector.
! 2315:
! 2316: $\bullet$ The {\it\idx{module}\/} generated by a pseudo-matrix $(A,I)$ is
! 2317: the sum $\sum_i{\Bbb a}_jA_j$ where the ${\Bbb a}_j$ are the ideals of $I$
! 2318: and $A_j$ is the $j$-th column of $A$.
! 2319:
! 2320: $\bullet$ A pseudo-matrix $(A,I)$ is a {\it\idx{pseudo-basis}} of the module it
! 2321: generates if $A$ is a square matrix with non-zero determinant and all the
! 2322: ideals of $I$ are non-zero. We say that it is in Hermite Normal
! 2323: Form\sidx{Hermite normal form} (HNF) if
! 2324: it is upper triangular and all the elements of the diagonal are equal to 1.
! 2325:
! 2326: $\bullet$ The {\it determinant\/} of a pseudo-basis $(A,I)$ is the ideal
! 2327: equal to the product of the determinant of $A$ by all the ideals of $I$. The
! 2328: determinant of a pseudo-matrix is the determinant of any pseudo-basis of the
! 2329: module it generates.
! 2330:
! 2331: Finally, when defining a relative extension, the base field should be
! 2332: defined by a variable having a lower priority (i.e.~a higher number)
! 2333: than the variable defining the extension. For example, under GP you can
! 2334: use the variable name $y$ (or $t$) to define the base field, and the
! 2335: variable name $x$ to define the relative extension.
! 2336:
! 2337: Now a last set of definitions concerning the way big ray number fields
! 2338: (or \var{bnr}) are input, using class field theory.
! 2339: These are defined by a triple
! 2340: $a1$, $a2$, $a3$, where the defining set $[a1,a2,a3]$ can have any of the
! 2341: following forms: $[\var{bnr}]$, $[\var{bnr},\var{subgroup}]$,
! 2342: $[\var{bnf},\var{module}]$, $[\var{bnf},\var{module},\var{subgroup}]$, where:
! 2343:
! 2344: $\bullet$ $\var{bnf}$ is as output by \kbd{bnfclassunit} or \kbd{bnfinit},
! 2345: where units are mandatory unless the ideal is trivial; \var{bnr} by
! 2346: \kbd{bnrclass} (with $\fl>0$) or \kbd{bnrinit}. This is the ground field.
! 2347:
! 2348: $\bullet$ \var{module} is either an ideal in any form (see above) or a
! 2349: two-component row vector containing an ideal and an $r_1$-component row
! 2350: vector of flags indicating which real Archimedean embeddings to take in the
! 2351: module.
! 2352:
! 2353: $\bullet$ \var{subgroup} is the HNF matrix of a subgroup of the ray class group
! 2354: of the ground field for the modulus \var{module}. This is input as a square
! 2355: matrix expressing generators of a subgroup of the ray class group
! 2356: \kbd{\var{bnr}.clgp} on the given generators.
! 2357:
! 2358: The corresponding \var{bnr} is then the subfield of the ray class field of the
! 2359: ground field for the given modulus, associated to the given subgroup.
! 2360:
! 2361: All the functions which are specific to relative extensions, number fields,
! 2362: big number fields, big number rays, share the prefix \kbd{rnf}, \kbd{nf},
! 2363: \kbd{bnf}, \kbd{bnr} respectively. They are meant to take as first argument a
! 2364: number field of that precise type, respectively output by \kbd{rnfinit},
! 2365: \kbd{nfinit}, \kbd{bnfinit}, and \kbd{bnrinit}.
! 2366:
! 2367: However, and even though it may not be specified in the descriptions of the
! 2368: functions below, it is permissible, if the function expects a $\var{nf}$, to
! 2369: use a $\var{bnf}$ instead (which contains much more information). The program
! 2370: will make the effort of converting to what it needs. On the other hand, if
! 2371: the program requires a big number field, the program will {\it not\/} launch
! 2372: \kbd{bnfinit} for you, which can be a costly operation. Instead, it will give
! 2373: you a specific error message.
! 2374:
! 2375: The data types corresponding to the structures described above are rather
! 2376: complicated. Thus, as we already have seen it with elliptic curves, GP
! 2377: provides you with some ``member functions'' to retrieve the data you need
! 2378: from these structures (once they have been initialized of course). The
! 2379: relevant types of number fields are indicated between parentheses:
! 2380: \smallskip
! 2381:
! 2382: \sidx{member functions}
! 2383: \settabs\+xxxxxxx&(\var{bnr},x&\var{bnf},x&nf\hskip2pt&)x&: &\cr
! 2384:
! 2385: \+\tet{bnf} &(\var{bnr},& \var{bnf}&&)&: & big number field.\cr
! 2386:
! 2387: \+\tet{clgp} &(\var{bnr},& \var{bnf}&&)&: & classgroup. This one admits the
! 2388: following three subclasses:\cr
! 2389:
! 2390: \+ \quad \tet{cyc} &&&&&: & \quad cyclic decomposition
! 2391: (SNF)\sidx{Smith normal form}.\cr
! 2392:
! 2393: \+ \quad \kbd{gen}\sidx{gen (member function)} &&&&&: &
! 2394: \quad generators.\cr
! 2395:
! 2396: \+ \quad \tet{no} &&&&&: & \quad number of elements.\cr
! 2397:
! 2398: \+\tet{diff} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & the different ideal.\cr
! 2399:
! 2400: \+\tet{codiff}&(\var{bnr},& \var{bnf},& \var{nf}&)&: & the codifferent
! 2401: (inverse of the different in the ideal group).\cr
! 2402:
! 2403: \+\tet{disc} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & discriminant.\cr
! 2404:
! 2405: \+\tet{fu} &(\var{bnr},& \var{bnf},& \var{nf}&)&: &
! 2406: \idx{fundamental units}.\cr
! 2407:
! 2408: \+\tet{futu} &(\var{bnr},& \var{bnf}&&)&: & $[u,w]$, $u$ is a vector of
! 2409: fundamental units, $w$ generates the torsion.\cr
! 2410:
! 2411: \+\tet{nf} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & number field.\cr
! 2412:
! 2413: \+\tet{reg} &(\var{bnr},& \var{bnf},&&)&: & regulator.\cr
! 2414:
! 2415: \+\tet{roots}&(\var{bnr},& \var{bnf},& \var{nf}&)&: & roots of the
! 2416: polnomial generating the field.\cr
! 2417:
! 2418: \+\tet{sign} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & $[r_1,r_2]$ the
! 2419: signature of the field. This means that the field has $r_1$ real \cr
! 2420: \+ &&&&&& embeddings, $2r_2$ complex ones.\cr
! 2421:
! 2422: \+\tet{t2} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & the T2 matrix (see
! 2423: \kbd{nfinit}).\cr
! 2424:
! 2425: \+\tet{tu} &(\var{bnr},& \var{bnf},&&)&: & a generator for the torsion
! 2426: units.\cr
! 2427:
! 2428: \+\tet{tufu} &(\var{bnr},& \var{bnf},&&)&: & as \kbd{futu}, but outputs
! 2429: $[w,u]$.\cr
! 2430:
! 2431: \+\tet{zk} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & integral basis, i.e.~a
! 2432: $\Z$-basis of the maximal order.\cr
! 2433:
! 2434: \+\tet{zkst} &(\var{bnr}& & &)&: & structure of $(\Z_K/m)^*$ (can be
! 2435: extracted also from an \var{idealstar}).\cr
! 2436:
! 2437: For instance, assume that $\var{bnf} = \kbd{bnfinit}(\var{pol})$, for some
! 2438: polynomial. Then \kbd{\var{bnf}.clgp} retrieves the class group, and
! 2439: \kbd{\var{bnf}.clgp.no} the class number. If we had set $\var{bnf} =
! 2440: \kbd{nfinit}(\var{pol})$, both would have output an error message. All these
! 2441: functions are completely recursive, thus for instance
! 2442: \kbd{\var{bnr}.bnf.nf.zk} will yield the maximal order of \var{bnr} (which
! 2443: you could get directly with a simple \kbd{\var{bnr}.zk} of course).
! 2444:
! 2445: \medskip
! 2446: The following functions, starting with \kbd{buch} in library mode, and with
! 2447: \kbd{bnf} under GP, are implementations of the sub-exponential algorithms for
! 2448: finding class and unit groups under \idx{GRH}, due to Hafner-McCurley,
! 2449: \idx{Buchmann} and Cohen-Diaz-Olivier.
! 2450:
! 2451: The general call to the functions concerning class groups of general number
! 2452: fields (i.e.~excluding \kbd{quadclassunit}) involves a polynomial $P$ and a
! 2453: technical vector
! 2454: $$\var{tech} = [c,c2,\var{nrel},\var{borne},\var{nrpid},\var{minsfb}],$$
! 2455: where the parameters are to be understood as follows:
! 2456:
! 2457: $P$ is the defining polynomial for the number field, which must be in
! 2458: $\Z[X]$, irreducible and, preferably, monic. In fact, if you supply a
! 2459: non-monic polynomial at this point, GP will issue a warning, then
! 2460: {\it transform your polynomial\/} so that it becomes monic. Instead of
! 2461: the normal
! 2462: result, say \kbd{res}, you then get a vector \kbd{[res,Mod(a,Q)]}, where
! 2463: \kbd{Mod(a,Q)=Mod(X,P)} gives the change of variables.
! 2464:
! 2465: The numbers $c$ and $c2$ are positive real numbers which control the
! 2466: execution time and the stack size. To get maximum speed, set $c2=c$. To get a
! 2467: rigorous result (under \idx{GRH}) you must take $c2=12$ (or $c2=6$ in the
! 2468: quadratic case, but then you should use the much faster function
! 2469: \kbd{quadclassunit}). Reasonable values for $c$ are between $0.1$ and
! 2470: $2$. (The defaults are $c=c2=0.3$).
! 2471:
! 2472: $\var{nrel\/}$ is the number of initial extra relations requested in
! 2473: computing the
! 2474: relation matrix. Reasonable values are between 5 and 20. (The default is 5).
! 2475:
! 2476: $\var{borne\/}$ is a multiplicative coefficient of the Minkowski bound which
! 2477: controls
! 2478: the search for small norm relations. If this parameter is set equal to 0, the
! 2479: program does not search for small norm relations. Otherwise reasonable values
! 2480: are between $0.5$ and $2.0$. (The default is $1.0$).
! 2481:
! 2482: $\var{nrpid\/}$ is the maximal number of small norm relations associated to each
! 2483: ideal in the factor base. Irrelevant when $\var{borne}=0$. Otherwise,
! 2484: reasonable values are between 4 and 20. (The default is 4).
! 2485:
! 2486: $\var{minsfb\/}$ is the minimal number of elements in the ``sub-factorbase''.
! 2487: If the
! 2488: program does not seem to succeed in finding a full rank matrix (which you can
! 2489: see in GP by typing \kbd{\bs g 2}), increase this number. Reasonable values
! 2490: are between 2 and 5. (The default is 3).
! 2491:
! 2492: \misctitle{Remarks.}
! 2493:
! 2494: Apart from the polynomial $P$, you don't need to supply any of the technical
! 2495: parameters (under the library you still need to send at least an empty
! 2496: vector, \kbd{cgetg(1,t\_VEC)}). However, should you choose to set some of
! 2497: them, they {\it must\/} be given in the requested order. For example, if you
! 2498: want to specify a given value of $nrel$, you must give some values as well
! 2499: for $c$ and $c2$, and provide a vector $[c,c2,nrel]$.
! 2500:
! 2501: Note also that you can use an $\var{nf}$ instead of $P$, which avoids
! 2502: recomputing the integral basis and analogous quantities.
! 2503:
! 2504: \smallskip
! 2505: \subsecidx{bnfcertify}$(\var{bnf\/})$: $\var{bnf}$ being a big number field
! 2506: as output by \kbd{bnfinit} or \kbd{bnfclassunit}, checks whether the result
! 2507: is correct, i.e.~whether it is possible to remove the assumption of the
! 2508: Generalized Riemann Hypothesis\sidx{GRH}. If it is correct, the answer is 1.
! 2509: If not, the program may output some error message, but more probably will loop
! 2510: indefinitely. In {\it no\/} occasion can the program give a wrong answer
! 2511: (barring bugs of course): if the program answers 1, the answer is certified.
! 2512:
! 2513: \syn{certifybuchall}{\var{bnf\/}}, and the result is a C long.
! 2514:
! 2515: \subsecidx{bnfclassunit}$(P,\{\fl=0\},\{\var{tech}=[\,]\})$: \idx{Buchmann}'s
! 2516: sub-exponential algorithm for computing the class group, the regulator and a
! 2517: system of \idx{fundamental units} of the general algebraic number field $K$
! 2518: defined by the irreducible polynomial $P$ with integer coefficients.
! 2519:
! 2520: The result of this function is a vector $v$ with 10 components (it is {\it
! 2521: not\/} a $\var{bnf}$, you need \kbd{bnfinit} for that), which for ease of
! 2522: presentation is in fact output as a one column matrix. First we describe the
! 2523: default behaviour ($\fl=0$):
! 2524:
! 2525: $v[1]$ is equal to the polynomial $P$. Note that for optimum performance,
! 2526: $P$ should have gone through \kbd{polred} or $\kbd{nfinit}(x,2)$.
! 2527:
! 2528: $v[2]$ is the 2-component vector $[r1,r2]$, where $r1$ and $r2$ are as usual
! 2529: the number of real and half the number of complex embeddings of the number
! 2530: field $K$.
! 2531:
! 2532: $v[3]$ is the 2-component vector containing the field discriminant and the
! 2533: index.
! 2534:
! 2535: $v[4]$ is an integral basis in Hermite normal form.
! 2536:
! 2537: $v[5]$ (\kbd{$v$.clgp}) is a 3-component vector containing the class number
! 2538: (\kbd{$v$.clgp.no}), the structure of the class group as a product of cyclic
! 2539: groups of order $n_i$ (\kbd{$v$.clgp.cyc}), and the corresponding generators
! 2540: of the class group of respective orders $n_i$ (\kbd{$v$.clgp.gen}).
! 2541:
! 2542: $v[6]$ (\kbd{$v$.reg}) is the regulator computed to an accuracy which is the
! 2543: maximum of an internally determined accuracy and of the default.
! 2544:
! 2545: $v[7]$ is a measure of the correctness of the result. If it is close to 1,
! 2546: the results are correct (under \idx{GRH}). If it is close to a larger integer,
! 2547: this shows that the product of the class number by the regulator is off by a
! 2548: factor equal to this integer, and you must start again with a larger value
! 2549: for $c$ or a different random seed, i.e.~use the function \kbd{setrand}.
! 2550: (Since the computation involves a random process, starting again with exactly
! 2551: the same parameters may give the correct result.) In this case a warning
! 2552: message is printed.
! 2553:
! 2554: $v[8]$ (\kbd{$v$.tu}) a vector with 2 components, the first being the number
! 2555: $w$ of roots of unity in $K$ and the second a primitive $w$-th root of unity
! 2556: expressed as a polynomial.
! 2557:
! 2558: $v[9]$ (\kbd{$v$.fu}) is a system of fundamental units also expressed as
! 2559: polynomials.
! 2560:
! 2561: $v[10]$ gives a measure of the correctness of the computations of the
! 2562: fundamental units (not of the regulator), expressed as a number of bits. If
! 2563: this number is greater than $20$, say, everything is OK. If $v[10]\le0$,
! 2564: then we have lost all accuracy in computing the units (usually an error
! 2565: message will be printed and the units not given). In the intermediate cases,
! 2566: one must proceed with caution (for example by increasing the current
! 2567: precision).
! 2568:
! 2569: If $\fl=1$, and the precision happens to be insufficient for obtaining the
! 2570: fundamental units exactly, the internal precision is doubled and the
! 2571: computation redone, until the exact results are obtained. The user should be
! 2572: warned that this can take a very long time when the coefficients of the
! 2573: fundamental units on the integral basis are very large, for example in the
! 2574: case of large real quadratic fields. In that case, there are alternate
! 2575: methods for representing algebraic numbers which are not implemented in PARI.
! 2576:
! 2577: If $\fl=2$, the fundamental units and roots of unity are not computed.
! 2578: Hence the result has only 7 components, the first seven ones.
! 2579:
! 2580: $\var{tech\/}$ is a technical vector (empty by default) containing $c$, $c2$,
! 2581: \var{nrel}, \var{borne}, \var{nbpid}, \var{minsfb}, in this order (see
! 2582: the beginning of the section or the keyword \kbd{bnf}).
! 2583: You can supply any number of these {\it provided you give an actual value to
! 2584: each of them} (the ``empty arg'' trick won't work here). Careful use of these
! 2585: parameters may speed up your computations considerably.
! 2586:
! 2587: \syn{bnfclassunit0}{P,\fl,\var{tech},\var{prec}}.
! 2588:
! 2589: \subsecidx{bnfclgp}$(P,\{\var{tech}=[\,]\})$: as \kbd{bnfclassunit}, but only
! 2590: outputs $v[5]$, i.e.~the class group.
! 2591:
! 2592: \syn{bnfclassgrouponly}{P,\var{tech},\var{prec}}, where \var{tech}
! 2593: is as described under \kbd{bnfclassunit}.
! 2594:
! 2595: \subsecidx{bnfdecodemodule}$(\var{nf},m)$: if $m$ is a module as output in the
! 2596: first component of an extension given by \kbd{bnrdisclist}, outputs the
! 2597: true module.
! 2598:
! 2599: \syn{decodemodule}{\var{nf},m}.
! 2600:
! 2601: \subsecidx{bnf{}init}$(P,\{\fl=0\},\{\var{tech}=[\,]\})$: essentially identical
! 2602: to \kbd{bnfclassunit} except that the output contains a lot of technical data,
! 2603: and should not be printed out explicitly in general. The result of
! 2604: \kbd{bnfinit} is used in programs such as \kbd{bnfisprincipal},
! 2605: \kbd{bnfisunit} or \kbd{bnfnarrow}. The result is a 10-component vector
! 2606: $\var{bnf}$.
! 2607:
! 2608: \noindent $\bullet$ The first 6 and last 2 components are technical and in
! 2609: principle are not used by the casual user. However, for the sake of
! 2610: completeness, their description is as follows. We use the notations explained
! 2611: in the book by H. Cohen, {\it A Course in Computational Algebraic Number
! 2612: Theory\/}, Graduate Texts in Maths \key{138}, Springer-Verlag, 1993, Section
! 2613: 6.5, and subsection 6.5.5 in particular.
! 2614:
! 2615: $\var{bnf\/}[1]$ contains the matrix $W$, i.e.~the matrix in Hermite normal
! 2616: form giving relations for the class group on prime ideal generators
! 2617: $(\p_i)_{1\le i\le r}$.
! 2618:
! 2619: $\var{bnf\/}[2]$ contains the matrix $B$, i.e.~the matrix containing the
! 2620: expressions of the prime ideal factorbase in terms of the $\p_i$. It is an
! 2621: $r\times c$ matrix.
! 2622:
! 2623: $\var{bnf\/}[3]$ contains the complex logarithmic embeddings of the system of
! 2624: fundamental units which has been found. It is an $(r_1+r_2)\times(r_1+r_2-1)$
! 2625: matrix.
! 2626:
! 2627: $\var{bnf\/}[4]$ contains the matrix $M''_C$ of Archimedean components of the
! 2628: relations of the matrix $M''$, except that the first $r_1+r_2-1$ columns are
! 2629: suppressed since they are already in $\var{bnf\/}[3]$.
! 2630:
! 2631: $\var{bnf\/}[5]$ contains the prime factor base, i.e.~the list of $k$ prime
! 2632: ideals used in finding the relations.
! 2633:
! 2634: $\var{bnf\/}[6]$ contains the permutation of the prime factor base which was
! 2635: necessary
! 2636: to reduce the relation matrix to the form explained in subsection 6.5.5
! 2637: of GTM~138 (i.e.~with a
! 2638: big $c\times c$ identity matrix on the lower right). Note that in the above
! 2639: mentioned book, the need to permute the rows of the relation matrices which
! 2640: occur was not emphasized.
! 2641:
! 2642: $\var{bnf\/}[9]$ is a 3-element row vector obtained as follows. Let
! 2643: $b=u_1^{-1}\var{bnf\/}[1]u_2$ obtained by applying the \idx{Smith normal form}
! 2644: algorithm to the matrix $W$ (= $\var{bnf}[1]$). Then
! 2645: $\var{bnf\/}[9]=[u_1,u_2,b]$. Note that the final class group generators
! 2646: given by \kbd{bnfinit} or \kbd{bnfclassunit} are obtained by
! 2647: \idx{LLL}-reducing the generators whose list is $b$.
! 2648:
! 2649: Finally, $\var{bnf\/}[10]$ is unused and set equal to 0, but it is essential
! 2650: that this component be present, because PARI distinguishes a number field
! 2651: \var{nf} from a big number field \var{bnf} by the number of its
! 2652: components. \smallskip
! 2653:
! 2654: \noindent$\bullet$ The less technical components are as follows:
! 2655:
! 2656: $\var{bnf\/}[7]$ or \kbd{\var{bnf}.nf} is equal to the number field data
! 2657: $\var{nf}$ as would be given by \kbd{nfinit}.
! 2658:
! 2659: $\var{bnf\/}[8]$ is a vector containing the last 6 components of
! 2660: \kbd{bnfclassunit[,1]}, i.e.~the classgroup \kbd{\var{bnf}.clgp}, the
! 2661: regulator \kbd{\var{bnf}.reg}, the general ``check'' number which should be
! 2662: close to 1, the number of roots of unity and a generator \kbd{\var{bnf}.tu},
! 2663: the fundamental units \kbd{\var{bnf}.fu}, and finally the check on their
! 2664: computation. If the precision becomes insufficient, GP outputs a warning
! 2665: (\kbd{fundamental units too large, not given}) and does not strive to
! 2666: compute the units by default ($\fl=0$).
! 2667:
! 2668: When $\fl=1$, GP insists on finding the fundamental units exactly, the
! 2669: internal precision being doubled and the computation redone, until the exact
! 2670: results are obtained. The user should be warned that this can take a very
! 2671: long time when the coefficients of the fundamental units on the integral
! 2672: basis are very large.
! 2673:
! 2674: When $\fl=2$, on the contrary, it is initially agreed that GP
! 2675: will not compute units.
! 2676:
! 2677: When $\fl=3$, computes a very small version of \kbd{bnfinit}, a ``small big
! 2678: number field'' (or \var{sbnf} for short) which contains enough information
! 2679: to recover the full $\var{bnf}$ vector very rapidly, but which is much
! 2680: smaller and hence easy to store and print. It is supposed to be used in
! 2681: conjunction with \kbd{bnfmake}. The output is a 12 component vector $v$, as
! 2682: follows. Let $\var{bnf}$ be the result of a full \kbd{bnfinit}, complete with
! 2683: units. Then $v[1]$ is the polynomial $P$, $v[2]$ is the number of real
! 2684: embeddings $r_1$, $v[3]$ is the field discriminant, $v[4]$ is the integral
! 2685: basis, $v[5]$ is the list of roots as in the sixth component of \kbd{nfinit},
! 2686: $v[6]$ is the matrix $MD$ of \kbd{nfinit} giving a $\Z$-basis of the
! 2687: different, $v[7]$ is the matrix $\kbd{W} = \var{bnf\/}[1]$, $v[8]$ is the
! 2688: matrix $\kbd{matalpha}=\var{bnf\/}[2]$, $v[9]$ is the prime ideal factor base
! 2689: $\var{bnf\/}[5]$ coded in a compact way, and ordered according to the
! 2690: permutation $\var{bnf\/}[6]$, $v[10]$ is the 2-component vector giving the
! 2691: number of roots of unity and a generator, expressed on the integral basis,
! 2692: $v[11]$ is the list of fundamental units, expressed on the integral basis,
! 2693: $v[12]$ is a vector containing the algebraic numbers alpha corresponding to
! 2694: the columns of the matrix \kbd{matalpha}, expressed on the integral basis.
! 2695:
! 2696: Note that all the components are exact (integral or rational), except for
! 2697: the roots in $v[5]$. In practice, this is the only component which a user
! 2698: is allowed to modify, by recomputing the roots to a higher accuracy if
! 2699: desired. Note also that the member functions will {\it not\/} work on
! 2700: \var{sbnf}, you have to use \kbd{bnfmake} explicitly first.
! 2701:
! 2702: \syn{bnf{}init0}{P,\fl,\var{tech},\var{prec}}.
! 2703:
! 2704: \subsecidx{bnf{}isintnorm}$(\var{bnf},x)$: computes a complete system of
! 2705: solutions (modulo units of positive norm) of the absolute norm equation
! 2706: $\text{Norm}(a)=x$,
! 2707: where $a$ is an integer in $\var{bnf}$. If $\var{bnf}$ has not been certified,
! 2708: the correctness of the result depends on the validity of \idx{GRH}.
! 2709:
! 2710: \syn{bnf{}isintnorm}{\var{bnf},x}.
! 2711:
! 2712: \subsecidx{bnf{}isnorm}$(\var{bnf},x,\{\fl=1\})$: tries to tell whether the
! 2713: rational number $x$ is the norm of some element y in $\var{bnf}$. Returns a
! 2714: vector $[a,b]$ where $x=Norm(a)*b$. Looks for a solution which is an $S$-unit,
! 2715: with $S$ a certain set of prime ideals containing (among others) all primes
! 2716: dividing $x$. If $\var{bnf}$ is known to be \idx{Galois}, set $\fl=0$ (in
! 2717: this case,
! 2718: $x$ is a norm iff $b=1$). If $\fl$ is non zero the program adds to $S$ the
! 2719: following prime ideals, depending on the sign of $\fl$. If $\fl>0$, the
! 2720: ideals of norm less than $\fl$. And if $\fl<0$ the ideals dividing $\fl$.
! 2721:
! 2722: If you are willing to assume \idx{GRH}, the answer is guaranteed
! 2723: (i.e.~$x$ is a norm iff $b=1$), if $S$ contains all primes less than
! 2724: $12\log(\var{disc}(\var{Bnf}))^2$,
! 2725: where $\var{Bnf}$ is the Galois closure of $\var{bnf}$.
! 2726:
! 2727: \syn{bnf{}isnorm}{\var{bnf},x,\fl,\var{prec}}, where $\fl$ and
! 2728: $\var{prec}$ are \kbd{long}s.
! 2729:
! 2730: \subsecidx{bnf{}issunit}$(\var{bnf},\var{sfu},x)$: $\var{bnf}$ being output by
! 2731: \kbd{bnfinit}, \var{sfu} by \kbd{bnfsunit}, gives the column vector of
! 2732: exponents of $x$ on the fundamental $S$-units and the roots of unity.
! 2733: If $x$ is not a unit, outputs an empty vector.
! 2734:
! 2735: \syn{bnf{}issunit}{\var{bnf},\var{sfu},x}.
! 2736:
! 2737: \subsecidx{bnf{}isprincipal}$(\var{bnf},x,\{\fl=1\})$: $\var{bnf}$ being the
! 2738: number field data output by \kbd{bnfinit}, and $x$ being either a $\Z$-basis
! 2739: of an ideal in the number field (not necessarily in HNF) or a prime ideal in
! 2740: the format output by the function \kbd{idealprimedec}, this function tests
! 2741: whether the ideal is principal or not. The result is more complete than a
! 2742: simple true/false answer: it gives a row vector $[v_1,v_2,check]$, where
! 2743:
! 2744: $v_1$ is the vector of components $c_i$ of the class of the ideal $x$ in the
! 2745: class group, expressed on the generators $g_i$ given by \kbd{bnfinit}
! 2746: (specifically \kbd{\var{bnf}.clgp.gen} which is the same as
! 2747: \kbd{\var{bnf\/}[8][1][3]}). The $c_i$ are chosen so that $0\le c_i<n_i$
! 2748: where $n_i$ is the order of $g_i$ (the vector of $n_i$ being
! 2749: \kbd{\var{bnf}.clgp.cyc}, that is \kbd{\var{bnf\/}[8][1][2]}).
! 2750:
! 2751: $v_2$ gives on the integral basis the components of $\alpha$ such that
! 2752: $x=\alpha\prod_ig_i^{c_i}$. In particular, $x$ is principal if and only if
! 2753: $v_1$ is equal to the zero vector, and if this the case $x=\alpha\Z_K$ where
! 2754: $\alpha$ is given by $v_2$. Note that if $\alpha$ is too large to be given, a
! 2755: warning message will be printed and $v_2$ will be set equal to the empty
! 2756: vector.
! 2757:
! 2758: Finally the third component \var{check} is analogous to the last component of
! 2759: \kbd{bnfclassunit}: it gives a check on the accuracy of the result, in bits.
! 2760: \var{check} should be at least $10$, and preferably much more. In any case, the
! 2761: result is checked for correctness.
! 2762:
! 2763: If $\fl=0$, outputs only $v_1$, which is much easier to compute.
! 2764:
! 2765: If $\fl=2$, does as if $\fl$ were $0$, but doubles the precision until a result is
! 2766: obtained.
! 2767:
! 2768: If $\fl=3$, as in the default behaviour ($\fl=1$), but doubles the precision
! 2769: until a result is obtained.
! 2770:
! 2771: The user is warned that these two last setting may induce {\it very\/} lengthy
! 2772: computations.
! 2773:
! 2774: \syn{isprincipalall}{\var{bnf},x,\fl}.
! 2775:
! 2776: \subsecidx{bnf{}isunit}$(\var{bnf},x)$: $\var{bnf}$ being the number field data
! 2777: output by
! 2778: \kbd{bnfinit} and $x$ being an algebraic number (type integer, rational or
! 2779: polmod), this outputs the decomposition of $x$ on the fundamental units and
! 2780: the roots of unity if $x$ is a unit, the empty vector otherwise. More
! 2781: precisely, if $u_1$,\dots,$u_r$ are the fundamental units, and $\zeta$ is
! 2782: the generator of the group of roots of unity (found by \kbd{bnfclassunit} or
! 2783: \kbd{bnfinit}), the output is a vector $[x_1,\dots,x_r,x_{r+1}]$ such that
! 2784: $x=u_1^{x_1}\cdots u_r^{x_r}\cdot\zeta^{x_{r+1}}$. The $x_i$ are integers for
! 2785: $i\le r$ and is an integer modulo the order of $\zeta$ for $i=r+1$.
! 2786:
! 2787: \syn{isunit}{\var{bnf},x}.
! 2788:
! 2789: \subsecidx{bnfmake}$(\var{sbnf})$: \var{sbnf} being a ``small $\var{bnf}$''
! 2790: as output
! 2791: by \kbd{bnfinit}$(x,3)$, computes the complete \kbd{bnfinit} information. The
! 2792: result is {\it not\/} identical to what \kbd{bnfinit} would yield, but is
! 2793: functionally identical. The execution time is very small compared to a
! 2794: complete \kbd{bnfinit}. Note that if the default precision in GP (or
! 2795: $\var{prec}$ in library mode) is greater than the precision of the roots
! 2796: $\var{sbnf}[5]$, these are recomputed so as to get a result with greater
! 2797: accuracy.
! 2798:
! 2799: Note that the member functions are {\it not\/} available for \var{sbnf}, you
! 2800: have to use \kbd{bnfmake} explicitly first.
! 2801:
! 2802: \syn{makebigbnf}{\var{sbnf},\var{prec}}, where $\var{prec}$ is a
! 2803: C long integer.
! 2804:
! 2805: \subsecidx{bnfnarrow}$(\var{bnf\/})$: $\var{bnf}$ being a big number field as
! 2806: output by \kbd{bnfinit}, computes the narrow class group of $\var{bnf}$. The
! 2807: output is a 3-component row vector $v$ analogous to the corresponding
! 2808: class group component \kbd{\var{bnf}.clgp} (\kbd{\var{bnf\/}[8][1]}): the
! 2809: first component is the narrow class number \kbd{$v$.no}, the second component
! 2810: is a vector containing the SNF\sidx{Smith normal form} cyclic components
! 2811: \kbd{$v$.cyc} of the narrow
! 2812: class group, and the third is a vector giving the generators of the
! 2813: corresponding \kbd{$v$.gen} cyclic groups. Note that this function is a
! 2814: special case of \kbd{bnrclass}.
! 2815:
! 2816: \syn{buchnarrow}{\var{bnf\/}}.
! 2817:
! 2818: \subsecidx{bnfsignunit}$(\var{bnf\/})$: $\var{bnf}$ being a big number field
! 2819: output by \kbd{bnfinit}, this computes an $r_1\times(r_1+r_2-1)$ matrix
! 2820: having $\pm1$ components, giving the signs of the real embeddings of the
! 2821: fundamental units.
! 2822:
! 2823: \syn{signunits}{\var{bnf\/}}.
! 2824:
! 2825: \subsecidx{bnfreg}$(\var{bnf\/})$: $\var{bnf}$ being a big number field
! 2826: output by \kbd{bnfinit}, computes its regulator.
! 2827:
! 2828: \syn{regulator}{\var{bnf},\var{tech},\var{prec}}, where \var{tech} is as in
! 2829: \kbd{bnfclassunit}.
! 2830:
! 2831: \subsecidx{bnfsunit}$(\var{bnf},S)$: computes the fundamental $S$-units of the
! 2832: number field $\var{bnf}$ (output by \kbd{bnfinit}), where $S$ is a list of
! 2833: prime ideals (output by \kbd{idealprimedec}). The output is a vector $v$ with
! 2834: 6 components.
! 2835:
! 2836: $v[1]$ gives a minimal system of (integral) generators of the $S$-unit group
! 2837: modulo the unit group.
! 2838:
! 2839: $v[2]$ contains technical data needed by \kbd{bnfissunit}.
! 2840:
! 2841: $v[3]$ is an empty vector (used to give the logarithmic embeddings of the
! 2842: generators in $v[1]$ in version 2.0.16).
! 2843:
! 2844: $v[4]$ is the $S$-regulator (this is the product of the regulator, the
! 2845: determinant of $v[2]$ and the natural logarithms of the norms of the ideals
! 2846: in $S$).
! 2847:
! 2848: $v[5]$ gives the $S$-class group structure, in the usual format
! 2849: (a row vector whose three components give in order the $S$-class number,
! 2850: the cyclic components and the generators).
! 2851:
! 2852: $v[6]$ is a copy of $S$.
! 2853:
! 2854: \syn{bnfsunit}{\var{bnf},S,\var{prec}}.
! 2855:
! 2856: \subsecidx{bnfunit}$(\var{bnf\/})$: $\var{bnf}$ being a big number field as
! 2857: output by
! 2858: \kbd{bnfinit}, outputs a two-component row vector giving in the first
! 2859: component the vector of fundamental units of the number field, and in the
! 2860: second component the number of bit of accuracy which remained in the
! 2861: computation (which is always correct, otherwise an error message is printed).
! 2862: This function is mainly for people who used the wrong flag in \kbd{bnfinit}
! 2863: and would like to skip part of a lengthy \kbd{bnfinit} computation.
! 2864:
! 2865: \syn{buchfu}{\var{bnf\/}}.
! 2866:
! 2867: \subsecidx{bnrL1}$(\var{bnr},\{\fl=0\})$:
! 2868: \var{bnr} being the number field data which is output by
! 2869: \kbd{bnrinit(,,1)}, returns for each \idx{character} $\chi$ of the
! 2870: corresponding ray class group, the value at $s = 1$ (or $s = 0$) of
! 2871: the abelian $L$-functions associated to $\chi$. For the value at $s =
! 2872: 0$, the function returns in fact for each character $\chi$ a vector
! 2873: $[r_\chi , c_\chi]$ where $r_\chi$ is the order of $L(s, \chi)$ at $s
! 2874: = 0$ and $c_\chi$ the first non-zero term in the expansion of $L(s,
! 2875: \chi)$ at $s = 0$; in other words
! 2876: %
! 2877: $$L(s, \chi) = c_\chi \cdot s^{r_\chi} + O(s^{r_\chi + 1})$$
! 2878: %
! 2879: \noindent near $0$. \fl\ is optional, default value is 0; its binary digits
! 2880: mean 1: compute at $s = 1$ if set to 1 or $s = 0$ if set to 0, 2: compute
! 2881: the primitive $L$-functions associated to $\chi$ if set to 0 or the
! 2882: $L$-function with Euler factors at prime ideals dividing the modulus of
! 2883: \var{bnr} removed if set to 1 (this is the so-called $L_S(s, \chi)$
! 2884: function where $S$ is the set of infinite places of the number field
! 2885: together with the finite prime ideals dividing the modulus of \var{bnr},
! 2886: see the example below), 3: returns also the character.
! 2887:
! 2888: Example:
! 2889:
! 2890: \bprog%
! 2891: bnf = bnfinit(x\pow 2-229);
! 2892: bnr = bnrinit(bnf,1,1);
! 2893: bnrL1(bnr)%
! 2894: \eprog\noindent
! 2895: returns the order and the first non-zero term of the abelian
! 2896: $L$-functions $L(s, \chi)$ at $s = 0$ where $\chi$ runs through the
! 2897: characters of the class group of $\Q(\sqrt{229})$. Then
! 2898: \bprog%
! 2899: bnr2 = bnrinit(bnf,2,1);
! 2900: bnrL1(bnr2,2)%
! 2901: \eprog\noindent
! 2902: returns the order and the first non-zero terms of the abelian
! 2903: $L$-functions $L_S(s, \chi)$ at $s = 0$ where $\chi$ runs through the
! 2904: characters of the class group of $\Q(\sqrt{229})$ and $S$ is the set
! 2905: of infinite places of $\Q(\sqrt{229})$ together with the finite prime
! 2906: $2$ (note that the ray class group modulo $2$ is in fact the class
! 2907: group, so \kbd{bnrL1(bnr2)} returns exactly the same answer as
! 2908: \kbd{bnrL1(bnr)}!).
! 2909:
! 2910: \syn{bnrL1}{\var{bnr},\fl,\var{prec}}
! 2911:
! 2912: \subsecidx{bnrclass}$(\var{bnf},\var{ideal},\{\fl=0\})$:
! 2913: $\var{bnf}$ being a big number field
! 2914: as output by \kbd{bnfinit} (the units are mandatory unless the ideal is
! 2915: trivial), and \var{ideal} being either an ideal in any form or a two-component
! 2916: row vector containing an ideal and an $r_1$-component row vector of flags
! 2917: indicating which real Archimedean embeddings to take in the module, computes
! 2918: the ray class group of the number field for the module \var{ideal}, as a
! 2919: 3-component vector as all other finite Abelian groups (cardinality, vector of
! 2920: cyclic components, corresponding generators).
! 2921:
! 2922: If $\fl=2$, the output is different. It is a 6-component vector $w$. $w[1]$
! 2923: is $\var{bnf}$. $w[2]$ is the result of applying
! 2924: $\kbd{idealstar}(\var{bnf},I,2)$. $w[3]$, $w[4]$ and $w[6]$ are technical
! 2925: components used only by the function \kbd{bnrisprincipal}. $w[5]$ is the
! 2926: structure of the ray class group as would have been output with $\fl=0$.
! 2927:
! 2928: If $\fl=1$, as above, except that the generators of the ray class group are
! 2929: not computed, which saves time.
! 2930:
! 2931: \syn{bnrclass0}{\var{bnf},\var{ideal},\fl,\var{prec}}.
! 2932:
! 2933: \subsecidx{bnrclassno}$(\var{bnf},I)$: $\var{bnf}$ being a big number field
! 2934: as output
! 2935: by \kbd{bnfinit} (units are mandatory unless the ideal is trivial), and $I$
! 2936: being either an ideal in any form or a two-component row vector containing an
! 2937: ideal and an $r_1$-component row vector of flags indicating which real
! 2938: Archimedean embeddings to take in the modulus, computes the ray class number
! 2939: of the number field for the modulus $I$. This is faster than \kbd{bnrclass}
! 2940: and should be used if only the ray class number is desired.
! 2941:
! 2942: \syn{rayclassno}{\var{bnf},I}.
! 2943:
! 2944: \subsecidx{bnrclassnolist}$(\var{bnf},\var{list})$: $\var{bnf}$ being a
! 2945: big number field as output by \kbd{bnfinit} (units are mandatory unless
! 2946: the ideal is trivial), and \var{list} being a list of modules as output
! 2947: by \kbd{ideallist} of \kbd{ideallistarch},
! 2948: outputs the list of the class numbers of the corresponding ray class groups.
! 2949:
! 2950: \syn{rayclassnolist}{\var{bnf},\var{list}}.
! 2951:
! 2952: \subsecidx{bnrconductor}$(a_1,\{a_2\},\{a_3\}, \{\fl=0\})$: conductor of the
! 2953: subfield of a ray class field as defined by $[a_1,a_2,a_3]$ (see \kbd{bnr}
! 2954: at the beginning of this section).
! 2955:
! 2956: \syn{bnrconductor}{a_1,a_2,a_3,\fl,\var{prec}}, where an omitted argument
! 2957: among the $a_i$ is input as \kbd{gzero}, and $\fl$ is a C long.
! 2958:
! 2959: \subsecidx{bnrconductorofchar}$(\var{bnr},\var{chi})$: \var{bnr} being a
! 2960: big ray number field
! 2961: as output by \kbd{bnrclass}, and \var{chi} being a row vector representing a
! 2962: \idx{character} as expressed on the generators of the ray class group, gives
! 2963: the conductor of this character as a modulus.
! 2964:
! 2965: \syn{bnrconductorofchar}{\var{bnr},\var{chi},\var{prec}} where $\var{prec}$
! 2966: is a \kbd{long}.
! 2967:
! 2968: \subsecidx{bnrdisc}$(a1,\{a2\},\{a3\},\{\fl=0\})$: $a1$, $a2$, $a3$
! 2969: defining a big ray number field $L$ over a groud field $K$ (see \kbd{bnr}
! 2970: at the beginning of this section for the
! 2971: meaning of $a1$, $a2$, $a3$), outputs a 3-component row vector $[N,R_1,D]$,
! 2972: where $N$ is the (absolute) degree of $L$, $R_1$ the number of real places of
! 2973: $L$, and $D$ the discriminant of $L/\Q$, including sign (if $\fl=0$).
! 2974:
! 2975: If $\fl=1$, as above but outputs relative data. $N$ is now the degree of
! 2976: $L/K$, $R_1$ is the number of real places of $K$ unramified in $L$ (so that
! 2977: the number of real places of $L$ is equal to $R_1$ times the relative degree
! 2978: $N$), and $D$ is the relative discriminant ideal of $L/K$.
! 2979:
! 2980: If $\fl=2$, does as in case 0, except that if the modulus is not the exact
! 2981: conductor corresponding to the $L$, no data is computed and the result is $0$
! 2982: (\kbd{gzero}).
! 2983:
! 2984: If $\fl=3$, as case 2, outputting relative data.
! 2985:
! 2986: \syn{bnrdisc0}{a1,a2,a3,\fl,\var{prec}}.
! 2987:
! 2988: \subsecidx{bnrdisclist}$(\var{bnf},\var{bound},\{\var{arch}\},\{\fl=0\})$:
! 2989: $\var{bnf}$ being a big
! 2990: number field as output by \kbd{bnfinit} (the units are mandatory), computes a
! 2991: list of discriminants of Abelian extensions of the number field by increasing
! 2992: modulus norm up to bound {\it bound}, where the ramified Archimedean places are
! 2993: given by \var{arch} (unramified at infinity if \var{arch} is void or
! 2994: omitted). If
! 2995: \fl\ is non-zero, give \var{arch} all the possible values. (See \kbd{bnr}
! 2996: at the beginning of this section for the meaning of $a1$, $a2$, $a3$.)
! 2997:
! 2998: The alternative syntax $\kbd{bnrdisclist}(\var{bnf},\var{list})$
! 2999: is supported, where \var{list} is as output by \kbd{ideallist} or
! 3000: \kbd{ideallistarch} (with units).
! 3001:
! 3002: The output format is as follows. The output $v$ is a row vector of row
! 3003: vectors, allowing the bound to be greater than $2^{16}$ for 32-bit machines,
! 3004: and $v[i][j]$ is understood to be in fact $V[2^{15}(i-1)+j]$ of a unique big
! 3005: vector $V$ (note that $2^{15}$ is hardwired and can be increased in the
! 3006: source code only on 64-bit machines and higher).
! 3007:
! 3008: Such a component $V[k]$ is itself a vector $W$ (maybe of length 0) whose
! 3009: components correspond to each possible ideal of norm $k$. Each component
! 3010: $W[i]$ corresponds to an Abelian extension $L$ of $\var{bnf}$ whose modulus is
! 3011: an ideal of norm $k$ and no Archimedean components (hence the extension is
! 3012: unramified at infinity). The extension $W[i]$ is represented by a 4-component
! 3013: row vector $[m,d,r,D]$ with the following meaning. $m$ is the prime ideal
! 3014: factorization of the modulus, $d=[L:\Q]$ is the absolute degree of $L$,
! 3015: $r$ is the number of real places of $L$, and $D$ is the factorization of the
! 3016: absolute discriminant. Each prime ideal $pr=[p,\alpha,e,f,\beta]$ in the
! 3017: prime factorization $m$ is coded as $p\cdot n^2+(f-1)\cdot n+(j-1)$, where
! 3018: $n$ is the degree of the base field and $j$ is such that
! 3019:
! 3020: \kbd{pr=idealprimedec(\var{nf},p)[j]}.
! 3021:
! 3022: $m$ can be decoded using \kbd{bnfdecodemodule}.
! 3023:
! 3024: \syn{bnrdisclist0}{a1,a2,a3,\var{bound},\var{arch},\fl}.
! 3025:
! 3026: \subsecidx{bnrinit}$(\var{bnf},\var{ideal},\{\fl=0\})$: $\var{bnf}$ is as
! 3027: output by \kbd{bnfinit}, \var{ideal} is a valid ideal (or a module),
! 3028: initializes data linked
! 3029: to the ray class group structure corresponding to this module. This is the
! 3030: same as $\kbd{bnrclass}(\var{bnf},\var{ideal},\fl+1)$.
! 3031:
! 3032: \syn{bnrinit0}{\var{bnf},\var{ideal},\fl,\var{prec}}.
! 3033:
! 3034: \subsecidx{bnrisconductor}$(a1,\{a2\},\{a3\})$: $a1$, $a2$, $a3$ represent
! 3035: an extension of the base field, given by class field theory for some modulus
! 3036: encoded in the parameters. Outputs 1 if this modulus is the conductor, and 0
! 3037: otherwise. This is slightly faster than \kbd{bnrconductor}.
! 3038:
! 3039: \syn{bnrisconductor}{a1,a2,a3} and the result is a \kbd{long}.
! 3040:
! 3041: \subsecidx{bnrisprincipal}$(\var{bnr},x,\{\fl=1\})$: \var{bnr} being the
! 3042: number field
! 3043: data which is output by \kbd{bnrinit} and $x$ being an ideal in any form,
! 3044: outputs the components of $x$ on the ray class group generators in a way
! 3045: similar to \kbd{bnfisprincipal}. That is a 3-component vector $v$ where
! 3046: $v[1]$ is the vector of components of $x$ on the ray class group generators,
! 3047: $v[2]$ gives on the integral basis an element $\alpha$ such that
! 3048: $x=\alpha\prod_ig_i^{x_i}$. Finally $v[3]$ indicates the number of bits of
! 3049: accuracy left in the result. In any case the result is checked for
! 3050: correctness, but $v[3]$ is included to see if it is necessary to increase the
! 3051: accuracy in other computations.
! 3052:
! 3053: If $\fl=0$, outputs only $v_1$.
! 3054:
! 3055: {\it The settings $\fl=2$ or $3$ are not available in this case}.
! 3056:
! 3057: \syn{isprincipalrayall}{\var{bnr},x,\fl}.
! 3058:
! 3059: \subsecidx{bnrrootnumber}$(\var{bnr},\var{chi},\{\fl=0\})$:
! 3060: if $\chi=\var{chi}$ is a (not necessarily primitive)
! 3061: \idx{character} over \var{bnr}, let
! 3062: $L(s,\chi) = \sum_{id} \chi(id) N(id)^{-s}$ be the associated
! 3063: \idx{Artin L-function}. Returns the so-called \idx{Artin root number}, i.e.~the
! 3064: complex number $W(\chi)$ of modulus 1 such that
! 3065: %
! 3066: $$\Lambda(1-s,\chi) = W(\chi) \Lambda(s,\overline{\chi})$$
! 3067: %
! 3068: \noindent where $\Lambda(s,\chi) = A(\chi)^{s/2}\gamma_\chi(s) L(s,\chi)$ is
! 3069: the enlarged L-function associated to $L$.
! 3070:
! 3071: The generators of the ray class group are needed, and you can set $\fl=1$ if
! 3072: the character is known to be primitive. Example:
! 3073:
! 3074: \bprog%
! 3075: bnf = bnfinit(x\pow 2-145);
! 3076: bnr = bnrinit(bnf,7,1);
! 3077: bnrrootnumber(bnr, [5])%
! 3078: \eprog\noindent
! 3079: returns the root number of the character $\chi$ of $Cl_7(\Q(\sqrt{145}))$
! 3080: such that $\chi(g) = \zeta^5$, where $g$ is the generator of the ray-class
! 3081: field and $\zeta = e^{2i\pi/N}$ where $N$ is the order of $g$ ($N=12$ as
! 3082: \kbd{bnr.cyc} readily tells us).
! 3083:
! 3084: \syn{bnrrootnumber}{\var{bnf},\var{chi},\fl}
! 3085:
! 3086: \subsecidx{bnrstark}${(\var{bnr},\var{subgroup},\{\fl=0\})}$: \var{bnr}
! 3087: being as output by \kbd{bnrinit(,,1)}, finds a relative equation for the
! 3088: class field corresponding to the modulus in \var{bnr} and the given
! 3089: congruence subgroup using \idx{Stark units} (set $\var{subgroup}=0$ if you
! 3090: want the whole ray class group). The main variable of \var{bnr} must not be
! 3091: $x$, and the ground field and the class field must be totally real and not
! 3092: isomorphic to $\Q$. \fl\ is optional and may be set to 0 to obtain a
! 3093: reduced relative polynomial, 1 to be satisfied with any relative
! 3094: polynomial, 2 to obtain an absolute polynomial and 3 to obtain the
! 3095: irreducible relative polynomial of the Stark unit, 0 being default.
! 3096: Example:
! 3097:
! 3098: \bprog%
! 3099: bnf = bnfinit(y\pow 2-3);
! 3100: bnr = bnrinit(bnf,5,1);
! 3101: bnrstark(bnr,0)%
! 3102: \eprog\noindent
! 3103: returns the ray class field of $\Q(\sqrt{3})$ modulo $5$.
! 3104:
! 3105: \misctitle{Remark.} The function may fail, returning the error message
! 3106:
! 3107: \kbd{"Cannot find a suitable modulus in FindModule"}.
! 3108:
! 3109: In this case, the corresponding congruence group is a product of cyclic
! 3110: groups and, for the time being, the class field has to be obtained by
! 3111: splitting this group into its cyclic components.
! 3112:
! 3113: \syn{bnrstark}{\var{bnr},\var{subgroup},\fl}.
! 3114:
! 3115: \subsecidx{dirzetak}$(\var{nf},b)$: gives as a vector the first $b$
! 3116: coefficients of the \idx{Dedekind} zeta function of the number field $\var{nf}$
! 3117: considered as a \idx{Dirichlet series}.
! 3118:
! 3119: \syn{dirzetak}{\var{nf},b}.
! 3120:
! 3121: \subsecidx{factornf}$(x,t)$: factorization of the univariate polynomial $x$
! 3122: over the number field defined by the (univariate) polynomial $t$. $x$ may
! 3123: have coefficients in $\Q$ or in the number field. The main variable of
! 3124: $t$ must be of {\it lower\/} priority than that of $x$ (in other words the
! 3125: variable number of $t$ must be {\it greater\/} than that of $x$). However if
! 3126: the coefficients of the number field occur explicitly (as polmods) as
! 3127: coefficients of $x$, the variable of these polmods {\it must\/} be the same as
! 3128: the main variable of $t$. For example
! 3129: \kbd{factornf(x\pow 2 + Mod(y,y\pow 2+1), y\pow 2+1)} and
! 3130: \kbd{factornf(x\pow 2+1, y\pow 2+1)} are legal but
! 3131: \kbd{factornf(x\pow 2 + Mod(z,z\pow 2+1), y\pow 2+1)} is not.
! 3132:
! 3133: \syn{polfnf}{x,t}.
! 3134:
! 3135: \subsecidx{ffinit}$(p,n,\{v=x\})$: computes a monic polynomial of degree
! 3136: $n$ which is irreducible over $\F_p$. For instance if
! 3137: \kbd{P = ffinit(3,2,y)}, you can represent elements in $\F_{3^2}$ as polmods
! 3138: modulo \kbd{P}. This function is rather crude and expects $p$ to be
! 3139: relatively small ($p < 2^31$).
! 3140:
! 3141: \syn{ffinit}{p,n,v}, where $v$ is a variable number.
! 3142:
! 3143: \subsecidx{idealadd}$(\var{nf},x,y)$: sum of the two ideals $x$ and $y$ in the
! 3144: number field $\var{nf}$. When $x$ and $y$ are given by $\Z$-bases, this does
! 3145: not depend on $\var{nf}$ and can be used to compute the sum of any two
! 3146: $\Z$-modules. The result is given in HNF.
! 3147:
! 3148: \syn{idealadd}{\var{nf},x,y}.
! 3149:
! 3150: \subsecidx{idealaddtoone}$(\var{nf},x,\{y\})$: $x$ and $y$ being two co-prime
! 3151: integral ideals (given in any form), this gives a two-component row vector
! 3152: $[a,b]$ such that $a\in x$, $b\in y$ and $a+b=1$.
! 3153:
! 3154: The alternative syntax $\kbd{idealaddtoone}(\var{nf},v)$, is supported, where
! 3155: $v$ is a $k$-component vector of ideals (given in any form) which sum to
! 3156: $\Z_K$. This outputs a $k$-component vector $e$ such that $e[i]\in x[i]$ for
! 3157: $1\le i\le k$ and $\sum_{1\le i\le k}e[i]=1$.
! 3158:
! 3159: \syn{idealaddtoone0}{\var{nf},x,y}, where an omitted $y$ is coded as
! 3160: \kbd{NULL}.
! 3161:
! 3162: \subsecidx{idealappr}$(\var{nf},x,\{\fl=0\})$: if $x$ is a fractional ideal
! 3163: (given in any form), gives an element $\alpha$ in $\var{nf}$ such that for
! 3164: all prime ideals $\p$ such that the valuation of $x$ at $\p$ is non-zero, we
! 3165: have $v_{\p}(\alpha)=v_{\p}(x)$, and. $v_{\p}(\alpha)\ge0$ for all other
! 3166: ${\p}$.
! 3167:
! 3168: If $\fl$ is non-zero, $x$ must be given as a prime ideal factorization, as
! 3169: output by \kbd{idealfactor}, but possibly with zero or negative exponents.
! 3170: This yields an element $\alpha$ such that for all prime ideals $\p$ occurring
! 3171: in $x$, $v_{\p}(\alpha)$ is equal to the exponent of $\p$ in $x$, and for all
! 3172: other prime ideals, $v_{\p}(\alpha)\ge0$. This generalizes
! 3173: $\kbd{idealappr}(\var{nf},x,0)$ since zero exponents are allowed. Note that
! 3174: the algorithm used is slightly different, so that
! 3175: \kbd{idealapp(\var{nf},idealfactor(\var{nf},x))} may not be the same as
! 3176: \kbd{idealappr(\var{nf},x,1)}.
! 3177:
! 3178: \syn{idealappr0}{\var{nf},x,\fl}.
! 3179:
! 3180: \subsecidx{idealchinese}$(\var{nf},x,y)$: $x$ being a prime ideal factorization
! 3181: (i.e.~a 2 by 2 matrix whose first column contain prime ideals, and the second
! 3182: column integral exponents), $y$ a vector of elements in $\var{nf}$ indexed by
! 3183: the ideals in $x$, computes an element $b$ such that
! 3184:
! 3185: $v_\p(b - y_\p) \geq v_\p(x)$ for all prime ideals in $x$ and $v_\p(b)\geq 0$
! 3186: for all other $\p$.
! 3187:
! 3188: \syn{idealchinese}{\var{nf},x,y}.
! 3189:
! 3190: \subsecidx{idealcoprime}$(\var{nf},x,y)$: given two integral ideals $x$ and $y$
! 3191: in the number field $\var{nf}$, finds a $\beta$ in the field, expressed on the
! 3192: integral basis $\var{nf\/}[7]$, such that $\beta\cdot y$ is an integral ideal
! 3193: coprime to $x$.
! 3194:
! 3195: \syn{idealcoprime}{\var{nf},x}.
! 3196:
! 3197: \subsecidx{idealdiv}$(\var{nf},x,y,\{\fl=0\})$: quotient $x\cdot y^{-1}$ of the
! 3198: two ideals $x$ and $y$ in the number field $\var{nf}$. The result is given in
! 3199: HNF.
! 3200:
! 3201: If $\fl$ is non-zero, the quotient $x \cdot y^{-1}$ is assumed to be an
! 3202: integral ideal. This can be much faster when the norm of the quotient is
! 3203: small even though the norms of $x$ and $y$ are large.
! 3204:
! 3205: \syn{idealdiv0}{\var{nf},x,y,\fl}. Also available
! 3206: are $\teb{idealdiv}(\var{nf},x,y)$ ($\fl=0$) and
! 3207: $\teb{idealdivexact}(\var{nf},x,y)$ ($\fl=1$).
! 3208:
! 3209: \subsecidx{idealfactor}$(\var{nf},x)$: factors into prime ideal powers the
! 3210: ideal $x$ in the number field $\var{nf}$. The output format is similar to the
! 3211: \kbd{factor} function, and the prime ideals are represented in the form
! 3212: output by the \kbd{idealprimedec} function, i.e.~as 5-element vectors.
! 3213:
! 3214: \syn{idealfactor}{\var{nf},x}.
! 3215:
! 3216: \subsecidx{idealhnf}$(\var{nf},a,\{b\})$: gives the \idx{Hermite normal form}
! 3217: matrix of the ideal $a$. The ideal can be given in any form whatsoever
! 3218: (typically by an algebraic number if it is principal, by a $\Z_K$-system of
! 3219: generators, as a prime ideal as given by \kbd{idealprimedec}, or by a
! 3220: $\Z$-basis).
! 3221:
! 3222: If $b$ is not omitted, assume the ideal given was $a\Z_K+b\Z_K$, where $a$
! 3223: and $b$ are elements of $K$ given either as vectors on the integral basis
! 3224: $\var{nf\/}[7]$ or as algebraic numbers.
! 3225:
! 3226: \syn{idealhnf0}{\var{nf},a,b} where an omitted $b$ is coded as \kbd{NULL}.
! 3227: Also available is $\teb{idealhermite}(\var{nf},a)$ ($b$ omitted).
! 3228:
! 3229: \subsecidx{idealintersect}$(\var{nf},x,y)$: intersection of the two ideals
! 3230: $x$ and $y$ in the number field $\var{nf}$. When $x$ and $y$ are given by
! 3231: $\Z$-bases, this does not depend on $\var{nf}$ and can be used to compute the
! 3232: intersection of any two $\Z$-modules. The result is given in HNF.
! 3233:
! 3234: \syn{idealintersect}{\var{nf},x,y}.
! 3235:
! 3236: \subsecidx{idealinv}$(\var{nf},x,\{\fl=0\})$: inverse of the ideal $x$ in the
! 3237: number field $\var{nf}$. The result is the Hermite normal form of the inverse
! 3238: of the ideal, together with the opposite of the Archimedean information if it
! 3239: is given.
! 3240:
! 3241: If $\fl=1$, uses the different. This is usually slower.
! 3242:
! 3243: \syn{idealinv0}{\var{nf},x,\fl}. Also available is
! 3244: $\teb{idealinv}(\var{nf},x)$ ($\fl=0$).
! 3245:
! 3246: \subsecidx{ideallist}$(\var{nf},\var{bound},\{\fl=4\})$: computes the list
! 3247: of all ideals of norm less or equal to \var{bound} in the number field
! 3248: \var{nf}. The result is a row vector with exactly \var{bound} components.
! 3249: Each component is itself a row vector containing the information about
! 3250: ideals of a given norm, in no specific order. This information can be
! 3251: either the HNF of the ideal or the \kbd{idealstar} with possibly some
! 3252: additional information.
! 3253:
! 3254: If $\fl$ is present, its binary digits are toggles meaning
! 3255:
! 3256: \quad 1: give also the generators in the \kbd{idealstar}.
! 3257:
! 3258: \quad 2: output $[L,U]$, where $L$ is as before and $U$ is a vector of
! 3259: \kbd{zinternallog}s of the units.
! 3260:
! 3261: \quad 4: give only the ideals and not the \kbd{idealstar} or the \kbd{ideallog}
! 3262: of the units.
! 3263:
! 3264: \syn{ideallist0}{\var{nf},\var{bound},\fl}, where \var{bound} must
! 3265: be a C long integer. Also available is $\teb{ideallist}(\var{nf},\var{bound})$,
! 3266: corresponding to the case $\fl=0$.
! 3267:
! 3268: \subsecidx{ideallistarch}$(\var{nf},\var{list},\{\var{arch}=[\,]\},\{\fl=0\})$:
! 3269: vector of vectors of all \kbd{idealstarinit} (see \kbd{idealstar}) of all
! 3270: modules in \var{list}, with Archimedean part \var{arch} added (void if
! 3271: omitted). \var{list} is a vector of big ideals, as output by
! 3272: \kbd{ideallist}$(\ldots, \fl)$ for instance. $\fl$ is optional; its binary
! 3273: digits are toggles meaning: 1: give generators as well, 2: list format is
! 3274: $[L,U]$ (see \kbd{ideallist}).
! 3275:
! 3276: \syn{ideallistarch0}{\var{nf},\var{list},\var{arch},\fl}, where an omitted
! 3277: \var{arch} is coded as \kbd{NULL}.
! 3278:
! 3279: \subsecidx{ideallog}$(\var{nf},x,\var{bid})$: $\var{nf}$ being a number field,
! 3280: \var{bid} being a ``big ideal'' as output by \kbd{idealstar} and $x$ being a
! 3281: non-necessarily integral element of \var{nf} which must have valuation
! 3282: equal to 0 at all prime ideals dividing $I=\var{bid}[1]$, computes the
! 3283: ``discrete logarithm'' of $x$ on the generators given in $\var{bid}[2]$.
! 3284: In other words, if $g_i$ are these generators, of orders $d_i$ respectively,
! 3285: the result is a column vector of integers $(x_i)$ such that $0\le x_i<d_i$ and
! 3286: $$x\equiv\prod_ig_i^{x_i}\pmod{\ ^*I}\enspace.$$
! 3287: Note that when $I$ is a module, this implies also sign conditions on the
! 3288: embeddings.
! 3289:
! 3290: \syn{zideallog}{\var{nf},x,\var{bid}}.
! 3291:
! 3292: \subsecidx{idealmin}$(\var{nf},x,\var{vdir})$: computes a minimum of the
! 3293: ideal $x$ in the direction \var{vdir} in the number field \var{nf}.
! 3294:
! 3295: \syn{minideal}{\var{nf},x,\var{vdir},\var{prec}}.
! 3296:
! 3297: \subsecidx{idealmul}$(\var{nf},x,y,\{\fl=0\})$: ideal multiplication of the
! 3298: ideals $x$ and $y$ in the number field \var{nf}. The result is a generating
! 3299: set for the ideal product with at most $n$ elements, and is in Hermite normal
! 3300: form if either $x$ or $y$ is in HNF or is a prime ideal as output by
! 3301: \kbd{idealprimedec}, and this is given together with the sum of the
! 3302: Archimedean information in $x$ and $y$ if both are given.
! 3303:
! 3304: If $\fl$ is non-zero, reduce the result using \kbd{idealred}.
! 3305:
! 3306: \syn{idealmul}{\var{nf},x,y} ($\fl=0$) or
! 3307: $\teb{idealmulred}(\var{nf},x,y,\var{prec})$ ($\fl\neq0$), where as usual,
! 3308: $\var{prec}$ is a C long integer representing the precision.
! 3309:
! 3310: \subsecidx{idealnorm}$(\var{nf},x)$: computes the norm of the ideal~$x$
! 3311: in the number field~$\var{nf}$.
! 3312:
! 3313: \syn{idealnorm}{\var{nf}, x}.
! 3314:
! 3315: \subsecidx{idealpow}$(\var{nf},x,k,\{\fl=0\})$: computes the $k$-th power of
! 3316: the ideal $x$ in the number field $\var{nf}$. $k$ can be positive, negative
! 3317: or zero. The result is NOT reduced, it is really the $k$-th ideal power, and
! 3318: is given in HNF.
! 3319:
! 3320: If $\fl$ is non-zero, reduce the result using \kbd{idealred}. Note however
! 3321: that this is NOT the same as as $\kbd{idealpow}(\var{nf},x,k)$ followed by
! 3322: reduction, since the reduction is performed throughout the powering process.
! 3323:
! 3324: The library syntax corresponding to $\fl=0$ is
! 3325: $\teb{idealpow}(\var{nf},x,k)$. If $k$ is a \kbd{long}, you can use
! 3326: $\teb{idealpows}(\var{nf},x,k)$. Corresponding to $\fl=1$ is
! 3327: $\teb{idealpowred}(\var{nf},vp,k,\var{prec})$, where $\var{prec}$ is a
! 3328: \kbd{long}.
! 3329:
! 3330: \subsecidx{idealprimedec}$(\var{nf},p)$: computes the prime ideal
! 3331: decomposition of the prime number $p$ in the number field $\var{nf}$. $p$
! 3332: must be a (positive) prime number. Note that the fact that $p$ is prime is
! 3333: not checked, so if a non-prime number $p$ is given it may lead to
! 3334: unpredictable results.
! 3335:
! 3336: The result is a vector of 5-component vectors, each representing one of the
! 3337: prime ideals above $p$ in the number field $\var{nf}$. The representation
! 3338: $vp=[p,a,e,f,b]$ of a prime ideal means the following. The prime ideal is
! 3339: equal to $p\Z_K+\alpha\Z_K$ where $\Z_K$ is the ring of integers of the field
! 3340: and $\alpha=\sum_i a_i\omega_i$ where the $\omega_i$ form the integral basis
! 3341: \kbd{\var{nf}.zk}, $e$ is the ramification index, $f$ is the residual index,
! 3342: and $b$ is an $n$-component column vector representing a $\beta\in\Z_K$ such
! 3343: that $vp^{-1}=\Z_K+\beta/p\Z_K$ which will be useful for computing
! 3344: valuations, but which the user can ignore. The number $\alpha$ is guaranteed
! 3345: to have a valuation equal to 1 at the prime ideal (this is automatic if
! 3346: $e>1$).
! 3347:
! 3348: \syn{idealprimedec}{\var{nf},p}.
! 3349:
! 3350: \subsecidx{idealprincipal}$(\var{nf},x)$: creates the principal ideal
! 3351: generated by the algebraic number $x$ (which must be of type integer,
! 3352: rational or polmod) in the number field $\var{nf}$. The result is a
! 3353: one-column matrix.
! 3354:
! 3355: \syn{principalideal}{\var{nf},x}.
! 3356:
! 3357: \subsecidx{idealred}$(\var{nf},x,\{\var{vdir}=0\})$: \idx{LLL} reduction of
! 3358: the ideal $x$ in the number field \var{nf}, along the direction \var{vdir}.
! 3359: Here \var{vdir} must be either an $r1+r2$-component vector ($r1$ and $r2$
! 3360: number of real and complex places of \var{nf} as usual), or the PARI zero,
! 3361: in which case \var{vdir} is assumed to be equal to the vector having only
! 3362: components equal to 1. The notion of reduction along a direction is
! 3363: technical and cannot be explained here. Note that this is {\it not\/} the
! 3364: same as the LLL reduction of the lattice $x$ since ideal operations are
! 3365: involved. The result is the \idx{Hermite normal form} of the LLL-reduced
! 3366: ideal, which is usually, but not always, a reduced ideal. $x$ may also be a
! 3367: 2-component vector, the first being as above, and the second containing a
! 3368: matrix of Archimedean information. In that case, this matrix is suitably
! 3369: updated.
! 3370:
! 3371: \syn{ideallllred}{\var{nf},x,\var{vdir},\var{prec}}.
! 3372:
! 3373: \subsecidx{idealstar}$(\var{nf},I,\{\fl=1\})$: \var{nf} being a number
! 3374: field, and $I$
! 3375: either and ideal in any form, or a row vector whose first component is an
! 3376: ideal and whose second component is a row vector of $r_1$ 0 or 1, outputs
! 3377: necessary data for computing in the group $(\Z_K/I)^*$.
! 3378:
! 3379: If $\fl=2$, the result is a 5-component vector $w$. $w[1]$ is the ideal
! 3380: or module $I$ itself. $w[2]$ is the structure of the group. The other
! 3381: components are difficult to describe and are used only in conjunction with
! 3382: the function \kbd{ideallog}.
! 3383:
! 3384: If $\fl=1$ (default), as $\fl=2$, but do not compute explicit generators
! 3385: for the cyclic components, which saves time.
! 3386:
! 3387: If $\fl=0$, computes the structure of $(\Z_K/I)^*$ as a 3-component vector
! 3388: $v$. $v[1]$ is the order, $v[2]$ is the vector of SNF\sidx{Smith normal form}
! 3389: cyclic components and
! 3390: $v[3]$ the corresponding generators. When the row vector is explicitly
! 3391: included, the
! 3392: non-zero elements of this vector are considered as real embeddings of
! 3393: \var{nf} in the order given by \kbd{polroots}, i.e.~in \var{nf\/}[6]
! 3394: (\kbd{\var{nf}.roots}), and then $I$ is a module with components at infinity.
! 3395:
! 3396: To solve discrete logarithms (using \kbd{ideallog}), you have to choose
! 3397: $\fl=2$.
! 3398:
! 3399: \syn{idealstar0}{\var{nf},I,\fl}.
! 3400:
! 3401: \subsecidx{idealtwoelt}$(\var{nf},x,\{a\})$: computes a two-element
! 3402: representation of the ideal $x$ in the number field $\var{nf}$, using a
! 3403: straightforward (exponential time) search. $x$ can be an ideal in any form,
! 3404: (including perhaps an Archimedean part, which is ignored) and the result is a
! 3405: row vector $[a,\alpha]$ with two components such that $x=a\Z_K+\alpha\Z_K$
! 3406: and $a\in\Z$, where $a$ is the one passed as argument if any. If $x$ is given
! 3407: by at least two generators, $a$ is chosen to be the positive generator of
! 3408: $x\cap\Z$.
! 3409:
! 3410: Note that when an explicit $a$ is given, we use an asymptotically faster
! 3411: method, however in practice it is usually slower.
! 3412:
! 3413: \synx{ideal\_two\_elt0}{\var{nf},x,a}{ideal\string\_two\string\_elt0}, where
! 3414: an omitted $a$ is entered as \kbd{NULL}.
! 3415:
! 3416: \subsecidx{idealval}$(\var{nf},x,\var{vp})$: gives the valuation of the
! 3417: ideal $x$ at the prime ideal \var{vp} in the number field $\var{nf}$,
! 3418: where \var{vp} must be a
! 3419: 5-component vector as given by \kbd{idealprimedec}.
! 3420:
! 3421: \syn{idealval}{\var{nf},x,\var{vp}}, and the result is a \kbd{long}
! 3422: integer.
! 3423:
! 3424: \subsecidx{ideleprincipal}$(\var{nf},x)$: creates the principal idele
! 3425: generated by the algebraic number $x$ (which must be of type integer,
! 3426: rational or polmod) in the number field $\var{nf}$. The result is a
! 3427: two-component vector, the first being a one-column matrix representing the
! 3428: corresponding principal ideal, and the second being the vector with $r_1+r_2$
! 3429: components giving the complex logarithmic embedding of $x$.
! 3430:
! 3431: \syn{principalidele}{\var{nf},x}.
! 3432:
! 3433: \subsecidx{matalgtobasis}$(\var{nf},x)$: $\var{nf}$ being a number field in
! 3434: \kbd{nfinit} format, and $x$ a matrix whose coefficients are expressed as
! 3435: polmods in $\var{nf}$, transforms this matrix into a matrix whose
! 3436: coefficients are expressed on the integral basis of $\var{nf}$. This is the
! 3437: same as applying \kbd{nfalgtobasis} to each entry, but it would be dangerous
! 3438: to use the same name.
! 3439:
! 3440: \syn{matalgtobasis}{\var{nf},x}.
! 3441:
! 3442: \subsecidx{matbasistoalg}$(\var{nf},x)$: $\var{nf}$ being a number field in
! 3443: \kbd{nfinit} format, and $x$ a matrix whose coefficients are expressed as
! 3444: column vectors on the integral basis of $\var{nf}$, transforms this matrix
! 3445: into a matrix whose coefficients are algebraic numbers expressed as
! 3446: polmods. This is the same as applying \kbd{nfbasistoalg} to each entry, but
! 3447: it would be dangerous to use the same name.
! 3448:
! 3449: \syn{matbasistoalg}{\var{nf},x}.
! 3450:
! 3451: \subsecidx{modreverse}$(a)$: $a$ being a polmod $A(X)$ modulo $T(X)$, finds
! 3452: the ``reverse polmod'' $B(X)$ modulo $Q(X)$, where $Q$ is the minimal
! 3453: polynomial of $a$, which must be equal to the degree of $T$, and such that if
! 3454: $\theta$ is a root of $T$ then $\theta=B(\alpha)$ for a certain root $\alpha$
! 3455: of $Q$.
! 3456:
! 3457: This is very useful when one changes the generating element in algebraic
! 3458: extensions.
! 3459:
! 3460: \syn{polmodrecip}{x}.
! 3461:
! 3462: \subsecidx{newtonpoly}$(x,p)$: gives the vector of the slopes of the Newton
! 3463: polygon of the polynomial $x$ with respect to the prime number $p$. The $n$
! 3464: components of the vector are in decreasing order, where $n$ is equal to the
! 3465: degree of $x$. Vertical slopes occur iff the constant coefficient of $x$ is
! 3466: zero and are denoted by \kbd{VERYBIGINT}, the biggest single precision
! 3467: integer representable on the machine ($2^{31}-1$ (resp.~$2^{63}-1$) on 32-bit
! 3468: (resp.~64-bit) machines), see \secref{se:valuation}.
! 3469:
! 3470: \syn{newtonpoly}{x,p}.
! 3471:
! 3472: \subsecidx{nfalgtobasis}$(\var{nf},x)$: this is the inverse function of
! 3473: \kbd{nfbasistoalg}. Given an object $x$ whose entries are expressed as
! 3474: algebraic numbers in the number field $\var{nf}$, transforms it so that the
! 3475: entries are expressed as a column vector on the integral basis
! 3476: \kbd{\var{nf}.zk}.
! 3477:
! 3478: \syn{algtobasis}{\var{nf},x}.
! 3479:
! 3480: \subsecidx{nfbasis}$(x,\{\fl=0\},\{p\})$: \idx{integral basis} of the number
! 3481: field defined by the irreducible, preferably monic, polynomial $x$, using the
! 3482: \idx{round 4} algorithm by default. (This program is the translation into C by
! 3483: Pascal Letard of a program written by David \idx{Ford} in Maple.) The binary
! 3484: digits of $\fl$ have the following meaning:
! 3485:
! 3486: 1: assume that no square of a prime greater than the default \kbd{primelimit}
! 3487: divides the discriminant of $x$, i.e.~that the index of $x$ has only small
! 3488: prime divisors.
! 3489:
! 3490: 2: use \idx{round 2} algorithm. For small degrees and coefficient size, this is
! 3491: sometimes a little faster. (This program is the translation into C of a program
! 3492: written by David \idx{Ford} in Algeb.)
! 3493:
! 3494: Thus for instance, if $\fl=3$, this uses the round 2 algorithm and outputs
! 3495: an order which will be maximal at all the small primes.
! 3496:
! 3497: If $p$ is present, we assume (without checking!) that it is the two-column
! 3498: matrix of the factorization of the discriminant of the polynomial $x$. Note
! 3499: that it does {\it not\/} have to be a complete factorization. This is
! 3500: especially useful if only a local integral basis for some small set of places
! 3501: is desired: only factors with exponents greater or equal to 2 will be
! 3502: considered.
! 3503:
! 3504: \syn{nfbasis0}{x,\fl,p}. An extended version
! 3505: is $\teb{nfbasis}(x,\&d,\fl,p)$, where $d$ will receive the discriminant of
! 3506: the number field ({\it not\/} of the polynomial $x$), and an omitted $p$ should
! 3507: be input as \kbd{gzero}. Also available are $\teb{base}(x,\&d)$ ($\fl=0$),
! 3508: $\teb{base2}(x,\&d)$ ($\fl=2$) and $\teb{factoredbase}(x,p,\&d)$.
! 3509:
! 3510: \subsecidx{nfbasistoalg}$(\var{nf},x)$: this is the inverse function of
! 3511: \kbd{nfalgtobasis}. Given an object $x$ whose entries are expressed on the
! 3512: integral basis \kbd{\var{nf}.zk}, transforms it into an object whose entries
! 3513: are algebraic numbers (i.e.~polmods).
! 3514:
! 3515: \syn{basistoalg}{\var{nf},x}.
! 3516:
! 3517: \subsecidx{nfdetint}$(\var{nf},x)$: given a pseudo-matrix $x$, computes a
! 3518: non-zero ideal contained in (i.e.~multiple of) the determinant of $x$. This
! 3519: is particularly useful in conjunction with \kbd{nfhnfmod}.
! 3520:
! 3521: \syn{nfdetint}{\var{nf},x}.
! 3522:
! 3523: \subsecidx{nfdisc}$(x,\{\fl=0\},\{p\})$: \idx{field discriminant} of the
! 3524: number field defined by the integral, preferably monic, irreducible
! 3525: polynomial $x$. $\fl$ and $p$ are exactly as in \kbd{nfbasis}. That is, $p$
! 3526: provides the matrix of a partial factorization of the discriminant of $x$,
! 3527: and binary digits of $\fl$ are as follows:
! 3528:
! 3529: 1: assume that no square of a prime greater than \kbd{primelimit}
! 3530: divides the discriminant.
! 3531:
! 3532: 2: use the round 2 algorithm, instead of the default \idx{round 4}.
! 3533: This should be
! 3534: slower except maybe for polynomials of small degree and coefficients.
! 3535:
! 3536: \syn{nfdiscf0}{x,\fl,p} where, to omit $p$, you should input \kbd{gzero}. You
! 3537: can also use $\teb{discf}(x)$ ($\fl=0$).
! 3538:
! 3539: \subsecidx{nfeltdiv}$(\var{nf},x,y)$: given two elements $x$ and $y$ in
! 3540: \var{nf}, computes their quotient $x/y$ in the number field $\var{nf}$.
! 3541:
! 3542: \synx{element\_div}{\var{nf},x,y}{element\string\_div}.
! 3543:
! 3544: \subsecidx{nfeltdiveuc}$(\var{nf},x,y)$: given two elements $x$ and $y$ in
! 3545: \var{nf}, computes an algebraic integer $q$ in the number field $\var{nf}$
! 3546: such that the components of $x-qy$ are reasonably small. In fact, this is
! 3547: functionally identical to \kbd{round(nfeltdiv(\var{nf},x,y))}.
! 3548:
! 3549: \syn{nfdiveuc}{\var{nf},x,y}.
! 3550:
! 3551: \subsecidx{nfeltdivmodpr}$(\var{nf},x,y,\var{pr})$: given two elements $x$
! 3552: and $y$ in \var{nf} and \var{pr} a prime ideal in \kbd{modpr} format (see
! 3553: \tet{nfmodprinit}), computes their quotient $x / y$ modulo the prime ideal
! 3554: \var{pr}.
! 3555:
! 3556: \synx{element\_divmodpr}{\var{nf},x,y,\var{pr}}{element\string\_divmodpr}.
! 3557:
! 3558: \subsecidx{nfeltdivrem}$(\var{nf},x,y)$: given two elements $x$ and $y$ in
! 3559: \var{nf}, gives a two-element row vector $[q,r]$ such that $x=qy+r$, $q$ is
! 3560: an algebraic integer in $\var{nf}$, and the components of $r$ are
! 3561: reasonably small.
! 3562:
! 3563: \syn{nfdivres}{\var{nf},x,y}.
! 3564:
! 3565: \subsecidx{nfeltmod}$(\var{nf},x,y)$: given two elements $x$ and $y$ in
! 3566: \var{nf}, computes an element $r$ of $\var{nf}$ of the form $r=x-qy$ with
! 3567: $q$ and algebraic integer, and such that $r$ is small. This is functionally
! 3568: identical to
! 3569: $$\kbd{x - nfeltmul(\var{nf},round(nfeltdiv(\var{nf},x,y)),y)}.$$
! 3570:
! 3571: \syn{nfmod}{\var{nf},x,y}.
! 3572:
! 3573: \subsecidx{nfeltmul}$(\var{nf},x,y)$: given two elements $x$ and $y$ in
! 3574: \var{nf}, computes their product $x*y$ in the number field $\var{nf}$.
! 3575:
! 3576: \synx{element\_mul}{\var{nf},x,y}{element\string\_mul}.
! 3577:
! 3578: \subsecidx{nfeltmulmodpr}$(\var{nf},x,y,\var{pr})$: given two elements $x$ and
! 3579: $y$ in \var{nf} and \var{pr} a prime ideal in \kbd{modpr} format (see
! 3580: \tet{nfmodprinit}), computes their product $x*y$ modulo the prime ideal
! 3581: \var{pr}.
! 3582:
! 3583: \synx{element\_mulmodpr}{\var{nf},x,y,\var{pr}}{element\string\_mulmodpr}.
! 3584:
! 3585: \subsecidx{nfeltpow}$(\var{nf},x,k)$: given an element $x$ in \var{nf},
! 3586: and a positive or negative integer $k$, computes $x^k$ in the number field
! 3587: $\var{nf}$.
! 3588:
! 3589: \synx{element\_pow}{\var{nf},x,k}{element\string\_pow}.
! 3590:
! 3591: \subsecidx{nfeltpowmodpr}$(\var{nf},x,k,\var{pr})$: given an element $x$ in
! 3592: \var{nf}, an integer $k$ and a prime ideal \var{pr} in \kbd{modpr} format
! 3593: (see \tet{nfmodprinit}), computes $x^k$ modulo the prime ideal \var{pr}.
! 3594:
! 3595: \synx{element\_powmodpr}{\var{nf},x,k,\var{pr}}{element\string\_powmodpr}.
! 3596:
! 3597: \subsecidx{nfeltreduce}$(\var{nf},x,\var{ideal})$: given an ideal in
! 3598: Hermite normal form and an element $x$ of the number field $\var{nf}$,
! 3599: finds an element $r$ in $\var{nf}$ such that $x-r$ belongs to the ideal
! 3600: and $r$ is small.
! 3601:
! 3602: \synx{element\_reduce}{\var{nf},x,\var{ideal}}{element\string\_reduce}.
! 3603:
! 3604: \subsecidx{nfeltreducemodpr}$(\var{nf},x,\var{pr})$: given
! 3605: an element $x$ of the number field $\var{nf}$ and a prime ideal \var{pr} in
! 3606: \kbd{modpr} format compute a canonical representative for the class of $x$
! 3607: modulo \var{pr}.
! 3608:
! 3609: \syn{nfreducemodpr2}{\var{nf},x,\var{pr}}.
! 3610:
! 3611: \subsecidx{nfeltval}$(\var{nf},x,\var{pr})$: given an element $x$ in
! 3612: \var{nf} and a prime ideal \var{pr} in the format output by
! 3613: \kbd{idealprimedec}, computes their the valuation at \var{pr} of the
! 3614: element $x$. The same result could be obtained using
! 3615: \kbd{idealval(\var{nf},x,\var{pr})} (since $x$ would then be converted to a
! 3616: principal ideal), but it would be less efficient.
! 3617:
! 3618: \synx{element\_val}{\var{nf},x,\var{pr}}{element\string\_val},
! 3619: and the result is a \kbd{long}.
! 3620:
! 3621: \subsecidx{nf{}factor}$(\var{nf},x)$: factorization of the univariate
! 3622: polynomial $x$ over the number field $\var{nf}$ given by \kbd{nfinit}. $x$
! 3623: has coefficients in $\var{nf}$ (i.e.~either scalar, polmod, polynomial or
! 3624: column vector). The main variable of $\var{nf}$ must be of {\it lower\/}
! 3625: priority than that of $x$ (in other words, the variable number of $\var{nf}$
! 3626: must be {\it greater\/} than that of $x$). However if the polynomial defining
! 3627: the number field occurs explicitly in the coefficients of $x$ (as modulus of
! 3628: a \typ{POLMOD}), its main variable must be {\it the same\/} as the main
! 3629: variable of $x$. For example, if $\var{nf}=\hbox{\kbd{nfinit(y\pow 2+1)}}$
! 3630: then
! 3631: \hbox{\kbd{nffactor(\var{nf},x\pow 2+Mod(y,y\pow 2+1))}} and
! 3632: \hbox{\kbd{nffactor(\var{nf},x\pow 2+1)}} are both legal but
! 3633: \hbox{\kbd{nffactor(\var{nf},x\pow 2+Mod(z,z\pow 2+1))}} is not.
! 3634:
! 3635: \syn{nf{}factor}{\var{nf},x}.
! 3636:
! 3637: \subsecidx{nf{}factormod}$(\var{nf},x,\var{pr})$: factorization of the
! 3638: univariate polynomial $x$ modulo the prime ideal \var{pr} in the number
! 3639: field $\var{nf}$. $x$ can have coefficients in the number field (scalar,
! 3640: polmod, polynomial, column vector) or modulo the prime ideal (integermod
! 3641: modulo the rational prime under \var{pr}, polmod or polynomial with
! 3642: integermod coefficients, column vector of integermod). The prime ideal
! 3643: \var{pr} {\it must\/} be in the format output by \kbd{idealprimedec}. The
! 3644: main variable of $\var{nf}$ must be of lower priority than that of $x$ (in
! 3645: other words the variable number of $\var{nf}$ must be greater than that of
! 3646: $x$). However if the coefficients of the number field occur explicitly (as
! 3647: polmods) as coefficients of $x$, the variable of these polmods {\it must\/}
! 3648: be the same as the main variable of $t$ (see \kbd{nffactor}).
! 3649:
! 3650: \syn{nf{}factormod}{\var{nf},x,\var{pr}}.
! 3651:
! 3652: \subsecidx{nfgaloisapply}$(\var{nf},\var{aut},x)$: $\var{nf}$ being a
! 3653: number field as output by \kbd{nfinit}, and \var{aut} being a \idx{Galois}
! 3654: automorphism of $\var{nf}$ expressed either as a polynomial or a polmod
! 3655: (such automorphisms being found using for example one of the variants of
! 3656: \kbd{nfgaloisconj}), computes the action of the automorphism \var{aut} on
! 3657: the object $x$ in the number field. $x$ can be an element (scalar, polmod,
! 3658: polynomial or column vector) of the number field, an ideal (either given by
! 3659: $\Z_K$-generators or by a $\Z$-basis), a prime ideal (given as a 5-element
! 3660: row vector) or an idele (given as a 2-element row vector). Because of
! 3661: possible confusion with elements and ideals, other vector or matrix
! 3662: arguments are forbidden.
! 3663:
! 3664: \syn{galoisapply}{\var{nf},\var{aut},x}.
! 3665:
! 3666: \subsecidx{nfgaloisconj}$(\var{nf},\{\fl=0\},\{d\})$: $\var{nf}$ being a
! 3667: number field as output by \kbd{nfinit}, computes the conjugates of a root
! 3668: $r$ of the non-constant polynomial $x=\var{nf\/}[1]$ expressed as
! 3669: polynomials in $r$. This can be used even if the number field $\var{nf}$ is
! 3670: not \idx{Galois} since some conjugates may lie in the field. As a note to
! 3671: old-timers of PARI, starting with version 2.0.17 this function works much
! 3672: better than in earlier versions.
! 3673:
! 3674: $\var{nf}$ can simply be a polynomial if $\fl\neq 1$.
! 3675:
! 3676: If no flags or $\fl=0$, if $\var{nf}$ is a number field use a combination
! 3677: of flag $4$ and $1$ and the result is always complete, else use a
! 3678: combination of flag $4$ and $2$ and the result is subject to the
! 3679: restriction of $\fl=2$.
! 3680:
! 3681: If $\fl=1$, use \kbd{nfroots} (require a number field).
! 3682:
! 3683: If $\fl=2$, use complex approximations to the roots and an integral
! 3684: \idx{LLL}. The result is not guaranteed to be complete: some conjugates may
! 3685: be missing (especially so if the corresponding polynomial has a huge
! 3686: index). In that case, increasing the default precision may help.
! 3687:
! 3688: If $\fl=4$, use Allombert's algorithm and permutation testing. If the field
! 3689: is Galois with ``weakly'' super solvable Galois group, return the complete
! 3690: list of automorphisms, else only the identity element. If present, $d$ is
! 3691: assumed to be a multiple of the index of the power basis in the maximal
! 3692: order.
! 3693:
! 3694: A group G is ``weakly'' super solvable if it contains a super solvable
! 3695: normal subgroup $H$ such that $G=H$ , or $G/H \simeq A_4$ , or $G/H \simeq
! 3696: S_4$. Abelian and nilpotent groups are ``weakly'' super solvable. In
! 3697: practice, almost all groups of small order are weakly super solvable, the
! 3698: exceptions having order 36(1 exception), 48(2), 56(1), 60(1), 72(5), 75(1),
! 3699: 80(1), 96(10) and $\geq 108$.
! 3700:
! 3701: Hence $\fl = 4$ permits to quickly check whether a polynomial of order
! 3702: strictly less than $36$ is Galois or not. This method is much faster than
! 3703: \kbd{nfroots} and be applied to polynomial of degree more than $50$.
! 3704:
! 3705: \syn{galoisconj0}{\var{nf},\fl,d,\var{prec}}. Also available are
! 3706: $\teb{galoisconj}(\var{nf})$ for $\fl=0$,
! 3707: $\teb{galoisconj2}(\var{nf},n,\var{prec})$ for $\fl=2$ where $n$ is a bound
! 3708: on the number of conjugates, and $\teb{galoisconj4}(\var{nf},d)$
! 3709: corresponding to $\fl=4$.
! 3710:
! 3711: \subsecidx{nfhilbert}$(\var{nf},a,b,\{\var{pr}\})$: if \var{pr} is omitted,
! 3712: compute the global \idx{Hilbert symbol} $(a,b)$ in $\var{nf}$, that is $1$
! 3713: if $x^2 - a y^2 - b z^2$ has a non trivial solution $(x,y,z)$ in $\var{nf}$,
! 3714: and $-1$ otherwise. Otherwise compute the local symbol modulo the prime ideal
! 3715: \var{pr} (as output by \kbd{idealprimedec}).
! 3716:
! 3717: \syn{nfhilbert}{\var{nf},a,b,\var{pr}}, where an omitted \var{pr} is coded
! 3718: as \kbd{NULL}.
! 3719:
! 3720: \subsecidx{nfhnf}$(\var{nf},x)$: given a pseudo-matrix $(A,I)$, finds a
! 3721: pseudo-basis in \idx{Hermite normal form} of the module it generates.
! 3722:
! 3723: \syn{nfhermite}{\var{nf},x}.
! 3724:
! 3725: \subsecidx{nfhnfmod}$(\var{nf},x,\var{detx})$: given a pseudo-matrix $(A,I)$
! 3726: and an ideal \var{detx} which is contained in (read integral multiple of) the
! 3727: determinant of $(A,I)$, finds a pseudo-basis in \idx{Hermite normal form}
! 3728: of the module generated by $(A,I)$. This avoids coefficient explosion.
! 3729: \var{detx} can be computed using the function \kbd{nfdetint}.
! 3730:
! 3731: \syn{nfhermitemod}{\var{nf},x,\var{detx}}.
! 3732:
! 3733: \subsecidx{nf{}init}$(\var{pol},\{\fl=0\})$: \var{pol} being a non-constant,
! 3734: preferably monic, irreducible polynomial in $\Z[X]$, computes a 9-component
! 3735: vector \var{nf} useful in working in the number field $K$ defined by
! 3736: \var{pol}.
! 3737:
! 3738: $\var{nf\/}[1]$ contains the polynomial \var{pol} (\kbd{\var{nf}.pol}).
! 3739:
! 3740: $\var{nf\/}[2]$ contains $[r1,r2]$ (\kbd{\var{nf}.sign}), the number of real
! 3741: and complex places of $K$.
! 3742:
! 3743: $\var{nf\/}[3]$ contains the discriminant $d(K)$ (\kbd{\var{nf}.disc}) of
! 3744: the number field $K$.
! 3745:
! 3746: $\var{nf\/}[4]$ contains the index of $\var{nf\/}[1]$,
! 3747: i.e.~$[\Z_K:\Z[\theta]]$, where $\theta$ is any root of $\var{nf\/}[1]$.
! 3748:
! 3749: $\var{nf\/}[5]$ is a vector containing 7 matrices $M$, $MC$, $T2$, $T$,
! 3750: $MD$, $TI$, $MDI$ useful for certain computations in the number field $K$.
! 3751:
! 3752: \quad$\bullet$ $M$ is the $(r1+r2)\times n$ matrix whose columns represent
! 3753: the numerical values of the conjugates of the elements of the integral
! 3754: basis.
! 3755:
! 3756: \quad$\bullet$ $MC$ is essentially the conjugate of the transpose of $M$,
! 3757: except that the last $r2$ columns are also multiplied by 2.
! 3758:
! 3759: \quad$\bullet$ $T2$ is an $n\times n$ matrix equal to the real part of the
! 3760: product $MC\cdot M$ (which is a real positive definite symmetric matrix), the
! 3761: so-called $T_2$-matrix (\kbd{\var{nf}.t2}).
! 3762:
! 3763: \quad$\bullet$ $T$ is the $n\times n$ matrix whose coefficients are
! 3764: $\text{Tr}(\omega_i\omega_j)$ where the $\omega_i$ are the elements of the
! 3765: integral basis. Note that $T=\overline{MC}\cdot M$ and in particular that
! 3766: $T=T_2$ if the field is totally real (in practice $T_2$ will have real
! 3767: approximate entries and $T$ will have integer entries). Note also that
! 3768: $\det(T)$ is equal to the discriminant of the field $K$.
! 3769:
! 3770: \quad$\bullet$ The columns of $MD$ (\kbd{\var{nf}.diff}) express a $\Z$-basis
! 3771: of the different of $K$ on the integral basis.
! 3772:
! 3773: \quad$\bullet$ $TI$ is equal to $d(K)T^{-1}$, which has integral
! 3774: coefficients.
! 3775:
! 3776: \quad$\bullet$ Finally, $MDI$ has the form $[x,y,n]$, where $(x,y)$ expresses
! 3777: a $\Z_K$-basis of $d(K)$ times the codifferent ideal
! 3778: (\kbd{\var{nf}.disc$*$\var{nf}.codiff}, which is an integral ideal) and $n$
! 3779: is its norm (this ideal is used in \tet{idealinv}).
! 3780:
! 3781: $\var{nf\/}[6]$ is the vector containing the $r1+r2$ roots
! 3782: (\kbd{\var{nf}.roots}) of $\var{nf\/}[1]$ corresponding to the $r1+r2$
! 3783: embeddings of the number field into $\C$ (the first $r1$ components are real,
! 3784: the next $r2$ have positive imaginary part).
! 3785:
! 3786: $\var{nf\/}[7]$ is an integral basis in Hermite normal form for $\Z_K$
! 3787: (\kbd{\var{nf}.zk}) expressed on the powers of~$\theta$.
! 3788:
! 3789: $\var{nf\/}[8]$ is the $n\times n$ integral matrix expressing the power
! 3790: basis in terms of the integral basis, and finally
! 3791:
! 3792: $\var{nf\/}[9]$ is the $n\times n^2$ matrix giving the multiplication table
! 3793: of the integral basis.
! 3794:
! 3795: If a non monic polynomial is input, \kbd{nfinit} will transform it into a
! 3796: monic one, then reduce it (see $\fl=3$). It is allowed, though not very
! 3797: useful given the existence of \teb{nfnewprec}, to input a \kbd{nf} or a
! 3798: \kbd{bnf} instead of a polynomial.
! 3799:
! 3800: The special input format $[x,B]$ is also accepted where $x$ is a polynomial
! 3801: as above and $B$ is the integer basis, as computed by \tet{nfbasis}. This can
! 3802: be useful since \kbd{nfinit} uses the round 4 algorithm by default, which can
! 3803: be very slow in pathological cases where round 2 (\kbd{nfbasis(x,2)}) would
! 3804: succeed very quickly.
! 3805:
! 3806: If $\fl=1$: does not compute the different, replace it by a dummy $0$.
! 3807:
! 3808: If $\fl=2$: \var{pol} is changed into another polynomial $P$ defining the same
! 3809: number field, which is as simple as can easily be found using the
! 3810: \kbd{polred} algorithm, and all the subsequent computations are done using
! 3811: this new polynomial. In particular, the first component of the result is the
! 3812: modified polynomial.
! 3813:
! 3814: If $\fl=3$, does a \kbd{polred} as in case 2, but outputs
! 3815: $[\var{nf},\kbd{Mod}(a,P)]$, where $\var{nf}$ is as before and
! 3816: $\kbd{Mod}(a,P)=\kbd{Mod}(x,\var{pol})$ gives the change of
! 3817: variables. This is implicit when \var{pol} is not monic: first a linear change
! 3818: of variables is performed, to get a monic polynomial, then a \kbd{polred}
! 3819: reduction.
! 3820:
! 3821: If $\fl=4$, as $2$ but uses a partial \kbd{polred}.
! 3822:
! 3823: If $\fl=5$, as $3$ using a partial \kbd{polred}.
! 3824:
! 3825: \syn{nf{}init0}{x,\fl,\var{prec}}.
! 3826:
! 3827: \subsecidx{nf{}isideal}$(\var{nf},x)$: returns 1 if $x$ is an ideal in
! 3828: the number field $\var{nf}$, 0 otherwise.
! 3829:
! 3830: \syn{isideal}{x}.
! 3831:
! 3832: \subsecidx{nf{}isincl}$(x,y)$: tests whether the number field $K$ defined
! 3833: by the polynomial $x$ is conjugate to a subfield of the field $L$ defined
! 3834: by $y$ (where $x$ and $y$ must be in $\Q[X]$). If they are not, the output
! 3835: is the number 0. If they are, the output is a vector of polynomials, each
! 3836: polynomial $a$ representing an embedding of $K$ into $L$, i.e.~being such
! 3837: that $y\mid x\circ a$.
! 3838:
! 3839: If $y$ is a number field (\var{nf}), a much faster algorithm is used
! 3840: (factoring $x$ over $y$ using \tet{nffactor}). Before version 2.0.14, this
! 3841: wasn't guaranteed to return all the embeddings, hence was triggered by a
! 3842: special flag. This is no more the case.
! 3843:
! 3844: \syn{nf{}isincl}{x,y,\fl}.
! 3845:
! 3846: \subsecidx{nf{}isisom}$(x,y)$: as \tet{nfisincl}, but tests
! 3847: for isomorphism. If either $x$ or $y$ is a number field, a much faster
! 3848: algorithm will be used.
! 3849:
! 3850: \syn{nf{}isisom}{x,y,\fl}.
! 3851:
! 3852: \subsecidx{nfnewprec}$(\var{nf\/})$: transforms the number field $\var{nf}$
! 3853: into the corresponding data using current (usually larger) precision. This
! 3854: function works as expected if $\var{nf}$ is in fact a $\var{bnf}$ (update
! 3855: $\var{bnf}$ to current precision) but may be quite slow (many generators of
! 3856: principal ideals have to be computed).
! 3857:
! 3858: \syn{nfnewprec}{\var{nf},\var{prec}}.
! 3859:
! 3860: \subsecidx{nfkermodpr}$(\var{nf},a,\var{pr})$: kernel of the matrix $a$ in
! 3861: $\Z_K/\var{pr}$, where \var{pr} is in \key{modpr} format
! 3862: (see \kbd{nfmodprinit}).
! 3863:
! 3864: \syn{nfkermodpr}{\var{nf},a,\var{pr}}.
! 3865:
! 3866: \subsecidx{nfmodprinit}$(\var{nf},\var{pr})$: transforms the prime ideal
! 3867: \var{pr} into \tet{modpr} format necessary for all operations modulo
! 3868: \var{pr} in the number field \var{nf}. Returns a two-component vector
! 3869: $[P,a]$, where $P$ is the \idx{Hermite normal form} of \var{pr}, and $a$ is
! 3870: an integral element congruent to $1$ modulo \var{pr}, and congruent to $0$
! 3871: modulo $p / pr^e$. Here $p = \Z \cap \var{pr}$ and $e$
! 3872: is the absolute ramification index.\label{se:nfmodprinit}
! 3873:
! 3874: \syn{nfmodprinit}{\var{nf},\var{pr}}.
! 3875:
! 3876: \subsecidx{nfsubfields}$(\var{nf},\{d=0\})$: finds all subfields of degree $d$
! 3877: of the number field $\var{nf}$ (all subfields if $d$ is null or omitted).
! 3878: The result is a vector of subfields, each being given by $[g,h]$, where $g$ is an
! 3879: absolute equation and $h$ expresses one of the roots of $g$ in terms of the
! 3880: root $x$ of the polynomial defining $\var{nf}$. This is a crude
! 3881: implementation by M.~Olivier of an algorithm due to J.~Kl\"uners.
! 3882:
! 3883: \syn{subfields}{\var{nf},d}.
! 3884:
! 3885: \subsecidx{nfroots}$(\var{nf},x)$: roots of the polynomial $x$ in the number
! 3886: field $\var{nf}$ given by \kbd{nfinit} without multiplicity. $x$ has
! 3887: coefficients in the number field (scalar, polmod, polynomial, column
! 3888: vector). The main variable of $\var{nf}$ must be of lower priority than that
! 3889: of $x$ (in other words the variable number of $\var{nf}$ must be greater than
! 3890: that of $x$). However if the coefficients of the number field occur
! 3891: explicitly (as polmods) as coefficients of $x$, the variable of these
! 3892: polmods {\it must\/} be the same as the main variable of $t$ (see
! 3893: \kbd{nffactor}).
! 3894:
! 3895: \syn{nfroots}{\var{nf},x}.
! 3896:
! 3897: \subsecidx{nfrootsof1}$(\var{nf\/})$: computes the number of roots of unity
! 3898: $w$ and a primitive $w$-th root of unity (expressed on the integral basis)
! 3899: belonging to the number field $\var{nf}$. The result is a two-component
! 3900: vector $[w,z]$ where $z$ is a column vector expressing a primitive $w$-th
! 3901: root of unity on the integral basis \kbd{\var{nf}.zk}.
! 3902:
! 3903: \syn{rootsof1}{\var{nf\/}}.
! 3904:
! 3905: \subsecidx{nfsnf}$(\var{nf},x)$: given a torsion module $x$ as a 3-component
! 3906: row
! 3907: vector $[A,I,J]$ where $A$ is a square invertible $n\times n$ matrix, $I$ and
! 3908: $J$ are two ideal lists, outputs an ideal list $d_1,\dots,d_n$ which is the
! 3909: \idx{Smith normal form} of $x$. In other words, $x$ is isomorphic to
! 3910: $\Z_K/d_1\oplus\cdots\oplus\Z_K/d_n$ and $d_i$ divides $d_{i-1}$ for $i\ge2$.
! 3911: The link between $x$ and $[A,I,J]$ is as follows: if $e_i$ is the canonical
! 3912: basis of $K^n$, $I=[b_1,\dots,b_n]$ and $J=[a_1,\dots,a_n]$, then $x$ is
! 3913: isomorphic to
! 3914: $$ (b_1e_1\oplus\cdots\oplus b_ne_n) / (a_1A_1\oplus\cdots\oplus a_nA_n)
! 3915: \enspace, $$
! 3916: where the $A_j$ are the columns of the matrix $A$. Note that every finitely
! 3917: generated torsion module can be given in this way, and even with $b_i=Z_K$
! 3918: for all $i$.
! 3919:
! 3920: \syn{nfsmith}{\var{nf},x}.
! 3921:
! 3922: \subsecidx{nfsolvemodpr}$(\var{nf},a,b,\var{pr})$: solution of $a\cdot x = b$
! 3923: in $\Z_K/\var{pr}$, where $a$ is a matrix and $b$ a column vector, and where
! 3924: \var{pr} is in \key{modpr} format (see \kbd{nfmodprinit}).
! 3925:
! 3926: \syn{nfsolvemodpr}{\var{nf},a,b,\var{pr}}.
! 3927:
! 3928: \subsecidx{polcompositum}$(x,y,\{\fl=0\})$: $x$ and $y$ being polynomials in
! 3929: $\Z[x]$ in the same variable, outputs a vector giving the list of all
! 3930: possible composita of the number fields defined by $x$ and $y$, if $x$ and
! 3931: $y$ are irreducible, or of the corresponding \'etale algebras, if they are
! 3932: only squarefree. Returns an error if one of the polynomials is not squarefree.
! 3933:
! 3934: If $\fl=1$, outputs a vector of 4-component vectors $[z,a,b,k]$, where $z$
! 3935: ranges through the list of all possible compositums as above, and $a$ (resp.
! 3936: $b$) expresses the root of $x$ (resp. $y$) as a polmod in a root of $z$,
! 3937: and $k$ is a small integer k such that $a+kb$ is the chosen root of $z$.
! 3938:
! 3939: \syn{polcompositum0}{x,y,\fl}.
! 3940:
! 3941: \subsecidx{polgalois}$(x)$: \idx{Galois} group of the non-constant polynomial
! 3942: $x\in\Q[X]$. In the present version \vers, $x$ must be irreducible and
! 3943: the degree of $x$ must be less than or equal to 7. On certain versions for
! 3944: which the data file of Galois resolvents has been installed (available
! 3945: in the Unix distribution as a separate package), degrees 8, 9, 10 and 11
! 3946: are also implemented.
! 3947:
! 3948: The output is a 3-component vector $[n,s,k]$ with the following meaning: $n$
! 3949: is the cardinality of the group, $s$ is its signature ($s=1$ if the group is
! 3950: a subgroup of the alternating group $A_n$, $s=-1$ otherwise), and $k$ is the
! 3951: number of the group corresponding to a given pair $(n,s)$ ($k=1$ except in 2
! 3952: cases). Specifically, the groups are coded as follows, using standard
! 3953: notations (see GTM 138, quoted at the beginning of this section):
! 3954: \smallskip
! 3955: In degree 1: $S_1=[1,-1,1]$.
! 3956: \smallskip
! 3957: In degree 2: $S_2=[2,-1,1]$.
! 3958: \smallskip
! 3959: In degree 3: $A_3=C_3=[3,1,1]$, $S_3=[6,-1,1]$.
! 3960: \smallskip
! 3961: In degree 4: $C_4=[4,-1,1]$, $V_4=[4,1,1]$, $D_4=[8,-1,1]$, $A_4=[12,1,1]$,
! 3962: $S_4=[24,-1,1]$.
! 3963: \smallskip
! 3964: In degree 5: $C_5=[5,1,1]$, $D_5=[10,1,1]$, $M_{20}=[20,-1,1]$,
! 3965: $A_5=[60,1,1]$, $S_5=[120,-1,1]$.
! 3966: \smallskip
! 3967: In degree 6: $C_6=[6,-1,1]$, $S_3=[6,-1,2]$, $D_6=[12,-1,1]$, $A_4=[12,1,1]$,
! 3968: $G_{18}=[18,-1,1]$, $S_4^-=[24,-1,1]$, $A_4\times C_2=[24,-1,2]$,
! 3969: $S_4^+=[24,1,1]$, $G_{36}^-=[36,-1,1]$, $G_{36}^+=[36,1,1]$,
! 3970: $S_4\times C_2=[48,-1,1]$, $A_5=PSL_2(5)=[60,1,1]$, $G_{72}=[72,-1,1]$,
! 3971: $S_5=PGL_2(5)=[120,-1,1]$, $A_6=[360,1,1]$, $S_6=[720,-1,1]$.
! 3972: \smallskip
! 3973: In degree 7: $C_7=[7,1,1]$, $D_7=[14,-1,1]$, $M_{21}=[21,1,1]$,
! 3974: $M_{42}=[42,-1,1]$, $PSL_2(7)=PSL_3(2)=[168,1,1]$, $A_7=[2520,1,1]$,
! 3975: $S_7=[5040,-1,1]$.
! 3976: \smallskip
! 3977: The method used is that of resolvent polynomials and is sensitive to the
! 3978: current precision. The precision is updated internally but, in very rare
! 3979: cases, a wrong result may be returned if the initial precision was not
! 3980: sufficient.
! 3981:
! 3982: \syn{galois}{x,\var{prec}}.
! 3983:
! 3984: \subsecidx{polred}$(x,\{\fl=0\},\{p\})$: finds polynomials with reasonably
! 3985: small coefficients defining subfields of the number field defined by $x$.
! 3986: One of the polynomials always defines $\Q$ (hence is equal to $x-1$),
! 3987: and another always defines the same number field as $x$ if $x$ is irreducible.
! 3988: All $x$ accepted by \tet{nfinit} are also allowed here (e.g. non-monic
! 3989: polynomials, \kbd{nf}, \kbd{bnf}, \kbd{[x,Z\_K\_basis]}).
! 3990:
! 3991: The following binary digits of $\fl$ are significant:
! 3992:
! 3993: 1: does a partial reduction only. This means that only a suborder of the
! 3994: maximal order may be used.
! 3995:
! 3996: 2: gives also elements. The result is a two-column matrix, the first column
! 3997: giving the elements defining these subfields, the second giving the
! 3998: corresponding minimal polynomials.
! 3999:
! 4000: If $p$ is given, it is assumed that it is the two-column matrix of the
! 4001: factorization of the discriminant of the polynomial $x$.
! 4002:
! 4003: \syn{polred0}{x,\fl,p,\var{prec}}, where an omitted $p$ is
! 4004: coded by $gzero$. Also available are $\teb{polred}(x,\var{prec})$ and
! 4005: $\teb{factoredpolred}(x,p,\var{prec})$, both corresponding to $\fl=0$.
! 4006:
! 4007: \subsecidx{polredabs}$(x,\{\fl=0\})$: finds one of the polynomial defining
! 4008: the same number field as the one defined by $x$, and such that the sum of the
! 4009: squares of the modulus of the roots (i.e.~the $T_2$-norm) is minimal.
! 4010: All $x$ accepted by \tet{nfinit} are also allowed here (e.g. non-monic
! 4011: polynomials, \kbd{nf}, \kbd{bnf}, \kbd{[x,Z\_K\_basis]}).
! 4012:
! 4013: The binary digits of $\fl$ mean
! 4014:
! 4015: 1: outputs a two-component row vector $[P,a]$, where $P$ is the default
! 4016: output and $a$ is an element expressed on a root of the polynomial $P$,
! 4017: whose minimal polynomial is equal to $x$.
! 4018:
! 4019: 4: gives {\it all} polynomials of minimal $T_2$ norm (of the two polynomials
! 4020: $P(x)$ and $P(-x)$, only one is given).
! 4021:
! 4022: \syn{polredabs0}{x,\fl,\var{prec}}.
! 4023:
! 4024: \subsecidx{polredord}$(x)$: finds polynomials with reasonably small
! 4025: coefficients and of the same degree as that of $x$ defining suborders of the
! 4026: order defined by $x$. One of the polynomials always defines $\Q$ (hence
! 4027: is equal to $(x-1)^n$, where $n$ is the degree), and another always defines
! 4028: the same order as $x$ if $x$ is irreducible.
! 4029:
! 4030: \syn{ordred}{x}.
! 4031:
! 4032: \subsecidx{poltschirnhaus}$(x)$: applies a random Tschirnhausen
! 4033: transformation to the polynomial $x$, which is assumed to be non-constant
! 4034: and separable, so as to obtain a new equation for the \'etale algebra
! 4035: defined by $x$. This is for instance useful when computing resolvents,
! 4036: hence is used by the \kbd{polgalois} function.
! 4037:
! 4038: \syn{tschirnhaus}{x}.
! 4039:
! 4040: \subsecidx{rnfalgtobasis}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
! 4041: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an element of
! 4042: $L$ expressed as a polynomial or polmod with polmod coefficients, expresses
! 4043: $x$ on the relative integral basis.
! 4044:
! 4045: \syn{rnfalgtobasis}{\var{rnf},x}.
! 4046:
! 4047: \subsecidx{rnfbasis}$(\var{bnf},x)$: given a big number field $\var{bnf}$ as
! 4048: output by \kbd{bnfinit}, and either a polynomial $x$ with coefficients in
! 4049: $\var{bnf}$ defining a relative extension $L$ of $\var{bnf}$, or a
! 4050: pseudo-basis $x$ of such an extension, gives either a true $\var{bnf}$-basis
! 4051: of $L$ if it exists, or an $n+1$-element generating set of $L$ if not, where
! 4052: $n$ is the rank of $L$ over $\var{bnf}$.
! 4053:
! 4054: \syn{rnfbasis}{\var{bnf},x}.
! 4055:
! 4056: \subsecidx{rnfbasistoalg}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
! 4057: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an element of
! 4058: $L$ expressed on the relative integral basis, computes the representation of
! 4059: $x$ as a polmod with polmods coefficients.
! 4060:
! 4061: \syn{rnfbasistoalg}{\var{rnf},x}.
! 4062:
! 4063: \subsecidx{rnfcharpoly}$(\var{nf},T,a,\{v=x\})$: characteristic polynomial of
! 4064: $a$ over $\var{nf}$, where $a$ belongs to the algebra defined by $T$ over
! 4065: $\var{nf}$, i.e.~$\var{nf\/}[X]/(T)$. Returns a polynomial in variable $v$
! 4066: ($x$ by default).
! 4067:
! 4068: \syn{rnfcharpoly}{\var{nf},T,a,v}, where $v$ is a variable number.
! 4069:
! 4070: \subsecidx{rnfconductor}$(\var{bnf},\var{pol})$: $\var{bnf}$ being a big number
! 4071: field as output by \kbd{bnfinit}, and \var{pol} a relative polynomial defining
! 4072: an \idx{Abelian extension}, computes the class field theory conductor of this
! 4073: Abelian extension. The result is a 3-component vector
! 4074: $[\var{conductor},\var{rayclgp},\var{subgroup}]$, where \var{conductor} is
! 4075: the conductor of the extension given as a 2-component row vector
! 4076: $[f_0,f_\infty]$, \var{rayclgp} is the full ray class group corresponding to
! 4077: the conductor given as a 3-component vector [h,cyc,gen] as usual for a group,
! 4078: and \var{subgroup} is a matrix in HNF defining the subgroup of the ray class
! 4079: group on the given generators gen.
! 4080:
! 4081: \syn{rnfconductor}{\var{rnf},\var{pol},\var{prec}}.
! 4082:
! 4083: \subsecidx{rnfdedekind}$(\var{nf},\var{pol},\var{pr})$: given a number field
! 4084: $\var{nf}$ as output by \kbd{nfinit} and a polynomial \var{pol} with
! 4085: coefficients in $\var{nf}$ defining a relative extension $L$ of $\var{nf}$,
! 4086: evaluates the relative \idx{Dedekind} criterion over the order defined by a
! 4087: root of \var{pol} for the prime ideal \var{pr}
! 4088: and outputs a 3-component vector as the result. The first component is a flag
! 4089: equal to 1 if the enlarged order is \var{pr}-maximal and to 0 otherwise, the
! 4090: second component is a pseudo-basis of the enlarged order and the third
! 4091: component is the valuation at \var{pr} of the order discriminant.
! 4092:
! 4093: \syn{rnfdedekind}{\var{nf},\var{pol},\var{pr}}.
! 4094:
! 4095: \subsecidx{rnfdet}$(\var{nf},M)$: given a pseudomatrix $M$ over the maximal
! 4096: order of $\var{nf}$, computes its pseudodeterminant.
! 4097:
! 4098: \syn{rnfdet}{\var{nf},M}.
! 4099:
! 4100: \subsecidx{rnfdisc}$(\var{nf},\var{pol})$: given a number field $\var{nf}$ as
! 4101: output by \kbd{nfinit} and a polynomial \var{pol} with coefficients in
! 4102: $\var{nf}$ defining a relative extension $L$ of $\var{nf}$, computes
! 4103: the relative
! 4104: discriminant of $L$. This is a two-element row vector $[D,d]$, where $D$ is
! 4105: the relative ideal discriminant and $d$ is the relative discriminant
! 4106: considered as an element of $\var{nf}^*/{\var{nf}^*}^2$. The main variable of
! 4107: $\var{nf}$ {\it must\/} be of lower priority than that of \var{pol}.
! 4108:
! 4109: Note: As usual, $\var{nf}$ can be a $\var{bnf}$ as output by \kbd{nfinit}.
! 4110:
! 4111: \syn{rnfdiscf}{\var{bnf},\var{pol}}.
! 4112:
! 4113: \subsecidx{rnfeltabstorel}$(\var{rnf},x)$: $\var{rnf}$ being a relative
! 4114: number field
! 4115: extension $L/K$ as output by \kbd{rnfinit} and $x$ being an element of $L$
! 4116: expressed as a polynomial modulo the absolute equation $\var{rnf\/}[11][1]$,
! 4117: computes $x$ as an element of the relative extension $L/K$ as a polmod with
! 4118: polmod coefficients.
! 4119:
! 4120: \syn{rnfelementabstorel}{\var{rnf},x}.
! 4121:
! 4122: \subsecidx{rnfeltdown}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
! 4123: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an element of
! 4124: $L$ expressed as a polynomial or polmod with polmod coefficients, computes
! 4125: $x$ as an element of $K$ as a polmod, assuming $x$ is in $K$ (otherwise an
! 4126: error will occur). If $x$ is given on the relative integral basis, apply
! 4127: \kbd{rnfbasistoalg} first, otherwise PARI will believe you are dealing with a
! 4128: vector.
! 4129:
! 4130: \syn{rnfelementdown}{\var{rnf},x}.
! 4131:
! 4132: \subsecidx{rnfeltreltoabs}$(\var{rnf},x)$: $\var{rnf}$ being a relative
! 4133: number field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an
! 4134: element of $L$ expressed as a polynomial or polmod with polmod
! 4135: coefficients, computes $x$ as an element of the absolute extension $L/\Q$ as
! 4136: a polynomial modulo the absolute equation $\var{rnf\/}[11][1]$. If $x$ is
! 4137: given on the relative integral basis, apply \kbd{rnfbasistoalg} first,
! 4138: otherwise PARI will believe you are dealing with a vector.
! 4139:
! 4140: \syn{rnfelementreltoabs}{\var{rnf},x}.
! 4141:
! 4142: \subsecidx{rnfeltup}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
! 4143: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an element of
! 4144: $K$ expressed as a polynomial or polmod, computes $x$ as an element of the
! 4145: absolute extension $L/\Q$ as a polynomial modulo the absolute equation
! 4146: $\var{rnf\/}[11][1]$. Note that it is unnecessary to compute $x$ as an
! 4147: element of the relative extension $L/K$ (its expression would be identical to
! 4148: itself). If $x$ is given on the integral basis of $K$, apply
! 4149: \kbd{nfbasistoalg} first, otherwise PARI will believe you are dealing with a
! 4150: vector.
! 4151:
! 4152: \syn{rnfelementup}{\var{rnf},x}.
! 4153:
! 4154: \subsecidx{rnfequation}$(\var{nf},\var{pol},\{\fl=0\})$: given a number field
! 4155: $\var{nf}$ as output by \kbd{nfinit} (or simply a polynomial) and a
! 4156: polynomial \var{pol} with
! 4157: coefficients in $\var{nf}$ defining a relative extension $L$ of $\var{nf}$,
! 4158: computes the absolute equation of $L$ over $\Q$.
! 4159:
! 4160: If $\fl$ is non-zero, outputs a 3-component row vector $[z,a,k]$, where $z$
! 4161: is the absolute equation of $L$ over $\Q$, as in the default behaviour,
! 4162: $a$ expresses as a polmod a root $\beta$ of $pol$ in terms of a root $\theta$
! 4163: of $z$, and $k$ is a small integer such that $\theta=\beta+k\alpha$ where
! 4164: $\alpha$ is a root of the polynomial defining the base field $\var{nf}$.
! 4165:
! 4166: The main variable of $\var{nf}$ {\it must\/} be of lower priority than that
! 4167: of \var{pol}. Note that for efficiency, this does not check whether the
! 4168: relative equation is irreducible over $\var{nf}$, but only if it is
! 4169: squarefree. If it is reducible but squarefree, the result will be the
! 4170: absolute equation of the \'etale algebra defined by \var{pol}. If \var{pol}
! 4171: is not squarefree, an error message will be issued.
! 4172:
! 4173: \syn{rnfequation0}{\var{nf},\var{pol},\fl}.
! 4174:
! 4175: \subsecidx{rnfhnfbasis}$(\var{bnf},x)$: given a big number field $\var{bnf}$
! 4176: as output by \kbd{bnfinit}, and either a polynomial $x$ with coefficients in
! 4177: $\var{bnf}$ defining a relative extension $L$ of $\var{bnf}$, or a
! 4178: pseudo-basis $x$ of such an extension, gives either a true $\var{bnf}$-basis
! 4179: of $L$ in upper triangular Hermite normal form, if it exists,
! 4180: zero otherwise.
! 4181:
! 4182: \syn{rnfhermitebasis}{\var{nf},x}.
! 4183:
! 4184: \subsecidx{rnf{}idealabstorel}$(\var{rnf},x)$: $\var{rnf}$ being a relative
! 4185: number field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an
! 4186: ideal of the absolute extension $L/\Q$ given in HNF\sidx{Hermite normal form}
! 4187: (if it is not, apply \kbd{idealhnf} first), computes the relative pseudomatrix
! 4188: in HNF giving the ideal $x$ considered as an ideal of the relative extension
! 4189: $L/K$.
! 4190:
! 4191: \syn{rnf{}idealabstorel}{\var{rnf},x}.
! 4192:
! 4193: \subsecidx{rnf{}idealdown}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
! 4194: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being an ideal of
! 4195: the absolute extension $L/\Q$ given in HNF (if it is not, apply
! 4196: \kbd{idealhnf} first), gives the ideal of $K$ below $x$, i.e.~the
! 4197: intersection of $x$ with $K$. Note that, if $x$ is given as a relative ideal
! 4198: (i.e.~a pseudomatrix in HNF), then it is not necessary to use this function
! 4199: since the result is simply the first ideal of the ideal list of the
! 4200: pseudomatrix.
! 4201:
! 4202: \syn{rnf{}idealdown}{\var{rnf},x}.
! 4203:
! 4204: \subsecidx{rnf{}idealhnf}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
! 4205: field extension $L/K$ as output by \kbd{rnfinit} and $x$ being a relative
! 4206: ideal (which can be, as in the absolute case, of many different types,
! 4207: including of course elements), computes as a 2-component row vector the
! 4208: relative Hermite normal form of $x$, the first component being the HNF matrix
! 4209: (with entries on the integral basis), and the second component the ideals.
! 4210:
! 4211: \syn{rnf{}idealhermite}{\var{rnf},x}.
! 4212:
! 4213: \subsecidx{rnfidealmul}$(\var{rnf},x,y)$: $\var{rnf}$ being a relative number
! 4214: field extension $L/K$ as output by \kbd{rnfinit} and $x$ and $y$ being ideals
! 4215: of the relative extension $L/K$ given by pseudo-matrices, outputs the ideal
! 4216: product, again as a relative ideal.
! 4217:
! 4218: \syn{rnf{}idealmul}{\var{rnf},x,y}.
! 4219:
! 4220: \subsecidx{rnf{}idealnormabs}$(\var{rnf},x)$: $\var{rnf}$ being a relative
! 4221: number field extension $L/K$ as output by \kbd{rnfinit} and $x$ being a
! 4222: relative ideal (which can be, as in the absolute case, of many different
! 4223: types, including of course elements), computes the norm of the ideal $x$
! 4224: considered as an ideal of the absolute extension $L/\Q$. This is identical to
! 4225: \kbd{idealnorm(rnfidealnormrel(\var{rnf},x))}, only faster.
! 4226:
! 4227: \syn{rnf{}idealnormabs}{\var{rnf},x}.
! 4228:
! 4229: \subsecidx{rnf{}idealnormrel}$(\var{rnf},x)$: $\var{rnf}$ being a relative
! 4230: number field
! 4231: extension $L/K$ as output by \kbd{rnfinit} and $x$ being a relative ideal
! 4232: (which can be, as in the absolute case, of many different types, including
! 4233: of course elements), computes the relative norm of $x$ as a ideal of $K$
! 4234: in HNF.
! 4235:
! 4236: \syn{rnf{}idealnormrel}{\var{rnf},x}.
! 4237:
! 4238: \subsecidx{rnf{}idealreltoabs}$(\var{rnf},x)$: $\var{rnf}$ being a relative
! 4239: number field
! 4240: extension $L/K$ as output by \kbd{rnfinit} and $x$ being a relative ideal
! 4241: (which can be, as in the absolute case, of many different types, including
! 4242: of course elements), computes the HNF matrix of the ideal $x$ considered
! 4243: as an ideal of the absolute extension $L/\Q$.
! 4244:
! 4245: \syn{rnf{}idealreltoabs}{\var{rnf},x}.
! 4246:
! 4247: \subsecidx{rnf{}idealtwoelt}$(\var{rnf},x)$: $\var{rnf}$ being a relative
! 4248: number field
! 4249: extension $L/K$ as output by \kbd{rnfinit} and $x$ being an ideal of the
! 4250: relative extension $L/K$ given by a pseudo-matrix, gives a vector of
! 4251: two generators of $x$ over $\Z_L$ expressed as polmods with polmod
! 4252: coefficients.
! 4253:
! 4254: \syn{rnf{}idealtwoelement}{\var{rnf},x}.
! 4255:
! 4256: \subsecidx{rnf{}idealup}$(\var{rnf},x)$: $\var{rnf}$ being a relative number
! 4257: field
! 4258: extension $L/K$ as output by \kbd{rnfinit} and $x$ being an ideal of
! 4259: $K$, gives the ideal $x\Z_L$ as an absolute ideal of $L/\Q$ (the relative
! 4260: ideal representation is trivial: the matrix is the identity matrix, and
! 4261: the ideal list starts with $x$, all the other ideals being $\Z_K$).
! 4262:
! 4263: \syn{rnf{}idealup}{\var{rnf},x}.
! 4264:
! 4265: \subsecidx{rnf{}init}$(\var{nf},\var{pol})$: $\var{nf}$ being a number field in
! 4266: \kbd{nfinit}
! 4267: format considered as base field, and \var{pol} a polynomial defining a relative
! 4268: extension over $\var{nf}$, this computes all the necessary data to work in the
! 4269: relative extension. The main variable of \var{pol} must be of higher priority
! 4270: (i.e.~lower number) than that of $\var{nf}$, and the coefficients of \var{pol}
! 4271: must be in $\var{nf}$.
! 4272:
! 4273: The result is an 11-component row vector as follows (most of the components
! 4274: are technical), the numbering being very close to that of \kbd{nfinit}.
! 4275: In the following description, we let $K$ be the base field defined by
! 4276: $\var{nf}$,
! 4277: $m$ the degree of the base field, $n$ the relative degree, $L$ the large
! 4278: field (of relative degree $n$ or absolute degree $nm$), $r_1$ and $r_2$ the
! 4279: number of real and complex places of $K$.
! 4280:
! 4281: $\var{rnf\/}[1]$ contains the relative polynomial \var{pol}.
! 4282:
! 4283: $\var{rnf\/}[2]$ is a row vector with $r_1+r_2$ entries, entry $j$ being
! 4284: a 2-component row vector $[r_{j,1},r_{j,2}]$ where $r_{j,1}$ and $r_{j,2}$
! 4285: are the number of real and complex places of $L$ above the $j$-th place of
! 4286: $K$ so that $r_{j,1}=0$ and $r_{j,2}=n$ if $j$ is a complex place, while if
! 4287: $j$ is a real place we have $r_{j,1}+2r_{j,2}=n$.
! 4288:
! 4289: $\var{rnf\/}[3]$ is a two-component row vector $[\d(L/K),s]$ where $\d(L/K)$
! 4290: is the relative ideal discriminant of $L/K$ and $s$ is the discriminant of
! 4291: $L/K$ viewed as an element of $K^*/(K^*)^2$, in other words it is the output
! 4292: of \kbd{rnfdisc}.
! 4293:
! 4294: $\var{rnf\/}[4]$ is the ideal index $\f$, i.e.~such that
! 4295: $d(pol)\Z_K=\f^2\d(L/K)$.
! 4296:
! 4297: $\var{rnf\/}[5]$ is a vector \var{vm} with 7 entries useful for certain
! 4298: computations in the relative extension $L/K$. $\var{vm}[1]$ is a vector of
! 4299: $r_1+r_2$ matrices, the $j$-th matrix being an $(r_{1,j}+r_{2,j})\times n$
! 4300: matrix $M_j$ representing the numerical values of the conjugates of the
! 4301: $j$-th embedding of the elements of the integral basis, where $r_{i,j}$ is as
! 4302: in $\var{rnf\/}[2]$. $\var{vm}[2]$ is a vector of $r_1+r_2$ matrices, the
! 4303: $j$-th matrix $MC_j$ being essentially the conjugate of the matrix $M_j$
! 4304: except that the last $r_{2,j}$ columns are also multiplied by 2.
! 4305: $\var{vm}[3]$ is a vector of $r_1+r_2$ matrices $T2_j$, where $T2_j$ is
! 4306: an $n\times n$ matrix equal to the real part of the product $MC_j\cdot M_j$
! 4307: (which is a real positive definite matrix). $\var{vm}[4]$ is the $n\times n$
! 4308: matrix $T$ whose entries are the relative traces of $\omega_i\omega_j$
! 4309: expressed as polmods in $\var{nf}$, where the $\omega_i$ are the elements
! 4310: of the relative integral basis. Note that the $j$-th embedding of $T$ is
! 4311: equal to $\overline{MC_j}\cdot M_j$, and in particular will be equal to
! 4312: $T2_j$ if $r_{2,j}=0$. Note also that the relative ideal discriminant of
! 4313: $L/K$ is equal to $\det(T)$ times the square of the product of the ideals
! 4314: in the relative pseudo-basis (in $\var{rnf\/}[7][2]$). The last 3 entries
! 4315: $\var{vm}[5]$, $\var{vm}[6]$ and $\var{vm}[7]$ are linked to the different
! 4316: as in \kbd{nfinit}, but have not yet been implemented.
! 4317:
! 4318: $\var{rnf\/}[6]$ is a row vector with $r_1+r_2$ entries, the $j$-th entry
! 4319: being the
! 4320: row vector with $r_{1,j}+r_{2,j}$ entries of the roots of the $j$-th embedding
! 4321: of the relative polynomial \var{pol}.
! 4322:
! 4323: $\var{rnf\/}[7]$ is a two-component row vector, where the first component is
! 4324: the relative integral pseudo basis expressed as polynomials (in the variable of
! 4325: $pol$) with polmod coefficients in $\var{nf}$, and the second component is the
! 4326: ideal list of the pseudobasis in HNF.
! 4327:
! 4328: $\var{rnf\/}[8]$ is the inverse matrix of the integral basis matrix, with
! 4329: coefficients polmods in $\var{nf}$.
! 4330:
! 4331: $\var{rnf\/}[9]$ may be the multiplication table of the integral basis, but
! 4332: is not implemented at present.
! 4333:
! 4334: $\var{rnf\/}[10]$ is $\var{nf}$.
! 4335:
! 4336: $\var{rnf\/}[11]$ is a vector \var{vabs} with 5 entries describing the {\it
! 4337: absolute\/} extension $L/\Q$. $\var{vabs}[1]$ is an absolute equation.
! 4338: $\var{vabs}[2]$ expresses the generator $\alpha$ of the number field
! 4339: $\var{nf}$ as a polynomial modulo the absolute equation $\var{vabs}[1]$.
! 4340: $\var{vabs}[3]$ is a small integer $k$ such that, if $\beta$ is an abstract
! 4341: root of \var{pol} and $\alpha$ the generator of $\var{nf}$, the generator
! 4342: whose root is \var{vabs} will be $\beta + k \alpha$. Note that one must
! 4343: be very careful if $k\neq0$ when dealing simultaneously with absolute and
! 4344: relative quantities since the generator chosen for the absolute extension
! 4345: is not the same as for the relative one. If this happens, one can of course
! 4346: go on working, but we strongly advise to change the relative polynomial so
! 4347: that its root will be $\beta + k \alpha$. Typically, the GP instruction would
! 4348: be
! 4349:
! 4350: \kbd{pol = subst(pol, x, x - k*Mod(y,\var{nf}.pol))}
! 4351:
! 4352: Finally, $\var{vabs}[4]$ is the absolute integral basis of $L$ expressed in HNF
! 4353: (hence as would be output by \kbd{nfinit(vabs[1])}), and $\var{vabs}[5]$ the
! 4354: inverse matrix of the integral basis, allowing to go from polmod to integral
! 4355: basis representation.
! 4356:
! 4357: \syn{rnf{}initalg}{\var{nf},\var{pol},\var{prec}}.
! 4358:
! 4359: \subsecidx{rnf{}isfree}$(\var{bnf},x)$: given a big number field $\var{bnf}$ as
! 4360: output by \kbd{bnfinit}, and either a polynomial $x$ with coefficients in
! 4361: $\var{bnf}$ defining a relative extension $L$ of $\var{bnf}$, or a
! 4362: pseudo-basis $x$ of such an extension, returns true (1) if $L/\var{bnf}$ is
! 4363: free, false (0) if not.
! 4364:
! 4365: \syn{rnf{}isfree}{\var{bnf},x}, and the result is a \kbd{long}.
! 4366:
! 4367: \subsecidx{rnf{}isnorm}$(\var{bnf},\var{ext},\var{el},\{\fl=1\})$: similar to
! 4368: \kbd{bnfisnorm} but in the relative case. This tries to decide whether the
! 4369: element \var{el} in \var{bnf} is the norm of some $y$ in \var{ext}.
! 4370: $\var{bnf}$ is as output by \kbd{bnfinit}.
! 4371:
! 4372: $\var{ext\/}$ is a relative extension which has to be a row vector whose
! 4373: components are:
! 4374:
! 4375: $\var{ext}[1]$: a relative equation of the number field \var{ext} over
! 4376: \var{bnf}. As usual, the priority of the variable of the polynomial
! 4377: defining the ground field \var{bnf} (say $y$) must be lower than the
! 4378: main variable of $\var{ext}[1]$, say $x$.
! 4379:
! 4380: $\var{ext}[2]$: the generator $y$ of the base field as a polynomial in $x$ (as
! 4381: given by \kbd{rnfequation} with $\fl = 1$).
! 4382:
! 4383: $\var{ext}[3]$: is the \kbd{bnfinit} of the absolute extension $\var{ext}/\Q$.
! 4384:
! 4385: This returns a vector $[a,b]$, where $\var{el}=\var{Norm}(a)*b$. It looks for a
! 4386: solution which is an $S$-integer, with $S$ a list of places (of \var{bnf})
! 4387: containing the ramified primes, the generators of the class group of
! 4388: \var{ext}, as well as those primes dividing \var{el}. If $\var{ext}/\var{bnf}$
! 4389: is known to be \idx{Galois}, set $\fl=0$
! 4390: (here \var{el} is a norm iff $b=1$). If $\fl$ is non zero add to $S$ all
! 4391: the places above the primes which: divide $\fl$ if $\fl<0$, or are less
! 4392: than $\fl$ if $\fl>0$. The answer is guaranteed (i.e.~\var{el} is a norm
! 4393: iff $b=1$) under \idx{GRH}, if $S$ contains all primes less than
! 4394: $12\log^2\left|\text{disc}(\var{Ext})\right|$, where \var{Ext} is the normal
! 4395: closure of $\var{ext} / \var{bnf}$.
! 4396:
! 4397: \syn{rnf{}isnorm}{\var{bnf},ext,x,\fl,\var{prec}}.
! 4398:
! 4399: \subsecidx{rnfkummer}$(\var{bnr},\var{subgroup},\{deg=0\})$: \var{bnr}
! 4400: being as output by \kbd{bnrinit}, finds a relative equation for the
! 4401: class field corresponding to the module in \var{bnr} and the given
! 4402: congruence subgroup. If \var{deg} is positive, outputs the list of all
! 4403: relative equations of degree \var{deg} contained in the ray class field
! 4404: defined by \var{bnr}.
! 4405:
! 4406: (THIS PROGRAM IS STILL IN DEVELOPMENT STAGE)
! 4407:
! 4408: \syn{rnfkummer}{\var{bnr},\var{subgroup},\var{deg},\var{prec}},
! 4409: where \var{deg} is a \kbd{long}.
! 4410:
! 4411: \subsecidx{rnf{}lllgram}$(\var{nf},\var{pol},\var{order})$: given a polynomial
! 4412: \var{pol} with coefficients in \var{nf} and an order \var{order} as output
! 4413: by \kbd{rnfpseudobasis} or similar, gives $[[\var{neworder}],U]$, where
! 4414: \var{neworder} is a reduced order and $U$ is the unimodular transformation
! 4415: matrix.
! 4416:
! 4417: \syn{rnf{}lllgram}{\var{nf},\var{pol},\var{order},\var{prec}}.
! 4418:
! 4419: \subsecidx{rnfnormgroup}$(\var{bnr},\var{pol})$: \var{bnr} being a big ray
! 4420: class field as output by \kbd{bnrinit} and \var{pol} a relative polynomial
! 4421: defining an \idx{Abelian extension}, computes the norm group (alias Artin
! 4422: or Takagi group) corresponding to the Abelian extension of $\var{bnf}=bnr[1]$
! 4423: defined by \var{pol}, where the module corresponding to \var{bnr} is assumed
! 4424: to be a multiple of the conductor (i.e.~polrel defines a subextension of
! 4425: bnr). The result is the HNF defining the norm group on the given generators
! 4426: of $\var{bnr}[5][3]$. Note that neither the fact that \var{pol} defines an
! 4427: Abelian extension nor the fact that the module is a multiple of the conductor
! 4428: is checked. The result is undefined if the assumption is not correct.
! 4429:
! 4430: \syn{rnfnormgroup}{\var{bnr},\var{pol}}.
! 4431:
! 4432: \subsecidx{rnfpolred}$(\var{nf},\var{pol})$: relative version of \kbd{polred}.
! 4433: Given a monic polynomial \var{pol} with coefficients in $\var{nf}$, finds a
! 4434: list of relative polynomials defining some subfields, hopefully simpler and
! 4435: containing the original field.
! 4436:
! 4437: \syn{rnfpolred}{\var{nf},\var{pol},\var{prec}}.
! 4438:
! 4439: \subsecidx{rnfpolredabs}$(\var{nf},\var{pol},\{\fl=0\})$: relative version of
! 4440: \kbd{polredabs}. Given a monic polynomial \var{pol} with coefficients in
! 4441: $\var{nf}$, finds a simpler relative polynomial defining the same field. If
! 4442: $\fl=1$, returns $[P,a]$ where $P$ is the default output and $a$ is an
! 4443: element expressed on a root of $P$ whose characteristic polynomial is
! 4444: \var{pol}, if $\fl=2$, returns an absolute polynomial (same as
! 4445:
! 4446: {\tt rnfequation(\var{nf},rnfpolredabs(\var{nf},\var{pol}))}
! 4447:
! 4448: \noindent but faster).
! 4449:
! 4450: \misctitle{Remark.} In the present implementation, although this is slower
! 4451: than \kbd{rnfpolred}, it is much more efficient, the difference being more
! 4452: dramatic than in the absolute case. This is because the implementation of
! 4453: \kbd{rnfpolred} is based on an incomplete reduction theory of lattices over
! 4454: number fields (i.e.~the function \kbd{rnflllgram}) which deserves to be
! 4455: improved.
! 4456:
! 4457: \syn{rnfpolredabs}{\var{nf},\var{pol},\fl,\var{prec}}.
! 4458:
! 4459: \subsecidx{rnfpseudobasis}$(\var{nf},\var{pol})$: given a number field
! 4460: $\var{nf}$ as output by \kbd{nfinit} and a polynomial \var{pol} with
! 4461: coefficients in $\var{nf}$ defining a relative extension $L$ of $\var{nf}$,
! 4462: computes a pseudo-basis $(A,I)$ and the relative discriminant of $L$.
! 4463: This is output as
! 4464: a four-element row vector $[A,I,D,d]$, where $D$ is the relative ideal
! 4465: discriminant and $d$ is the relative discriminant considered as an element of
! 4466: $\var{nf}^*/{\var{nf}^*}^2$.
! 4467:
! 4468: Note: As usual, $\var{nf}$ can be a $\var{bnf}$ as output by \kbd{bnfinit}.
! 4469:
! 4470: \syn{rnfpseudobasis}{\var{nf},\var{pol}}.
! 4471:
! 4472: \subsecidx{rnfsteinitz}$(\var{nf},x)$: given a number field $\var{nf}$ as
! 4473: output by \kbd{nfinit} and either a polynomial $x$ with coefficients in
! 4474: $\var{nf}$ defining a relative extension $L$ of $\var{nf}$, or a pseudo-basis
! 4475: $x$ of such an extension as output for example by \kbd{rnfpseudobasis},
! 4476: computes another pseudo-basis $(A,I)$ (not in HNF in general) such that all
! 4477: the ideals of $I$ except perhaps the last one are equal to the ring of
! 4478: integers of $\var{nf}$, and outputs the four-component row vector $[A,I,D,d]$
! 4479: as in \kbd{rnfpseudobasis}. The name of this function comes from the fact
! 4480: that the ideal class of the last ideal of $I$ (which is well defined) is
! 4481: called the {\it Steinitz class\/} of the module $\Z_L$.
! 4482:
! 4483: Note: $\var{nf}$ can be a $\var{bnf}$ as output by \kbd{bnfinit}.
! 4484:
! 4485: \syn{rnfsteinitz}{\var{nf},x}.
! 4486:
! 4487: \subsecidx{subgrouplist}$(\var{bnr},\{\var{bound}\},\{\fl=0\})$:
! 4488: \var{bnr} being as output by \kbd{bnrinit} or a list of cyclic components
! 4489: of a finite Abelian group $G$, outputs the list of subgroups of $G$
! 4490: (of index bounded by \var{bound}, if not omitted). Subgroups are given
! 4491: as HNF\sidx{Hermite normal form} left divisors of the
! 4492: SNF\sidx{Smith normal form} matrix corresponding to $G$. If $\fl=0$
! 4493: (default) and \var{bnr} is as output by
! 4494: \kbd{bnrinit}, gives only the subgroups whose modulus is the conductor.
! 4495:
! 4496: \syn{subgrouplist0}{\var{bnr},\var{bound},\fl,\var{prec}}, where
! 4497: \var{bound}, $\fl$ and $\var{prec}$ are long integers.
! 4498:
! 4499: \subsecidx{zetak}$(\var{znf},x,\{\fl=0\})$: \var{znf} being a number
! 4500: field initialized by \kbd{zetakinit} ({\it not\/} by \kbd{nfinit}),
! 4501: computes the value of the \idx{Dedekind} zeta function of the number
! 4502: field at the complex number $x$. If $\fl=1$ computes Dedekind $\Lambda$
! 4503: function instead (i.e.~the product of the
! 4504: Dedekind zeta function by its gamma and exponential factors).
! 4505:
! 4506: The accuracy of the result depends in an essential way on the accuracy of
! 4507: both the \kbd{zetakinit} program and the current accuracy, but even so the
! 4508: result may be off by up to 5 or 10 decimal digits.
! 4509:
! 4510: \syn{glambdak}{\var{znf},x,\var{prec}} or
! 4511: $\teb{gzetak}(\var{znf},x,\var{prec})$.
! 4512:
! 4513: \subsecidx{zetakinit}$(x)$: computes a number of initialization data
! 4514: concerning the number field defined by the polynomial $x$ so as to be
! 4515: able to compute the \idx{Dedekind} zeta and lambda functions (respectively
! 4516: $\kbd{zetak}(x)$ and $\kbd{zetak}(x,1)$). This function calls in particular
! 4517: the \kbd{bnfinit} program. The result is a 9-component vector $v$ whose
! 4518: components are very technical and cannot really be used by the user except
! 4519: through the \kbd{zetak} function. The only component which can be used if it
! 4520: has not been computed already is $v[1][4]$ which is the result of the
! 4521: \kbd{bnfinit} call.
! 4522:
! 4523: This function is very inefficient and needs to computes millions of
! 4524: coefficients of the corresponding Dirichlet series if the precision is big.
! 4525: Unless the discriminant is small it will not be able to handle more than 9
! 4526: digits of relative precision (e.g~\kbd{zetakinit(x\pow 8 - 2)} needs 440MB of
! 4527: memory at default precision).
! 4528:
! 4529: \syn{initzeta}{x}.
! 4530:
! 4531: \section{Polynomials and power series}
! 4532:
! 4533: We group here all functions which are specific to polynomials or power
! 4534: series. Many other functions which can be applied on these objects are
! 4535: described in the other sections. Also, some of the functions described here
! 4536: can be applied to other types.
! 4537:
! 4538: \subsecidx{O}$(a$\kbd{\pow}$b)$: $p$-adic (if $a$ is an integer greater or
! 4539: equal to 2) or power series zero (in all other cases), with precision given
! 4540: by $b$.
! 4541:
! 4542: \syn{ggrandocp}{a,b}, where $b$ is a \kbd{long}.
! 4543:
! 4544: \subsecidx{deriv}$(x,\{v\})$: derivative of $x$ with respect to the main
! 4545: variable if $v$ is omitted, and with respect to $v$ otherwise. $x$ can be any
! 4546: type except polmod. The derivative of a scalar type is zero, and the
! 4547: derivative of a vector or matrix is done componentwise. One can use $x'$ as a
! 4548: shortcut if the derivative is with respect to the main variable of $x$.
! 4549:
! 4550: \syn{deriv}{x,v}, where $v$ is a \kbd{long}, and an omitted $v$ is coded as
! 4551: $-1$.
! 4552:
! 4553: \subsecidx{eval}$(x)$: replaces in $x$ the formal variables by the values that
! 4554: have been assigned to them after the creation of $x$. This is mainly useful
! 4555: in GP, and not in library mode. Do not confuse this with substitution (see
! 4556: \kbd{subst}). Applying this function to a character string yields the
! 4557: output from the corresponding GP command, as if directly input from the
! 4558: keyboard (see \secref{se:strings}).\label{se:eval}
! 4559:
! 4560: \syn{geval}{x}. The more basic functions $\teb{poleval}(q,x)$,
! 4561: $\teb{qfeval}(q,x)$, and $\teb{hqfeval}(q,x)$ evaluate $q$ at $x$, where $q$
! 4562: is respectively assumed to be a polynomial, a quadratic form (a symmetric
! 4563: matrix), or an Hermitian form (an Hermitian complex matrix).
! 4564:
! 4565: \subsecidx{factorpadic}$(\var{pol},p,r,\{\fl=0\})$: $p$-adic factorization
! 4566: of the polynomial \var{pol} to precision $r$, the result being a two-column
! 4567: matrix as in \kbd{factor}. $r$ must be strictly larger than the $p$-adic
! 4568: valuation of the discriminant of \var{pol} for the result to make any sense.
! 4569: The method used is \idx{Ford}-Letard's implementation of the \idx{round 4}
! 4570: algorithm of \idx{Zassenhaus}.
! 4571:
! 4572: If $\fl=1$, use an algorithm due to \idx{Buchmann} and \idx{Lenstra}, which is
! 4573: usually less efficient.
! 4574:
! 4575: \syn{factorpadic4}{\var{pol},p,r}, where $r$ is a \kbd{long} integer.
! 4576:
! 4577: \subsecidx{intformal}$(x,\{v\})$: \idx{formal integration} of $x$ with
! 4578: respect to the main variable if $v$ is omitted, with respect to the variable
! 4579: $v$ otherwise. Since PARI does not know about ``abstract'' logarithms (they
! 4580: are immediately evaluated, if only to a power series), logarithmic terms in
! 4581: the result will yield an error. $x$ can be of any type. When $x$ is a
! 4582: rational function, it is assumed that the base ring is an integral domain of
! 4583: characteristic zero.
! 4584:
! 4585: \syn{integ}{x,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded
! 4586: as $-1$.
! 4587:
! 4588: \subsecidx{padicappr}$(\var{pol},a)$: vector of $p$-adic roots of the
! 4589: polynomial
! 4590: $pol$ congruent to the $p$-adic number $a$ modulo $p$ (or modulo 4 if $p=2$),
! 4591: and with the same $p$-adic precision as $a$. The number $a$ can be an
! 4592: ordinary $p$-adic number (type \typ{PADIC}, i.e.~an element of $\Q_p$) or
! 4593: can be an element of a finite extension of $\Q_p$, in which case it is of
! 4594: type \typ{POLMOD}, where at least one of the coefficients of the polmod is a
! 4595: $p$-adic number. In this case, the result is the vector of roots belonging to
! 4596: the same extension of $\Q_p$ as $a$.
! 4597:
! 4598: \syn{apprgen9}{\var{pol},a}, but if $a$ is known to be simply a $p$-adic number
! 4599: (type \typ{PADIC}), the syntax $\teb{apprgen}(\var{pol},a)$ can be used.
! 4600:
! 4601: \subsecidx{polcoeff}$(x,s,\{v\})$: coefficient of degree $s$ of the
! 4602: polynomial $x$, with respect to the main variable if $v$ is omitted, with
! 4603: respect to $v$ otherwise.
! 4604:
! 4605: \syn{polcoeff0}{x,s,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded
! 4606: as $-1$. Also available is \teb{truecoeff}$(x,v)$.
! 4607:
! 4608: \subsecidx{poldegree}$(x,\{v\})$: degree of the polynomial $x$ in the main
! 4609: variable if $v$ is omitted, in the variable $v$ otherwise. This is to be
! 4610: understood as follows. When $x$ is a polynomial or a rational function, it
! 4611: gives the degree of $x$, the degree of $0$ being $-1$ by convention. When $x$
! 4612: is a non-zero scalar, it gives 0, and when $x$ is a zero scalar, it gives
! 4613: $-1$. Return an error otherwise.
! 4614:
! 4615: \syn{poldegree}{x,v}, where $v$ and the result are \kbd{long}s (and an
! 4616: omitted $v$ is coded as $-1$). Also available is \teb{degree}$(x)$, which is
! 4617: equivalent to \kbd{poldegree($x$,-1)}.
! 4618:
! 4619: \subsecidx{polcyclo}$(n,\{v=x\})$: $n$-th cyclotomic polynomial, in variable
! 4620: $v$ ($x$ by default). The integer $n$ must be positive.
! 4621:
! 4622: \syn{cyclo}{n,v}, where $n$ and $v$ are \kbd{long}
! 4623: integers ($v$ is a variable number, usually obtained through \kbd{varn}).
! 4624:
! 4625: \subsecidx{poldisc}$(\var{pol},\{v\})$: discriminant of the polynomial
! 4626: \var{pol} in the main variable is $v$ is omitted, in $v$ otherwise. The
! 4627: algorithm used is the \idx{subresultant algorithm}.
! 4628:
! 4629: \syn{poldisc0}{x,v}. Also available is \teb{discsr}$(x)$, equivalent
! 4630: to \kbd{poldisc0(x,-1)}.
! 4631:
! 4632: \subsecidx{poldiscreduced}$(f)$: reduced discriminant vector of the
! 4633: (integral, monic) polynomial $f$. This is the vector of elementary divisors
! 4634: of $\Z[\alpha]/f'(\alpha)\Z[\alpha]$, where $\alpha$ is a root of the
! 4635: polynomial $f$. The components of the result are all positive, and their
! 4636: product is equal to the absolute value of the discriminant of~$f$.
! 4637:
! 4638: \syn{reduceddiscsmith}{x}.
! 4639:
! 4640: \subsecidx{polinterpolate}$(xa,ya,\{v=x\},\{\&e\})$: given the data vectors
! 4641: $xa$ and $ya$ of the same length $n$ ($xa$ containing the $x$-coordinates,
! 4642: and $ya$ the corresponding $y$-coordinates), this function finds the
! 4643: \idx{interpolating polynomial} passing through these points and evaluates it
! 4644: at~$v$. If present, $e$ will contain an error estimate on the returned value.
! 4645:
! 4646: \syn{polint}{xa,ya,v,\&e}, where $e$ will contain an error estimate on the
! 4647: returned value.
! 4648:
! 4649: \subsecidx{polisirreducible}$(\var{pol})$: \var{pol} being a polynomial
! 4650: (univariate in the present version \vers), returns 1 if \var{pol} is
! 4651: non-constant and irreducible, 0 otherwise. Irreducibility is checked over
! 4652: the smallest base field over which \var{pol} seems to be defined.
! 4653:
! 4654: \syn{gisirreducible}{\var{pol}}.
! 4655:
! 4656: \subsecidx{pollead}$(x,\{v\})$: leading coefficient of the polynomial or
! 4657: power series $x$. This is computed with respect to the main variable of $x$
! 4658: if $v$ is omitted, with respect to the variable $v$ otherwise.
! 4659:
! 4660: \syn{pollead}{x,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded as
! 4661: $-1$. Also available is \teb{leadingcoeff}$(x)$.
! 4662:
! 4663: \subsecidx{pollegendre}$(n,\{v=x\})$: creates the $n^{\text{th}}$
! 4664: \idx{Legendre polynomial}, in variable $v$.
! 4665:
! 4666: \syn{legendre}{n}, where $x$ is a \kbd{long}.
! 4667:
! 4668: \subsecidx{polrecip}$(\var{pol})$: reciprocal polynomial of \var{pol},
! 4669: i.e.~the coefficients are in reverse order. \var{pol} must be a polynomial.
! 4670:
! 4671: \syn{polrecip}{x}.
! 4672:
! 4673: \subsecidx{polresultant}$(x,y,\{v\},\{\fl=0\})$: resultant of the two
! 4674: polynomials $x$ and $y$ with exact entries, with respect to the main
! 4675: variables of $x$ and $y$ if $v$ is omitted, with respect to the variable $v$
! 4676: otherwise. The algorithm used is the \idx{subresultant algorithm} by default.
! 4677:
! 4678: If $\fl=1$, uses the determinant of Sylvester's matrix instead (here $x$ and
! 4679: $y$ may have non-exact coefficients).
! 4680:
! 4681: If $\fl=2$, uses Ducos's modified subresultant algorithm. It should be much
! 4682: faster than the default if the coefficient ring is complicated (e.g
! 4683: multivariate polynomials or huge coefficients), and slightly slower
! 4684: otherwise.
! 4685:
! 4686: \syn{polresultant0}{x,y,v,\fl}, where $v$ is a \kbd{long} and an omitted $v$
! 4687: is coded as $-1$. Also available are $\teb{subres}(x,y)$ ($\fl=0$) and
! 4688: $\teb{resultant2}(x,y)$ ($\fl=1$).
! 4689:
! 4690: \subsecidx{polroots}$(\var{pol},\{\fl=0\})$: complex roots of the polynomial
! 4691: \var{pol}, given as a column vector where each root is repeated according to
! 4692: its multiplicity. The precision is given as for transcendental functions: under
! 4693: GP it is kept in the variable \kbd{realprecision} and is transparent to the
! 4694: user, but it must be explicitly given as a second argument in library mode.
! 4695:
! 4696: The algorithm used is a modification of A.~\idx{Sch\"onhage}'s remarkable
! 4697: root-finding algorithm, due to and implemented by X.~Gourdon. Barring bugs,
! 4698: it is guaranteed to converge and to give the roots to the required accuracy.
! 4699:
! 4700: If $\fl=1$, use a variant of the Newton-Raphson method, which is {\it not}
! 4701: guaranteed to converge, but is rather fast. If you get the messages ``too
! 4702: many iterations in roots'' or ``INTERNAL ERROR: incorrect result in roots'',
! 4703: use the default function (i.e.~no flag or $\fl=0$). This used to be the
! 4704: default root-finding function in PARI until version 1.39.06.
! 4705:
! 4706: \syn{roots}{\var{pol},\var{prec}} or $\teb{rootsold}(\var{pol},\var{prec})$.
! 4707:
! 4708: \subsecidx{polrootsmod}$(\var{pol},p,\{\fl=0\})$: row vector of roots modulo
! 4709: $p$ of the polynomial \var{pol}. The particular non-prime value $p=4$ is
! 4710: accepted, mainly for $2$-adic computations. Multiple roots are {\it not\/}
! 4711: repeated.
! 4712:
! 4713: If $p<100$, you may try setting $\fl=1$, which uses a naive search. In this
! 4714: case, multiple roots {\it are\/} repeated with their order of multiplicity.
! 4715:
! 4716: \syn{rootmod}{\var{pol},p} ($\fl=0$) or
! 4717: $\teb{rootmod2}(\var{pol},p)$ ($\fl=1$).
! 4718:
! 4719: \subsecidx{polrootspadic}$(\var{pol},p,r)$: row vector of $p$-adic roots of the
! 4720: polynomial \var{pol} with $p$-adic precision equal to $r$. Multiple roots are
! 4721: {\it not\/} repeated. $p$ is assumed to be a prime.
! 4722:
! 4723: \syn{rootpadic}{\var{pol},p,r}, where $r$ is a \kbd{long}.
! 4724:
! 4725: \subsecidx{polsturm}$(\var{pol},\{a\},\{b\})$: number of real roots of the real
! 4726: polynomial \var{pol} in the interval $]a,b]$, using Sturm's algorithm. $a$
! 4727: (resp.~$b$) is taken to be $-\infty$ (resp.~$+\infty$) if omitted.
! 4728:
! 4729: \syn{sturmpart}{\var{pol},a,b}. Use \kbd{NULL} to omit an argument.
! 4730: \kbd{\teb{sturm}(\var{pol})} is equivalent to
! 4731: \kbd{\key{sturmpart}(\var{pol},NULL,NULL)}.
! 4732: The result is a \kbd{long}.
! 4733:
! 4734: \subsecidx{polsubcyclo}$(n,d,\{v=x\})$: gives a polynomial (in variable
! 4735: $v$) defining the sub-Abelian extension of degree $d$ of the cyclotomic
! 4736: field $\Q(\zeta_n)$, where $d\mid \phi(n)$. $(\Z/n\Z)^*$ has to be cyclic
! 4737: (i.e.~$n=2$, $4$, $p^k$ or $2p^k$ for an odd prime $p$).
! 4738:
! 4739: \syn{subcyclo}{n,d,v}, where $v$ is a variable number.
! 4740:
! 4741: \subsecidx{polsylvestermatrix}$(x,y)$: forms the Sylvester matrix
! 4742: corresponding to the two polynomials $x$ and $y$, where the coefficients of
! 4743: the polynomials are put in the columns of the matrix (which is the natural
! 4744: direction for solving equations afterwards). The use of this matrix can be
! 4745: essential when dealing with polynomials with inexact entries, since
! 4746: polynomial Euclidean division doesn't make much sense in this case.
! 4747:
! 4748: \syn{sylvestermatrix}{x,y}.
! 4749:
! 4750: \subsecidx{polsym}$(x,n)$: creates the vector of the \idx{symmetric powers}
! 4751: of the roots of the polynomial $x$ up to power $n$, using Newton's
! 4752: formula.
! 4753:
! 4754: \syn{polsym}{x}.
! 4755:
! 4756: \subsecidx{poltchebi}$(n,\{v=x\})$: creates the $n^{\text{th}}$
! 4757: \idx{Chebyshev} polynomial, in variable $v$.
! 4758:
! 4759: \syn{tchebi}{n,v}, where $n$ and $v$ are \kbd{long}
! 4760: integers ($v$ is a variable number).
! 4761:
! 4762: \subsecidx{polzagier}$(n,m)$: creates Zagier's polynomial $P_{n,m}$ used in
! 4763: the functions \kbd{sumalt} and \kbd{sumpos} (with $\fl=1$). The exact
! 4764: definition can be found in a forthcoming paper. One must have $m\le n$.
! 4765:
! 4766: \syn{polzagreel}{n,m,\var{prec}} if the result is only wanted as a polynomial
! 4767: with real coefficients to the precision $\var{prec}$, or $\teb{polzag}(n,m)$
! 4768: if the result is wanted exactly, where $n$ and $m$ are \kbd{long}s.
! 4769:
! 4770: \subsecidx{serconvol}$(x,y)$: convolution (or \idx{Hadamard product}) of the
! 4771: two power series $x$ and $y$; in other words if $x=\sum a_k*X^k$ and $y=\sum
! 4772: b_k*X^k$ then $\kbd{serconvol}(x,y)=\sum a_k*b_k*X^k$.
! 4773:
! 4774: \syn{convol}{x,y}.
! 4775:
! 4776: \subsecidx{serlaplace}$(x)$: $x$ must be a power series with only
! 4777: non-negative exponents. If $x=\sum (a_k/k!)*X^k$ then the result is $\sum
! 4778: a_k*X^k$.
! 4779:
! 4780: \syn{laplace}{x}.
! 4781:
! 4782: \subsecidx{serreverse}$(x)$: reverse power series (i.e.~$x^{-1}$, not $1/x$)
! 4783: of $x$. $x$ must be a power series whose valuation is exactly equal to one.
! 4784:
! 4785: \syn{recip}{x}.
! 4786:
! 4787: \subsecidx{subst}$(x,y,z)$:
! 4788: replace the simple variable $y$ by the argument $z$ in the ``polynomial''
! 4789: expression $x$. Every type is allowed for $x$, but if it is not a genuine
! 4790: polynomial (or power series, or rational function), the substitution will be
! 4791: done as if the scalar components were polynomials of degree one. In
! 4792: particular, beware that:
! 4793:
! 4794: \bprog%
! 4795: ? subst(1, x, [1,2; 3,4])
! 4796: \%1 =
! 4797: [1 0]
! 4798: \smallskip%
! 4799: [0 1]
! 4800: \smallskip%
! 4801: ? subst(1, x, Mat([0,1]))
! 4802: \q *** forbidden substitution by a non square matrix%
! 4803: \eprog
! 4804:
! 4805: If $x$ is a power series, $z$ must be either a polynomial, a power series, or
! 4806: a rational function. $y$ must be a simple variable name.
! 4807:
! 4808: \syn{gsubst}{x,v,z}, where $v$ is the number of
! 4809: the variable $y$.
! 4810:
! 4811: \subsecidx{taylor}$(x,y)$: Taylor expansion around $0$ of $x$ with respect
! 4812: to\label{se:taylor}
! 4813: the simple variable $y$. $x$ can be of any reasonable type, for example a
! 4814: rational function. The number of terms of the expansion is transparent to the
! 4815: user under GP, but must be given as a second argument in library mode.
! 4816:
! 4817: \syn{tayl}{x,y,n}, where the \kbd{long} integer $n$ is the desired number of
! 4818: terms in the expansion.
! 4819:
! 4820: \subsecidx{thue}$(\var{tnf},a,\{\var{sol}\})$: solves the equation
! 4821: $P(x,y)=a$ in integers $x$ and $y$, where \var{tnf} was created with
! 4822: $\kbd{thueinit}(P)$. \var{sol}, if present, contains the solutions of
! 4823: $\text{Norm}(x)=a$ modulo units of positive norm in the number field
! 4824: defined by $P$ (as computed by \kbd{bnfisintnorm}). If \var{tnf} was
! 4825: computed without assuming \idx{GRH} ($\fl=1$ in \kbd{thueinit}), the
! 4826: result is unconditional.
! 4827:
! 4828: \syn{thue}{\var{tnf},a,\var{sol}}, where an omitted \var{sol} is coded
! 4829: as \kbd{NULL}.
! 4830:
! 4831: \subsecidx{thueinit}$(P,\{\fl=0\})$: initializes the \var{tnf} corresponding to
! 4832: $P$. It is meant to be used in conjunction with \tet{thue} to solve Thue
! 4833: equations $P(x,y) = a$, where $a$ is an integer. If $\fl$ is non-zero,
! 4834: certify the result unconditionnaly, Otherwise, assume \idx{GRH}, this being
! 4835: much faster of course.
! 4836:
! 4837: \syn{thueinit}{P,\fl,\var{prec}}.
! 4838:
! 4839: \section{Vectors, matrices, linear algebra and sets}
! 4840: \label{se:linear_algebra}
! 4841:
! 4842: Note that most linear algebra functions operating on subspaces defined by
! 4843: generating sets (such as \tet{mathnf}, \tet{qflll}, etc.) take matrices as
! 4844: arguments. As usual, the generating vectors are taken to be the
! 4845: {\it columns\/} of the given matrix.
! 4846:
! 4847: \subsecidx{algdep}$(x,k,\{\fl=0\})$:\sidx{algebraic dependence} $x$ being
! 4848: real or complex, finds a polynomial of degree at most $k$ having $x$ as
! 4849: approximate root. The algorithm used is a variant of the \idx{LLL} algorithm
! 4850: due to Hastad, Lagarias and Schnorr (STACS 1986). Note that the polynomial
! 4851: which is obtained is not necessarily the ``correct'' one (it's not even
! 4852: guaranteed to be irreducible!). One can check the closeness either by a
! 4853: polynomial evaluation or substitution, or by computing the roots of the
! 4854: polynomial given by algdep. If the precision is too low, the routine may
! 4855: enter an infinite loop.
! 4856:
! 4857: If $\fl$ is non-zero, use a standard LLL. $\fl$ then indicates a precision,
! 4858: which should be between $0.5$ and $1.0$ times the number of decimal digits
! 4859: to which $x$ was computed.
! 4860:
! 4861: \syn{algdep0}{x,k,\fl,\var{prec}}, where $k$ and $\fl$ are \kbd{long}s.
! 4862: Also available is $\teb{algdep}(x,k,\var{prec})$ ($\fl=0$).
! 4863:
! 4864: \subsecidx{charpoly}$(A,\{v=x\},\{\fl=0\})$: \idx{characteristic polynomial}
! 4865: of $A$ with respect to the variable $v$, i.e.~determinant of $v*I-A$ if $A$
! 4866: is a square matrix, determinant of the map ``multiplication by $A$'' if $A$
! 4867: is a scalar, in particular a polmod (e.g.~\kbd{charpoly(I,x)=x\pow2+1}),
! 4868: error if $A$ is of any other type. The value of $\fl$ is only significant
! 4869: for matrices.
! 4870:
! 4871: If $\fl=0$, the method used is essentially the same as for computing the
! 4872: adjoint matrix, i.e.~computing the traces of the powers of $A$.
! 4873:
! 4874: If $\fl=1$, uses Lagrange interpolation which is almost always slower.
! 4875:
! 4876: If $\fl=2$, uses the Hessenberg form. This is faster than the default when the
! 4877: coefficients are integermod a prime or real numbers, but is usually slower in
! 4878: other base rings.
! 4879:
! 4880: \syn{charpoly0}{A,v,\fl}, where $v$ is the variable number. Also available
! 4881: are the functions $\teb{caract}(A,v)$ ($\fl=1$), $\teb{carhess}(A,v)$
! 4882: ($\fl=2$), and $\teb{caradj}(A,v,\var{pt})$ where, in this last case,
! 4883: \var{pt} is a \kbd{GEN*} which, if not equal to \kbd{NULL}, will receive
! 4884: the address of the adjoint matrix of $A$ (see \kbd{matadjoint}), so both
! 4885: can be obtained at once.
! 4886:
! 4887: \subsecidx{concat}$(x,\{y\})$: concatenation of $x$ and $y$. If $x$ or $y$ is
! 4888: not a vector or matrix, it is considered as a one-dimensional vector. All
! 4889: types are allowed for $x$ and $y$, but the sizes must be compatible. Note
! 4890: that matrices are concatenated horizontally, i.e.~the number of rows stays
! 4891: the same. Using transpositions, it is easy to concatenate them vertically.
! 4892:
! 4893: To concatenate vectors sideways (i.e.~to obtain a two-row or two-column
! 4894: matrix), first transform the vector into a one-row or one-column matrix using
! 4895: the function \tet{Mat}. Concatenating a row vector to a matrix having the
! 4896: same number of columns will add the row to the matrix (top row if the vector
! 4897: is $x$, i.e.~comes first, and bottom row otherwise).
! 4898:
! 4899: The empty matrix \kbd{[;]} is considered to have a number of rows compatible
! 4900: with any operation, in particular concatenation. (Note that this is
! 4901: definitely {\it not\/} the case for empty vectors \kbd{[~]} or \kbd{[~]\til}.)
! 4902:
! 4903: If $y$ is omitted, $x$ has to be a row vector or a list, in which case its
! 4904: elements are concatenated, from left to right, using the above rules.
! 4905:
! 4906: \bprog%
! 4907: ? concat([1,2], [3,4])
! 4908: \%1 = [1, 2, 3, 4]
! 4909: ? concat([1,2]\til, [3,4]\til)
! 4910: \%2 = [1, 2, 3, 4]\til
! 4911: ? concat([1,2; 3,4], [5,6]\til)
! 4912: \%3 =
! 4913: [1, 2, 5]
! 4914: \smallskip%
! 4915: [3, 4, 6]
! 4916: \smallskip%
! 4917: ? concat([\%, [7,8]\til, [1,2,3,4]])
! 4918: \%4 =
! 4919: [1 2 5 7]
! 4920: \smallskip%
! 4921: [3 4 6 8]
! 4922: \smallskip%
! 4923: [1 2 3 4]
! 4924: \eprog
! 4925:
! 4926: \syn{concat}{x,y}.
! 4927:
! 4928: \subsecidx{lindep}$(x,\{\fl=0\})$:\sidx{linear dependence}$x$ being a
! 4929: vector with real or complex coefficients, finds a small integral linear
! 4930: combination among these coefficients.
! 4931:
! 4932: If $\fl=0$, uses a variant of the \idx{LLL} algorithm due to Hastad, Lagarias
! 4933: and Schnorr (STACS 1986).
! 4934:
! 4935: If $\fl>0$, uses the LLL algorithm. $\fl$ is a parameter which should be
! 4936: between one half the number of decimal digits of precision and that number
! 4937: (see \kbd{algdep}).
! 4938:
! 4939: If $\fl<0$, returns as soon as one relation has been found.
! 4940:
! 4941: \syn{lindep0}{x,\fl,\var{prec}}. Also available is
! 4942: $\teb{lindep}(x,\var{prec})$ ($\fl=0$).
! 4943:
! 4944: \subsecidx{listcreate}$(n)$: creates an empty list of maximal length $n$.
! 4945:
! 4946: This function is useless in library mode.
! 4947:
! 4948: \subsecidx{listinsert}$(\var{list},x,n)$: inserts the object $x$ at
! 4949: position $n$ in \var{list} (which must be of type \typ{LIST}). All the
! 4950: remaining elements of \var{list} (from position $n+1$ onwards) are shifted
! 4951: to the right. This and \kbd{listput} are the only commands which enable
! 4952: you to increase a list's effective length (as long as it remains under
! 4953: the maximal length specified at the time of the \kbd{listcreate}).
! 4954:
! 4955: This function is useless in library mode.
! 4956:
! 4957: \subsecidx{listkill}$(\var{list})$: kill \var{list}. This deletes all
! 4958: elements from \var{list} and sets its effective length to $0$. The maximal
! 4959: length is not affected.
! 4960:
! 4961: This function is useless in library mode.
! 4962:
! 4963: \subsecidx{listput}$(\var{list},x,\{n\})$: sets the $n$-th element of the list
! 4964: \var{list} (which must be of type \typ{LIST}) equal to $x$. If $n$ is omitted,
! 4965: or greater than the list current effective length, just appends $x$. This and
! 4966: \kbd{listinsert} are the only commands which enable you to increase a list's
! 4967: effective length (as long as it remains under the maximal length specified at
! 4968: the time of the \kbd{listcreate}).
! 4969:
! 4970: If you want to put an element into an occupied cell, i.e.~if you don't want to
! 4971: change the effective length, you can consider the list as a vector and use
! 4972: the usual \kbd{list[n] = x} construct.
! 4973:
! 4974: This function is useless in library mode.
! 4975:
! 4976: \subsecidx{listsort}$(\var{list},\{\fl=0\})$: sorts \var{list} (which must
! 4977: be of type \typ{LIST}) in place. If $\fl$ is non-zero, suppresses all repeated
! 4978: coefficients. This is much faster than the \kbd{vecsort} command since no
! 4979: copy has to be made.
! 4980:
! 4981: This function is useless in library mode.
! 4982:
! 4983: \subsecidx{matadjoint}$(x)$: \idx{adjoint matrix} of $x$, i.e.~the matrix $y$
! 4984: of cofactors of $x$, satisfying $x*y=\det(x)*\text{Id}$. $x$ must be a
! 4985: (non-necessarily invertible) square matrix.
! 4986:
! 4987: \syn{adj}{x}.
! 4988:
! 4989: \subsecidx{matcompanion}$(x)$: the left companion matrix to the polynomial $x$.
! 4990:
! 4991: \syn{assmat}{x}.
! 4992:
! 4993: \subsecidx{matdet}$(x,\{\fl=0\})$: determinant of $x$. $x$ must be a
! 4994: square matrix.
! 4995:
! 4996: If $\fl=0$, uses Gauss-Bareiss.
! 4997:
! 4998: If $\fl=1$, uses classical Gaussian elimination, which is better when the
! 4999: entries of the matrix are reals or integers for example, but usually much
! 5000: worse for more complicated entries like multivariate polynomials.
! 5001:
! 5002: \syn{det}{x} ($\fl=0$) and $\teb{det2}(x)$
! 5003: ($\fl=1$).
! 5004:
! 5005: \subsecidx{matdetint}$(x)$: $x$ being an $m\times n$ matrix with integer
! 5006: coefficients, this function computes a multiple of the determinant of the
! 5007: lattice generated by the columns of $x$ if it is of rank $m$, and returns
! 5008: zero otherwise. This function can be useful in conjunction with the function
! 5009: \kbd{mathnfmod} which needs to know such a multiple. Other ways to obtain
! 5010: this determinant (assuming the rank is maximal) is
! 5011: \kbd{matdet(qflll(x,4)[2]$*$x)} or more simply \kbd{matdet(mathnf(x))}.
! 5012: Experiment to see which is faster for your applications.
! 5013:
! 5014: \syn{detint}{x}.
! 5015:
! 5016: \subsecidx{matdiagonal}$(x)$: $x$ being a vector, creates the diagonal matrix
! 5017: whose diagonal entries are those of $x$.
! 5018:
! 5019: \syn{diagonal}{x}.
! 5020:
! 5021: \subsecidx{mateigen}$(x)$: gives the eigenvectors of $x$ as columns of a
! 5022: matrix.
! 5023:
! 5024: \syn{eigen}{x}.
! 5025:
! 5026: \subsecidx{mathess}$(x)$: Hessenberg form of the square matrix $x$.
! 5027:
! 5028: \syn{hess}{x}.
! 5029:
! 5030: \subsecidx{mathilbert}$(x)$: $x$ being a \kbd{long}, creates the \idx{Hilbert
! 5031: matrix} of order $x$, i.e.~the matrix whose coefficient ($i$,$j$) is $1/
! 5032: (i+j-1)$.
! 5033:
! 5034: \syn{mathilbert}{x}.
! 5035:
! 5036: \subsecidx{mathnf}$(x,\{\fl=0\})$: if $x$ is a (not necessarily square)
! 5037: matrix of maximal rank, finds the {\it upper triangular\/}
! 5038: \idx{Hermite normal form}
! 5039: of $x$. If the rank of $x$ is equal to its number of rows, the result is a
! 5040: square matrix. In general, the columns of the result form a basis of the
! 5041: lattice spanned by the columns of $x$.
! 5042:
! 5043: If $\fl=0$, uses the naive algorithm. If the $\Z$-module generated by the
! 5044: columns is a lattice, it is recommanded to use \kbd{mathnfmod(x,
! 5045: matdetint(x))} instead (much faster).
! 5046:
! 5047: If $\fl=1$, uses Batut's algorithm. Outputs a two-component row vector
! 5048: $[H,U]$, where $H$ is the {\it upper triangular\/} Hermite normal form
! 5049: of $x$ (i.e.~the default result) and $U$ is the unimodular transformation
! 5050: matrix such that $xU=[0|H]$. If the rank of $x$ is equal to its number of
! 5051: rows, $H$ is a square matrix. In general, the columns of $H$ form a basis
! 5052: of the lattice spanned by the columns of $x$.
! 5053:
! 5054: If $\fl=2$, uses Havas's algorithm. Outputs $[H,U,P]$, such that
! 5055: $H$ and $U$ are as before and $P$ is a permutation of the rows such that $P$
! 5056: applied to $xU$ gives $H$. This does not work very well in present version
! 5057: \vers.
! 5058:
! 5059: If $\fl=3$, uses Batut's algorithm, and outputs $[H,U,P]$ as in the previous
! 5060: case.
! 5061:
! 5062: If $\fl=4$, as in case 1 above, but uses \idx{LLL} reduction along the way.
! 5063:
! 5064: \syn{mathnf0}{x,\fl}. Also available are $\teb{hnf}(x)$ ($\fl=0$) and
! 5065: $\teb{hnfall}(x)$ ($\fl=1$). To reduce {\it huge} (say $400 \times 400$ and
! 5066: more) relation matrices (sparse with small entries), you can use the pair
! 5067: \kbd{hnfspec} / \kbd{hnfadd}. Since this is rather technical and the
! 5068: calling interface may change, they are not documented yet. Look at the code
! 5069: in \kbd{basemath/alglin1.c}.
! 5070:
! 5071: \subsecidx{mathnfmod}$(x,d)$: if $x$ is a (not necessarily square) matrix of
! 5072: maximal rank with integer entries, and $d$ is a multiple of the (non-zero)
! 5073: determinant of the lattice spanned by the columns of $x$, finds the
! 5074: {\it upper triangular\/} \idx{Hermite normal form} of $x$.
! 5075:
! 5076: If the rank of $x$ is equal to its number of rows, the result is a square
! 5077: matrix. In general, the columns of the result form a basis of the lattice
! 5078: spanned by the columns of $x$. This is much faster than \kbd{mathnf} when $d$
! 5079: is known.
! 5080:
! 5081: \syn{hnfmod}{x,d}.
! 5082:
! 5083: \subsecidx{mathnfmodid}$(x,d)$: outputs the (upper triangular)
! 5084: \idx{Hermite normal form} of $x$ concatenated with $d$ times
! 5085: the identity matrix.
! 5086:
! 5087: \syn{hnfmodid}{x,d}.
! 5088:
! 5089: \subsecidx{matid}$(n)$: creates the $n\times n$ identity matrix.
! 5090:
! 5091: \syn{idmat}{n} where $n$ is a \kbd{long}.
! 5092:
! 5093: Related functions are $\teb{gscalmat}(x,n)$, which creates $x$ times the
! 5094: identity matrix ($x$ being a \kbd{GEN} and $n$ a \kbd{long}), and
! 5095: $\teb{gscalsmat}(x,n)$ which is the same when $x$ is a \kbd{long}.
! 5096:
! 5097: \subsecidx{matimage}$(x,\{\fl=0\})$: gives a basis for the image of the
! 5098: matrix $x$ as columns of a matrix. A priori the matrix can have entries of
! 5099: any type. If $\fl=0$, use standard Gauss pivot. If $\fl=1$, use
! 5100: \kbd{matsupplement}.
! 5101:
! 5102: \syn{matimage0}{x,\fl}. Also available is $\teb{image}(x)$ ($\fl=0$).
! 5103:
! 5104: \subsecidx{matimagecompl}$(x)$: gives the vector of the column indices which
! 5105: are not extracted by the function \kbd{matimage}. Hence the number of
! 5106: components of \kbd{matimagecompl(x)} plus the number of columns of
! 5107: \kbd{matimage(x)} is equal to the number of columns of the matrix $x$.
! 5108:
! 5109: \syn{imagecompl}{x}.
! 5110:
! 5111: \subsecidx{matindexrank}$(x)$: $x$ being a matrix of rank $r$, gives two
! 5112: vectors $y$ and $z$ of length $r$ giving a list of rows and columns
! 5113: respectively (starting from 1) such that the extracted matrix obtained from
! 5114: these two vectors using $\tet{vecextract}(x,y,z)$ is invertible.
! 5115:
! 5116: \syn{indexrank}{x}.
! 5117:
! 5118: \subsecidx{matintersect}$(x,y)$: $x$ and $y$ being two matrices with the same
! 5119: number of rows each of whose columns are independent, finds a basis of the
! 5120: $\Q$-vector space equal to the intersection of the spaces spanned by the
! 5121: columns of $x$ and $y$ respectively. See also the function
! 5122: \tet{idealintersect}, which does the same for free $\Z$-modules.
! 5123:
! 5124: \syn{intersect}{x,y}.
! 5125:
! 5126: \subsecidx{matinverseimage}$(x,y)$: gives a column vector belonging to the
! 5127: inverse image of the column vector $y$ by the matrix $x$ if one exists, the
! 5128: empty vector otherwise. To get the complete inverse image, it suffices to add
! 5129: to the result any element of the kernel of $x$ obtained for example by
! 5130: \kbd{matker}.
! 5131:
! 5132: \syn{inverseimage}{x,y}.
! 5133:
! 5134: \subsecidx{matisdiagonal}$(x)$: returns true (1) if $x$ is a diagonal matrix,
! 5135: false (0) if not.
! 5136:
! 5137: \syn{isdiagonal}{x}, and this returns a \kbd{long}
! 5138: integer.
! 5139:
! 5140: \subsecidx{matker}$(x,\{\fl=0\})$: gives a basis for the kernel of the
! 5141: matrix $x$ as columns of a matrix. A priori the matrix can have entries of
! 5142: any type.
! 5143:
! 5144: If $x$ is known to have integral entries, set $\fl=1$.
! 5145:
! 5146: \noindent Note: The library function\sidx{ker\string\_mod\string\_p}
! 5147: $\kbd{ker\_mod\_p}(x, p)$, where $x$ has integer entries and $p$ is prime,
! 5148: which is equivalent to but many orders of magnitude faster than
! 5149: \kbd{matker(x*Mod(1,p))} and needs much less stack space. To use it under GP,
! 5150: type \kbd{install(ker\_mod\_p, GG)} first.
! 5151:
! 5152: \syn{matker0}{x,\fl}. Also available are $\teb{ker}(x)$ ($\fl=0$),
! 5153: $\teb{keri}(x)$ ($\fl=1$) and $\kbd{ker\_mod\_p}(x,p)$.
! 5154:
! 5155: \subsecidx{matkerint}$(x,\{\fl=0\})$: gives an \idx{LLL}-reduced $\Z$-basis
! 5156: for the lattice equal to the kernel of the matrix $x$ as columns of the
! 5157: matrix $x$ with integer entries (rational entries are not permitted).
! 5158:
! 5159: If $\fl=0$, uses a modified integer LLL algorithm.
! 5160:
! 5161: If $\fl=1$, uses $\kbd{matrixqz}(x,-2)$. If LLL reduction of the final result
! 5162: is not desired, you can save time using \kbd{matrixqz(matker(x),-2)} instead.
! 5163:
! 5164: If $\fl=2$, uses another modified LLL. In the present version \vers, only
! 5165: independent rows are allowed in this case.
! 5166:
! 5167: \syn{matkerint0}{x,\fl}. Also available is
! 5168: $\teb{kerint}(x)$ ($\fl=0$).
! 5169:
! 5170: \subsecidx{matmuldiagonal}$(x,d)$: product of the matrix $x$ by the diagonal
! 5171: matrix whose diagonal entries are those of the vector $d$. Equivalent to,
! 5172: but much faster than $x*\kbd{matdiagonal}(d)$.
! 5173:
! 5174: \syn{matmuldiagonal}{x,d}.
! 5175:
! 5176: \subsecidx{matmultodiagonal}$(x,y)$: product of the matrices $x$ and $y$
! 5177: knowing that the result is a diagonal matrix. Much faster than $x*y$ in
! 5178: that case.
! 5179:
! 5180: \syn{matmultodiagonal}{x,y}.
! 5181:
! 5182: \subsecidx{matpascal}$(x,\{q\})$: creates as a matrix the lower triangular
! 5183: \idx{pascal triangle} of order $x+1$ (i.e.~with binomial coefficients
! 5184: up to $x$). If $q$ is given, compute the $q$-Pascal triangle (i.e.~using
! 5185: $q$-binomial coefficients).
! 5186:
! 5187: \syn{matqpascal}{x,q}, where $x$ is a \kbd{long} and $q=\kbd{NULL}$ is used
! 5188: to omit $q$. Also available is \teb{matpascal}{x}.
! 5189:
! 5190: \subsecidx{matrank}$(x)$: rank of the matrix $x$.
! 5191:
! 5192: \syn{rank}{x}, and the result is a \kbd{long}.
! 5193:
! 5194: \subsecidx{matrixqz}$(x,p)$: $x$ being an $m\times n$ matrix with $m\ge n$
! 5195: with rational or integer entries, this function has varying behaviour
! 5196: depending on the sign of $p$:
! 5197:
! 5198: If $p\geq 0$, $x$ is assumed to be of maximal rank. This function returns a
! 5199: matrix having only integral entries, having the same image as $x$, such that
! 5200: the GCD of all its $n\times n$ subdeterminants is equal to 1 when $p$ is
! 5201: equal to 0, or not divisible by $p$ otherwise. Here $p$ must be a prime
! 5202: number (when it is non-zero). However, if the function is used when $p$ has
! 5203: no small prime factors, it will either work or give the message ``impossible
! 5204: inverse modulo'' and a non-trivial divisor of $p$.
! 5205:
! 5206: If $p=-1$, this function returns a matrix whose columns form a basis of the
! 5207: lattice equal to $\Z^n$ intersected with the lattice generated by the
! 5208: columns of $x$.
! 5209:
! 5210: If $p=-2$, returns a matrix whose columns form a basis of the lattice equal
! 5211: to $\Z^n$ intersected with the $\Q$-vector space generated by the
! 5212: columns of $x$.
! 5213:
! 5214: \syn{matrixqz0}{x,p}.
! 5215:
! 5216: \subsecidx{matsize}$(x)$: $x$ being a vector or matrix, returns a row vector
! 5217: with two components, the first being the number of rows (1 for a row vector),
! 5218: the second the number of columns (1 for a column vector).
! 5219:
! 5220: \syn{matsize}{x}.
! 5221:
! 5222: \subsecidx{matsnf}$(X,\{\fl=0\})$: if $X$ is a (singular or non-singular)
! 5223: square matrix outputs the vector of elementary divisors of $X$ (i.e.~the
! 5224: diagonal of the \idx{Smith normal form} of $X$).
! 5225:
! 5226: The binary digits of \fl\ mean:
! 5227:
! 5228: 1 (complete output): if set, outputs $[U,V,D]$, where $U$ and $V$ are two
! 5229: unimodular matrices such that $U\times X \times V$ is the diagonal matrix
! 5230: $D$. Otherwise output only the diagonal of $D$.
! 5231:
! 5232: 2 (generic input): if set, allows polynomial entries. Otherwise, assume
! 5233: that $X$ has integer coefficients.
! 5234:
! 5235: 4 (cleanup): if set, cleans up the output. This means that elementary
! 5236: divisors equal to $1$ will be deleted, i.e.~outputs a shortened vector $D'$
! 5237: instead of $D$. If complete output was required, returns $[U',V',D']$ so
! 5238: that $U'XV' = D'$ holds. If this flag is set, $X$ is allowed to be of the
! 5239: form $D$ or $[U,V,D]$ as would normally be output with the cleanup flag
! 5240: unset.
! 5241:
! 5242: \syn{matsnf0}{X,\fl}. Also available is $\teb{smith}(X)$ ($\fl=0$).
! 5243:
! 5244: \subsecidx{matsolve}$(x,y)$: $x$ being an invertible matrix and $y$ a column
! 5245: vector, finds the solution $u$ of $x*u=y$, using Gaussian elimination. This
! 5246: has the same effect as, but is a bit faster, than $x^{-1}*y$.
! 5247:
! 5248: \syn{gauss}{x,y}.
! 5249:
! 5250: \subsecidx{matsolvemod}$(m,d,y,\{\fl=0\})$: $m$ being any integral matrix,
! 5251: $d$ a vector of positive integer moduli, and $y$ an integral
! 5252: column vector, gives a small integer solution to the system of congruences
! 5253: $\sum_i m_{i,j}x_j\equiv y_i\pmod{d_i}$ if one exists, otherwise returns
! 5254: zero. Shorthand notation: $y$ (resp.~$d$) can be given as a single integer,
! 5255: in which case all the $y_i$ (resp.~$d_i$) above are taken to be equal to $y$
! 5256: (resp.~$d$).
! 5257:
! 5258: If $\fl=1$, all solutions are returned in the form of a two-component row
! 5259: vector $[x,u]$, where $x$ is a small integer solution to the system of
! 5260: congruences and $u$ is a matrix whose columns give a basis of the homogeneous
! 5261: system (so that all solutions can be obtained by adding $x$ to any linear
! 5262: combination of columns of $u$). If no solution exists, returns zero.
! 5263:
! 5264: \syn{matsolvemod0}{m,d,y,\fl}. Also available
! 5265: are $\teb{gaussmodulo}(m,d,y)$ ($\fl=0$)
! 5266: and $\teb{gaussmodulo2}(m,d,y)$ ($\fl=1$).
! 5267:
! 5268: \subsecidx{matsupplement}$(x)$: assuming that the columns of the matrix $x$
! 5269: are linearly independent (if they are not, an error message is issued), finds
! 5270: a square invertible matrix whose first columns are the columns of $x$,
! 5271: i.e.~supplement the columns of $x$ to a basis of the whole space.
! 5272:
! 5273: \syn{suppl}{x}.
! 5274:
! 5275: \subsecidx{mattranspose}$(x)$ or $x\til$: transpose of $x$.
! 5276: This has an effect only on vectors and matrices.
! 5277:
! 5278: \syn{gtrans}{x}.
! 5279:
! 5280: \subsecidx{qfgaussred}$(q)$: \idx{decomposition into squares} of the
! 5281: quadratic form represented by the symmetric matrix $q$. The result is a
! 5282: matrix whose diagonal entries are the coefficients of the squares, and the
! 5283: non-diagonal entries represent the bilinear forms. More precisely, if
! 5284: $(a_{ij})$ denotes the output, one has
! 5285: $$ q(x) = \sum_i a_{ii} (x_i + \sum_j>i a_{ij} x_j)^2 $$
! 5286:
! 5287: \syn{sqred}{x}.
! 5288:
! 5289: \subsecidx{qfjacobi}$(x)$: $x$ being a real symmetric matrix, this gives a
! 5290: vector having two components: the first one is the vector of eigenvalues of
! 5291: $x$, the second is the corresponding orthogonal matrix of eigenvectors of
! 5292: $x$. The method used is Jacobi's method for symmetric matrices.
! 5293:
! 5294: \syn{jacobi}{x}.
! 5295:
! 5296: \subsecidx{qf{}lll}$(x,\{\fl=0\})$: \idx{LLL} algorithm applied to the
! 5297: {\it columns}
! 5298: of the (not necessarily square) matrix $x$. The columns of $x$ must however
! 5299: be of maximal rank (unless specified otherwise below). The result is a square
! 5300: transformation matrix $T$ such that $x\cdot T$ is an LLL-reduced basis of the
! 5301: lattice generated by the column vectors of $x$.
! 5302:
! 5303: If $\fl=0$ (default), the computations are done with real numbers (i.e.~not
! 5304: with rational numbers) hence are fast but as presently programmed (version
! 5305: \vers) are numerically unstable.
! 5306:
! 5307: If $\fl=1$, it is assumed that the corresponding Gram matrix is integral.
! 5308: The computation is done entirely with integers and the algorithm is both
! 5309: accurate and quite fast. In this case, $x$ needs not be of maximal rank.
! 5310:
! 5311: If $\fl=2$, similar to case 1, except $x$ should be an integer matrix whose
! 5312: columns are linearly independent. The lattice generated by the columns of
! 5313: $x$ is first partially reduced before applying the LLL algorithm. [A basis
! 5314: is said to be {\it partially reduced} if $|v_i \pm v_j| \geq |v_i|$ for any
! 5315: two distinct basis vectors $v_i, \, v_j$.]
! 5316:
! 5317: This can be significantly faster than $\fl=1$ when one row is huge compared
! 5318: to the other rows.
! 5319:
! 5320: If $\fl=3$, all computations are done in rational numbers. This does not
! 5321: incur numerical instability, but is extremely slow. This function is
! 5322: essentially superseded by case 1, so will soon disappear.
! 5323:
! 5324: If $\fl=4$, $x$ is assumed to have integral entries, but needs not be of
! 5325: maximal rank. The result is a two-component vector of matrices, the columns
! 5326: of the first matrix representing a basis of the integer kernel of $x$ (not
! 5327: necessarily LLL-reduced) and the columns of the second matrix being an
! 5328: LLL-reduced $\Z$-basis of the image of the matrix $x$.
! 5329:
! 5330: If $\fl=5$, case as case $4$, but $x$ may have polynomial coefficients.
! 5331:
! 5332: If $\fl=7$, uses an older version of case $0$ above.
! 5333:
! 5334: If $\fl=8$, same as case $0$, where $x$ may have polynomial coefficients.
! 5335:
! 5336: If $\fl=9$, variation on case $1$, using content.
! 5337:
! 5338: \syn{qf{}lll0}{x,\fl,\var{prec}}. Also available are
! 5339: $\teb{lll}(x,\var{prec})$ ($\fl=0$), $\teb{lllint}(x)$ ($\fl=1$), and
! 5340: $\teb{lllkerim}(x)$ ($\fl=4$).
! 5341:
! 5342: \subsecidx{qf{}lllgram}$(x,\{\fl=0\})$: same as \kbd{qflll} except that the
! 5343: matrix $x$ which must now be a square symmetric real matrix is the Gram
! 5344: matrix of the lattice vectors, and not the coordinates of the vectors
! 5345: themselves. The result is again the transformation matrix $T$ which gives (as
! 5346: columns) the coefficients with respect to the initial basis vectors. The
! 5347: flags have more or less the same meaning, but some are missing. In brief:
! 5348:
! 5349: $\fl=0$: numerically unstable in the present version \vers.
! 5350:
! 5351: $\fl=1$: $x$ has integer entries, the computations are all done in integers.
! 5352:
! 5353: $\fl=4$: $x$ has integer entries, gives the kernel and reduced image.
! 5354:
! 5355: $\fl=5$: same as $4$ for generic $x$.
! 5356:
! 5357: $\fl=7$: an older version of case $0$.
! 5358:
! 5359: \syn{qf{}lllgram0}{x,\fl,\var{prec}}. Also available are
! 5360: $\teb{lllgram}(x,\var{prec})$ ($\fl=0$), $\teb{lllgramint}(x)$ ($\fl=1$), and
! 5361: $\teb{lllgramkerim}(x)$ ($\fl=4$).
! 5362:
! 5363: \subsecidx{qfminim}$(x,b,m,\{\fl=0\})$: $x$ being a square and symmetric
! 5364: matrix representing a positive definite quadratic form, this function
! 5365: deals with the minimal vectors of $x$, depending on $\fl$.
! 5366:
! 5367: If $\fl=0$ (default), seeks vectors of square norm less than or equal to $b$
! 5368: (for the norm defined by $x$), and at most $2m$ of these vectors. The result
! 5369: is a three-component vector, the first component being the number of vectors,
! 5370: the second being the maximum norm found, and the last vector is a matrix
! 5371: whose columns are the vectors found, only one being given for each
! 5372: pair $\pm v$ (at most $m$ such pairs).
! 5373:
! 5374: If $\fl=1$, ignores $m$ and returns the first vector whose norm is less than
! 5375: $b$.
! 5376:
! 5377: In both these cases, $x$ {\it is assumed to have integral entries}, and the
! 5378: function searches for the minimal non-zero vectors whenever $b=0$.
! 5379:
! 5380: If $\fl=2$, $x$ can have non integral real entries, but $b=0$ is now
! 5381: meaningless (uses Fincke-Pohst algorithm).
! 5382:
! 5383: \syn{minim}{x,b,m} ($\fl=0$), $\teb{minim2}(x,b,m)$
! 5384: ($\fl=1$), or finally $\key{fincke\_pohst}(x,b,m,\var{prec})$
! 5385: ($\fl=2$).\sidx{fincke\string\_pohst}
! 5386:
! 5387: \subsecidx{qfperfection}$(x)$: $x$ being a square and symmetric matrix with
! 5388: integer entries representing a positive definite quadratic form, outputs the
! 5389: perfection rank of the form. That is, gives the rank of the family of the $s$
! 5390: symmetric matrices $v_iv_i^t$, where $s$ is half the number of minimal
! 5391: vectors and the $v_i$ ($1\le i\le s$) are the minimal vectors.
! 5392:
! 5393: As a side note to old-timers, this used to fail bluntly when $x$ had more
! 5394: than $5000$ minimal vectors. Beware that the computations can now be very
! 5395: lengthy when $x$ has many minimal vectors.
! 5396:
! 5397: \syn{perf}{x}.
! 5398:
! 5399: \subsecidx{qfsign}$(x)$: signature of the quadratic form represented by the
! 5400: symmetric matrix $x$. The result is a two-component vector.
! 5401:
! 5402: \syn{signat}{x}.
! 5403:
! 5404: \subsecidx{setintersect}$(x,y)$: intersection of the two sets $x$ and $y$.
! 5405:
! 5406: \syn{setintersect}{x,y}.
! 5407:
! 5408: \subsecidx{setisset}$(x)$: returns true (1) if $x$ is a set, false (0) if
! 5409: not. In PARI, a set is simply a row vector whose entries are strictly
! 5410: increasing. To convert any vector (and other objects) into a set, use the
! 5411: function \kbd{Set}.
! 5412:
! 5413: \syn{setisset}{x}, and this returns a \kbd{long}.
! 5414:
! 5415: \subsecidx{setminus}$(x,y)$: difference of the two sets $x$ and $y$,
! 5416: i.e.~set of elements of $x$ which do not belong to $y$.
! 5417:
! 5418: \syn{setminus}{x,y}.
! 5419:
! 5420: \subsecidx{setsearch}$(x,y,\{\fl=0\})$: searches if $y$ belongs to the set
! 5421: $x$. If it does and $\fl$ is zero or omitted, returns the index $j$ such that
! 5422: $x[j]=y$, otherwise returns 0. If $\fl$ is non-zero returns the index $j$
! 5423: where $y$ should be inserted, and $0$ if it already belongs to $x$ (this is
! 5424: meant to be used in conjunction with \kbd{listinsert}).
! 5425:
! 5426: This function works also if $x$ is a {\it sorted\/} list (see \kbd{listsort}).
! 5427:
! 5428: \syn{setsearch}{x,y,\fl} which returns a \kbd{long}
! 5429: integer.
! 5430:
! 5431: \subsecidx{setunion}$(x,y)$: union of the two sets $x$ and $y$.
! 5432:
! 5433: \syn{setunion}{x,y}.
! 5434:
! 5435: \subsecidx{trace}$(x)$: this applies to quite general $x$. If $x$ is not a
! 5436: matrix, it is equal to the sum of $x$ and its conjugate, except for polmods
! 5437: where it is the trace as an algebraic number.
! 5438:
! 5439: For $x$ a square matrix, it is the ordinary trace. If $x$ is a
! 5440: non-square matrix (but not a vector), an error occurs.
! 5441:
! 5442: \syn{gtrace}{x}.
! 5443:
! 5444: \subsecidx{vecextract}$(x,y,\{z\})$: extraction of components of the
! 5445: vector or matrix $x$ according to $y$. In case $x$ is a matrix, its
! 5446: components are as usual the {\it columns} of $x$. The parameter $y$ is a
! 5447: component specifier, which is either an integer, a string describing a
! 5448: range, or a vector.
! 5449:
! 5450: If $y$ is an integer, it is considered as a mask: the binary bits of $y$ are
! 5451: read from right to left, but correspond to taking the components from left to
! 5452: right. For example, if $y=13=(1101)_2$ then the components 1,3 and 4 are
! 5453: extracted.
! 5454:
! 5455: If $y$ is a vector, which must have integer entries, these entries correspond
! 5456: to the component numbers to be extracted, in the order specified.
! 5457:
! 5458: If $y$ is a string, it can be
! 5459:
! 5460: $\bullet$ a single (non-zero) index giving a component number (a negative
! 5461: index means we start counting from the end).
! 5462:
! 5463: $\bullet$ a range of the form \kbd{"$a$..$b$"}, where $a$ and $b$ are
! 5464: indexes as above. Any of $a$ and $b$ can be omitted; in this case, we take
! 5465: as default values $a = 1$ and $b = -1$, i.e.~ the first and last components
! 5466: respectively. We then extract all components in the interval $[a,b]$, in
! 5467: reverse order if $b < a$.
! 5468:
! 5469: In addition, if the first character in the string is \kbd{\pow}, the
! 5470: complement of the given set of indices is taken.
! 5471:
! 5472: If $z$ is not omitted, $x$ must be a matrix. $y$ is then the {\it line}
! 5473: specifier, and $z$ the {\it column} specifier, where the component specifier
! 5474: is as explained above.
! 5475:
! 5476: \bprog%
! 5477: ? v = [a, b, c, d, e];
! 5478: ? vecextract(v, 5) \bs\bs~mask
! 5479: \%1 = [a, c]
! 5480: ? vecextract(v, [4, 2, 1]) \bs\bs~component list
! 5481: \%2 = [d, b, a]
! 5482: ? vecextract(v, "2..4") \bs\bs~interval
! 5483: \%3 = [b, c, d]
! 5484: ? vecextract(v, "-1..-3") \bs\bs~interval + reverse order
! 5485: \%4 = [e, d, c]
! 5486: ? vecextract([1,2,3], "\pow2") \bs\bs~complement
! 5487: \%5 = [1, 3]
! 5488: ? vecextract(matid(3), "2..", "..")
! 5489: \%6 =
! 5490: [0 1 0]
! 5491: \smallskip%
! 5492: [0 0 1]
! 5493: \eprog
! 5494:
! 5495: \syn{extract}{x,y} or $\teb{matextract}(x,y,z)$.
! 5496:
! 5497: \subsecidx{vecsort}$(x,\{k\},\{\fl=0\})$: sorts the vector $x$ in ascending
! 5498: order, using the heapsort method. $x$ must be a vector, and its components
! 5499: integers, reals, or fractions.
! 5500:
! 5501: If $k$ is present and is an integer, sorts according to the value of the
! 5502: $k$-th subcomponents of the components of~$x$. $k$ can also be a vector,
! 5503: in which case the
! 5504: sorting is done lexicographically according to the components listed in the
! 5505: vector $k$. For example, if $k=[2,1,3]$, sorting will be done with respect
! 5506: to the second component, and when these are equal, with respect to the
! 5507: first, and when these are equal, with respect to the third.
! 5508:
! 5509: \noindent The binary digits of \fl\ mean:
! 5510:
! 5511: $\bullet$ 1: indirect sorting of the vector $x$, i.e.~if $x$ is an
! 5512: $n$-component vector, returns a permutation of $[1,2,\dots,n]$ which
! 5513: applied to the components of $x$ sorts $x$ in increasing order.
! 5514: For example, \kbd{vecextract(x, vecsort(x,,1))} is equivalent to
! 5515: \kbd{vecsort(x)}.
! 5516:
! 5517: $\bullet$ 2: sorts $x$ by ascending lexicographic order (as per the
! 5518: \kbd{lex} comparison function).
! 5519:
! 5520: \syn{vecsort0}{x,k,flag}. To omit $k$, use \kbd{NULL} instead. You can also
! 5521: use the simpler functions
! 5522:
! 5523: $\teb{sort}(x)$ (= $\kbd{vecsort0}(x,\text{NULL},0)$).
! 5524:
! 5525: $\teb{indexsort}(x)$ (= $\kbd{vecsort0}(x,\text{NULL},1)$).
! 5526:
! 5527: $\teb{lexsort}(x)$ (= $\kbd{vecsort0}(x,\text{NULL},2)$).
! 5528:
! 5529: Also available are \teb{sindexsort} and \teb{sindexlexsort} which return a
! 5530: vector (type \typ{VEC}) of C-long integers $v$, where $v[1]\dots v[n]$
! 5531: contain the indices. Note that the resulting $v$ is {\it not\/} a valid PARI
! 5532: object, but is in general easier to use in C programs!
! 5533:
! 5534: \section{Sums, products, integrals and similar functions}
! 5535:
! 5536: Although the GP calculator is programmable, it is useful to have
! 5537: preprogrammed a number of loops, including sums, products, and a certain
! 5538: number of recursions. Also, a number of functions from numerical analysis
! 5539: like numerical integration and summation of series will be described here.
! 5540:
! 5541: One of the parameters in these loops must be the control variable, hence a
! 5542: simple variable name. The last parameter can be any legal PARI expression,
! 5543: including of course expressions using loops. Since it is much easier to
! 5544: program directly the loops in library mode, these functions are mainly
! 5545: useful for GP programming. The use of these functions in library mode is a
! 5546: little tricky and its explanation will be mostly omitted, although the
! 5547: reader can try and figure it out by himself by checking the example given
! 5548: for the \tet{sum} function. In this section we only give the library
! 5549: syntax, with no semantic explanation.
! 5550:
! 5551: The letter $X$ will always denote any simple variable name, and represents
! 5552: the formal parameter used in the function.
! 5553:
! 5554: \misctitle{(numerical) integration}:\sidx{numerical integration} A number
! 5555: of Romberg-like integration methods are implemented (see \kbd{intnum} as
! 5556: opposed to \kbd{intformal} which we already described). The user should not
! 5557: require too much accuracy: 18 or 28 decimal digits is OK, but not much more.
! 5558: In addition, analytical cleanup of the integral must have been done: there
! 5559: must be no singularities in the interval or at the boundaries. In practice
! 5560: this can be accomplished with a simple change of variable. Furthermore, for
! 5561: improper integrals, where one or both of the limits of integration are plus
! 5562: or minus infinity, the function must decrease sufficiently rapidly at
! 5563: infinity. This can often be accomplished through integration by parts.
! 5564:
! 5565: Note that \idx{infinity} can be represented with essentially no loss of
! 5566: accuracy by 1e4000. However beware of real underflow when dealing with
! 5567: rapidly decreasing functions. For example, if one wants to compute the
! 5568: $\int_0^\infty e^{-x^2}\,dx$ to 28 decimal digits, then one should set
! 5569: infinity equal to 10 for example, and certainly not to 1e4000.
! 5570:
! 5571: The integrand may have values belonging to a vector space over the real
! 5572: numbers; in particular, it can be complex-valued or vector-valued.
! 5573:
! 5574: See also the discrete summation methods below (sharing the prefix \kbd{sum}).
! 5575:
! 5576: \subsecidx{intnum}$(X=a,b,\var{expr},\{\fl=0\})$: numerical integration of
! 5577: \var{expr} (smooth in $]a,b[$), with respect to $X$.
! 5578:
! 5579: Set $\fl=0$ (or omit it altogether) when $a$ and $b$ are not too large, the
! 5580: function is smooth, and can be evaluated exactly everywhere on the interval
! 5581: $[a,b]$.
! 5582:
! 5583: If $\fl=1$, uses a general driver routine for doing numerical integration,
! 5584: making no particular assumption (slow).
! 5585:
! 5586: $\fl=2$ is tailored for being used when $a$ or $b$ are infinite. One
! 5587: {\it must\/} have $ab>0$, and in fact if for example $b=+\infty$, then it is
! 5588: preferable to have $a$ as large as possible, at least $a\ge1$.
! 5589:
! 5590: If $\fl=3$, the function is allowed to be undefined (but continuous) at $a$
! 5591: or $b$, for example the function $\sin(x)/x$ at $x=0$.
! 5592:
! 5593: \synt{intnum0}{entree$\,$*e,GEN a,GEN b,char$\,$*expr,long \fl,long prec}.
! 5594:
! 5595: \subsecidx{matrix}$(m,n,\{X\},\{Y\},\{\var{expr}=0\})$: creation of the
! 5596: $m\times n$ matrix whose coefficients are given by the expression
! 5597: \var{expr}. There are two formal parameters in \var{expr}, the first one
! 5598: ($X$) corresponding to the rows, the second ($Y$) to the columns, and $X$
! 5599: goes from 1 to $m$, $Y$ goes from 1 to $n$. If one of the last 3 parameters
! 5600: is omitted, fill the matrix with zeroes.
! 5601:
! 5602: \synt{matrice}{GEN nlig,GEN ncol,entree *e1,entree *e2,char *expr}.
! 5603:
! 5604: \subsecidx{prod}$(X=a,b,\var{expr},\{x=1\})$: product of expression \var{expr},
! 5605: initialized at $x$, the formal parameter $X$ going from $a$ to $b$. As for
! 5606: \kbd{sum}, the main purpose of the initialization parameter $x$ is to force
! 5607: the type of the operations being performed. For example if it is set equal to
! 5608: the integer 1, operations will start being done exactly. If it is set equal
! 5609: to the real $1.$, they will be done using real numbers having the default
! 5610: precision. If it is set equal to the power series $1+O(X^k)$ for a certain
! 5611: $k$, they will be done using power series of precision at most $k$. These
! 5612: are the three most common initializations.
! 5613:
! 5614: \noindent As an extreme example, compare
! 5615:
! 5616: \bprog%
! 5617: ? prod(i=1, 100, 1-X\pow i); \bs\bs\ this has degree $5050$~!!
! 5618: \smallskip%
! 5619: time = 3,335 ms.
! 5620: \smallskip%
! 5621: ? prod(i=1, 100, 1-X\pow i, 1+O(X\pow 101))
! 5622: \smallskip%
! 5623: time = 43 ms.
! 5624: \smallskip%
! 5625: \%2 = 1 - X - X\pow 2 + X\pow 5 + X\pow 7 - X\pow 12 - X\pow 15 + X\pow 22 + X\pow 26 - X\pow 35 - X\pow 40 + X\pow 51
! 5626: + X\pow 57 - X\pow 70 - X\pow 77 + X\pow 92 + X\pow 100 + O(X\pow 101)%
! 5627: \eprog
! 5628:
! 5629: \synt{produit}{entree *ep, GEN a, GEN b, char *expr, GEN x}.
! 5630:
! 5631: \subsecidx{prodeuler}$(X=a,b,\var{expr})$: product of expression \var{expr},
! 5632: initialized at 1. (i.e.~to a {\it real\/} number equal to 1 to the current
! 5633: \kbd{realprecision}), the formal parameter $X$ ranging over the prime numbers
! 5634: between $a$ and $b$.\sidx{Euler product}
! 5635:
! 5636: \synt{prodeuler}{entree *ep, GEN a, GEN b, char *expr, long prec}.
! 5637:
! 5638: \subsecidx{prodinf}$(X=a,\var{expr},\{\fl=0\})$: \idx{infinite product} of
! 5639: expression \var{expr}, the formal parameter $X$ starting at $a$. The evaluation
! 5640: stops when the relative error of the expression minus 1 is less than the
! 5641: default precision. The expressions must always evaluate to an element of
! 5642: $\C$.
! 5643:
! 5644: If $\fl=1$, do the product of the ($1+\var{expr}$) instead.
! 5645:
! 5646: \synt{prodinf}{entree *ep, GEN a, char *expr, long prec} ($\fl=0$), or
! 5647: \teb{prodinf1} with the same arguments ($\fl=1$).
! 5648:
! 5649: \subsecidx{solve}$(X=a,b,\var{expr})$: find a real root of expression
! 5650: \var{expr} between $a$ and $b$, under the condition
! 5651: $\var{expr}(X=a)*\var{expr}(X=b)\le0$. This
! 5652: routine uses Brent's method. This can fail miserably if \var{expr} is not
! 5653: defined in the whole of $[a,b]$ (try \kbd{solve(x=1, 2, tan(x)}).
! 5654:
! 5655: \synt{zbrent}{entree *ep, GEN a, GEN b, char *expr, long prec}.
! 5656:
! 5657: \subsecidx{sum}$(X=a,b,\var{expr},\{x=0\})$: sum of expression \var{expr},
! 5658: initialized at $x$, the formal parameter going from $a$ to $b$. As for
! 5659: \kbd{prod}, the initialization parameter $x$ may be given to force the type
! 5660: of the operations being performed.
! 5661:
! 5662: \noindent As an extreme example, compare
! 5663:
! 5664: \bprog%
! 5665: ? sum(i=1, 5000, 1/i); \bs\bs rational number: denominator has $2166$ digits.
! 5666: \smallskip%
! 5667: time = 1,241 ms.
! 5668: \smallskip%
! 5669: ? sum(i=1, 5000, 1/i, 0.)
! 5670: \smallskip%
! 5671: time = 158 ms.
! 5672: \smallskip%
! 5673: \%2 = 9.094508852984436967261245533%
! 5674: \eprog
! 5675:
! 5676: \synt{somme}{entree *ep, GEN a, GEN b, char *expr, GEN x}. This is to be
! 5677: used as follows: \kbd{ep} represents the dummy variable used in the
! 5678: expression \kbd{expr}
! 5679: \bprog%
! 5680: /* compute a\pow 2 + \dots + b\pow 2 */
! 5681: \obr
! 5682: \q /* define the dummy variable "i" */
! 5683: \q entree *ep = gp\_variable("i");
! 5684: \q /* sum for a <= i <= b */
! 5685: \q return somme(ep, a, b, "i\pow2", gzero);
! 5686: \cbr
! 5687: \eprog
! 5688:
! 5689: \subsecidx{sumalt}$(X=a,\var{expr},\{\fl=0\})$: numerical summation of the
! 5690: series \var{expr}, which should be an \idx{alternating series}, the formal
! 5691: variable $X$ starting at $a$.
! 5692:
! 5693: If $\fl=0$, use an algorithm of F.~Villegas as modified by D.~Zagier. This
! 5694: is much better than \idx{Euler}-Van Wijngaarden's method which was used
! 5695: formerly.
! 5696: Beware that the stopping criterion is that the term gets small enough, hence
! 5697: terms which are equal to 0 will create problems and should be removed.
! 5698:
! 5699: If $\fl=1$, use a variant with slightly different polynomials. Sometimes
! 5700: faster.
! 5701:
! 5702: Divergent alternating series can sometimes be summed by this method, as well
! 5703: as series which are not exactly alternating (see for example
! 5704: \secref{se:user_defined}).
! 5705:
! 5706: \misctitle{Important hint:} a significant speed gain can be obtained by
! 5707: writing the $(-1)^X$ which may occur in the expression as
! 5708: \kbd{(1.~- X\%2*2)}.
! 5709:
! 5710: \synt{sumalt}{entree *ep, GEN a, char *expr, long \fl, long prec}.
! 5711:
! 5712: \subsecidx{sumdiv}$(n,X,\var{expr})$: sum of expression \var{expr} over
! 5713: the positive divisors of $n$.
! 5714:
! 5715: In the present version \vers, $n$ is restricted to being less than $2^{31}$.
! 5716:
! 5717: \synt{divsum}{entree *ep, GEN num, char *expr}.
! 5718:
! 5719: \subsecidx{suminf}$(X=a,\var{expr})$: \idx{infinite sum} of expression
! 5720: \var{expr}, the formal parameter $X$ starting at $a$. The evaluation stops
! 5721: when the relative error of the expression is less than the default precision.
! 5722: The expressions must always evaluate to a complex number.
! 5723:
! 5724: \synt{suminf}{entree *ep, GEN a, char *expr, long prec}.
! 5725:
! 5726: \subsecidx{sumpos}$(X=a,\var{expr},\{\fl=0\})$: numerical summation of the
! 5727: series \var{expr}, which must be a series of terms having the same sign,
! 5728: the formal
! 5729: variable $X$ starting at $a$. The algorithm used is Van Wijngaarden's trick
! 5730: for converting such a series into an alternating one, and is quite slow.
! 5731: Beware that the stopping criterion is that the term gets small enough, hence
! 5732: terms which are equal to 0 will create problems and should be removed.
! 5733:
! 5734: If $\fl=1$, use slightly different polynomials. Sometimes faster.
! 5735:
! 5736: \synt{sumpos}{entree *ep, GEN a, char *expr, long \fl, long prec}.
! 5737:
! 5738: \subsecidx{vector}$(n,\{X\},\{\var{expr}=0\})$: creates a row vector (type
! 5739: \typ{VEC}) with $n$ components whose components are the expression
! 5740: \var{expr} evaluated at the integer points between 1 and $n$. If one of the
! 5741: last two arguments is omitted, fill the vector with zeroes.
! 5742:
! 5743: \synt{vecteur}{GEN nmax, entree *ep, char *expr}.
! 5744:
! 5745: \subsecidx{vectorv}$(n,X,\var{expr})$: as \teb{vector}, but returns a
! 5746: column vector (type \typ{COL}).
! 5747:
! 5748: \synt{vvecteur}{GEN nmax, entree *ep, char *expr}.
! 5749:
! 5750: \section{Plotting functions}
! 5751:
! 5752: Although plotting is not even a side purpose of PARI, a number of plotting
! 5753: functions are provided. Moreover, a lot of people felt like suggesting
! 5754: ideas or submitting huge patches for this section of the code. Among these,
! 5755: special thanks go to Klaus-Peter Nischke who suggested the recursive plotting
! 5756: and the forking/resizing stuff under X11, and Ilya Zakharevich who
! 5757: undertook a complete rewrite of the graphic code, so that most of it is now
! 5758: platform-independent and should be relatively easy to port or expand.
! 5759:
! 5760: These graphic functions are either
! 5761:
! 5762: $\bullet$ high-level plotting functions (all the functions starting with
! 5763: \kbd{ploth}) in which the user has little to do but explain what type of plot
! 5764: he wants, and whose syntax is similar to the one used in the preceding
! 5765: section (with somewhat more complicated flags).
! 5766:
! 5767: $\bullet$ low-level plotting functions, where every drawing primitive (point,
! 5768: line, box, etc.) must be specified by the user. These low-level functions
! 5769: (called {\it rectplot} functions, sharing the prefix \kbd{plot}) work as
! 5770: follows. You have at your disposal 16 virtual windows which are filled
! 5771: independently, and can then be physically ORed on a single window at
! 5772: user-defined positions. These windows are numbered from 0 to 15, and must be
! 5773: initialized before being used by the function \kbd{plotinit}, which specifies
! 5774: the height and width of the virtual window (called a {\it rectwindow} in the
! 5775: sequel). At all times, a virtual cursor (initialized at $[0,0]$) is
! 5776: associated to the window, and its current value can be obtained using the
! 5777: function \kbd{plotcursor}.
! 5778:
! 5779: A number of primitive graphic objects (called {\it rect} objects) can then
! 5780: be drawn in these windows, using a default color associated to that window
! 5781: (which can be changed under X11, using the \kbd{plotcolor} function, black
! 5782: otherwise) and only the part of the object which is inside the window will be
! 5783: drawn, with the exception of polygons and strings which are drawn entirely
! 5784: (but the virtual cursor can move outside of the window). The ones sharing the
! 5785: prefix \kbd{plotr} draw relatively to the current position of the virtual
! 5786: cursor, the others use absolute coordinates. Those having the prefix
! 5787: \kbd{plotrecth} put in the rectwindow a large batch of rect objects
! 5788: corresponding to the output of the related \kbd{ploth} function.
! 5789:
! 5790: Finally, the actual physical drawing is done using the function
! 5791: \kbd{plotdraw}. Note that the windows are preserved so that further drawings
! 5792: using the same windows at different positions or different windows can be
! 5793: done without extra work. If you want to erase a window (and free the
! 5794: corresponding memory), use the function \kbd{plotkill}. It is not possible to
! 5795: partially erase a window. Erase it completely, initialize it again and then
! 5796: fill it with the graphic objects that you want to keep.
! 5797:
! 5798: In addition to initializing the window, you may want to have a scaled
! 5799: window to avoid unnecessary conversions. For this, use the function
! 5800: \kbd{plotscale} below. As long as this function is not called, the scaling is
! 5801: simply the number of pixels, the origin being at the upper left and the
! 5802: $y$-coordinates going downwards.
! 5803:
! 5804: Note that in the present version \vers{} all these plotting functions
! 5805: (both low and high level) have been written for the X11-window system (hence
! 5806: also for GUI's based on X11 such as Openwindows and Motif), and for
! 5807: Sunview/Suntools only, though very little code remains which is actually
! 5808: platform-dependent. A Macintosh, and an Atari/Gem port were provided for
! 5809: previous versions. These {\it may} be adapted in future releases.
! 5810:
! 5811: Under X11/Suntools, the physical window (opened by \kbd{plotdraw} or any
! 5812: of the \kbd{ploth*} functions) is completely separated from GP (technically,
! 5813: a \kbd{fork} is done, and the non-graphical memory is immediately freed in
! 5814: the child process), which means you can go on working in the current GP
! 5815: session, without having to kill the window first. Under X11, this window can
! 5816: be closed, enlarged or reduced using the standard window manager functions.
! 5817: No zooming procedure is implemented though (yet).
! 5818:
! 5819: $\bullet$ Finally, note that in the same way that \kbd{printtex} allows you
! 5820: to have a \TeX{} output corresponding to printed results, the functions
! 5821: starting with \kbd{ps} allow you to have \tet{PostScript} output of the
! 5822: plots. This will not be absolutely identical with the screen output, but will
! 5823: be sufficiently close. Note that you can use PostScript output even if you do
! 5824: not have the plotting routines enabled. The PostScript output is written in a
! 5825: file whose name is derived from the \tet{psfile} default (\kbd{./pari.ps} if
! 5826: you did not tamper with it). Each time a new PostScript output is asked for,
! 5827: the PostScript output is appended to that file. Hence the user must remove
! 5828: this file, or change the value of \kbd{psfile}, first if he does not want
! 5829: unnecessary drawings from preceding sessions to appear. On the other hand, in
! 5830: this manner as many plots as desired can be kept in a single file. \smallskip
! 5831:
! 5832: {\it None of the graphic functions are available within the PARI library, you
! 5833: must be under GP to use them}. The reason for that is that you really should
! 5834: not use PARI for heavy-duty graphical work, there are much better specialized
! 5835: alternatives around. This whole set of routines was only meant as a
! 5836: convenient, but simple-minded, visual aid. If you really insist on using
! 5837: these in your program (we warned you), the source (\kbd{plot*.c}) should be
! 5838: readable enough for you to achieve something.
! 5839:
! 5840: \subsecidx{plot}$(X=a,b,\var{expr})$: crude (ASCII) plot of the function
! 5841: represented by expression \var{expr} from $a$ to $b$.
! 5842:
! 5843: \subsecidx{plotbox}$(w,x2,y2)$: let $(x1,y1)$ be the current position of the
! 5844: virtual cursor. Draw in the rectwindow $w$ the outline of the rectangle which
! 5845: is such that the points $(x1,y1)$ and $(x2,y2)$ are opposite corners. Only
! 5846: the part of the rectangle which is in $w$ is drawn. The virtual cursor does
! 5847: {\it not\/} move.
! 5848:
! 5849: \subsecidx{plotclip}$(w)$: `clips' the content of rectwindow $w$, i.e
! 5850: remove all parts of the drawing that would not be visible on the screen.
! 5851: Together with \tet{plotcopy} this function enables you to draw on a
! 5852: scratchpad before commiting the part you're interested in to the final
! 5853: picture.
! 5854:
! 5855: \subsecidx{plotcolor}$(w,c)$: set default color to $c$ in rectwindow $w$.
! 5856: In present version \vers, this is only implemented for X11 window system,
! 5857: and you only have the following palette to choose from:
! 5858:
! 5859: 1=black, 2=blue, 3=sienna, 4=red, 5=cornsilk, 6=grey, 7=gainsborough.
! 5860:
! 5861: Note that it should be fairly easy for you to hardwire some more colors by
! 5862: tweaking the files \kbd{rect.h} and \kbd{plotX.c}. User-defined
! 5863: colormaps would be nice, and {\it may\/} be available in future versions.
! 5864:
! 5865: \subsecidx{plotcopy}$(w1,w2,dx,dy)$: copy the contents of rectwindow
! 5866: $w1$ to rectwindow $w2$, with offset $(dx,dy)$.
! 5867:
! 5868: \subsecidx{plotcursor}$(w)$: give as a 2-component vector the current
! 5869: (scaled) position of the virtual cursor corresponding to the rectwindow $w$.
! 5870:
! 5871: \subsecidx{plotdraw}$(list)$: physically draw the rectwindows given in $list$
! 5872: which must be a vector whose number of components is divisible by 3. If
! 5873: $list=[w1,x1,y1,w2,x2,y2,\dots]$, the windows $w1$, $w2$, etc.~are
! 5874: physically placed with their upper left corner at physical position
! 5875: $(x1,y1)$, $(x2,y2)$,\dots\ respectively, and are then drawn together.
! 5876: Overlapping regions will thus be drawn twice, and the windows are considered
! 5877: transparent. Then display the whole drawing in a special window on your
! 5878: screen.
! 5879:
! 5880: \subsecidx{plotfile}$(s)$: set the output file for plotting output. Special
! 5881: filename \kbd{-} redirects to the same place as PARI output.
! 5882:
! 5883: \subsecidx{ploth}$(X=a,b,\var{expr},\{\fl=0\},\{n=0\})$: high precision
! 5884: plot of the function $y=f(x)$ represented by the expression \var{expr}, $x$
! 5885: going from $a$ to $b$. This opens a specific window (which is killed
! 5886: whenever you click on it), and returns a four-component vector giving the
! 5887: coordinates of the bounding box in the form
! 5888: $[\var{xmin},\var{xmax},\var{ymin},\var{ymax}]$.
! 5889:
! 5890: \misctitle{Important note}: Since this may involve a lot of function calls,
! 5891: it is advised to keep the current precision to a minimum (e.g.~9) before
! 5892: calling this function.
! 5893:
! 5894: $n$ specifies the number of reference point on the graph (0 means use the
! 5895: hardwired default values, that is: 1000 for general plot, 1500 for
! 5896: parametric plot, and 15 for recursive plot).
! 5897:
! 5898: If no $\fl$ is given, \var{expr} is either a scalar expression $f(X)$, in which
! 5899: case the plane curve $y=f(X)$ will be drawn, or a vector
! 5900: $[f_1(X),\dots,f_k(X)]$, and then all the curves $y=f_i(X)$ will be drawn in
! 5901: the same window.
! 5902:
! 5903: \noindent The binary digits of $\fl$ mean:
! 5904:
! 5905: $\bullet$ 1: {\it \idx{parametric plot}}. Here \var{expr} must be a vector with
! 5906: an even number of components. Successive pairs are then understood as the
! 5907: parametric coordinates of a plane curve. Each of these are then drawn.
! 5908:
! 5909: For instance:
! 5910:
! 5911: \kbd{ploth(X=0,2*Pi,[sin(X),cos(X)],1)} will draw a circle.
! 5912:
! 5913: \kbd{ploth(X=0,2*Pi,[sin(X),cos(X)])} will draw two entwined sinusoidal
! 5914: curves.
! 5915:
! 5916: \kbd{ploth(X=0,2*Pi,[X,X,sin(X),cos(X)],1)} will draw a circle and the line
! 5917: $y=x$.
! 5918:
! 5919:
! 5920: $\bullet$ 2: {\it \idx{recursive plot}}. If this flag is set, only {\it
! 5921: one\/} curve can be drawn at time, i.e.~\var{expr} must be either a
! 5922: two-component vector (for a single parametric curve, and the parametric flag
! 5923: {\it has\/} to be set), or a scalar function. The idea is to choose pairs of
! 5924: successive reference points, and if their middle point is not too far away
! 5925: from the segment joining them, draw this as a local approximation to the
! 5926: curve. Otherwise, add the middle point to the reference points. This is very
! 5927: fast, and usually more precise than usual plot. Compare the results of
! 5928: $$\kbd{ploth(X=-1,1,sin(1/X),2)}\quad
! 5929: \text{and}\quad\kbd{ploth(X=-1,1,sin(1/X))}$$
! 5930: for instance. But beware that if you are extremely unlucky, or choose too few
! 5931: reference points, you may draw some nice polygon bearing little resemblance
! 5932: to the original curve. For instance you should {\it never\/} plot recursively
! 5933: an odd function in a symmetric interval around 0. Try
! 5934: \bprog%
! 5935: ploth(x = -20, 20, sin(x), 2)
! 5936: \eprog
! 5937: \noindent to see why. Hence, it's usually a good idea to try and plot the same
! 5938: curve with slightly different parameters.
! 5939:
! 5940: $\bullet$ 8: do not print the $x$-axis.
! 5941:
! 5942: $\bullet$ 16: do not print the $y$-axis.
! 5943:
! 5944: $\bullet$ 32: do not print frame.
! 5945:
! 5946: $\bullet$ 64: only plot reference points, do not join them.
! 5947:
! 5948: \subsecidx{plothraw}$(\var{listx},\var{listy},\{\fl=0\})$: given
! 5949: \var{listx} and \var{listy} two vectors of equal length, plots (in high
! 5950: precision) the points whose $(x,y)$-coordinates are given in \var{listx}
! 5951: and \var{listy}. Automatic positioning and scaling is done, but with the
! 5952: same scaling factor on $x$ and $y$. If $\fl$ is non-zero, join points.
! 5953:
! 5954: \subsecidx{plothsizes}$()$: return data corresponding to the output window
! 5955: in the form of a 6-component vector: window width and height, sizes for ticks
! 5956: in horizontal and vertical directions (this is intended for the \kbd{gnuplot}
! 5957: interface and is currently not significant), width and height of characters.
! 5958:
! 5959: \subsecidx{plotinit}$(w,x,y)$: initialize the rectwindow $w$ to width $x$ and
! 5960: height $y$, and position the virtual cursor at $(0,0)$. This destroys any rect
! 5961: objects you may have already drawn in $w$.
! 5962:
! 5963: The plotting device imposes an upper bound for $x$ and $y$, for instance the
! 5964: number of pixels for screen output. These bounds are available through the
! 5965: \tet{plothsizes} function. The following sequence initializes in a portable way
! 5966: (i.e independant of the output device) a window of maximal size, accessed through
! 5967: coordinates in the $[0,1000] \times [0,1000]$ range~:
! 5968:
! 5969: \bprog%
! 5970: s = plothsizes();
! 5971: plotinit(0, s[1]-1, s[2]-1);
! 5972: plotscale(0, 0,1000, 0,1000);
! 5973: \eprog
! 5974:
! 5975: \subsecidx{plotkill}$(w)$: erase rectwindow $w$ and free the corresponding
! 5976: memory. Note that if you want to use the rectwindow $w$ again, you have to
! 5977: use \kbd{initrect} first to specify the new size. So it's better in this case
! 5978: to use \kbd{initrect} directly as this throws away any previous work in the
! 5979: given rectwindow.
! 5980:
! 5981: \subsecidx{plotlines}$(w,X,Y,\{\fl=0\})$: draw on the rectwindow $w$
! 5982: the polygon such that the (x,y)-coordinates of the vertices are in the
! 5983: vectors of equal length $X$ and $Y$. For simplicity, the whole
! 5984: polygon is drawn, not only the part of the polygon which is inside the
! 5985: rectwindow. If $\fl$ is non-zero, close the polygon. In any case, the
! 5986: virtual cursor does not move.
! 5987:
! 5988: $X$ and $Y$ are allowed to be scalars (in this case, both have to).
! 5989: There, a single segment will be drawn, between the virtual cursor current
! 5990: position and the point $(X,Y)$. And only the part thereof which
! 5991: actually lies within the boundary of $w$. Then {\it move} the virtual cursor
! 5992: to $(X,Y)$, even if it is outside the window. If you want to draw a
! 5993: line from $(x1,y1)$ to $(x2,y2)$ where $(x1,y1)$ is not necessarily the
! 5994: position of the virtual cursor, use \kbd{plotmove(w,x1,y1)} before using this
! 5995: function.
! 5996:
! 5997: \subsecidx{plotlinetype}$(w,\var{type})$: this is intended for the
! 5998: \kbd{gnuplot} interface and is currently not significant.
! 5999:
! 6000: \subsecidx{plotmove}$(w,x,y)$: move the virtual cursor of the rectwindow $w$
! 6001: to position $(x,y)$.
! 6002:
! 6003: \subsecidx{plotpoints}$(w,X,Y)$: draw on the rectwindow $w$ the
! 6004: points whose $(x,y)$-coordinates are in the vectors of equal length $X$ and
! 6005: $Y$ and which are inside $w$. The virtual cursor does {\it not\/} move. This
! 6006: is basically the same function as \kbd{plothraw}, but either with no scaling
! 6007: factor or with a scale chosen using the function \kbd{plotscale}.
! 6008:
! 6009: As was the case with the \kbd{plotlines} function, $X$ and $Y$ are allowed to
! 6010: be (simultaneously) scalar. In this case, draw the single point $(X,Y)$ on
! 6011: the rectwindow $w$ (if it is actually inside $w$), and in any case
! 6012: {\it move\/} the virtual cursor to position $(x,y)$.
! 6013:
! 6014: \subsecidx{plotpointsize}$(w,size)$: changes the ``size'' of following
! 6015: points in rectwindow $w$. If $w = -1$, change it in all rectwindows.
! 6016: This only works in the \kbd{gnuplot} interface.
! 6017:
! 6018: \subsecidx{plotpointtype}$(w,\var{type})$: this is intended for the
! 6019: \kbd{gnuplot} interface and is currently not significant.
! 6020:
! 6021: \subsecidx{plotrbox}$(w,dx,dy)$: draw in the rectwindow $w$ the outline of
! 6022: the rectangle which is such that the points $(x1,y1)$ and $(x1+dx,y1+dy)$ are
! 6023: opposite corners, where $(x1,y1)$ is the current position of the cursor.
! 6024: Only the part of the rectangle which is in $w$ is drawn. The virtual cursor
! 6025: does {\it not\/} move.
! 6026:
! 6027: \subsecidx{plotrecth}$(w,X=a,b,\var{expr},\{\fl=0\},\{n=0\})$: writes to
! 6028: rectwindow $w$ the curve output of \kbd{ploth}$(w,X=a,b,\var{expr},\fl,n)$.
! 6029:
! 6030: \subsecidx{plotrecthraw}$(w,\var{data},\{\fl=0\})$: plot graph(s) for
! 6031: \var{data} in rectwindow $w$. $\fl$ has the same significance here as in
! 6032: \kbd{ploth}, though recursive plot is no more significant.
! 6033:
! 6034: \var{data} is a vector of vectors, each corresponding to a list a coordinates.
! 6035: If parametric plot is set, there must be an even number of vectors, each
! 6036: successive pair corresponding to a curve. Otherwise, the first one containe
! 6037: the $x$ coordinates, and the other ones contain the $y$-coordinates
! 6038: of curves to plot.
! 6039:
! 6040: \subsecidx{plotrline}$(w,dx,dy)$: draw in the rectwindow $w$ the part of the
! 6041: segment $(x1,y1)-(x1+dx,y1+dy)$ which is inside $w$, where $(x1,y1)$ is the
! 6042: current position of the virtual cursor, and move the virtual cursor to
! 6043: $(x1+dx,y1+dy)$ (even if it is outside the window).
! 6044:
! 6045: \subsecidx{plotrmove}$(w,dx,dy)$: move the virtual cursor of the rectwindow
! 6046: $w$ to position $(x1+dx,y1+dy)$, where $(x1,y1)$ is the initial position of
! 6047: the cursor (i.e.~to position $(dx,dy)$ relative to the initial cursor).
! 6048:
! 6049: \subsecidx{plotrpoint}$(w,dx,dy)$: draw the point $(x1+dx,y1+dy)$ on the
! 6050: rectwindow $w$ (if it is inside $w$), where $(x1,y1)$ is the current position
! 6051: of the cursor, and in any case move the virtual cursor to position
! 6052: $(x1+dx,y1+dy)$.
! 6053:
! 6054: \subsecidx{plotscale}$(w,x1,x2,y1,y2)$: scale the local coordinates of the
! 6055: rectwindow $w$ so that $x$ goes from $x1$ to $x2$ and $y$ goes from $y1$ to
! 6056: $y2$ ($x2<x1$ and $y2<y1$ being allowed). Initially, after the initialization
! 6057: of the rectwindow $w$ using the function \kbd{plotinit}, the default scaling
! 6058: is the graphic pixel count, and in particular the $y$ axis is oriented
! 6059: downwards since the origin is at the upper left. The function \kbd{plotscale}
! 6060: allows to change all these defaults and should be used whenever functions are
! 6061: graphed.
! 6062:
! 6063: \subsecidx{plotstring}$(w,x)$: draw on the rectwindow $w$ the String $x$ (see
! 6064: Section 2.4), at the current position of the cursor.
! 6065:
! 6066: \subsecidx{plotterm}$(\var{type})$: this is intended for the \kbd{gnuplot}
! 6067: interface and is currently not significant.
! 6068:
! 6069: \subsecidx{psdraw}$(\var{list})$: same as \kbd{plotdraw}, except that the
! 6070: output is a PostScript program appended to the \kbd{psfile}.
! 6071:
! 6072: \subsecidx{psploth}$(X=a,b,\var{expr})$: same as \kbd{ploth}, except that the
! 6073: output is a PostScript program appended to the \kbd{psfile}.
! 6074:
! 6075: \subsecidx{psplothraw}$(\var{listx},\var{listy})$: same as \kbd{plothraw},
! 6076: except that the output is a PostScript program appended to the \kbd{psfile}.
! 6077:
! 6078: \section{Programming under GP}
! 6079: \sidx{programming}\label{se:programming}
! 6080: \subsecidx{Control statements}.
! 6081:
! 6082: A number of control statements are available under GP. They are simpler and
! 6083: have a syntax slightly different from their C counterparts, but are quite
! 6084: powerful enough to write any kind of program. Some of them are specific to
! 6085: GP, since they are made for number theorists. As usual, $X$ will denote any
! 6086: simple variable name, and \var{seq} will always denote a sequence of
! 6087: expressions, including the empty sequence.
! 6088:
! 6089: \subsubsecidx{break}$(\{n=1\})$: interrupts execution of current \var{seq}, and
! 6090: immediately exits from the $n$ innermost enclosing loops, within the
! 6091: current function call (or the top level loop). $n$ must be bigger than 1.
! 6092: If $n$ is greater than the number of enclosing loops, all enclosing loops
! 6093: are exited.
! 6094:
! 6095: \subsubsecidx{for}$(X=a,b,\var{seq})$: the formal variable $X$ going from
! 6096: $a$ to $b$, the \var{seq} is evaluated. Nothing is done if $a>b$.
! 6097: $a$ and $b$ must be in $\R$.
! 6098:
! 6099: \subsubsecidx{fordiv}$(n,X,\var{seq})$: the formal variable $X$ ranging
! 6100: through the positive divisors of $n$, the sequence \var{seq} is evaluated.
! 6101: $n$ must be of type integer.
! 6102:
! 6103: \subsubsecidx{forprime}$(X=a,b,\var{seq})$: the formal variable $X$
! 6104: ranging over the prime numbers between $a$ to $b$ (including $a$ and $b$
! 6105: if they are prime), the \var{seq} is evaluated. Nothing is done if $a>b$.
! 6106: Note that $a$ and $b$ must be in $\R$.
! 6107:
! 6108: \subsubsecidx{forstep}$(X=a,b,s,\var{seq})$: the formal variable $X$
! 6109: going from $a$ to $b$, in increments of $s$, the \var{seq} is evaluated.
! 6110: Nothing is done if $s>0$ and $a>b$ or if $s<0$ and $a<b$. $s$ must be in
! 6111: $\R^*$ or a vector of steps $[s_1,\dots,s_n]$. In the latter case, the
! 6112: successive steps are used in the order they appear in $s$.
! 6113:
! 6114: \bprog%
! 6115: ? forstep(x=5, 20, [2,4], print(x))
! 6116: 5
! 6117: 7
! 6118: 11
! 6119: 13
! 6120: 17
! 6121: 19
! 6122: \eprog
! 6123:
! 6124: \subsubsecidx{forsubgroup}$(H=G,\{B\},\var{seq})$: executes \var{seq} for
! 6125: each subgroup $H$ of the {\it abelian} group $G$ (given in
! 6126: SNF\sidx{Smith normal form} form or as a vector of elementary divisors),
! 6127: whose index is bounded by bound. The subgroups are not ordered in any
! 6128: obvious way, unless $G$ is a $p$-group in which case Birkhoff's algorithm
! 6129: produces them by decreasing index. A \idx{subgroup} is given as a matrix
! 6130: whose columns give its generators on the implicit generators of $G$. For
! 6131: example, the following prints all subgroups of index less than 2 in $G =
! 6132: \Z/2\Z g_1 \times \Z/2\Z g_2$~:
! 6133:
! 6134: \bprog%
! 6135: ? G = [2,2]; forsubgroup(H=G, 2, print(H))
! 6136: [1; 1]
! 6137: [1; 2]
! 6138: [2; 1]
! 6139: [1, 0; 1, 1]
! 6140: \eprog
! 6141: The last one, for instance is generated by $(g_1, g_1 + g_2)$. This
! 6142: routine is intended to treat huge groups, when \teb{subgrouplist} is not an
! 6143: option due to the sheer size of the output.
! 6144:
! 6145: For maximal speed the subgroups have been left as produced by the algorithm.
! 6146: To print them in canonical form (as left divisors of $G$ in
! 6147: HNF\sidx{Hermite normal form} form), one can for instance use
! 6148: \bprog%
! 6149: ? G = matdiagonal([2,2]); forsubgroup(H=G, 2, print(mathnf(concat(G,H))))
! 6150: [2, 1; 0, 1]
! 6151: [1, 0; 0, 2]
! 6152: [2, 0; 0, 1]
! 6153: [1, 0; 0, 1]
! 6154: \eprog
! 6155: Note that in this last representation, the index $[G:H]$ is given by the
! 6156: determinant.
! 6157:
! 6158: \subsubsecidx{forvec}$(X=v,\var{seq},\{\fl=0\})$: $v$ being an $n$-component
! 6159: vector (where $n$ is arbitrary) of two-component vectors $[a_i,b_i]$
! 6160: for $1\le i\le n$, the \var{seq} is evaluated with the formal variable
! 6161: $X[1]$ going from $a_1$ to $b_1$,\dots,$X[n]$ going from $a_n$ to $b_n$.
! 6162: The formal variable with the highest index moves the fastest. If $\fl=1$,
! 6163: generate only nondecreasing vectors $X$, and if $\fl=2$, generate only
! 6164: strictly increasing vectors $X$.
! 6165:
! 6166: \subsubsecidx{if}$(a,\{\var{seq1}\},\{\var{seq2}\})$: if $a$ is non-zero,
! 6167: the expression sequence \var{seq1} is evaluated, otherwise the expression
! 6168: \var{seq2} is evaluated. Of course, \var{seq1} or \var{seq2} may be empty,
! 6169: so \kbd{if ($a$,\var{seq})} evaluates \var{seq} if $a$ is not equal to zero
! 6170: (you don't have to write the second comma), and does nothing otherwise,
! 6171: whereas \kbd{if ($a$,,\var{seq})} evaluates \var{seq} if $a$ is equal to
! 6172: zero, and does nothing otherwise. You could get the same result using
! 6173: the \kbd{!} (\kbd{not}) operator: \kbd{if (!$a$,\var{seq})}.
! 6174:
! 6175: Note that the boolean operators \kbd{\&\&} and \kbd{||} are evaluated
! 6176: according to operator precedence as explained in \secref{se:operators}, but
! 6177: that, contrary to other operators, the evaluation of the arguments is
! 6178: stopped as soon as the final truth value has been determined. For instance
! 6179: \bprog%
! 6180: if (reallydoit \&\& longcomplicatedfunction(), $\dots$)%
! 6181: \eprog
! 6182: \noindent is a perfectly safe statement.
! 6183:
! 6184: Recall that functions such as \kbd{break} and \kbd{next} operate on
! 6185: {\it loops\/} (such as \kbd{for$xxx$}, \kbd{while}, \kbd{until}). The \kbd{if}
! 6186: statement is {\it not\/} a loop (obviously!).
! 6187:
! 6188: \subsubsecidx{next}$(\{n=1\})$: interrupts execution of current $seq$,
! 6189: resume the next iteration of the innermost enclosing loop, within the
! 6190: current fonction call (or top level loop). If $n$ is specified, resume at
! 6191: the $n$-th enclosing loop. If $n$ is bigger than the number of enclosing
! 6192: loops, all enclosing loops are exited.
! 6193:
! 6194: \subsubsecidx{return}$(\{x=0\})$: returns from current subroutine, with
! 6195: result $x$.
! 6196:
! 6197: \subsubsecidx{until}$(a,\var{seq})$: evaluates expression sequence \var{seq}
! 6198: until $a$ is not equal to 0 (i.e.~until $a$ is true). If $a$ is initially
! 6199: not equal to 0, \var{seq} is evaluated once (more generally, the condition
! 6200: on $a$ is tested {\it after\/} execution of the \var{seq}, not before as in
! 6201: \kbd{while}).
! 6202:
! 6203: \subsubsecidx{while}$(a,\var{seq})$: while $a$ is non-zero evaluate the
! 6204: expression sequence \var{seq}. The test is made {\it before\/} evaluating
! 6205: the $seq$, hence in particular if $a$ is initially equal to zero the
! 6206: \var{seq} will not be evaluated at all.\smallskip
! 6207:
! 6208: \subsec{Specific functions used in GP programming}.
! 6209: \label{se:gp_program}
! 6210:
! 6211: In addition to the general PARI functions, it is necessary to have some
! 6212: functions which will be of use specifically for GP, though a few of these can
! 6213: be accessed under library mode. Before we start describing these, we recall
! 6214: the difference between {\it strings\/} and {\it keywords\/} (see
! 6215: \secref{se:strings}): the latter don't get expanded at all, and you can type
! 6216: them without any enclosing quotes. The former are dynamic objects, where
! 6217: everything outside quotes gets immediately expanded.
! 6218:
! 6219: We need an additional notation for this chapter. An argument between braces,
! 6220: followed by a star, like $\{\var{str}\}*$, means that any number of such
! 6221: arguments (possibly none) can be given.
! 6222:
! 6223: \subsubsecidx{addhelp}$(S,\var{str})$:\label{se:addhelp} changes the help
! 6224: message for the symbol $S$. The string \var{str} is expanded on the spot
! 6225: and stored as the online help for $S$. If $S$ is a function {\it you\/} have
! 6226: defined, its definition will still be printed before the message \var{str}.
! 6227: It is recommended that you document global variables and user functions in
! 6228: this way. Of course GP won't protest if you don't do it.
! 6229:
! 6230: There's nothing to prevent you from modifying the help of built-in PARI
! 6231: functions (but if you do, we'd like to hear why you needed to do it!).
! 6232:
! 6233: \subsubsecidx{alias}$(\var{newkey},\var{key})$: defines the keyword
! 6234: \var{newkey} as an alias for keyword \var{key}. \var{key} must correspond
! 6235: to an existing {\it function\/} name.
! 6236: This is different from the general user macros in that alias expansion takes
! 6237: place immediately upon execution, without having to look up any function
! 6238: code, and is thus much faster. A sample alias file \kbd{misc/gpalias} is
! 6239: provided with the standard distribution. Alias commands are meant to be read
! 6240: upon startup from the \kbd{.gprc} file, to cope with function names you are
! 6241: dissatisfied with, and should be useless in interactive usage.
! 6242:
! 6243: \subsubsecidx{allocatemem}$(\{x=0\})$: this is a very special operation which
! 6244: allows the user to change the stack size {\it after\/} initialization. $x$
! 6245: must be a non-negative integer. If $x!=0$, a new stack of size $16*\lceil
! 6246: x/16\rceil$ bytes will be allocated, all the PARI data on the old stack will
! 6247: be moved to the new one, and the old stack will be discarded. If $x=0$, the
! 6248: size of the new stack will be twice the size of the old one.
! 6249:
! 6250: Although it is a function, this must be the {\it last\/} instruction in any GP
! 6251: sequence. The technical reason is that this routine usually moves the stack,
! 6252: so objects from the current sequence might not be correct anymore. Hence, to
! 6253: prevent such problems, this routine terminates by a \kbd{longjmp} (just as an
! 6254: error would) and not by a return.
! 6255:
! 6256: \syn{allocatemoremem}{x}, where $x$ is an unsigned long, and the return type
! 6257: is void. GP uses a variant which ends by a \kbd{longjmp}.
! 6258:
! 6259: \subsubsecidx{default}$(\{\var{key}\},\{\var{val}\},\{\fl\})$: sets the default
! 6260: corresponding to keyword \var{key} to value \var{val}. \var{val} is a string
! 6261: (which of course accepts numeric arguments without adverse effects, due to the
! 6262: expansion mechanism). See \secref{se:defaults} for a list of available
! 6263: defaults, and \secref{se:meta} for some shortcut alternatives.
! 6264: \label{se:default}
! 6265:
! 6266: If \var{val} is omitted, prints the current value of default \var{key}.
! 6267: If \var{key} is omitted, prints the current values of all the defaults.
! 6268: If $\fl$ is set, returns the result instead of printing it.
! 6269:
! 6270: \subsubsecidx{error}$(\{\var{str}\}*)$: outputs its argument list (each of them
! 6271: interpreted as a string), then interrupts the running GP program, returning to
! 6272: the input prompt.
! 6273:
! 6274: Example: \kbd{error("n = ", n, " is not squarefree !")}.
! 6275:
! 6276: Note that, due to the automatic concatenation of strings, you could in fact
! 6277: use only one argument, just by suppressing the commas.
! 6278:
! 6279: \subsubsecidxunix{extern}$(\var{str})$: the string \var{str} is the name
! 6280: of an external command (i.e.~one you would type from your UNIX shell prompt).
! 6281: This command is immediately run and its input fed into GP, just as if read
! 6282: from a file.
! 6283:
! 6284: \subsubsecidx{getheap}$()$: returns a two-component row vector giving the
! 6285: number of objects on the heap and the amount of memory they occupy in long
! 6286: words. Useful mainly for debugging purposes.
! 6287:
! 6288: \syn{getheap}{}.
! 6289:
! 6290: \subsubsecidx{getrand}$()$: returns the current value of the random number
! 6291: seed. Useful mainly for debugging purposes.
! 6292:
! 6293: \syn{getrand}{}, returns a C long.
! 6294:
! 6295: \subsubsecidx{getstack}$()$: returns the current value of
! 6296: \kbd{top${}-{}$avma},
! 6297: i.e.~the number of bytes used up to now on the stack. Should be equal to 0
! 6298: in between commands. Useful mainly for debugging purposes.
! 6299:
! 6300: \syn{getstack}{}, returns a C long.
! 6301:
! 6302: \subsubsecidx{gettime}$()$: returns the time (in milliseconds) elapsed since
! 6303: either the last call to \kbd{gettime}, or to the beginning of the containing
! 6304: GP instruction (if inside GP), whichever came last.
! 6305:
! 6306: \syn{gettime}{}, returns a C long.
! 6307:
! 6308: \subsubsecidx{global}$(\{\hbox{\it list of variables}\})$: \label{se:global}
! 6309: declares the corresponding variables to be global. From now on, you will be
! 6310: forbidden to use them as formal parameters for function definitions or as
! 6311: loop indexes. This is especially useful when patching together various
! 6312: scripts, possibly written with different naming conventions. For instance the
! 6313: following situation is dangerous:
! 6314: %
! 6315: \bprog%
! 6316: p = 3 \bs\bs~fix characteristic
! 6317: ...
! 6318: forprime(p = 2, N, ...)
! 6319: f(p) = ...
! 6320: \eprog
! 6321: since within the loop or within the function's body, the true global value of
! 6322: \kbd{p} will be hidden. If the statement \kbd{global(p = 3)} appears at the
! 6323: beginning of the script, then both expressions will trigger syntax errors.
! 6324:
! 6325: Calling \kbd{global} without arguments prints the list of global variables in
! 6326: use. In particular, \kbd{eval(global)} will output the values of all local
! 6327: variables.
! 6328:
! 6329: \subsubsecidx{input}$()$: reads a string, interpreted as a GP expression,
! 6330: from the input file, usually standard input (i.e.~the keyboard). If a
! 6331: sequence of expressions is given, the result is the result of the last
! 6332: expression of the sequence. When using this instruction, it is useful to
! 6333: prompt for the string by using the \kbd{print1} function. Note that in the
! 6334: present version 2.19 of \kbd{pari.el}, when using GP under GNU Emacs (see
! 6335: \secref{se:emacs}) one {\it must\/} prompt for the string, with a string
! 6336: which ends with the same prompt as any of the previous ones (a \kbd{"? "}
! 6337: will do for instance).
! 6338:
! 6339: \subsubsecidxunix{install}$(\var{name},\var{code},\{\var{gpname}\},\{\var{lib}\})$:
! 6340: loads from dynamic library \var{lib} the function \var{name}. Assigns to it
! 6341: the name \var{gpname} in this GP session, with argument code \var{code} (see
! 6342: \secref{se:gp.interface} for an explanation of those). If \var{lib} is
! 6343: omitted, uses \kbd{libpari.so}. If \var{gpname} is omitted, uses
! 6344: \var{name}.\label{se:install}
! 6345:
! 6346: This function is useful for adding custom functions to the GP interpreter.
! 6347: But it also gives you access to all (non static) functions defined in the
! 6348: PARI library. For instance, the function \kbd{GEN addii(GEN x, GEN y)} adds
! 6349: two PARI integers, and is not directly accessible under GP (it's eventually
! 6350: called by the \kbd{+} operator of course):
! 6351:
! 6352: \bprog%
! 6353: ? install("addii", "GG")
! 6354: ? addii(1, 2)
! 6355: \%1 = 3%
! 6356: \eprog
! 6357:
! 6358: \misctitle{Caution:} This function may not work on all systems, especially
! 6359: when GP has been compiled statically. In that case, the first use of an
! 6360: installed function will provoke a Segmentation Fault, i.e.~a major internal
! 6361: blunder (this should never happen with a dynamically linked executable). This
! 6362: {\it used\/} to be the fate of statically linked gp on \kbd{Linux} and
! 6363: \kbd{OSF1} up to and including version 2.0.3.
! 6364:
! 6365: Hence, if you intend to use this function, please check first on some
! 6366: harmless example such as the one above that it works properly on your
! 6367: machine.
! 6368:
! 6369: \subsubsecidx{kill}$(x)$:\label{se:kill} kills the present value of the
! 6370: variable, alias or user-defined function $x$ (you can only kill your own
! 6371: functions). The corresponding identifier can now be used to name any GP
! 6372: object (variable or function). This is the only way to replace a variable by
! 6373: a function having the same name (or the other way round), as in the following
! 6374: example:
! 6375:
! 6376: \bprog%
! 6377: ? f = 1
! 6378: \%1 = 1
! 6379: ? f(x) = 0
! 6380: \ \ ***\ \ \ unused characters:~f(x)=0
! 6381: \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \pow----
! 6382: ? kill(f)
! 6383: ? f(x) = 0
! 6384: ? f()
! 6385: \%2 = 0%
! 6386: \eprog
! 6387:
! 6388: When you kill a variable, all objects that used it become invalid. You
! 6389: can still display them, even though the killed variable will be printed in a
! 6390: funny way (following the same convention as used by the library function
! 6391: \kbd{fetch\_var}, see~\secref{se:vars}). For example:
! 6392:
! 6393: \bprog%
! 6394: ? a\pow 2 + 1
! 6395: \%1 = a\pow2 + 1
! 6396: ? kill(a)
! 6397: ? \%1
! 6398: \%2 = \#<1>\pow2 + 1%
! 6399: \eprog
! 6400:
! 6401: If you simply want to restore a variable to its original value (monomial of
! 6402: degree one), use the \idx{quote} operator: \kbd{x = 'x}.
! 6403:
! 6404: \subsubsecidx{print}$(\{\var{str}\}*)$: outputs its (string) arguments in raw
! 6405: format, ending with a newline.
! 6406:
! 6407: \subsubsecidx{print1}$(\{\var{str}\}*)$: outputs its (string) arguments in raw
! 6408: format, without ending with a newline (note that you can still embed newlines
! 6409: within your strings, using the \b{n} notation~!).
! 6410:
! 6411: \subsubsecidx{printp}$(\{\var{str}\}*)$: outputs its (string) arguments in
! 6412: prettyprint (beautified) format, ending with a newline.
! 6413:
! 6414: \subsubsecidx{printp1}$(\{\var{str}\}*)$: outputs its (string) arguments in
! 6415: prettyprint (beautified) format, without ending with a newline.
! 6416:
! 6417: \subsubsecidx{printtex}$(\{\var{str}\}*)$: outputs its (string) arguments in
! 6418: \TeX{} format. This output can then be used in a \TeX{} manuscript.
! 6419: The printing is done on the standard output. If you want to print it to a
! 6420: file you should use \kbd{writetex} (see there).
! 6421:
! 6422: Another possibility is to enable the \tet{log} default
! 6423: (see~\secref{se:defaults}).
! 6424: You could for instance do:\sidx{logfile}
! 6425: %
! 6426: \bprog%
! 6427: default(logfile, "new.tex");
! 6428: default(log, 1);
! 6429: printtex(result);%
! 6430: \eprog
! 6431: \noindent
! 6432: (You can use the automatic string expansion/concatenation process to have
! 6433: dynamic file names if you wish).
! 6434:
! 6435: \subsubsecidx{quit}$()$: exits GP.\label{se:quit}
! 6436:
! 6437: \subsubsecidx{read}$(\{\var{str}\})$: reads in the file whose name results
! 6438: from the expansion of the string \var{str}. If \var{str} is omitted,
! 6439: re-reads the last file that was fed into GP. The return value is the result of
! 6440: the last expression evaluated.\label{se:read}
! 6441:
! 6442: \subsubsecidx{reorder}$(\{x=[\,]\})$: $x$ must be a vector. If $x$ is the
! 6443: empty vector, this gives the vector whose components are the existing
! 6444: variables in increasing order (i.e.~in decreasing importance). Killed
! 6445: variables (see \kbd{kill}) will be shown as \kbd{0}. If $x$ is
! 6446: non-empty, it must be a permutation of variable names, and this permutation
! 6447: gives a new order of importance of the variables, {\it for output only}. For
! 6448: example, if the existing order is \kbd{[x,y,z]}, then after
! 6449: \kbd{reorder([z,x])} the order of importance of the variables, with respect
! 6450: to output, will be \kbd{[z,y,x]}. The internal representation is unaffected.
! 6451: \label{se:reorder}
! 6452:
! 6453: \subsubsecidx{setrand}$(n)$: reseeds the random number generator to the value
! 6454: $n$. The initial seed is $n=1$.
! 6455:
! 6456: \syn{setrand}{n}, where $n$ is a \kbd{long}. Returns $n$.
! 6457:
! 6458: \subsubsecidxunix{system}$(\var{str})$: \var{str} is a string representing
! 6459: a system command. This command is executed, its output written to the
! 6460: standard output (this won't get into your logfile), and control returns
! 6461: to the PARI system. This simply calls the C \kbd{system} command.
! 6462:
! 6463: \subsubsecidx{type}$(x,\{t\})$: this is useful only under GP. If $t$ is
! 6464: not present, returns the internal type number of the PARI object $x$.
! 6465: Otherwise, makes a copy of $x$ and sets its type equal to type $t$, which
! 6466: can be either a number or, preferably since internal codes may eventually
! 6467: change, a symbolic name such as \typ{FRACN} (you can skip the \typ{}
! 6468: part here, so that \kbd{FRACN} by itself would also be all right). Check out
! 6469: existing type names with the metacommand \b{t}.\label{se:gptype}
! 6470:
! 6471: Type changes must be used with extreme caution, or disasters may
! 6472: occur (\kbd{SIGSEGV} or \kbd{SIGBUS} being one's best bet), but one instance
! 6473: where it can be useful is \kbd{type(x,RFRACN)} when \kbd{x} is a rational
! 6474: function (type \typ{RFRAC}). In this case, the created object, as well as
! 6475: the objects created from it, will not be reduced automatically, making the
! 6476: operations much faster. In fact this function is the {\it only\/} way to create
! 6477: reducible rationals (type \typ{FRACN}) or rational functions (type
! 6478: \typ{RFRACN}) in GP.
! 6479:
! 6480: There is no equivalent library syntax, since the internal functions \kbd{typ}
! 6481: and \kbd{settyp} are available. Note that \kbd{settyp} does {\it not\/} create
! 6482: a copy of \kbd{x}, contrary to most PARI functions. It just changes the type in
! 6483: place (and returns nothing). \kbd{typ} returns a C long integer. Note also
! 6484: the different spellings of the internal functions (\kbd{set})\kbd{typ} and of
! 6485: the GP function \kbd{type}\footnote{*}{This is due to the fact that
! 6486: \kbd{type} is a reserved identifier for some C compilers.}.
! 6487:
! 6488: \subsubsecidx{whatnow}$(\var{key})$: if keyword \var{key} is the name
! 6489: of a function that was present in GP version 1.39.15 or lower, outputs
! 6490: the new function name and syntax, if it changed at all ($387$ out of $560$
! 6491: did).\label{se:whatnow}
! 6492:
! 6493: \subsubsecidx{write}$(\var{filename},\{\var{str}*\})$: writes (appends)
! 6494: to \var{filename} the remaining arguments, and appends a newline (same output
! 6495: as \kbd{print}).\label{se:write}
! 6496:
! 6497: \subsubsecidx{write1}$(\var{filename},\{\var{str}*\})$: writes (appends) to
! 6498: \var{filename} the remaining arguments without a trailing newline
! 6499: (same output as \kbd{print1}).
! 6500:
! 6501: \subsubsecidx{writetex}$(\var{filename},\{\var{str}*\})$: as \kbd{write},
! 6502: in \TeX\ format.\label{se:writetex}
! 6503:
! 6504: \vfill\eject
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to usersch3.tex CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM_contrib / pari / doc