=================================================================== RCS file: /home/cvs/OpenXM_contrib/pari-2.2/doc/Attic/usersch3.tex,v retrieving revision 1.1 retrieving revision 1.2 diff -u -p -r1.1 -r1.2 --- OpenXM_contrib/pari-2.2/doc/Attic/usersch3.tex 2001/10/02 11:16:58 1.1 +++ OpenXM_contrib/pari-2.2/doc/Attic/usersch3.tex 2002/09/11 07:26:42 1.2 @@ -1,4 +1,4 @@ -% $Id: usersch3.tex,v 1.1 2001/10/02 11:16:58 noro Exp $ +% $Id: usersch3.tex,v 1.2 2002/09/11 07:26:42 noro Exp $ % Copyright (c) 2000 The PARI Group % % This file is part of the PARI/GP documentation @@ -39,7 +39,7 @@ $$\hbox{% }$$ typing in \kbd{foo(6,4)} would give you \kbd{foo(6,4,3)}. In the rare case when you want to set some far away -flag, and leave the defaults in between as they stand, you can use the +argument, and leave the defaults in between as they stand, you can use the ``empty arg'' trick alluded to above: \kbd{foo(6,,1)} would yield \kbd{foo(6,2,1)}. By the way, \kbd{foo()} by itself yields \kbd{foo(1,2,3)} as was to be expected. In this rather special case of a @@ -50,16 +50,56 @@ to put optional arguments at the end of the argument l they would not make sense otherwise), and in order of decreasing usefulness so that, most of the time, you will be able to ignore them. -\misctitle{Binary Flags}.\sidx{binary flag} For some of these optional -flags, we adopted the customary binary notation as a compact way to -represent many toggles with just one number. Letting $(p_0,\dots,p_n)$ be a -list of switches (i.e.~of properties which can be assumed to take either -the value $0$ or~$1$), the number $2^3 + 2^5=40$ means that $p_3$ and $p_5$ +\misctitle{Flags}. A \tev{flag} is an argument which, rather than conveying +actual information to the routine, intructs it to change its default +behaviour, e.g.~return more or less information. All such +flags are optional, and will be called \fl\ in the function descriptions to +follow. There are two different kind of flags + +$\bullet$ generic: all valid values for the flag are individually +described (``If \fl\ is equal to $1$, then\dots''). + +$\bullet$ binary:\sidx{binary flag} use customary binary notation as a +compact way to represent many toggles with just one number. Letting +$(p_0,\dots,p_n)$ be a list of switches (i.e.~of properties which take either +the value $0$ or~$1$), the number $2^3 + 2^5 = 40$ means that $p_3$ and $p_5$ have been set (that is, set to $1$), and none of the others were (that is, -they were set to 0). This will usually be announced as ``The binary digits -of $\fl$ mean 1: $p_0$, 2: $p_1$, 4: $p_2$'', and so on, using the -available consecutive powers of~$2$. +they were set to $0$). This is announced as ``The binary digits of $\fl$ mean +1: $p_0$, 2: $p_1$, 4: $p_2$'', and so on, using the available consecutive +powers of~$2$. +\misctitle{Mnemonics for flags}. Numeric flags as mentionned above are +obscure, error-prone, and quite rigid: should the authors +want to adopt a new flag numbering scheme (for instance when noticing +flags with the same meaning but different numeric values), it would break +backward compatibility. The only advantage of explicit numeric values is that +they are fast to type, so their use is only advised when using the calculator +GP. + +As an alternative, one can replace a numeric flag by a character string +containing symbolic identifiers. For a generic flag, the mnemonic +corresponding to the numeric identifier is given after it as in (taken from +description of $\tet{log}(x,\{\fl=0\})$): + +\centerline{If \fl\ is equal to $1 = \kbd{AGM}$, use an agm formula\dots} + +\noindent which means that one can use indifferently \kbd{log($x$, 1)} or +\kbd{log($x$, AGM)}. + +For a binary flag, mnemonics corresponding to the various toggles are given +after each of them. They can be negated by prepending \kbd{no\_} to the +mnemonic, or by removing such a prefix. These toggles are grouped together +using any punctuation character (such as ',' or ';'). For instance (taken +from description of $\tet{ploth}(X=a,b,\var{expr},\{\fl=0\},\{n=0\})$) + +\centerline{Binary digits of flags mean: $1=\kbd{Parametric}$, +$2=\kbd{Recursive}$, \dots} + +\noindent so that, instead of $1$, one could use the mnemonic +\kbd{"Parametric; no\_Recursive"}, or simply \kbd{"Parametric"} since +\kbd{Recursive} is unset by default (default value of $\fl$ is $0$, +i.e.~everything unset). + \misctitle{Pointers}.\sidx{pointer} If a parameter in the function prototype is prefixed with a \& sign, as in @@ -71,15 +111,17 @@ to be typed in explicitly. As of version \vers, this \ is optional for all documented functions, hence the \& will always appear between brackets as in \kbd{issquare}$(x,\{\&e\})$. -\misctitle{About library programming}. To finish with our generic -simple-minded example, the \var{library} function \kbd{foo}, as defined -above, is seen to have two mandatory arguments, $x$ and \fl (no PARI -mathematical function has been implemented so as to accept a variable -number of arguments). When not mentioned otherwise, the result and -arguments of a function are assumed implicitly to be of type \kbd{GEN}. -Most other functions return an object of type \kbd{long} integer in C (see -Chapter~4). The variable or parameter names \var{prec} and \fl\ always -denote \kbd{long} integers. +\misctitle{About library programming}. +the \var{library} function \kbd{foo}, as defined +at the beginning of this section, is seen to have two mandatory arguments, +$x$ and \fl: no PARI mathematical function has been implemented so as to +accept a variable number of arguments, so all arguments are mandatory when +programming with the library (often, variants are provided corresponding to +the various flag values). When not mentioned otherwise, the result and +arguments of a function are assumed implicitly to be of type \kbd{GEN}. Most +other functions return an object of type \kbd{long} integer in C (see +Chapter~4). The variable or parameter names \var{prec} and \fl\ always denote +\kbd{long} integers. The \tet{entree} type is used by the library to implement iterators (loops, sums, integrals, etc.) when a formal variable has to successively assume a @@ -137,43 +179,74 @@ integers, add \kbd{O(p\pow k)} to the result; finally, \syn{gdiv}{x,y} for $x$ \kbd{/} $y$. -\subseckbd{\bs}: The expression $x$ \kbd{\bs} $y$ is the -% keep "Euclidean" and "quotient" on same line for gphelp -\idx{Euclidean quotient} of $x$ and $y$. The types must be either both -integer or both polynomials. The result is the Euclidean quotient. In the -case of integer division, the quotient is such that the corresponding -remainder is non-negative. +\subseckbd{\bs}: The expression \kbd{$x$ \bs\ $y$} is the \idx{Euclidean +quotient} of $x$ and $y$. If $y$ is a real scalar, this is defined as +\kbd{floor($x$/$y$)} if $y > 0$, and \kbd{ceil($x$/$y$)} if $y < 0$ and +the division is not exact. Hence the remainder \kbd{$x$ - ($x$\bs$y$)*$y$} +is in $[0, |y|[$. +Note that when $y$ is an integer and $x$ a polynomial, $y$ is first promoted +to a polynomial of degree $0$. When $x$ is a vector or matrix, the operator +is applied componentwise. + \syn{gdivent}{x,y} for $x$ \kbd{\bs} $y$. -\subseckbd{\bs/}: The expression $x$ \b{/} $y$ is the Euclidean -quotient of $x$ and $y$. The types must be either both integer or both -polynomials. The result is the rounded Euclidean quotient. In the case of -integer division, the quotient is such that the corresponding remainder is -smallest in absolute value and in case of a tie the quotient closest to -$+\infty$ is chosen. +\subseckbd{\bs/}: The expression $x$ \b{/} $y$ evaluates to the rounded +\idx{Euclidean quotient} of $x$ and $y$. This is the same as \kbd{$x$ \bs\ $y$} +except for scalar division: the quotient is such that the corresponding +remainder is smallest in absolute value and in case of a tie the quotient +closest to $+\infty$ is chosen (hence the remainder would belong to +$]-|y|/2, |y|/2]$). +When $x$ is a vector or matrix, the operator is applied componentwise. + \syn{gdivround}{x,y} for $x$ \b{/} $y$. -\subseckbd{\%}: The expression $x$ \kbd{\%} $y$ is the -% keep "Euclidean" and "remainder" on same line for gphelp -\idx{Euclidean remainder} of $x$ and $y$. The modulus $y$ must be of type -integer or polynomial. The result is the remainder, always non-negative in -the case of integers. Allowed dividend types are scalar exact types when -the modulus is an integer, and polynomials, polmods and rational functions -when the modulus is a polynomial. +\subseckbd{\%}: The expression \kbd{$x$ \% $y$} evaluates to the modular +\idx{Euclidean remainder} of $x$ and $y$, which we now define. If $y$ is an +integer, this is the smallest non-negative integer congruent to $x$ modulo +$y$. If $y$ is a polynomial, this is the polynomial of smallest degree +congruent to $x$ modulo $y$. When $y$ is a non-integral real number, + \kbd{$x$\%$y$} is defined as \kbd{$x$ - ($x$\bs$y$)*$y$}. This +coincides with the definition for $y$ integer if and only if $x$ is an +integer, but still belongs to $[0, |y|[$. For instance: +\bprog +? (1/2) % 3 +%1 = 2 +? 0.5 % 3 + *** forbidden division t_REAL % t_INT. +? (1/2) % 3.0 +%2 = 1/2 +@eprog +Note that when $y$ is an integer and $x$ a polynomial, $y$ is first promoted +to a polynomial of degree $0$. When $x$ is a vector or matrix, the operator +is applied componentwise. \syn{gmod}{x,y} for $x$ \kbd{\%} $y$. -\subsecidx{divrem}$(x,y)$: creates a column vector with two components, -the first being the Euclidean quotient, the second the Euclidean remainder, -of the division of $x$ by $y$. This avoids the need to do two divisions if -one needs both the quotient and the remainder. The arguments must be both -integers or both polynomials; in the case of integers, the remainder is -non-negative. +\subsecidx{divrem}$(x,y,\{v\})$: creates a column vector with two components, +the first being the Euclidean quotient (\kbd{$x$ \bs\ $y$}), the second the +Euclidean remainder (\kbd{$x$ - ($x$\bs$y$)*$y$}), of the division of $x$ by +$y$. This avoids the need to do two divisions if one needs both the quotient +and the remainder. If $v$ is present, and $x$, $y$ are multivariate +polynomials, divide with respect to the variable $v$. -\syn{gdiventres}{x,y}. +Beware that \kbd{divrem($x$,$y$)[2]} is in general not the same as +\kbd{$x$ \% $y$}; there is no operator to obtain it in GP: +\bprog +? divrem(1/2, 3)[2] +%1 = 1/2 +? (1/2) % 3 +%2 = 2 +? divrem(Mod(2,9), 3)[2] + *** forbidden division t_INTMOD \ t_INT. +? Mod(2,9) % 6 +%3 = Mod(2,3) +@eprog +\syn{divrem}{x,y,v},where $v$ is a \kbd{long}. Also available as +$\teb{gdiventres}(x,y)$ when $v$ is not needed. + \subseckbd{\pow}: The expression $x\hbox{\kbd{\pow}}n$ is \idx{powering}. If the exponent is an integer, then exact operations are performed using binary (left-shift) powering techniques. In particular, in this case $x$ @@ -208,15 +281,18 @@ Beware that \syn{gpow}{x,n,\var{prec}} for $x\hbox{\kbd{\pow}}n$. -\subsecidx{shift}$(x,n)$ or $x$ \kbd{<<} $n$ (= $x$ \kbd{>>} $(-n)$): shifts -$x$ componentwise left by $n$ bits if $n\ge0$ and right by $|n|$ bits if -$n<0$. A left shift by $n$ corresponds to multiplication by $2^n$. A right -shift of an integer $x$ by $|n|$ corresponds to a Euclidean division of -$x$ by $2^{|n|}$ with a -remainder of the same sign as $x$, hence is not the same (in general) as -$x \kbd{\bs} 2^n$. +\subsecidx{shift}$(x,n,\{\fl=0\})$ or $x$ \kbd{<<} $n$ (= $x$ \kbd{>>} $(-n)$): +shifts $x$ componentwise left by $n$ bits if $n\ge0$ and right by $|n|$ bits +if $n<0$. A left shift by $n$ corresponds to multiplication by $2^n$. A right +shift of an integer $x$ by $|n|$ corresponds to a Euclidean division of $x$ +by $2^{|n|}$ with a remainder of the same sign as $x$, hence is not the same +(when $x < 0$) as $x \kbd{\bs} 2^{|n|}$. If $\fl$ is non-zero, this behaviour +is modified and right shift of a negative $x$ \var{is} the same as $x +\kbd{\bs} 2^{|n|}$ (which is consistent with $2$-complement semantic of +negative numbers). -\syn{gshift}{x,n} where $n$ is a \kbd{long}. +\syn{gshift3}{x,n,\fl} where $n$ is a \kbd{long}. Also available is +$\teb{gshift}(x,n)$ for the case $\fl=0$. \subsecidx{shiftmul}$(x,n)$: multiplies $x$ by $2^n$. The difference with \kbd{shift} is that when $n<0$, ordinary division takes place, hence for @@ -266,11 +342,26 @@ Also, \kbd{<>} is accepted as a synonym for \kbd{!=}. assignment statement. \subsecidx{lex}$(x,y)$: gives the result of a lexicographic comparison -between $x$ and $y$. This is to be interpreted in quite a wide sense. For -example, the vector $[1,3]$ will be considered smaller than the longer -vector $[1,3,-1]$ (but of course larger than $[1,2,5]$), -i.e.~\kbd{lex([1,3], [1,3,-1])} will return $-1$. +between $x$ and $y$ (as $-1$, $0$ or $1$). This is to be interpreted in quite +a wide sense: It is admissible to compare objects of different types +(scalars, vectors, matrices), provided the scalars can be compared, as well +as vectors/matrices of different lengths. The comparison is recursive. +In case all components are equal up to the smallest length of the operands, +the more complex is considered to be larger. More precisely, the longest is +the largest; when lengths are equal, we have matrix $>$ vector $>$ scalar. +For example: +\bprog +? lex([1,3], [1,2,5]) +%1 = 1 +? lex([1,3], [1,3,-1]) +%2 = -1 +? lex([1], [[1]]) +%3 = -1 +? lex([1], [1]~) +%4 = 0 +@eprog + \syn{lexcmp}{x,y}. \subsecidx{sign}$(x)$: \idx{sign} ($0$, $1$ or $-1$) of $x$, which must be of @@ -359,9 +450,10 @@ i.e.~it chops off the $O(X^k)$. If $x$ is a vector, th the polynomial whose coefficients are given in $x$, with $x[1]$ being the leading coefficient (which can be zero). -Warning: this is \var{not} a substitution function. It is intended to be -quick and dirty. So if you try \kbd{Pol(a,y)} on the polynomial \kbd{a = x+y}, -you will get \kbd{y+y}, which is not a valid PARI object. +\misctitle{Warning:} this is \var{not} a substitution function. It is +intended to be quick and dirty. So if you try \kbd{Pol(a,y)} on the +polynomial \kbd{a = x+y}, you will get \kbd{y+y}, which is not a valid PARI +object. \syn{gtopoly}{x,v}, where $v$ is a variable number. @@ -479,20 +571,28 @@ Negative numbers behave as if modulo a huge power of $ \syn{gbitnegimply}{x,y}. -\subsecidx{bitor}$(x,y)$: bitwise (inclusive) \tet{or}\sidx{bitwise -inclusive or} of two integers $x$ and $y$, that is the integer +\subsecidx{bitor}$(x,y)$: \sidx{bitwise inclusive or}bitwise (inclusive) +\tet{or} of two integers $x$ and $y$, that is the integer $$\sum (x_i~\kbd{or}~y_i) 2^i$$ Negative numbers behave as if modulo a huge power of $2$. \syn{gbitor}{x,y}. -\subsecidx{bittest}$(x,n)$: outputs the $n^{\text{th}}$ bit of $|x|$ starting -from the right (i.e.~the coefficient of $2^n$ in the binary expansion of $x$). -The result is 0 or 1. To extract several bits at once as a vector, pass a -vector for $n$. +\subsecidx{bittest}$(x,n,\{c=1\})$: extracts $|c|$ bits starting from +number $n$ from the right in the development of $|x|$ (i.e.~the coefficient +of $2^n$ in the binary expansion of $x$), returning the bits as an integer +bitmap. That is, if $x = \sum x_i 2^i$ with the $x_i$ in $\{0,1\}$, this +routine returns the integer +$$ \sum_{0\leq i < |c|} x_{n + i} 2^i $$ +Bits at negative offsets are 0. A negative value of $c$ means that negative +values of $x$ are treated in the spirit of $2$-complement arithmetic (i.e +modulo a big power of $2$). To extract several bits (or groups of bits if +$|c|>1$) separately at once as a vector, pass a vector for $n$. -\syn{bittest}{x,n}, where $n$ and the result are \kbd{long}s. +\syn{gbittest3}{x,n,c}. Also available are $\teb{gbittest}(x,n)$ +(default case $c=1$) and for simple cases $\teb{bittest}(x,n)$, where $n$ +and the result are \kbd{long}s. \subsecidx{bitxor}$(x,y)$: bitwise (exclusive) \tet{or}\sidx{bitwise exclusive or} of two integers $x$ and $y$, that is the integer @@ -633,12 +733,26 @@ the degree of a polynomial is equal to its length minu \subsecidx{lift}$(x,\{v\})$: lifts an element $x=a \bmod n$ of $\Z/n\Z$ to $a$ in $\Z$, and similarly lifts a polmod to a polynomial if $v$ is omitted. -Otherwise, lifts only polmods with main variable $v$ (if $v$ does not occur -in $x$, lifts only intmods). If $x$ is of type fraction, complex, quadratic, -polynomial, power series, rational function, vector or matrix, the lift is -done for each coefficient. For $p$-adics, this routine acts as -\tet{truncate}. It is not allowed to have $x$ of type \typ{REAL}. +Otherwise, lifts only polmods whose modulus has main variable $v$ (if $v$ +does not occur in $x$, lifts only intmods). If $x$ is of recursive (non +modular) type, the lift is done coefficientwise. For $p$-adics, this routine +acts as \tet{truncate}. It is not allowed to have $x$ of type \typ{REAL}. +\bprog +? lift(Mod(5,3)) +%1 = 2 +? lift(3 + O(3^9)) +%2 = 3 +? lift(Mod(x,x^2+1)) +%3 = x +? lift(x * Mod(1,3) + Mod(2,3)) +%4 = x + 2 +? lift(x * Mod(y,y^2+1) + Mod(2,3)) +%5 = y*x + Mod(2, 3) \\@com do you understand this one ? +? lift(x * Mod(y,y^2+1) + Mod(2,3), x) +%6 = Mod(y, y^2+1) * x + Mod(2, y^2+1) +@eprog + \syn{lift0}{x,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded as $-1$. Also available is \teb{lift}$(x)$ = \kbd{lift0($x$,-1)}. @@ -1012,9 +1126,9 @@ small. \subsecidx{besselk}$(\var{nu},x,\{\fl=0\})$: $K$-Bessel function of index \var{nu} (which can be complex) and argument $x$. Only real and positive -arguments -$x$ are allowed in the present version \vers. If $\fl$ is equal to 1, -uses another implementation of this function which is often faster. +arguments $x$ are allowed in the present version \vers. If $\fl$ is equal to +1, uses another implementation of this function which is often faster. In the +present version \vers, this function is not very accurate when $x$ is small. \syn{kbessel}{\var{nu},x,\var{prec}} and $\teb{kbessel2}(\var{nu},x,\var{prec})$ respectively. @@ -1047,7 +1161,7 @@ repeatedly calling \kbd{eint1($i$ * x)}. $\teb{eint1}(x,\var{prec})$. \subsecidx{erfc}$(x)$: complementary error function -$(2/\sqrt\pi)\int_x^\infty e^{-t^2}\,dt$. +$(2/\sqrt\pi)\int_x^\infty e^{-t^2}\,dt$ ($x\in\R$). \syn{erfc}{x,\var{prec}}. @@ -1111,8 +1225,8 @@ $\ln(p)=0$. Hence in particular $\exp(\ln(x))/x$ will equal to 1 but to a $(p-1)$-th root of unity (or $\pm1$ if $p=2$) times a power of $p$. -If $\fl$ is equal to 1, use an agm formula suggested by Mestre, when $x$ is -real, otherwise identical to \kbd{log}. +If $\fl$ is equal to $1 = \kbd{AGM}$, use an agm formula suggested by Mestre, +when $x$ is real, otherwise identical to \kbd{log}. \syn{glog}{x,\var{prec}} or $\teb{glogagm}(x,\var{prec})$. @@ -1370,46 +1484,56 @@ Here $y$ must be an integer, but $x$ can be any PARI o \syn{binome}{x,y}, where $y$ must be a \kbd{long}. -\subsecidx{chinese}$(x,y)$: if $x$ and $y$ are both integermods or both +\subsecidx{chinese}$(x,\{y\})$: if $x$ and $y$ are both integermods or both polmods, creates (with the same type) a $z$ in the same residue class as $x$ and in the same residue class as $y$, if it is possible. This function also allows vector and matrix arguments, in which case the operation is recursively applied to each component of the vector or matrix. -For polynomial arguments, it is applied to each coefficient. Finally -$\kbd{chinese}(x,x) = x$ regardless of the type of $x$; this allows vector -arguments to contain other data, so long as they are identical in both +For polynomial arguments, it is applied to each coefficient. + +If $y$ is omitted, and $x$ is a vector, \kbd{chinese} is applied recursively +to the components of $x$, yielding a residue belonging to the same class as all +components of $x$. + +Finally $\kbd{chinese}(x,x) = x$ regardless of the type of $x$; this allows +vector arguments to contain other data, so long as they are identical in both vectors. \syn{chinois}{x,y}. \subsecidx{content}$(x)$: computes the gcd of all the coefficients of $x$, -when this gcd makes sense. If $x$ is a scalar, this simply returns $x$. If $x$ -is a polynomial (and by extension a power series), it gives the usual content -of $x$. If $x$ is a rational function, it gives the ratio of the contents of -the numerator and the denominator. Finally, if $x$ is a vector or a matrix, -it gives the gcd of all the entries. +when this gcd makes sense. If $x$ is a scalar, this simply returns the +absolute value of $x$ if $x$ is rationnal (\typ{INT}, \typ{FRAC} or +\typ{FRACN}), and $x$ otherwise. If $x$ is a polynomial (and by extension a +power series), it gives the usual content of $x$. If $x$ is a rational +function, it gives the ratio of the contents of the numerator and the +denominator. Finally, if $x$ is a vector or a matrix, it gives the gcd of all +the entries. \syn{content}{x}. -\subsecidx{contfrac}$(x,\{b\},\{lmax\})$: creates the row vector whose +\subsecidx{contfrac}$(x,\{b\},\{nmax\})$: creates the row vector whose components are the partial quotients of the \idx{continued fraction} -expansion of $x$, the number of partial quotients being limited to $lmax$. -If $x$ is a real number, the expansion stops at the last significant partial -quotient if $lmax$ is omitted. $x$ can also be a rational function or a power -series. +expansion of $x$. That is a result $[a_0,\dots,a_n]$ means that +$x \approx a_0+1/(a_1+\dots+1/a_n)\dots)$. The output is normalized so that +$a_n \neq 1$ (unless we also have $n = 0$). +The number of partial quotients $n$ is limited to $nmax$. If $x$ is a real +number, the expansion stops at the last significant partial quotient if $nmax$ +is omitted. $x$ can also be a rational function or a power series. + If a vector $b$ is supplied, the numerators will be equal to the coefficients -of $b$. The length of the result is then equal to the length of $b$, unless a -partial remainder is encountered which is equal to zero. In which case the -expansion stops. In the case of real numbers, the stopping criterion is thus -different from the one mentioned above since, if $b$ is too long, some partial -quotients may not be significant. +of $b$ (instead of all equal to $1$ as above). The length of the result is +then equal to the length of $b$, unless a partial remainder is encountered +which is equal to zero, in which case the expansion stops. In the case of real +numbers, the stopping criterion is thus different from the one mentioned above +since, if $b$ is too long, some partial quotients may not be significant. -If $b$ is an integer, the command is understood as \kbd{contfrac($x,lmax$)}. +If $b$ is an integer, the command is understood as \kbd{contfrac($x,nmax$)}. -\syn{contfrac0}{x,b,lmax}. Also available are -$\teb{gboundcf}(x,lmax)$, $\teb{gcf}(x)$, or $\teb{gcf2}(b,x)$, where $lmax$ +\syn{contfrac0}{x,b,nmax}. Also available are +$\teb{gboundcf}(x,nmax)$, $\teb{gcf}(x)$, or $\teb{gcf2}(b,x)$, where $nmax$ is a C integer. \subsecidx{contfracpnqn}$(x)$: when $x$ is a vector or a one-row matrix, $x$ @@ -1522,12 +1646,58 @@ Also available are $\teb{factor}(x)$ (= $\teb{factor0}(x,-1)$), $\teb{smallfact}(x)$ (= $\teb{factor0}(x,0)$). -\subsecidx{factorback}$(f,\{nf\})$: $f$ being any factorization, gives back -the factored object. If a second argument $\var{nf}$ is supplied, $f$ is -assumed to be a prime ideal factorization in the number field $\var{nf}$. -The resulting ideal is given in HNF\sidx{Hermite normal form} form. +\subsecidx{factorback}$(f,\{e\},\{nf\})$: gives back the factored object +corresponding to a factorization. If the last argument is of number field +type (e.g.~created by \kbd{nfinit} or \kbd{bnfinit}), assume we are dealing +with an ideal factorization in the number field. The resulting ideal product is +given in HNF\sidx{Hermite normal form} form. -\syn{factorback}{f,\var{nf}}, where an omitted +If $e$ is present, $e$ and $f$ must be vectors of the same length ($e$ being +integral), and the corresponding factorization is the product of the +$f[i]^{e[i]}$. + +If not, and $f$ is vector, it is understood as in the preceding case with +$e$ a vector of 1 (the product of the $f[i]$ is returned). Finally, +$f$ can be a regular factorization, as produced with any \kbd{factor} +command. A few examples: +\bprog +? factorback([2,2; 3,1]) +%1 = 12 +? factorback([2,2], [3,1]) +%2 = 12 +? factorback([5,2,3]) +%3 = 30 +? factorback([2,2], [3,1], nfinit(x^3+2)) +%4 = +[16 0 0] + +[0 16 0] + +[0 0 16] +? nf = nfinit(x^2+1); fa = idealfactor(nf, 10) +%5 = +[[2, [1, 1]~, 2, 1, [1, 1]~] 2] + +[[5, [-2, 1]~, 1, 1, [2, 1]~] 1] + +[[5, [2, 1]~, 1, 1, [-2, 1]~] 1] +? factorback(fa) + *** forbidden multiplication t_VEC * t_VEC. +? factorback(fa, nf) +%6 = +[10 0] + +[0 10] + +@eprog +In the fourth example, $2$ and $3$ are interpreted as principal ideals in a +cubic field. In the fifth one, \kbd{factorback(fa)} is meaningless since we +forgot to indicate the number field, and the entries in the first column of +\kbd{fa} can't be multiplied. + +\syn{factorback0}{f,e,\var{nf}}, where an omitted +$\var{nf}$ or $e$ is entered as \kbd{NULL}. Also available is +\tet{factorback}$(f,\var{nf})$ (case $e = \kbd{NULL}$) where an omitted $\var{nf}$ is entered as \kbd{NULL}. \subsecidx{factorcantor}$(x,p)$: factors the polynomial $x$ modulo the @@ -1607,32 +1777,40 @@ $\teb{simplefactmod}(x,p)$ (= $\teb{factormod}(x,p,1)$ \subsecidx{ffinit}$(p,n,\{v=x\})$: computes a monic polynomial of degree $n$ which is irreducible over $\F_p$. For instance if \kbd{P = ffinit(3,2,y)}, you can represent elements in $\F_{3^2}$ as polmods -modulo \kbd{P}. +modulo \kbd{P}. Starting with version 2.2.3 this function use a fast variant +of Adleman--Lenstra algorithm, and is much faster than in earlier versions. \syn{ffinit}{p,n,v}, where $v$ is a variable number. -\subsecidx{gcd}$(x,y,\{\fl=0\})$: creates the greatest common divisor of $x$ +\subsecidx{gcd}$(x,\{y\},\{\fl=0\})$: creates the greatest common divisor of $x$ and $y$. $x$ and $y$ can be of quite general types, for instance both rational numbers. Vector/matrix types are also accepted, in which case the GCD is taken recursively on each component. Note that for these -types, \kbd{gcd} is not commutative. +types, \kbd{gcd} is not commutative. \fl\ is obsolete and should not be used. -If $\fl=0$, use \idx{Euclid}'s algorithm. +If $y$ is omitted and $x$ is a vector, return the $\text{gcd}$ of all +components of $x$. The algorithm used is a naive \idx{Euclid} except for the +following inputs: -If $\fl=1$, use the modular gcd algorithm ($x$ and $y$ have to be -polynomials, with integer coefficients). +$\bullet$ integers: use modified right-shift binary (``plus-minus'' +variant). -If $\fl=2$, use the \idx{subresultant algorithm}. +$\bullet$ univariate polynomials with coeffients in the same number +field (in particular rational): use modular gcd algorithm. -\syn{gcd0}{x,y,\fl}. Also available are -$\teb{ggcd}(x,y)$, $\teb{modulargcd}(x,y)$, and $\teb{srgcd}(x,y)$ -corresponding to $\fl=0$, $1$ and $2$ respectively. +$\bullet$ general polynomials: use the \idx{subresultant algorithm} if +coefficient explosion is likely (exact, non modular, coefficients). +\syn{ggcd}{x,y}. For general polynomial inputs, $\teb{srgcd}(x,y)$ is also +available. For univariate {\it rational} polynomials, one also has +$\teb{modulargcd}(x,y)$. + \subsecidx{hilbert}$(x,y,\{p\})$: \idx{Hilbert symbol} of $x$ and $y$ modulo $p$. If $x$ and $y$ are of type integer or fraction, an explicit third parameter $p$ must be supplied, $p=0$ meaning the place at infinity. Otherwise, $p$ needs not be given, and $x$ and $y$ can be of compatible types -integer, fraction, real, integermod or $p$-adic. +integer, fraction, real, integermod a prime (result is undefined if the +modulus is not prime), or $p$-adic. \syn{hil}{x,y,p}. @@ -1643,38 +1821,56 @@ discriminant of a quadratic field, false (0) otherwise simpler function $\teb{isfundamental}(x)$ which returns a \kbd{long} should be used if $x$ is known to be of type integer. -\subsecidx{isprime}$(x,\{\fl=0\})$: if $\fl=0$ (default), true (1) if $x$ is a strong pseudo-prime -for 10 randomly chosen bases, false (0) otherwise. +\subsecidx{isprime}$(x,\{\fl=0\})$: true (1) if $x$ is a (proven) prime +number, false (0) otherwise. This can be very slow when $x$ is indeed +prime and has more than $1000$ digits, say. Use \tet{ispseudoprime} to +quickly check for pseudo primality. -If $\fl=1$, use Pocklington-Lehmer ``P-1'' test. true (1) if $x$ is -prime, false (0) otherwise. +If $\fl=0$, use a combination of Baillie-PSW pseudo primality test (see +\tet{ispseudoprime}), Selfridge ``$p-1$'' test if $x-1$ is smooth enough, and +Adleman-Pomerance-Rumely-Cohen-Lenstra (APRCL) for general $x$. -If $\fl=2$, use Pocklington-Lehmer ``P-1'' test and output a primality -certificate as follows: return 0 if $x$ is composite, 1 if $x$ is a -small prime (currently strictly less than $341 550 071 728 321$), and -a matrix if $x$ is a large prime. The matrix has three columns. The -first contains the prime factors $p$, the second the corresponding -elements $a_p$ as in Proposition~8.3.1 in GTM~138, and the third the -output of isprime(p,2). +If $\fl=1$, use Selfridge-Pocklington-Lehmer ``$p-1$'' test and output a +primality certificate as follows: return 0 if $x$ is composite, 1 if $x$ is +small enough that passing Baillie-PSW test guarantees its primality +(currently $x < 10^{13}$), $2$ if $x$ is a large prime whose primality could +only sensibly be proven (given the algorithms implemented in PARI) using the +APRCL test. Otherwise ($x$ is large and $x-1$ is smooth) output a three +column matrix as a primality certificate. The first column contains the prime +factors $p$ of $x-1$, the second the corresponding elements $a_p$ as in +Proposition~8.3.1 in GTM~138, and the third the output of isprime(p,1). The +algorithm fails if one of the pseudo-prime factors is not prime, which is +exceedingly unlikely (and well worth a bug report). -In the two last cases, the algorithm fails if one of the (strong -pseudo-)prime factors is not prime, but it should be exceedingly rare. +If $\fl=2$, use APRCL. - \syn{gisprime}{x,\fl}, but the simpler function $\teb{isprime}(x)$ which returns a \kbd{long} should be used if $x$ is known to be of -type integer. Also available is $\teb{plisprime}(N,\fl)$, -corresponding to $\teb{gisprime}(x,\fl+1)$ if $x$ is known to be of type integer. -\subsecidx{ispseudoprime}$(x)$: true (1) if $x$ is a strong -pseudo-prime for a randomly chosen base, false (0) otherwise. +\subsecidx{ispseudoprime}$(x,\{\fl\})$: true (1) if $x$ is a strong pseudo +prime (see below), false (0) otherwise. If this function returns false, $x$ +is not prime; if, on the other hand it returns true, it is only highly likely +that $x$ is a prime number. Use \tet{isprime} (which is of course much +slower) to prove that $x$ is indeed prime. -\syn{gispsp}{x}, but the -simpler function $\teb{ispsp}(x)$ which returns a \kbd{long} -should be used if $x$ is known to be of type integer. +If $\fl = 0$, checks whether $x$ is a Baillie-Pomerance-Selfridge-Wagstaff +pseudo prime (strong Rabin-Miller pseudo prime for base $2$, with +end-matching to catch square roots of $-1$, followed by strong Lucas test for +the sequence $(P,-1)$, $P$ smallest positive integer such that $P^2 - 4$ is +not a square mod $x$). +There are no known composite numbers passing this test, although it is +expected that infinitely such numbers exist. + +If $\fl > 0$, checks whether $x$ is a strong Miller-Rabin pseudo prime (with +end-matching) for $\fl$ randomly chosen bases. + +\syn{gispseudoprime}{x,\fl}, but the simpler function $\teb{ispseudoprime}(x)$ +which returns a \kbd{long} should be used if $x$ is known to be of type +integer. + \subsecidx{issquare}$(x,\{\&n\})$: true (1) if $x$ is square, false (0) if not. $x$ can be of any type. If $n$ is given and an exact square root had to be computed in the checking process, puts that square root in $n$. This is in @@ -1700,9 +1896,12 @@ must be of type integer. \syn{kronecker}{x,y}, the result ($0$ or $\pm 1$) is a \kbd{long}. -\subsecidx{lcm}$(x,y)$: least common multiple of $x$ and $y$, i.e.~such +\subsecidx{lcm}$(x,\{y\})$: least common multiple of $x$ and $y$, i.e.~such that $\text{lcm}(x,y)*\text{gcd}(x,y)=\text{abs}(x*y)$. +If $y$ is omitted and $x$ is a vector, return the $\text{lcm}$ of all +components of $x$. + \syn{glcm}{x,y}. \subsecidx{moebius}$(x)$: \idx{Moebius} $\mu$-function of $|x|$. $x$ must @@ -1717,7 +1916,7 @@ this function returns $x$ and not the smallest prime s \syn{nextprime}{x}. \subsecidx{numdiv}$(x)$: number of divisors of $|x|$. $x$ must be of type -integer, and the result is a \kbd{long}. +integer. \syn{numbdiv}{x}. @@ -1743,29 +1942,66 @@ are the first $x$ prime numbers, which must be among t \syn{primes}{x}. $x$ must be a \kbd{long}. -\subsecidx{qfbclassno}$(x,\{\fl=0\})$: class number of the quadratic field -of discriminant $x$. In the present version \vers, a simple algorithm is used -for $x>0$, so $x$ should not be too large (say $x<10^7$) for the time to be -reasonable. On the other hand, for $x<0$ one can reasonably compute -classno($x$) for $|x|<10^{25}$, since the method used is \idx{Shanks}' method -which is in $O(|x|^{1/4})$. For larger values of $|D|$, see -\kbd{quadclassunit}. +\subsecidx{qfbclassno}$(D,\{\fl=0\})$: ordinary class number of the quadratic +order of discriminant $D$. In the present version \vers, a $O(D^{1/2})$ +algorithm is used for $D > 0$ (using Euler product and the functional +equation) so $D$ should not be too large, say $D < 10^8$, for the time to be +reasonable. On the other hand, for $D < 0$ one can reasonably compute +\kbd{qfbclassno($D$)} for $|D|<10^{25}$, since the routine uses +\idx{Shanks}'method which is in $O(|D|^{1/4})$. For larger values of $|D|$, +see \kbd{quadclassunit}, which unfortunately works reliably only for +fundamental discriminants. If $\fl=1$, compute the class number using \idx{Euler product}s and the -functional equation. However, it is in $O(|x|^{1/2})$. +functional equation. However, it is in $O(|D|^{1/2})$. -\misctitle{Important warning.} For $D<0$, this function often gives +\misctitle{Important warning.} For $D < 0$, this function often gives incorrect results when the class group is non-cyclic, because the authors were too lazy to implement \idx{Shanks}' method completely. It is therefore -strongly recommended to use either the version with $\fl=1$, the function -$\kbd{qfhclassno}(-x)$ if $x$ is known to be a fundamental discriminant, or +strongly recommended to use either the version with $\fl = 1$, the function +$\kbd{qfbhclassno}(-D)$ if $D$ is known to be a fundamental discriminant, or the function \kbd{quadclassunit}. -\syn{qfbclassno0}{x,\fl}. Also available are -$\teb{classno}(x)$ (= $\teb{qfbclassno}(x)$), -$\teb{classno2}(x)$ (= $\teb{qfbclassno}(x,1)$), and finally -there exists the function $\teb{hclassno}(x)$ which computes the class -number of an imaginary quadratic field by counting reduced forms, an $O(|x|)$ +\misctitle{Warning.} contrary to what its name implies, this routine does not +compute the number of classes of binary primitive forms of discriminant $D$, +which is equal to the \var{narrow} class number. The two notions are the same +when $D < 0$ or the fundamental unit $\varepsilon$ has negative norm; when $D +> 0$ and $N\varepsilon > 0$, the number of classes of forms is twice the +ordinary class number. This is a problem which we cannot fix for backward +compatibility reasons. Use the following routine if you are only interested +in the number of classes of form: +\bprog +QFBclassno(D) = + qfbclassno(D) * if (D < 0 || norm(quadunit(D)) < 0, 1, 2) +@eprog +\noindent Here are a few examples, including an erroneous answer: +\bprog +? qfbclassno(400000028) +time = 3,140 ms. +%1 = 1 +? quadclassunit(400000028).no +time = 20 ms. \\@com{ much faster} +%2 = 1 +? qfbclassno(-400000028) +time = 0 ms. +%3 = 7253 \\@com{ correct, and fast enough} +? quadclassunit(-400000028).no + *** Warning: not a fundamental discriminant in quadclassunit. +time = 0 ms. +%4 = 7253 +? qfbclassno(-2878367) +time = 0 ms. +%6 = 1056 \\@com{ This is wrong! Correct answer is $1152$} +(14:40) gp > quadclassunit(-2878367) +time = 10 ms. +%7 = [1152, [48, 24], [Qfb(647, 189, 1126), Qfb(2, 1, 359796)], 1, 1.000250] +@eprog + +\syn{qfbclassno0}{D,\fl}. Also available: +$\teb{classno}(D)$ (= $\teb{qfbclassno}(D)$), +$\teb{classno2}(D)$ (= $\teb{qfbclassno}(D,1)$), and finally +there exists the function $\teb{hclassno}(D)$ which computes the class +number of an imaginary quadratic field by counting reduced forms, an $O(|D|)$ algorithm. See also \kbd{qfbhclassno}. \subsecidx{qfbcompraw}$(x,y)$ \idx{composition} of the binary quadratic forms @@ -1783,7 +2019,8 @@ non-negative and congruent to 0 or 3 modulo 4. See als definite binary quadratic forms $x$ and $y$ using the NUCOMP and NUDUPL algorithms of \idx{Shanks} (\`a la Atkin). $l$ is any positive constant, but for optimal speed, one should take $l=|D|^{1/4}$, where $D$ is the common -discriminant of $x$ and $y$. +discriminant of $x$ and $y$. When $x$ and $y$ do not have the same +discriminant, the result is undefined. \syn{nucomp}{x,y,l}. The auxiliary function $\teb{nudupl}(x,l)$ should be used instead for speed when $x=y$. @@ -2060,7 +2297,7 @@ only available for curves defined over $\Q_p$.\smallsk Some functions, in particular those relative to height computations (see \kbd{ellheight}) require also that the curve be in minimal Weierstrass -form. This is achieved by the function \kbd{ellglobalred}. +form. This is achieved by the function \kbd{ellminimalmodel}. All functions related to elliptic curves share the prefix \kbd{ell}, and the precise curve we are interested in is always the first argument, in either @@ -2082,7 +2319,7 @@ known to hold in full generality thanks to the work of medium or long vector of the type given by \kbd{ellinit}. For this function to work for every $n$ and not just those prime to the conductor, $E$ must be a minimal Weierstrass equation. If this is not the case, use the -function \kbd{ellglobalred} first before using \kbd{ellak}. +function \kbd{ellminimalmodel} first before using \kbd{ellak}. \syn{akell}{E,n}. @@ -2157,14 +2394,10 @@ minimal model of $E$ and the global \idx{Tamagawa numb elliptic curve given by a medium or long vector of the type given by \kbd{ellinit}, {\it and is supposed to have all its coefficients $a_i$ in} $\Q$. The result is a 3 component vector $[N,v,c]$. $N$ is the arithmetic -conductor of the curve, $v$ is itself a vector $[u,r,s,t]$ with rational -components. It gives a coordinate change for $E$ over $\Q$ such that the -resulting model has integral coefficients, is everywhere minimal, $a_1$ is 0 -or 1, $a_2$ is 0, 1 or $-1$ and $a_3$ is 0 or 1. Such a model is unique, and -the vector $v$ is unique if we specify that $u$ is positive. To get the new -model, simply type \kbd{ellchangecurve(E,v)}. Finally $c$ is the product of -the local Tamagawa numbers $c_p$, a quantity which enters in the -\idx{Birch and Swinnerton-Dyer conjecture}. +conductor of the curve. $v$ gives the coordinate change for $E$ over $\Q$ to +the minimal integral model (see \tet{ellminimalmodel}). Finally $c$ is the +product of the local Tamagawa numbers $c_p$, a quantity which enters in the +\idx{Birch and Swinnerton-Dyer conjecture}.\sidx{minimal model} \syn{globalreduction}{E}. @@ -2297,6 +2530,19 @@ $O(N^{1/2})$ algorithm. \syn{lseriesell}{E,s,A,\var{prec}} where $\var{prec}$ is a \kbd{long} and an omitted $A$ is coded as \kbd{NULL}. +\subsecidx{ellminimalmodel}$(E,\{\&v\})$: return the standard minimal +integral model of the rational elliptic curve $E$. If present, sets $v$ to the +corresponding change of variables, which is a vector $[u,r,s,t]$ with +rational components. The return value is identical to that of +\kbd{ellchangecurve(E, v)}. + +The resulting model has integral coefficients, is everywhere minimal, $a_1$ +is 0 or 1, $a_2$ is 0, 1 or $-1$ and $a_3$ is 0 or 1. Such a model is unique, +and the vector $v$ is unique if we specify that $u$ is positive, which we do. +\sidx{minimal model} + +\syn{ellminimalmodel}{E,\&v}, where an omitted $v$ is coded as \kbd{NULL}. + \subsecidx{ellorder}$(E,z)$: gives the order of the point $z$ on the elliptic curve $E$ if it is a torsion point, zero otherwise. In the present version \vers, this is implemented only for elliptic curves defined over $\Q$. @@ -2364,7 +2610,7 @@ $H/\Gamma_0(N)$ where $N$ is the conductor of the curv the power series for $u$ and $v$ is $x$, which is implicitly understood to be equal to $\exp(2i\pi z)$. It is assumed that the curve is a \var{strong} \idx{Weil curve}, and the Manin constant is equal to 1. The equation of -the curve $E$ must be minimal (use \kbd{ellglobalred} to get a minimal +the curve $E$ must be minimal (use \kbd{ellminimalmodel} to get a minimal equation). \syn{taniyama}{E}, and the precision of the result is determined by the @@ -2445,7 +2691,7 @@ associated to the number field: signature, maximal ord $\bullet$ $\tev{bnf}$ denotes a big number field, i.e.~a 10-component vector in the format output by \tet{bnfinit}. This contains $\var{nf}$ and the deeper invariants of the field: units, class groups, as well as a lot of -technical data necessary for some complex fonctions like \kbd{bnfisprincipal}. +technical data necessary for some complex functions like \kbd{bnfisprincipal}. $\bullet$ $\tev{bnr}$ denotes a big ``ray number field'', i.e.~some data structure output by \kbd{bnrinit}, even more complicated than $\var{bnf}$, @@ -2531,10 +2777,10 @@ determinant of a pseudo-matrix is the determinant of a module it generates. Finally, when defining a relative extension, the base field should be -defined by a variable having a lower priority (i.e.~a higher number) -than the variable defining the extension. For example, under GP you can -use the variable name $y$ (or $t$) to define the base field, and the -variable name $x$ to define the relative extension. +defined by a variable having a lower priority (i.e.~a higher number, see +\secref{se:priority}) than the variable defining the extension. For example, +under GP you can use the variable name $y$ (or $t$) to define the base field, +and the variable name $x$ to define the relative extension. Now a last set of definitions concerning the way big ray number fields (or \var{bnr}) are input, using class field theory. @@ -2615,7 +2861,7 @@ fundamental units, $w$ generates the torsion.\cr \+\tet{reg} &(\var{bnr},& \var{bnf},&&)&: & regulator.\cr \+\tet{roots}&(\var{bnr},& \var{bnf},& \var{nf}&)&: & roots of the -polnomial generating the field.\cr +polynomial generating the field.\cr \+\tet{sign} &(\var{bnr},& \var{bnf},& \var{nf}&)&: & $[r_1,r_2]$ the signature of the field. This means that the field has $r_1$ real \cr @@ -2653,7 +2899,7 @@ finding class and unit groups under \idx{GRH}, due to The general call to the functions concerning class groups of general number fields (i.e.~excluding \kbd{quadclassunit}) involves a polynomial $P$ and a technical vector -$$\var{tech} = [c,c2,\var{nrel},\var{borne},\var{nrpid},\var{minsfb}],$$ +$$\var{tech} = [c,c2,\var{nrel},\var{small\_norm},\var{nrpid},\var{minsfb}],$$ where the parameters are to be understood as follows: $P$ is the defining polynomial for the number field, which must be in @@ -2670,25 +2916,23 @@ quadratic case, but then you should use the much faste \kbd{quadclassunit}). Reasonable values for $c$ are between $0.1$ and $2$. (The defaults are $c=c2=0.3$). -$\var{nrel}$ is the number of initial extra relations requested in -computing the -relation matrix. Reasonable values are between 5 and 20. (The default is 5). +$\var{nrel}$ is the number of initial extra relations requested in computing +the relation matrix. Reasonable values are between 5 and 20. (The default is +5). -$\var{borne}$ is a multiplicative coefficient of the Minkowski bound which -controls -the search for small norm relations. If this parameter is set equal to 0, the -program does not search for small norm relations. Otherwise reasonable values -are between $0.5$ and $2.0$. (The default is $1.0$). +$\var{small\_norm}$ is a toggle used to disable the search for small norm +relations. If this parameter is set equal to $0$, the program does not search +for small norm relations (default value is $1$). {\sl This is obsolete and +should not be used. Set $\var{nrpid} = 0$ instead}. $\var{nrpid}$ is the maximal number of small norm relations associated to each -ideal in the factor base. Irrelevant when $\var{borne}=0$. Otherwise, +ideal in the factor base. Irrelevant when $\var{small\_norm}=0$. Otherwise, reasonable values are between 4 and 20. (The default is 4). $\var{minsfb}$ is the minimal number of elements in the ``sub-factorbase''. -If the -program does not seem to succeed in finding a full rank matrix (which you can -see in GP by typing \kbd{\bs g 2}), increase this number. Reasonable values -are between 2 and 5. (The default is 3). +If the program does not seem to succeed in finding a full rank matrix (which +you can see in GP by typing \kbd{\bs g 2}), increase this number. Reasonable +values are between 2 and 5. (The default is 3). \misctitle{Remarks.} @@ -2815,10 +3059,10 @@ Theory}, Graduate Texts in Maths \key{138}, Springer-V $\var{bnf}[1]$ contains the matrix $W$, i.e.~the matrix in Hermite normal form giving relations for the class group on prime ideal generators -$(\p_i)_{1\le i\le r}$. +$(\wp_i)_{1\le i\le r}$. $\var{bnf}[2]$ contains the matrix $B$, i.e.~the matrix containing the -expressions of the prime ideal factorbase in terms of the $\p_i$. It is an +expressions of the prime ideal factorbase in terms of the $\wp_i$. It is an $r\times c$ matrix. $\var{bnf}[3]$ contains the complex logarithmic embeddings of the system of @@ -2831,18 +3075,15 @@ relations of the matrix $(W|B)$. $\var{bnf}[5]$ contains the prime factor base, i.e.~the list of prime ideals used in finding the relations. -$\var{bnf}[6]$ contains the permutation of the prime factor base which was -necessary to reduce the relation matrix to the form explained in subsection -6.5.5 of GTM~138 (i.e.~with a big $c\times c$ identity matrix on the lower -right). Note that in the above mentioned book, the need to permute the rows -of the relation matrices which occur was not emphasized. +$\var{bnf}[6]$ used to contain a permutation of the prime factor base, but +has been obsoleted. It contains a dummy $0$. $\var{bnf}[9]$ is a 3-element row vector used in \tet{bnfisprincipal} only and obtained as follows. Let $D = U W V$ obtained by applying the \idx{Smith normal form} algorithm to the matrix $W$ (= $\var{bnf}[1]$) and let $U_r$ be the reduction of $U$ modulo $D$. The first elements of the factorbase are given (in terms of \kbd{bnf.gen}) by the columns of $U_r$, -with archimedian component $g_a$; let also $GD_a$ be the archimedian +with Archimedean component $g_a$; let also $GD_a$ be the Archimedean components of the generators of the (principal) ideals defined by the \kbd{bnf.gen[i]\pow bnf.cyc[i]}. Then $\var{bnf}[9]=[U_r, g_a, GD_a]$. @@ -2947,14 +3188,12 @@ simple true/false answer: it gives a row vector $[v_1, $v_1$ is the vector of components $c_i$ of the class of the ideal $x$ in the class group, expressed on the generators $g_i$ given by \kbd{bnfinit} -(specifically \kbd{\var{bnf}.clgp.gen} which is the same as -\kbd{\var{bnf}[8][1][3]}). The $c_i$ are chosen so that $0\le c_i 7$, $k$ is the numbering of the group among all +transitive subgroups of $S_n$, as given in ``The transitive groups of degree up +to eleven'', G.~Butler and J.~McKay, Communications in Algebra, vol.~11, 1983, +pp.~863--911 (group $k$ is denoted $T_k$ there). And for $n \leq 7$, it was ad +hoc, so as to ensure that a given triple would design a unique group. +Specifically, for polynomials of degree $\leq 7$, the groups are coded as +follows, using standard notations \smallskip -In degree 1: $S_1=[1,-1,1]$. +In degree 1: $S_1=[1,1,1]$. \smallskip In degree 2: $S_2=[2,-1,1]$. \smallskip @@ -4393,14 +4667,44 @@ In degree 7: $C_7=[7,1,1]$, $D_7=[14,-1,1]$, $M_{21}=[ $M_{42}=[42,-1,1]$, $PSL_2(7)=PSL_3(2)=[168,1,1]$, $A_7=[2520,1,1]$, $S_7=[5040,-1,1]$. \smallskip -The method used is that of resolvent polynomials and is sensitive to the -current precision. The precision is updated internally but, in very rare -cases, a wrong result may be returned if the initial precision was not -sufficient. +This is deprecated and obsolete, but for reasons of backward compatibility, +we cannot change this behaviour yet. So you can use the default +\tet{newgaloisformat} to switch to a consistent naming scheme, namely $k$ is +always the standard numbering of the group among all transitive subgroups of +$S_n$. If this default is in effect, the above groups will be coded as: +\smallskip +In degree 1: $S_1=[1,1,1]$. +\smallskip +In degree 2: $S_2=[2,-1,1]$. +\smallskip +In degree 3: $A_3=C_3=[3,1,1]$, $S_3=[6,-1,2]$. +\smallskip +In degree 4: $C_4=[4,-1,1]$, $V_4=[4,1,2]$, $D_4=[8,-1,3]$, $A_4=[12,1,4]$, +$S_4=[24,-1,5]$. +\smallskip +In degree 5: $C_5=[5,1,1]$, $D_5=[10,1,2]$, $M_{20}=[20,-1,3]$, + $A_5=[60,1,4]$, $S_5=[120,-1,5]$. +\smallskip +In degree 6: $C_6=[6,-1,1]$, $S_3=[6,-1,2]$, $D_6=[12,-1,3]$, $A_4=[12,1,4]$, +$G_{18}=[18,-1,5]$, $A_4\times C_2=[24,-1,6]$, $S_4^+=[24,1,7]$, +$S_4^-=[24,-1,8]$, $G_{36}^-=[36,-1,9]$, $G_{36}^+=[36,1,10]$, +$S_4\times C_2=[48,-1,11]$, $A_5=PSL_2(5)=[60,1,12]$, $G_{72}=[72,-1,13]$, +$S_5=PGL_2(5)=[120,-1,14]$, $A_6=[360,1,15]$, $S_6=[720,-1,16]$. +\smallskip +In degree 7: $C_7=[7,1,1]$, $D_7=[14,-1,2]$, $M_{21}=[21,1,3]$, +$M_{42}=[42,-1,4]$, $PSL_2(7)=PSL_3(2)=[168,1,5]$, $A_7=[2520,1,6]$, +$S_7=[5040,-1,7]$. +\smallskip -\syn{galois}{x,\var{prec}}. +\misctitle{Warning} The method used is that of resolvent polynomials and is +sensitive to the current precision. The precision is updated internally but, +in very rare cases, a wrong result may be returned if the initial precision +was not sufficient. -\subsecidx{polred}$(x,\{\fl=0\},\{p\})$: finds polynomials with reasonably +\syn{galois}{x,\var{prec}}. To enable the new format in library mode, set the +global variable \tet{new_galois_format} to $1$. + +\subsecidx{polred}$(x,\{\fl=0\},\{fa\})$: finds polynomials with reasonably small coefficients defining subfields of the number field defined by $x$. One of the polynomials always defines $\Q$ (hence is equal to $x-1$), and another always defines the same number field as $x$ if $x$ is irreducible. @@ -4409,19 +4713,20 @@ polynomials, \kbd{nf}, \kbd{bnf}, \kbd{[x,Z\_K\_basis] The following binary digits of $\fl$ are significant: -1: does a partial reduction only. This means that only a suborder of the -maximal order may be used. +1: possibly use a suborder of the maximal order. The primes dividing the +index of the order chosen are larger than \tet{primelimit} or divide integers +stored in the \tet{addprimes} table. 2: gives also elements. The result is a two-column matrix, the first column giving the elements defining these subfields, the second giving the corresponding minimal polynomials. -If $p$ is given, it is assumed that it is the two-column matrix of the +If $fa$ is given, it is assumed that it is the two-column matrix of the factorization of the discriminant of the polynomial $x$. -\syn{polred0}{x,\fl,p,\var{prec}}, where an omitted $p$ is -coded by $gzero$. Also available are $\teb{polred}(x,\var{prec})$ and -$\teb{factoredpolred}(x,p,\var{prec})$, both corresponding to $\fl=0$. +\syn{polred0}{x,\fl,fa}, where an omitted $fa$ is coded by \kbd{NULL}. Also +available are $\teb{polred}(x)$ and $\teb{factoredpolred}(x,fa)$, both +corresponding to $\fl=0$. \subsecidx{polredabs}$(x,\{\fl=0\})$: finds one of the polynomial defining the same number field as the one defined by $x$, and such that the sum of the @@ -4429,6 +4734,12 @@ squares of the modulus of the roots (i.e.~the $T_2$-no All $x$ accepted by \tet{nfinit} are also allowed here (e.g. non-monic polynomials, \kbd{nf}, \kbd{bnf}, \kbd{[x,Z\_K\_basis]}). +\misctitle{Warning:} this routine uses an exponential-time algorithm to +enumerate all potential generators, and may be exceedingly slow when the +number field has many subfields, hence a lot of elements of small $T_2$-norm. +E.g. do not try it on the compositum of many quadratic fields, use +\tet{polred} instead. + The binary digits of $\fl$ mean 1: outputs a two-component row vector $[P,a]$, where $P$ is the default @@ -4438,8 +4749,13 @@ whose minimal polynomial is equal to $x$. 4: gives \var{all} polynomials of minimal $T_2$ norm (of the two polynomials $P(x)$ and $P(-x)$, only one is given). -\syn{polredabs0}{x,\fl,\var{prec}}. +16: possibly use a suborder of the maximal order. The primes dividing the +index of the order chosen are larger than \tet{primelimit} or divide integers +stored in the \tet{addprimes} table. In that case it may happen that the +output polynomial does not have minimal $T_2$ norm.\label{se:polredabs} +\syn{polredabs0}{x,\fl}. + \subsecidx{polredord}$(x)$: finds polynomials with reasonably small coefficients and of the same degree as that of $x$ defining suborders of the order defined by $x$. One of the polynomials always defines $\Q$ (hence @@ -4496,8 +4812,8 @@ where \var{conductor} is the conductor of the extensio class group corresponding to the conductor given as a 3-component vector [h,cyc,gen] as usual for a group, and \var{subgroup} is a matrix in HNF defining the subgroup of the ray class group on the -given generators gen. If $\fl$ is non-zero, check under GRH that -\var{pol} indeed defines an Abelian extension, return 0 if it does not. +given generators gen. If $\fl$ is non-zero, check that \var{pol} indeed +defines an Abelian extension, return 0 if it does not. \syn{rnfconductor}{\var{rnf},\var{pol},\fl}. @@ -4526,7 +4842,8 @@ the relative discriminant of $L$. This is a two-element row vector $[D,d]$, where $D$ is the relative ideal discriminant and $d$ is the relative discriminant considered as an element of $\var{nf}^*/{\var{nf}^*}^2$. The main variable of -$\var{nf}$ \var{must} be of lower priority than that of \var{pol}. +$\var{nf}$ \var{must} be of lower priority than that of \var{pol}, see +\secref{se:priority}. Note: As usual, $\var{nf}$ can be a $\var{bnf}$ as output by \kbd{nfinit}. @@ -4587,11 +4904,11 @@ $\theta = \beta+k\alpha$ where $\theta$ is a root of $ of $\var{pol}$. The main variable of $\var{nf}$ \var{must} be of lower priority than that -of \var{pol}. Note that for efficiency, this does not check whether the -relative equation is irreducible over $\var{nf}$, but only if it is -squarefree. If it is reducible but squarefree, the result will be the -absolute equation of the \'etale algebra defined by \var{pol}. If \var{pol} -is not squarefree, an error message will be issued. +of \var{pol} (see \secref{se:priority}). Note that for efficiency, this does +not check whether the relative equation is irreducible over $\var{nf}$, but +only if it is squarefree. If it is reducible but squarefree, the result will +be the absolute equation of the \'etale algebra defined by \var{pol}. If +\var{pol} is not squarefree, an error message will be issued. \syn{rnfequation0}{\var{nf},\var{pol},\fl}. @@ -4690,8 +5007,8 @@ the ideal list starts with $x$, all the other ideals b format considered as base field, and \var{pol} a polynomial defining a relative extension over $\var{nf}$, this computes all the necessary data to work in the relative extension. The main variable of \var{pol} must be of higher priority -(i.e.~lower number) than that of $\var{nf}$, and the coefficients of \var{pol} -must be in $\var{nf}$. +(i.e.~lower number, see \secref{se:priority}) than that of $\var{nf}$, and +the coefficients of \var{pol} must be in $\var{nf}$. The result is an 11-component row vector as follows (most of the components are technical), the numbering being very close to that of \kbd{nfinit}. In @@ -4708,13 +5025,13 @@ are the number of real and complex places of $L$ above $K$ so that $r_{j,1}=0$ and $r_{j,2}=n$ if $j$ is a complex place, while if $j$ is a real place we have $r_{j,1}+2r_{j,2}=n$. -$\var{rnf}[3]$ is a two-component row vector $[\d(L/K),s]$ where $\d(L/K)$ -is the relative ideal discriminant of $L/K$ and $s$ is the discriminant of -$L/K$ viewed as an element of $K^*/(K^*)^2$, in other words it is the output -of \kbd{rnfdisc}. +$\var{rnf}[3]$ is a two-component row vector $[\goth{d}(L/K),s]$ where +$\goth{d}(L/K)$ is the relative ideal discriminant of $L/K$ and $s$ is the +discriminant of $L/K$ viewed as an element of $K^*/(K^*)^2$, in other words it is +the output of \kbd{rnfdisc}. -$\var{rnf}[4]$ is the ideal index $\f$, i.e.~such that -$d(pol)\Z_K=\f^2\d(L/K)$. +$\var{rnf}[4]$ is the ideal index $\goth{f}$, i.e.~such that +$d(pol)\Z_K=\goth{f}^2\goth{d}(L/K)$. $\var{rnf}[5]$ is a vector \var{vm} with 7 entries useful for certain computations in the relative extension $L/K$. $\var{vm}[1]$ is a vector of @@ -4786,59 +5103,78 @@ free, false (0) if not. \syn{rnfisfree}{\var{bnf},x}, and the result is a \kbd{long}. -\subsecidx{rnfisnorm}$(\var{bnf},\var{ext},\var{el},\{\fl=1\})$: similar to -\kbd{bnfisnorm} but in the relative case. This tries to decide whether the -element \var{el} in \var{bnf} is the norm of some $y$ in \var{ext}. -$\var{bnf}$ is as output by \kbd{bnfinit}. +\subsecidx{rnfisnorm}$(\var{T},\var{a},\{\fl=0\})$: similar to +\kbd{bnfisnorm} but in the relative case. $T$ is as output by +\tet{rnfisnorminit} applied to the extension $L/K$. This tries to decide +whether the element $a$ in $K$ is the norm of some $x$ in the extension +$L/K$. -$\var{ext}$ is a relative extension which has to be a row vector whose -components are: +The output is a vector $[x,q]$, where $\var{a}=\var{Norm}(x)*q$. The +algorithm looks for a solution $x$ which is an $S$-integer, with $S$ a list +of places of $K$ containing at least the ramified primes, the generators of +the class group of $L$, as well as those primes dividing \var{a}. If $L/K$ is +Galois, then this is enough; otherwise, $\fl$ is used to add more primes to +$S$: all the places above the primes $p \leq \fl$ (resp.~$p|\fl$) if $\fl>0$ +(resp.~$\fl<0$). -$\var{ext}[1]$: a relative equation of the number field \var{ext} over -\var{bnf}. As usual, the priority of the variable of the polynomial -defining the ground field \var{bnf} (say $y$) must be lower than the -main variable of $\var{ext}[1]$, say $x$. +The answer is guaranteed (i.e.~\var{a} is a norm iff $q = 1$) if the field is +Galois, or, under \idx{GRH}, if $S$ contains all primes less than +$12\log^2\left|\text{disc}(\var{M})\right|$, where \var{M} is the normal +closure of $L/K$. -$\var{ext}[2]$: the generator $y$ of the base field as a polynomial in $x$ (as -given by \kbd{rnfequation} with $\fl = 1$). +If \tet{rnfisnorminit} has determined (or was told) that $L/K$ is +\idx{Galois}, and $\fl \neq 0$, a Warning is issued (so that you can set +$\fl = 1$ to check whether $L/K$ is known to be Galois, according to $T$). -$\var{ext}[3]$: is the \kbd{bnfinit} of the absolute extension $\var{ext}/\Q$. +Example: -This returns a vector $[a,b]$, where $\var{el}=\var{Norm}(a)*b$. It looks for a -solution which is an $S$-integer, with $S$ a list of places (of \var{bnf}) -containing the ramified primes, the generators of the class group of -\var{ext}, as well as those primes dividing \var{el}. If $\var{ext}/\var{bnf}$ -is known to be \idx{Galois}, set $\fl=0$ (here \var{el} is a norm iff $b=1$). -If $\fl$ is non zero add to $S$ all the places above the primes which: divide -$\fl$ if $\fl<0$, or are less than $\fl$ if $\fl>0$. The answer is guaranteed -(i.e.~\var{el} is a norm iff $b=1$) under \idx{GRH}, if $S$ contains all -primes less than $12\log^2\left|\text{disc}(\var{Ext})\right|$, where -\var{Ext} is the normal closure of $\var{ext} / \var{bnf}$. Example: - \bprog bnf = bnfinit(y^3 + y^2 - 2*y - 1); p = x^2 + Mod(y^2 + 2*y + 1, bnf.pol); -rnf = rnfequation(bnf,p,1); -ext = [p, rnf[2], bnfinit(rnf[1])]; -rnfisnorm(bnf,ext,17, 1) +T = rnfisnorminit(bnf, p); +rnfisnorm(T, 17) @eprog \noindent checks whether $17$ is a norm in the Galois extension $\Q(\beta) / \Q(\alpha)$, where $\alpha^3 + \alpha^2 - 2\alpha - 1 = 0$ and $\beta^2 + -\alpha^2 + 2*\alpha + 1 = 0$ (it is). +\alpha^2 + 2\alpha + 1 = 0$ (it is). -\syn{rnfisnorm}{\var{bnf},ext,x,\fl,\var{prec}}. +\syn{rnfisnorm}{\var{T},x,\fl}. -\subsecidx{rnfkummer}$(\var{bnr},\var{subgroup},\{deg=0\})$: \var{bnr} +\subsecidx{rnfisnorminit}$(\var{pol},\var{polrel},\{\fl=2\})$: +let $K$ be defined by a root of \var{pol}, and $L/K$ the extension defined by +the polynomial \var{polrel}. As usual, \var{pol} can in fact be an \var{nf}, +or \var{bnf}, etc; if \var{pol} has degree $1$ (the base field is $\Q$), +polrel is also allowed to be an \var{nf}, etc. Computes technical data needed +by \tet{rnfisnorm} to solve norm equations $Nx = a$, for $x$ in $L$, and $a$ +in $K$. + +If $\fl = 0$, do not care whether $L/K$ is Galois or not. + +If $\fl = 1$, $L/K$ is assumed to be Galois (unchecked), which speeds up +\tet{rnfisnorm}. + +If $\fl = 2$, let the routine determine whether $L/K$ is Galois. + +\syn{rnfisnorminit}{\var{pol},\var{polrel},\fl}. + +\subsecidx{rnfkummer}$(\var{bnr},\{\var{subgroup}\},\{deg=0\})$: \var{bnr} being as output by \kbd{bnrinit}, finds a relative equation for the class field corresponding to the module in \var{bnr} and the given -congruence subgroup. If \var{deg} is positive, outputs the list of all -relative equations of degree \var{deg} contained in the ray class field -defined by \var{bnr}. +congruence subgroup (the full ray class field if \var{subgroup} is omitted). +If \var{deg} is positive, outputs the list of all relative equations of +degree \var{deg} contained in the ray class field defined by \var{bnr}, with +the same conductor as $(\var{bnr}, \var{subgroup})$. -(THIS PROGRAM IS STILL IN DEVELOPMENT STAGE) +\misctitle{Warning:} this routine only works for subgroups of prime index. It +uses Kummer theory, adjoining necessary roots of unity (it needs to compute a +tough \kbd{bnfinit} here), and finds a generator via Hecke's characterization +of ramification in Kummer extensions of prime degree. If your extension does +not have prime degree, for the time being, you have to split it by hand as a +tower of such extensions. -\syn{rnfkummer}{\var{bnr},\var{subgroup},\var{deg},\var{prec}}, -where \var{deg} is a \kbd{long}. +\syn{rnfkummer}{\var{bnr},\var{subgroup},\var{deg},\var{prec}}, where +\var{deg} is a \kbd{long} and an omitted \var{subgroup} is coded as +\kbd{NULL} \subsecidx{rnflllgram}$(\var{nf},\var{pol},\var{order})$: given a polynomial \var{pol} with coefficients in \var{nf} defining a relative extension $L$ and @@ -4854,7 +5190,7 @@ class field as output by \kbd{bnrinit} and \var{pol} a defining an \idx{Abelian extension}, computes the norm group (alias Artin or Takagi group) corresponding to the Abelian extension of $\var{bnf}=bnr[1]$ defined by \var{pol}, where the module corresponding to \var{bnr} is assumed -to be a multiple of the conductor (i.e.~polrel defines a subextension of +to be a multiple of the conductor (i.e.~\var{pol} defines a subextension of bnr). The result is the HNF defining the norm group on the given generators of $\var{bnr}[5][3]$. Note that neither the fact that \var{pol} defines an Abelian extension nor the fact that the module is a multiple of the conductor @@ -4866,20 +5202,26 @@ is checked. The result is undefined if the assumption Given a monic polynomial \var{pol} with coefficients in $\var{nf}$, finds a list of relative polynomials defining some subfields, hopefully simpler and containing the original field. In the present version \vers, this is slower -than \kbd{rnfpolredabs}. +and less efficient than \kbd{rnfpolredabs}. \syn{rnfpolred}{\var{nf},\var{pol},\var{prec}}. \subsecidx{rnfpolredabs}$(\var{nf},\var{pol},\{\fl=0\})$: relative version of \kbd{polredabs}. Given a monic polynomial \var{pol} with coefficients in -$\var{nf}$, finds a simpler relative polynomial defining the same field. If -$\fl=1$, returns $[P,a]$ where $P$ is the default output and $a$ is an +$\var{nf}$, finds a simpler relative polynomial defining the same field. The +binary digits of $\fl$ mean + +1: returns $[P,a]$ where $P$ is the default output and $a$ is an element expressed on a root of $P$ whose characteristic polynomial is -\var{pol}, if $\fl=2$, returns an absolute polynomial (same as +\var{pol} +2: returns an absolute polynomial (same as {\tt rnfequation(\var{nf},rnfpolredabs(\var{nf},\var{pol}))} +but faster). -\noindent but faster). +16: possibly use a suborder of the maximal order. This is slower than the +default when the relative discriminant is smooth, and much faster otherwise. +See \secref{se:polredabs}. \misctitle{Remark.} In the present implementation, this is both faster and much more efficient than \kbd{rnfpolred}, the difference being more @@ -4899,8 +5241,6 @@ a four-element row vector $[A,I,D,d]$, where $D$ is th discriminant and $d$ is the relative discriminant considered as an element of $\var{nf}^*/{\var{nf}^*}^2$. -Note: As usual, $\var{nf}$ can be a $\var{bnf}$ as output by \kbd{bnfinit}. - \syn{rnfpseudobasis}{\var{nf},\var{pol}}. \subsecidx{rnfsteinitz}$(\var{nf},x)$: given a number field $\var{nf}$ as @@ -4914,22 +5254,51 @@ as in \kbd{rnfpseudobasis}. The name of this function that the ideal class of the last ideal of $I$ (which is well defined) is called the \idx{Steinitz class} of the module $\Z_L$. -Note: $\var{nf}$ can be a $\var{bnf}$ as output by \kbd{bnfinit}. - \syn{rnfsteinitz}{\var{nf},x}. \subsecidx{subgrouplist}$(\var{bnr},\{\var{bound}\},\{\fl=0\})$: \var{bnr} being as output by \kbd{bnrinit} or a list of cyclic components -of a finite Abelian group $G$, outputs the list of subgroups of $G$ -(of index bounded by \var{bound}, if not omitted). Subgroups are given -as HNF\sidx{Hermite normal form} left divisors of the -SNF\sidx{Smith normal form} matrix corresponding to $G$. If $\fl=0$ -(default) and \var{bnr} is as output by -\kbd{bnrinit}, gives only the subgroups whose modulus is the conductor. +of a finite Abelian group $G$, outputs the list of subgroups of $G$. Subgroups +are given as HNF\sidx{Hermite normal form} left divisors of the +SNF\sidx{Smith normal form} matrix corresponding to $G$. -\syn{subgrouplist0}{\var{bnr},\var{bound},\fl}, where \var{bound} and $\fl$ -are long integers. +\misctitle{Warning:} the present implementation cannot treat a group $G$ +where any cyclic factor has more than $2^{31}$, resp.~$2^{63}$ elements on a +$32$-bit, resp.~$64$-bit architecture. \tet{forsubgroup} is a bit more +general and can handle $G$ if all $p$-Sylow subgroups of $G$ satisfy the +condition above. +If $\fl=0$ (default) and \var{bnr} is as output by $\kbd{bnrinit}(,,1)$, gives +only the subgroups whose modulus is the conductor. Otherwise, the modulus is +not taken into account. + +If \var{bound} is present, and is a positive integer, restrict the output to +subgroups of index less than \var{bound}. If \var{bound} is a vector +containing a single positive integer $B$, then only subgroups of index +exactly equal to $B$ are computed. For instance +\bprog +? subgrouplist([6,2]) +%1 = [[6, 0; 0, 2], [2, 0; 0, 2], [6, 3; 0, 1], [2, 1; 0, 1], [3, 0; 0, 2], + [1, 0; 0, 2], [6, 0; 0, 1], [2, 0; 0, 1], [3, 0; 0, 1], [1, 0; 0, 1]] +? subgrouplist([6,2],3) \\@com index less than 3 +%2 = [[2, 1; 0, 1], [1, 0; 0, 2], [2, 0; 0, 1], [3, 0; 0, 1], [1, 0; 0, 1]] +? subgrouplist([6,2],[3]) \\@com index 3 +%3 = [[3, 0; 0, 1]] +? bnr = bnrinit(bnfinit(x), [120,[1]], 1); +? L = subgrouplist(bnr, [8]); +@eprog\noindent +In the last example, $L$ corresponds to the 24 subfields of +$\Q(\zeta_{120})$, of degree $8$ and conductor $120\infty$ (by setting \fl, +we see there are a total of $43$ subgroups of degree $8$). +\bprog +? vector(#L, i, galoissubcyclo(bnr, L[i])) +@eprog\noindent +will produce their equations. (For a general base field, you would +have to rely on \tet{bnrstark}, or \tet{rnfkummer}.) + +\syn{subgrouplist0}{\var{bnr},\var{bound},\fl}, where $\fl$ +is a long integer, and an omitted \var{bound} is coded by \kbd{NULL}. + \subsecidx{zetak}$(\var{znf},x,\{\fl=0\})$: \var{znf} being a number field initialized by \kbd{zetakinit} (\var{not} by \kbd{nfinit}), computes the value of the \idx{Dedekind} zeta function of the number @@ -5037,7 +5406,9 @@ the same extension of $\Q_p$ as $a$. \subsecidx{polcoeff}$(x,s,\{v\})$: coefficient of degree $s$ of the polynomial $x$, with respect to the main variable if $v$ is omitted, with -respect to $v$ otherwise. +respect to $v$ otherwise. Also applies to power series, scalars (polynomial +of degree $0$), and to rational functions provided the denominator is a +monomial. \syn{polcoeff0}{x,s,v}, where $v$ is a \kbd{long} and an omitted $v$ is coded as $-1$. Also available is \teb{truecoeff}$(x,v)$. @@ -5141,15 +5512,14 @@ GP it is kept in the variable \kbd{realprecision} and user, but it must be explicitly given as a second argument in library mode. The algorithm used is a modification of A.~Sch\"onhage\sidx{Sch\"onage}'s -remarkable root-finding algorithm, due to and implemented by X.~Gourdon. -Barring bugs, it is guaranteed to converge and to give the roots to the -required accuracy. +root-finding algorithm, due to and implemented by X.~Gourdon. Barring bugs, it +is guaranteed to converge and to give the roots to the required accuracy. If $\fl=1$, use a variant of the Newton-Raphson method, which is \var{not} guaranteed to converge, but is rather fast. If you get the messages ``too many iterations in roots'' or ``INTERNAL ERROR: incorrect result in roots'', -use the default function (i.e.~no flag or $\fl=0$). This used to be the -default root-finding function in PARI until version 1.39.06. +use the default algorithm. This used to be the default root-finding function in +PARI until version 1.39.06. \syn{roots}{\var{pol},\var{prec}} or $\teb{rootsold}(\var{pol},\var{prec})$. @@ -5166,7 +5536,8 @@ $\teb{rootmod2}(\var{pol},p)$ ($\fl=1$). \subsecidx{polrootspadic}$(\var{pol},p,r)$: row vector of $p$-adic roots of the polynomial \var{pol} with $p$-adic precision equal to $r$. Multiple roots are -\var{not} repeated. $p$ is assumed to be a prime. +\var{not} repeated. $p$ is assumed to be a prime, and \var{pol} to be +non-zero modulo $p$. \syn{rootpadic}{\var{pol},p,r}, where $r$ is a \kbd{long}. @@ -5178,14 +5549,22 @@ polynomial \var{pol} in the interval $]a,b]$, using St \teb{sturm}\kbd{(\var{pol})} is equivalent to \key{sturmpart}\kbd{(\var{pol},NULL,NULL)}. The result is a \kbd{long}. -\subsecidx{polsubcyclo}$(n,d,\{v=x\})$: gives a polynomial (in variable -$v$) defining the sub-Abelian extension of degree $d$ of the cyclotomic -field $\Q(\zeta_n)$, where $d\mid \phi(n)$. $(\Z/n\Z)^*$ has to be cyclic -(i.e.~$n=2$, $4$, $p^k$ or $2p^k$ for an odd prime $p$). The function -\tet{galoissubcyclo} covers the general case. +\subsecidx{polsubcyclo}$(n,d,\{v=x\})$: gives polynomials (in variable +$v$) defining the sub-Abelian extensions of degree $d$ of the cyclotomic +field $\Q(\zeta_n)$, where $d\mid \phi(n)$. -\syn{subcyclo}{n,d,v}, where $v$ is a variable number. +If there is exactly one such extension the output is a polynomial, else it is +a vector of polynomials, eventually empty. +To be sure to get a vector, you can use \kbd{concat([],polsubcyclo(n,d))} + +The function \tet{galoissubcyclo} allows to specify more closely which sub-Abelian extension should be computed. + +\syn{polsubcyclo}{n,d,v}, where $n$, $d$ and $v$ are \kbd{long} and $v$ is a +variable number. When $(\Z/n\Z)^*$ is cyclic, you can use +\teb{subcyclo}$(n,d,v)$, where $n$, $d$ and $v$ are \kbd{long} and $v$ is a +variable number. + \subsecidx{polsylvestermatrix}$(x,y)$: forms the Sylvester matrix corresponding to the two polynomials $x$ and $y$, where the coefficients of the polynomials are put in the columns of the matrix (which is the natural @@ -5290,7 +5669,7 @@ as \kbd{NULL}. \subsecidx{thueinit}$(P,\{\fl=0\})$: initializes the \var{tnf} corresponding to $P$. It is meant to be used in conjunction with \tet{thue} to solve Thue equations $P(x,y) = a$, where $a$ is an integer. If $\fl$ is -non-zero, certify the result unconditionnaly, Otherwise, assume \idx{GRH}, +non-zero, certify the result unconditionnally, Otherwise, assume \idx{GRH}, this being much faster of course. \syn{thueinit}{P,\fl,\var{prec}}. @@ -5311,7 +5690,7 @@ guaranteed to be irreducible!). One can check the clos polynomial evaluation or substitution, or by computing the roots of the polynomial given by algdep. -If $x$ is padic, $\fl$ is meaningless and the algorithm LLL-reduces the +If $x$ is $p$-adic, $\fl$ is meaningless and the algorithm LLL-reduces the ``dual lattice'' corresponding to the powers of $x$. Otherwise, if $\fl$ is zero, the algorithm used is a variant of the \idx{LLL} @@ -5414,7 +5793,9 @@ If $\fl>0$, uses the LLL algorithm. $\fl$ is a paramet between one half the number of decimal digits of precision and that number (see \kbd{algdep}). -If $\fl<0$, returns as soon as one relation has been found. +If $\fl<0$, $x$ is allowed to be (and in any case interpreted as) a matrix. +Returns a non trivial element of the kernel of $x$, or $0$ if $x$ has trivial +kernel. \syn{lindep0}{x,\fl,\var{prec}}. Also available is $\teb{lindep}(x,\var{prec})$ ($\fl=0$). @@ -5623,10 +6004,10 @@ any type. If $x$ is known to have integral entries, set $\fl=1$. -\noindent Note: The library function $\tet{ker_mod_p}(x, p)$, where $x$ has +\noindent Note: The library function $\tet{FpM_ker}(x, p)$, where $x$ has integer entries and $p$ is prime, which is equivalent to but many orders of magnitude faster than \kbd{matker(x*Mod(1,p))} and needs much less stack -space. To use it under GP, type \kbd{install(ker\_mod\_p, GG)} first. +space. To use it under GP, type \kbd{install(FpM\_ker, GG)} first. \syn{matker0}{x,\fl}. Also available are $\teb{ker}(x)$ ($\fl=0$), $\teb{keri}(x)$ ($\fl=1$) and $\kbd{ker\_mod\_p}(x,p)$. @@ -5640,9 +6021,6 @@ If $\fl=0$, uses a modified integer LLL algorithm. If $\fl=1$, uses $\kbd{matrixqz}(x,-2)$. If LLL reduction of the final result is not desired, you can save time using \kbd{matrixqz(matker(x),-2)} instead. -If $\fl=2$, uses another modified LLL. In the present version \vers, only -independent rows are allowed in this case. - \syn{matkerint0}{x,\fl}. Also available is $\teb{kerint}(x)$ ($\fl=0$). @@ -5788,8 +6166,8 @@ result is a transformation matrix $T$ such that $x\cdo basis of the lattice generated by the column vectors of $x$. If $\fl=0$ (default), the computations are done with real numbers (i.e.~not -with rational numbers) hence are fast but as presently programmed (version -\vers) are numerically unstable. +with rational numbers), using Householder matrices for orthogonalization +(as presently programmed: slow but stable). If $\fl=1$, it is assumed that the corresponding Gram matrix is integral. The computation is done entirely with integers and the algorithm is both @@ -5805,10 +6183,6 @@ two distinct basis vectors $v_i, \, v_j$.] This can be significantly faster than $\fl=1$ when one row is huge compared to the other rows. -If $\fl=3$, all computations are done in rational numbers. This does not -incur numerical instability, but is extremely slow. This function is -essentially superseded by case 1, so will soon disappear. - If $\fl=4$, $x$ is assumed to have integral entries, but needs not be of maximal rank. The result is a two-component vector of matrices~: the columns of the first matrix represent a basis of the integer kernel of $x$ @@ -5818,12 +6192,8 @@ of the matrix $x$. If $\fl=5$, case as case $4$, but $x$ may have polynomial coefficients. -If $\fl=7$, uses an older version of case $0$ above. - If $\fl=8$, same as case $0$, where $x$ may have polynomial coefficients. -If $\fl=9$, variation on case $1$, using content. - \syn{qflll0}{x,\fl,\var{prec}}. Also available are $\teb{lll}(x,\var{prec})$ ($\fl=0$), $\teb{lllint}(x)$ ($\fl=1$), and $\teb{lllkerim}(x)$ ($\fl=4$). @@ -5843,8 +6213,6 @@ $\fl=4$: $x$ has integer entries, gives the kernel and $\fl=5$: same as $4$ for generic $x$. -$\fl=7$: an older version of case $0$. - \syn{qflllgram0}{x,\fl,\var{prec}}. Also available are $\teb{lllgram}(x,\var{prec})$ ($\fl=0$), $\teb{lllgramint}(x)$ ($\fl=1$), and $\teb{lllgramkerim}(x)$ ($\fl=4$). @@ -6006,7 +6374,7 @@ For example, \kbd{vecextract(x, vecsort(x,,1))} is equ $\bullet$ 2: sorts $x$ by ascending lexicographic order (as per the \kbd{lex} comparison function). -$\bullet$ 4: use decreasing instead of ascending order. +$\bullet$ 4: use descending instead of ascending order. \syn{vecsort0}{x,k,flag}. To omit $k$, use \kbd{NULL} instead. You can also use the simpler functions @@ -6030,6 +6398,13 @@ last two arguments is omitted, fill the vector with ze \synt{vecteur}{GEN nmax, entree *ep, char *expr}. +\subsecidx{vectorsmall}$(n,\{X\},\{\var{expr}=0\})$: creates a row vector of small integers (type +\typ{VECSMALL}) with $n$ components whose components are the expression +\var{expr} evaluated at the integer points between 1 and $n$. If one of the +last two arguments is omitted, fill the vector with zeroes. + +\synt{vecteursmall}{GEN nmax, entree *ep, char *expr}. + \subsecidx{vectorv}$(n,X,\var{expr})$: as \tet{vector}, but returns a column vector (type \typ{COL}). @@ -6207,7 +6582,7 @@ the positive divisors of $n$. Arithmetic functions like \tet{sigma} use the multiplicativity of the underlying expression to speed up the computation. In the present version \vers, there is no way to indicate that \var{expr} is multiplicative in -$n$, hence specialized functions should be prefered whenever possible. +$n$, hence specialized functions should be preferred whenever possible. \synt{divsum}{entree *ep, GEN num, char *expr}. @@ -6363,8 +6738,9 @@ Overlapping regions will thus be drawn twice, and the transparent. Then display the whole drawing in a special window on your screen. -\subsecidx{plotfile}$(s)$: set the output file for plotting output. Special -filename \kbd{-} redirects to the same place as PARI output. +\subsecidx{plotfile}$(s)$: set the output file for plotting output. The +special filename \kbd{"-"} redirects to the same place as PARI output. This +is only taken into account by the \kbd{gnuplot} interface. \subsecidx{ploth}$(X=a,b,\var{expr},\{\fl=0\},\{n=0\})$: high precision plot of the function $y=f(x)$ represented by the expression \var{expr}, $x$ @@ -6388,9 +6764,10 @@ the same window. \noindent The binary digits of $\fl$ mean: -$\bullet$ 1: \tev{parametric plot}. Here \var{expr} must be a vector with -an even number of components. Successive pairs are then understood as the -parametric coordinates of a plane curve. Each of these are then drawn. +$\bullet$ $1 = \kbd{Parametric}$: \tev{parametric plot}. Here \var{expr} must +be a vector with an even number of components. Successive pairs are then +understood as the parametric coordinates of a plane curve. Each of these are +then drawn. For instance: @@ -6403,14 +6780,14 @@ curves. $y=x$. -$\bullet$ 2: \tev{recursive plot}. If this flag is set, only \var{one} -curve can be drawn at time, i.e.~\var{expr} must be either a two-component -vector (for a single parametric curve, and the parametric flag \var{has} to -be set), or a scalar function. The idea is to choose pairs of successive -reference points, and if their middle point is not too far away from the -segment joining them, draw this as a local approximation to the curve. -Otherwise, add the middle point to the reference points. This is very fast, -and usually more precise than usual plot. Compare the results of +$\bullet$ $2 = \kbd{Recursive}$: \tev{recursive plot}. If this flag is set, +only \var{one} curve can be drawn at time, i.e.~\var{expr} must be either a +two-component vector (for a single parametric curve, and the parametric flag +\var{has} to be set), or a scalar function. The idea is to choose pairs of +successive reference points, and if their middle point is not too far away +from the segment joining them, draw this as a local approximation to the +curve. Otherwise, add the middle point to the reference points. This is very +fast, and usually more precise than usual plot. Compare the results of $$\kbd{ploth(X=-1,1,sin(1/X),2)}\quad \text{and}\quad\kbd{ploth(X=-1,1,sin(1/X))}$$ for instance. But beware that if you are extremely unlucky, or choose too few @@ -6425,26 +6802,29 @@ curve with slightly different parameters. The other values toggle various display options: -$\bullet$ 4: do not rescale plot according to the computed extrema. This is -meant to be used when graphing multiple functions on a rectwindow (as a -\tet{plotrecth} call), in conjuction with \tet{plotscale}. +$\bullet$ $4 = \kbd{no\_Rescale}$: do not rescale plot according to the +computed extrema. This is meant to be used when graphing multiple functions +on a rectwindow (as a \tet{plotrecth} call), in conjunction with +\tet{plotscale}. -$\bullet$ 8: do not print the $x$-axis. +$\bullet$ $8 = \kbd{no\_X\_axis}$: do not print the $x$-axis. -$\bullet$ 16: do not print the $y$-axis. +$\bullet$ $16 = \kbd{no\_Y\_axis}$: do not print the $y$-axis. -$\bullet$ 32: do not print frame. +$\bullet$ $32 = \kbd{no\_Frame}$: do not print frame. -$\bullet$ 64: only plot reference points, do not join them. +$\bullet$ $64 = \kbd{no\_Lines}$: only plot reference points, do not join them. -$\bullet$ 256: use splines to interpolate the points. +$\bullet$ $128 = \kbd{Points_too}$: plot both lines and points. -$\bullet$ 512: plot no $x$-ticks. +$\bullet$ $256 = \kbd{Splines}$: use splines to interpolate the points. -$\bullet$ 1024: plot no $y$-ticks. +$\bullet$ $512 = \kbd{no\_X\_ticks}$: plot no $x$-ticks. -$\bullet$ 2048: plot all ticks with the same length. +$\bullet$ $1024 = \kbd{no\_Y\_ticks}$: plot no $y$-ticks. +$\bullet$ $2048 = \kbd{Same\_ticks}$: plot all ticks with the same length. + \subsecidx{plothraw}$(\var{listx},\var{listy},\{\fl=0\})$: given \var{listx} and \var{listy} two vectors of equal length, plots (in high precision) the points whose $(x,y)$-coordinates are given in \var{listx} @@ -6468,7 +6848,7 @@ must be between $0$ and $1$) and internally converted The plotting device imposes an upper bound for $x$ and $y$, for instance the number of pixels for screen output. These bounds are available through the \tet{plothsizes} function. The following sequence initializes in a portable -way (i.e independant of the output device) a window of maximal size, accessed +way (i.e independent of the output device) a window of maximal size, accessed through coordinates in the $[0,1000] \times [0,1000]$ range~: \bprog @@ -6479,8 +6859,8 @@ plotscale(0, 0,1000, 0,1000); \subsecidx{plotkill}$(w)$: erase rectwindow $w$ and free the corresponding memory. Note that if you want to use the rectwindow $w$ again, you have to -use \kbd{initrect} first to specify the new size. So it's better in this case -to use \kbd{initrect} directly as this throws away any previous work in the +use \kbd{plotinit} first to specify the new size. So it's better in this case +to use \kbd{plotinit} directly as this throws away any previous work in the given rectwindow. \subsecidx{plotlines}$(w,X,Y,\{\fl=0\})$: draw on the rectwindow $w$ @@ -6544,7 +6924,7 @@ rectwindow $w$ the curve output of \kbd{ploth}$(w,X=a, \var{data} is a vector of vectors, each corresponding to a list a coordinates. If parametric plot is set, there must be an even number of vectors, each -successive pair corresponding to a curve. Otherwise, the first one containe +successive pair corresponding to a curve. Otherwise, the first one contains the $x$ coordinates, and the other ones contain the $y$-coordinates of curves to plot. @@ -6688,11 +7068,15 @@ HNF\sidx{Hermite normal form} form), one can for insta [1, 0; 0, 2] [2, 0; 0, 1] [1, 0; 0, 1] -@eprog +@eprog\noindent Note that in this last representation, the index $[G:H]$ is given by the determinant. See \tet{galoissubcyclo} and \tet{galoisfixedfield} for \tet{nfsubfields} applications to \idx{Galois} theory. +\misctitle{Warning:} the present implementation cannot treat a group $G$, if +one of its $p$-Sylow subgroups has a cyclic factor has more than $2^{31}$, +resp.~$2^{63}$ elements on a $32$-bit, resp.~$64$-bit architecture. + \subsubsecidx{forvec}$(X=v,\var{seq},\{\fl=0\})$: $v$ being an $n$-component vector (where $n$ is arbitrary) of two-component vectors $[a_i,b_i]$ for $1\le i\le n$, the \var{seq} is evaluated with the formal variable @@ -6725,12 +7109,13 @@ statement is \var{not} a loop (obviously!). \subsubsecidx{next}$(\{n=1\})$: interrupts execution of current $seq$, resume the next iteration of the innermost enclosing loop, within the -current fonction call (or top level loop). If $n$ is specified, resume at +current function call (or top level loop). If $n$ is specified, resume at the $n$-th enclosing loop. If $n$ is bigger than the number of enclosing loops, all enclosing loops are exited. \subsubsecidx{return}$(\{x=0\})$: returns from current subroutine, with -result $x$. +result $x$. If $x$ is omitted, return the \kbd{(void)} value (return no +result, like \kbd{print}). \subsubsecidx{until}$(a,\var{seq})$: evaluates expression sequence \var{seq} until $a$ is not equal to 0 (i.e.~until $a$ is true). If $a$ is initially @@ -7030,12 +7415,11 @@ result of the evaluation of \var{rec}, and the control GP prompt. In particular, current computation is then lost. The following error handler prints the list of all user variables, then -stores in a file their name and their values: +stores in a file their name and their values:\sidx{writebin} \bprog ? { trap( , print(reorder); - write("crash", reorder); - write("crash", eval(reorder))) } + writebin("crash")) } @eprog If no recovery code is given (\var{rec} is omitted) a so-called @@ -7134,15 +7518,21 @@ the corresponding user variable to the saved value. E. x = 1; writebin("log") @eprog \noindent reading \kbd{log} into a clean session will set \kbd{x} to $1$. -The relative variables priorities of new variables set in this way remain the -same (preset variables retain their former priority, but are set to the new -value). In particular, reading such a session log into a clean session will -restore all variables exactly as they were in the original one. +The relative variables priorities (see \secref{se:priority}) of new variables +set in this way remain the same (preset variables retain their former +priority, but are set to the new value). In particular, reading such a +session log into a clean session will restore all variables exactly as they +were in the original one. User functions, installed functions and history objects can not be saved via this function. Just as a regular input file, a binary file can be compressed using \tet{gzip}, provided the file name has the standard \kbd{.gz} extension. \label{se:writebin}\sidx{binary file} + +In the present implementation, the binary files are architecture dependant +and compatibility with future versions of GP is not guaranteed. Hence +binary files should not be used for long term storage (also, they are +larger and harder to compress than text files). \subsubsecidx{writetex}$(\var{filename},\{\var{str}*\})$: as \kbd{write}, in \TeX\ format.\label{se:writetex}