diff options
Diffstat (limited to 'Master/tlpkg/tlperl.straw/lib/Math/libPARI.pod')
| -rwxr-xr-x | Master/tlpkg/tlperl.straw/lib/Math/libPARI.pod | 8045 |
1 files changed, 8045 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl.straw/lib/Math/libPARI.pod b/Master/tlpkg/tlperl.straw/lib/Math/libPARI.pod new file mode 100755 index 00000000000..723da009df9 --- /dev/null +++ b/Master/tlpkg/tlperl.straw/lib/Math/libPARI.pod @@ -0,0 +1,8045 @@ +=head1 NAME + +libPARI - Functions and Operations Available in PARI and GP + +=head1 DESCRIPTION + +X<Label se:functions> +The functions and operators available in PARI and in the GP/PARI calculator +are numerous and everexpanding. Here is a description of the ones available +in version B<2.2.0>. It should be noted that many of these functions accept +quite different types as arguments, but others are more restricted. The list +of acceptable types will be given for each function or class of functions. +Except when stated otherwise, it is understood that a function or operation +which should make natural sense is legal. In this chapter, we will describe +the functions according to a rough classification. The general entry looks +something like: + +B<foo>C<(x,{I<flag> = 0})>: short description. + +X<foo>The library syntax is B<foo>C<(x,I<flag>)>. + +This means that the GP function C<foo> has one mandatory argument C<x>, and +an optional one, C<I<flag>>, whose default value is 0 (the C<{}> should never be +typed, it is just a convenient notation we will use throughout to denote +optional arguments). That is, you can type C<foo(x,2)>, or C<foo(x)>, +which is then understood to mean C<foo(x,0)>. As well, a comma or closing +parenthesis, where an optional argument should have been, signals to GP it +should use the default. Thus, the syntax C<foo(x,)> is also accepted as a +synonym for our last expression. When a function has more than one optional +argument, the argument list is filled with user supplied values, in order. +And when none are left, the defaults are used instead. Thus, assuming that +C<foo>'s prototype had been + +S< >C< +B<foo>({x = 1},{y = 2},{z = 3}), +> + +typing in C<foo(6,4)> would give +you C<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 +``empty arg'' trick alluded to above: C<foo(6,,1)> would yield +C<foo(6,2,1)>. By the way, C<foo()> by itself yields +C<foo(1,2,3)> as was to be expected. In this rather special case of a +function having no mandatory argument, you can even omit the C<()>: a +standalone C<foo> would be enough (though we don't really recommend it for +your scripts, for the sake of clarity). In defining GP syntax, we strove +to put optional arguments at the end of the argument list (of course, since +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. + +B<Binary Flags>.X<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 C<(p_0,...,p_n)> be a +list of switches (i.e.S< >of properties which can be assumed to take either +the value C<0> orS< >C<1>), the number C<2^3 + 2^5 = 40> means that C<p_3> and C<p_5> +have been set (that is, set to C<1>), and none of the others were (that is, +they were set to 0). This will usually be announced as ``The binary digits +of C<I<flag>> mean 1: C<p_0>, 2: C<p_1>, 4: C<p_2>'', and so on, using the +available consecutive powers ofS< >C<2>. + +B<Pointers>.X<pointer> If a parameter in the function +prototype is prefixed with a & sign, as in + +B<foo>C<(x,&e)> + +it means that, besides the normal return value, the variable named +C<e> may be set as a side effect. When passing the argument, the & sign has +to be typed in explicitly. As of version B<2.2.0>, this X<pointer>C<pointer> argument +is optional for all documented functions, hence the & will always appear +between brackets as in C<issquare>C<(x,{&e})>. + +B<About library programming>. To finish with our generic +simple-minded example, the I<library> function C<foo>, as defined +above, is seen to have two mandatory arguments, C<x> and I<flag> (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 C<GEN>. +Most other functions return an object of type C<long> integer in C (see +ChapterS< >4). The variable or parameter names I<prec> and I<flag> always +denote C<long> integers. + +The X<entree>C<entree> type is used by the library to implement iterators (loops, +sums, integrals, etc.) when a formal variable has to successively assume a +number of values in a given set. When programming with the library, it is +easier and much more efficient to code loops and the like directly. Hence +this type is not documented, although it does appear in a few library +function prototypes below. See L<Label se:sums> for more details. + +=head1 Standard monadic or dyadic operators + +=head2 +C</>- + +The expressions C<+>C<x> and C<->C<x> refer +to monadic operators (the first does nothing, the second negates C<x>). + +X<gneg>The library syntax is B<gneg>C<(x)> for C<->C<x>. + +=head2 +, C<-> + +The expression C<x> C<+> C<y> is the X<sum>sum and +C<x> C<-> C<y> is the X<difference>difference of C<x> and C<y>. Among the prominent +impossibilities are addition/subtraction between a scalar type and a vector +or a matrix, between vector/matrices of incompatible sizes and between an +integermod and a real number. + +X<gadd>The library syntax is B<gadd>C<(x,y)> C<x> C<+> C<y>, C<X<gsub>B<gsub>(x,y)> for C<x> C<-> C<y>. + +=head2 * + +The expression C<x> C<*> C<y> is the X<product>product of C<x> +and C<y>. Among the prominent impossibilities are multiplication between +vector/matrices of incompatible sizes, between an integermod and a real +number. Note that because of vector and matrix operations, C<*> is not +necessarily commutative. Note also that since multiplication between two +column or two row vectors is not allowed, to obtain the X<scalar product>scalar product +of two vectors of the same length, you must multiply a line vector by a +column vector, if necessary by transposing one of the vectors (using +the operator C<~> or the function C<mattranspose>, see +L<Label se:linear_algebra>). + +If C<x> and C<y> are binary quadratic forms, compose them. See also +C<qfbnucomp> and C<qfbnupow>. + +X<gmul>The library syntax is B<gmul>C<(x,y)> for C<x> C<*> C<y>. Also available is +C<X<gsqr>B<gsqr>(x)> for C<x> C<*> C<x> (faster of course!). + +=head2 / + +The expression C<x> C</> C<y> is the X<quotient>quotient of C<x> +and C<y>. In addition to the impossibilities for multiplication, note that if +the divisor is a matrix, it must be an invertible square matrix, and in that +case the result is C<x*y^{-1}>. Furthermore note that the result is as exact +as possible: in particular, division of two integers always gives a rational +number (which may be an integer if the quotient is exact) and I<not> the +Euclidean quotient (see C<x> C<\> C<y> for that), and similarly the +quotient of two polynomials is a rational function in general. To obtain the +approximate real value of the quotient of two integers, add C<0.> to the +result; to obtain the approximate C<p>-adic value of the quotient of two +integers, add C<O(p^k)> to the result; finally, to obtain the +X<Taylor series>Taylor series expansion of the quotient of two polynomials, add +C<O(X^k)> to the result or use the C<taylor> function +(see L<Label se:taylor>). X<Label se:gdiv> + +X<gdiv>The library syntax is B<gdiv>C<(x,y)> for C<x> C</> C<y>. + +=head2 \ + +The expression C<x> C<\> C<y> is the + +X<Euclidean quotient>Euclidean quotient of C<x> and C<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. + +X<gdivent>The library syntax is B<gdivent>C<(x,y)> for C<x> C<\> C<y>. + +=head2 \/ + +The expression C<x> C<\/> C<y> is the Euclidean +quotient of C<x> and C<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 +C<+ oo > is chosen. + +X<gdivround>The library syntax is B<gdivround>C<(x,y)> for C<x> C<\/> C<y>. + +=head2 % + +The expression C<x> C<%> C<y> is the + +X<Euclidean remainder>Euclidean remainder of C<x> and C<y>. The modulus C<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. + +X<gmod>The library syntax is B<gmod>C<(x,y)> for C<x> C<%> C<y>. + +=head2 X<divrem>divremC<(x,y)> + +creates a column vector with two components, +the first being the Euclidean quotient, the second the Euclidean remainder, +of the division of C<x> by C<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. + +X<gdiventres>The library syntax is B<gdiventres>C<(x,y)>. + +=head2 ^ + +The expression C<x^n> is X<powering>powering. +If the exponent is an integer, then exact operations are performed using +binary (left-shift) powering techniques. In particular, in this case C<x> +cannot be a vector or matrix unless it is a square matrix (and moreover +invertible if the exponent is negative). If C<x> is a C<p>-adic number, its +precision will increase if C<v_p(n) E<gt> 0>. PARI is able to rewrite the +multiplication C<x * x> of two I<identical> objects as C<x^2>, or +C<sqr(x)> (here, identical means the operands are two different labels +referencing the same chunk of memory; no equality test is performed). This +is no longer true when more than two arguments are involved. + +If the exponent is not of type integer, this is treated as a transcendental +function (see L<Label se:trans>), and in particular has the effect of +componentwise powering on vector or matrices. + +As an exception, if the exponent is a rational number C<p/q> and C<x> an +integer modulo a prime, return a solution C<y> of C<y^q = x^p> if it +exists. Currently, C<q> must not have large prime factors. + +Beware that + + ? Mod(7,19)^(1/2) + %1 = Mod(11, 19)/*is any square root*/ + ? sqrt(Mod(7,19)) + %2 = Mod(8, 19)/*is the smallest square root*/ + ? Mod(7,19)^(3/5) + %3 = Mod(1, 19) + ? %3^(5/3) + %4 = Mod(1, 19)/*Mod(7,19) is just another cubic root*/ + +X<gpow>The library syntax is B<gpow>C<(x,n,I<prec>)> for C<x^n>. + +=head2 X<shift>shiftC<(x,n)> or C<x> C<E<lt>E<lt> > C<n> ( = C<x> C<E<gt>E<gt> > C<(-n)>) + +shifts +C<x> componentwise left by C<n> bits if C<n E<gt>= 0> and right by C<|n|> bits if +C<n E<lt> 0>. A left shift by C<n> corresponds to multiplication by C<2^n>. A right +shift of an integer C<x> by C<|n|> corresponds to a Euclidean division of +C<x> by C<2^{|n|}> with a +remainder of the same sign as C<x>, hence is not the same (in general) as +C<x \ 2^n>. + +X<gshift>The library syntax is B<gshift>C<(x,n)> where C<n> is a C<long>. + +=head2 X<shiftmul>shiftmulC<(x,n)> + +multiplies C<x> by C<2^n>. The difference with +C<shift> is that when C<n E<lt> 0>, ordinary division takes place, hence for +example if C<x> is an integer the result may be a fraction, while for +C<shift> Euclidean division takes place when C<n E<lt> 0> hence if C<x> is an +integer the result is still an integer. + +X<gmul2n>The library syntax is B<gmul2n>C<(x,n)> where C<n> is a C<long>. + +=head2 Comparison and boolean operators + +X<boolean operators> +The six standard X<comparison operators>comparison operators C<E<lt>= >, C<E<lt> >, C<E<gt>= >, +C<E<gt> >, C< == >, C<! = > are available in GP, and in library mode under +the names X<gle>B<gle>, X<glt>B<glt>, X<gge>B<gge>, X<ggt>B<ggt>, X<geq>B<geq>, X<gne>B<gne> +respectively. The library syntax is C<I<co>(x,y)>, where I<co> is the +comparison operator. The result is 1 (as a C<GEN>) if the comparison is +true, 0 (as a C<GEN>) if it is false. + +The standard boolean functions C<||> (X<inclusive or>inclusive or), C<&&> +(X<and>and)X<or> and C<!> (X<not>not) are also available, and the +library syntax is C<X<gor>B<gor>(x,y)>, C<X<gand>B<gand>(x,y)> and C<X<gnot>B<gnot>(x)> +respectively. + +In library mode, it is in fact usually preferable to use the two basic +functions which are C<X<gcmp>B<gcmp>(x,y)> which gives the sign (1, 0, or -1) of +C<x-y>, where C<x> and C<y> must be in B<I<R>>, and C<X<gegal>B<gegal>(x,y)> which +can be applied to any two PARI objects C<x> and C<y> and gives 1 (i.e.S< >true) if +they are equal (but not necessarily identical), 0 (i.e.S< >false) otherwise. +Particular cases of X<gegal>B<gegal> which should be used are C<X<gcmp0>B<gcmp0>(x)> +(C<x == 0> ?), C<X<gcmp1>B<gcmp1>(x)> (C<x == 1> ?), and +C<X<gcmp_1>B<gcmp_1>(x)> (C<x == -1> ?). + +Note that C<X<gcmp0>B<gcmp0>(x)> tests whether C<x> is equal to zero, even if C<x> is +not an exact object. To test whether C<x> is an exact object which is equal to +zero, one must use C<X<isexactzero>B<isexactzero>>. + +Also note that the C<gcmp> and C<gegal> functions return a C-integer, +and I<not> a C<GEN> like C<gle> etc. + +GP accepts the following synonyms for some of the above functions: since we +thought it might easily lead to confusion, we don't use the customary C +operators for bitwise C<and> or bitwise C<or> (use X<bitand>C<bitand> or +X<bitor>C<bitor>), hence C<|> and C<&> are accepted asX<bitwise +and>X<bitwise or> synonyms of C<||> and C<&&> respectively. +Also, C<E<lt> E<gt> > is accepted as a synonym for C<! = >. On the other hand, +C< = > is definitely I<not> a synonym for C< == > since it is the +assignment statement. + +=head2 X<lex>lexC<(x,y)> + +gives the result of a lexicographic comparison +between C<x> and C<y>. This is to be interpreted in quite a wide sense. For +example, the vector C<[1,3]> will be considered smaller than the longer +vector C<[1,3,-1]> (but of course larger than C<[1,2,5]>), +i.e.S< >C<lex([1,3], [1,3,-1])> will return C<-1>. + +X<lexcmp>The library syntax is B<lexcmp>C<(x,y)>. + +=head2 X<sign>signC<(x)> + +X<sign>sign (C<0>, C<1> or C<-1>) of C<x>, which must be of +type integer, real or fraction. + +X<gsigne>The library syntax is B<gsigne>C<(x)>. The result is a C<long>. + +=head2 X<max>maxC<(x,y)> and X<min>B<min>C<(x,y)> + +creates the +maximum and minimum of C<x> and C<y> when they can be compared. + +X<gmax>The library syntax is B<gmax>C<(x,y)> and C<X<gmin>B<gmin>(x,y)>. + +=head2 X<vecmax>vecmaxC<(x)> + +if C<x> is a vector or a matrix, returns the maximum +of the elements of C<x>, otherwise returns a copy of C<x>. Returns C<- oo > +in the form of C<-(2^{31}-1)> (or C<-(2^{63}-1)> for 64-bit machines) if C<x> is +empty. + +X<vecmax>The library syntax is B<vecmax>C<(x)>. + +=head2 X<vecmin>vecminC<(x)> + +if C<x> is a vector or a matrix, returns the minimum +of the elements of C<x>, otherwise returns a copy of C<x>. Returns C<+ oo > +in the form of C<2^{31}-1> (or C<2^{63}-1> for 64-bit machines) if C<x> is empty. + +X<vecmin>The library syntax is B<vecmin>C<(x)>. + +=head1 Conversions and similar elementary functions or commands + +X<Label se:conversion> +Many of the conversion functions are rounding or truncating operations. In +this case, if the argument is a rational function, the result is the +Euclidean quotient of the numerator by the denominator, and if the argument +is a vector or a matrix, the operation is done componentwise. This will not +be restated for every function. + +=head2 X<List>ListC<({x = []})> + +transforms a (row or column) vector C<x> +into a list. The only other way to create a C<t_LIST> is to use the +function C<listcreate>. + +This is useless in library mode. + +=head2 X<Mat>MatC<({x = []})> + +transforms the object C<x> into a matrix. +If C<x> is not a vector or a matrix, this creates a C<1 x 1> matrix. +If C<x> is a row (resp. column) vector, this creates a 1-row (resp. +1-column) matrix. If C<x> is already a matrix, a copy of C<x> is created. + +This function can be useful in connection with the function C<concat> +(see there). + +X<gtomat>The library syntax is B<gtomat>C<(x)>. + +=head2 X<Mod>ModC<(x,y,{I<flag> = 0})> + +X<Label se:Mod> creates the PARI object +C<(x mod y)>, i.e.S< >an integermod or a polmod. C<y> must be an integer or a +polynomial. If C<y> is an integer, C<x> must be an integer, a rational +number, or a C<p>-adic number compatible with the modulus C<y>. If C<y> is a +polynomial, C<x> must be a scalar (which is not a polmod), a polynomial, a +rational function, or a power series. + +This function is not the same as C<x> C<%> C<y>, the result of which is an +integer or a polynomial. + +If C<I<flag>> is equal to C<1>, the modulus of the created result is put on the +heap and not on the stack, and hence becomes a permanent copy which cannot be +erased later by garbage collecting (see L<Label se:garbage>). Functions +will operate faster on such objects and memory consumption will be lower. +On the other hand, care should be taken to avoid creating too many such +objects. + +Under GP, the same effect can be obtained by assigning the object to a GP +variable (the value of which is a permanent object for the duration of the +relevant library function call, and is treated as such). This value is +subject to garbage collection, since it will be deleted when the value +changes. This is preferable and the above flag is only retained for +compatibility reasons (it can still be useful in library mode). + +X<Mod0>The library syntax is B<Mod0>C<(x,y,I<flag>)>. Also available are + +C<B<*>> for C<I<flag> = 1>: C<X<gmodulo>B<gmodulo>(x,y)>. + +C<B<*>> for C<I<flag> = 0>: C<X<gmodulcp>B<gmodulcp>(x,y)>. + +=head2 X<Pol>PolC<(x,{v = x})> + +transforms the object C<x> into a polynomial with +main variable C<v>. If C<x> is a scalar, this gives a constant polynomial. If +C<x> is a power series, the effect is identical to C<truncate> (see there), +i.e.S< >it chops off the C<O(X^k)>. If C<x> is a vector, this function creates +the polynomial whose coefficients are given in C<x>, with C<x[1]> being the +leading coefficient (which can be zero). + +Warning: this is I<not> a substitution function. It is intended to be +quick and dirty. So if you try C<Pol(a,y)> on the polynomial C<a = x+y>, +you will get C<y+y>, which is not a valid PARI object. + +X<gtopoly>The library syntax is B<gtopoly>C<(x,v)>, where C<v> is a variable number. + +=head2 X<Polrev>PolrevC<(x,{v = x})> + +transform the object C<x> into a polynomial +with main variable C<v>. If C<x> is a scalar, this gives a constant polynomial. +If C<x> is a power series, the effect is identical to C<truncate> (see +there), i.e.S< >it chops off the C<O(X^k)>. If C<x> is a vector, this function +creates the polynomial whose coefficients are given in C<x>, with C<x[1]> being +the constant term. Note that this is the reverse of C<Pol> if C<x> is a +vector, otherwise it is identical to C<Pol>. + +X<gtopolyrev>The library syntax is B<gtopolyrev>C<(x,v)>, where C<v> is a variable number. + +=head2 X<Qfb>QfbC<(a,b,c,{D = 0.})> + +creates the binary quadratic form +C<ax^2+bxy+cy^2>. If C<b^2-4ac E<gt> 0>, initialize X<Shanks>Shanks' distance +function to C<D>. + +X<Qfb0>The library syntax is B<Qfb0>C<(a,b,c,D,I<prec>)>. Also available are +C<X<qfi>B<qfi>(a,b,c)> (when C<b^2-4ac E<lt> 0>), and +C<X<qfr>B<qfr>(a,b,c,d)> (when C<b^2-4ac E<gt> 0>).X<binary quadratic form> + +=head2 X<Ser>SerC<(x,{v = x})> + +transforms the object C<x> into a power series +with main variable C<v> (C<x> by default). If C<x> is a scalar, this gives a +constant power series with precision given by the default C<serieslength> +(corresponding to the C global variable C<precdl>). If C<x> is a +polynomial, the precision is the greatest of C<precdl> and the degree of +the polynomial. If C<x> is a vector, the precision is similarly given, and the +coefficients of the vector are understood to be the coefficients of the power +series starting from the constant term (i.e.S< >the reverse of the function +C<Pol>). + +The warning given for C<Pol> applies here: this is not a substitution +function. + +X<gtoser>The library syntax is B<gtoser>C<(x,v)>, where C<v> is a variable number (i.e.S< >a C integer). + +=head2 X<Set>SetC<({x = []})> + +converts C<x> into a set, i.e.S< >into a row vector +with strictly increasing entries. C<x> can be of any type, but is most useful +when C<x> is already a vector. The components of C<x> are put in canonical form +(type C<t_STR>) so as to be easily sorted. To recover an ordinary C<GEN> +from such an element, you can apply X<eval>C<eval> to it. + +X<gtoset>The library syntax is B<gtoset>C<(x)>. + +=head2 X<Str>StrC<({x = ""},{I<flag> = 0})> + +converts C<x> into a +character string (type C<t_STR>, the empty string if C<x> is omitted). To +recover an ordinary C<GEN> from a string, apply C<eval> to it. The +arguments of C<Str> are evaluated in string context (see +L<Label se:strings>). If I<flag> is set, treat C<x> as a filename and perform +X<environment expansion>environment expansion on the string. This feature can be used to read +X<environment variable>environment variable values. + + ? i = 1; Str("x" i) + %1 = "x1" + ? eval(%) + %2 = x1; + ? Str("$HOME", 1) + %3 = "/home/pari" + +X<strtoGENstr>The library syntax is B<strtoGENstr>C<(x,I<flag>)>. This function is mostly useless in library mode. Use +the pair X<strtoGEN>C<strtoGEN>/X<GENtostr>C<GENtostr> to convert between C<char*> and +C<GEN>. + +=head2 X<Vec>VecC<({x = []})> + +transforms the object C<x> into a row vector. The +vector will be with one component only, except when C<x> is a vector/matrix or +a quadratic form (in which case the resulting vector is simply the initial +object considered as a row vector), but more importantly when C<x> is a +polynomial or a power series. In the case of a polynomial, the coefficients +of the vector start with the leading coefficient of the polynomial, while +for power series only the significant coefficients are taken into account, +but this time by increasing order of degree. + +X<gtovec>The library syntax is B<gtovec>C<(x)>. + +=head2 X<binary>binaryC<(x)> + +outputs the vector of the binary digits of C<|x|>. +Here C<x> can be an integer, a real number (in which case the result has two +components, one for the integer part, one for the fractional part) or a +vector/matrix. + +X<binaire>The library syntax is B<binaire>C<(x)>. + +=head2 X<bitand>bitandC<(x,y)> + +bitwise X<and>C<and>X<bitwise and> of two +integers C<x> and C<y>, that is the integer + +S< >C<F<sum> (x_iS< >andS< >y_i) 2^i> + +Negative numbers behave as if modulo a huge power of C<2>. + +X<gbitand>The library syntax is B<gbitand>C<(x,y)>. + +=head2 X<bitneg>bitnegC<(x,{n = -1})> + +X<bitwise negation>bitwise negation of an integer C<x>, +truncated to C<n> bits, that is the integer + +S< >C<F<sum>_{i = 0}^n not(x_i) 2^i> + +The special case C<n = -1> means no truncation: an infinite sequence of +leading C<1> is then represented as a negative number. + +Negative numbers behave as if modulo a huge power of C<2>. + +X<gbitneg>The library syntax is B<gbitneg>C<(x)>. + +=head2 X<bitnegimply>bitnegimplyC<(x,y)> + +bitwise negated imply of two integers C<x> +and C<y> (or C<not> C<(x ==E<gt> y)>), that is the integer + +S< >C<F<sum> (x_iS< >and not(y_i)) 2^i> + +Negative numbers behave as if modulo a huge power of C<2>. + +X<gbitnegimply>The library syntax is B<gbitnegimply>C<(x,y)>. + +=head2 X<bitor>bitorC<(x,y)> + +bitwise (inclusive) X<or>C<or>X<bitwise +inclusive or> of two integers C<x> and C<y>, that is the integer + +S< >C<F<sum> (x_iS< >orS< >y_i) 2^i> + +Negative numbers behave as if modulo a huge power of C<2>. + +X<gbitor>The library syntax is B<gbitor>C<(x,y)>. + +=head2 X<bittest>bittestC<(x,n)> + +outputs the C<n^{th}> bit of C<|x|> starting +from the right (i.e.S< >the coefficient of C<2^n> in the binary expansion of C<x>). +The result is 0 or 1. To extract several bits at once as a vector, pass a +vector for C<n>. + +X<bittest>The library syntax is B<bittest>C<(x,n)>, where C<n> and the result are C<long>s. + +=head2 X<bitxor>bitxorC<(x,y)> + +bitwise (exclusive) X<or>C<or>X<bitwise +exclusive or> of two integers C<x> and C<y>, that is the integer + +S< >C<F<sum> (x_iS< >xorS< >y_i) 2^i> + +Negative numbers behave as if modulo a huge power of C<2>. + +X<gbitxor>The library syntax is B<gbitxor>C<(x,y)>. + +=head2 X<ceil>ceilC<(x)> + +ceiling of C<x>. When C<x> is in B<I<R>>, +the result is the smallest integer greater than or equal to C<x>. Applied to a +rational function, C<ceil(x)> returns the euclidian quotient of the +numerator by the denominator. + +X<gceil>The library syntax is B<gceil>C<(x)>. + +=head2 X<centerlift>centerliftC<(x,{v})> + +lifts an element C<x = a mod n> of C<B<I<Z>>/nB<I<Z>>> +to C<a> in B<I<Z>>, and similarly lifts a polmod to a polynomial. This is the +same as C<lift> except that in the particular case of elements of +C<B<I<Z>>/nB<I<Z>>>, the lift C<y> is such that C<-n/2 E<lt> y E<lt>= n/2>. If C<x> is of type +fraction, complex, quadratic, polynomial, power series, rational function, +vector or matrix, the lift is done for each coefficient. Real and C<p>-adics +are forbidden. + +X<centerlift0>The library syntax is B<centerlift0>C<(x,v)>, where C<v> is a C<long> and an omitted C<v> is coded +as C<-1>. Also available is X<centerlift>B<centerlift>C<(x)> = C<centerlift0(x,-1)>. + +=head2 X<changevar>changevarC<(x,y)> + +creates a copy of the object C<x> where its +variables are modified according to the permutation specified by the vector +C<y>. For example, assume that the variables have been introduced in the +order C<x>, C<a>, C<b>, C<c>. Then, if C<y> is the vector +C<[x,c,a,b]>, the variable C<a> will be replaced by C<c>, C<b> by +C<a>, and C<c> by C<b>, C<x> being unchanged. Note that the +permutation must be completely specified, e.g.S< >C<[c,a,b]> would not work, +since this would replace C<x> by C<c>, and leave C<a> and C<b> +unchanged (as well as C<c> which is the fourth variable of the initial +list). In particular, the new variable names must be distinct. + +X<changevar>The library syntax is B<changevar>C<(x,y)>. + +=head2 components of a PARI object + +There are essentially three ways to extract the X<components>components from a PARI +object. + +The first and most general, is the function C<X<component>B<component>(x,n)> which +extracts the C<n^{th}>-component of C<x>. This is to be understood as +follows: every PARI type has one or two initial X<code words>code words. The +components are counted, starting at 1, after these code words. In particular +if C<x> is a vector, this is indeed the C<n^{th}>-component of C<x>, if +C<x> is a matrix, the C<n^{th}> column, if C<x> is a polynomial, the +C<n^{th}> coefficient (i.e.S< >of degree C<n-1>), and for power series, the +C<n^{th}> significant coefficient. The use of the function +C<component> implies the knowledge of the structure of the different PARI +types, which can be recalled by typing C<\t> under GP. + +X<compo>The library syntax is B<compo>C<(x,n)>, where C<n> is a C<long>. + +The two other methods are more natural but more restricted. The function +C< B<polcoeff>(x,n)>X<polcoeff> gives the coefficient of degree C<n> of the polynomial +or power series C<x>, with respect to the main variable of C<x> (to check +variable ordering, or to change it, use the function X<reorder>C<reorder>, see +L<Label se:reorder>). In particular if C<n> is less than the valuation of +C<x> or in the case of a polynomial, greater than the degree, the result is +zero (contrary to C<compo> which would send an error message). If C<x> is +a power series and C<n> is greater than the largest significant degree, then +an error message is issued. + +For greater flexibility, vector or matrix types are also accepted for C<x>, +and the meaning is then identical with that of C<compo>. + +Finally note that a scalar type is considered by C<polcoeff> as a +polynomial of degree zero. + +X<truecoeff>The library syntax is B<truecoeff>C<(x,n)>. + +The third method is specific to vectors or matrices under GP. If C<x> is a +(row or column) vector, then X<x[n]>C<x[n]> represents the C<n^{th}> +component of C<x>, i.e.S< >C<compo(x,n)>. It is more natural and shorter to +write. If C<x> is a matrix, X<x[m,n]>C<x[m,n]> represents the coefficient of +row C<m> and column C<n> of the matrix, X<x[m,]>C<x[m,]> represents +the C<m^{th}> I<row> of C<x>, and X<x[,n]>C<x[,n]> represents +the C<n^{th}> I<column> of C<x>. + +Finally note that in library mode, the macros X<coeff>B<coeff> and X<mael>B<mael> +are available to deal with the non-recursivity of the C<GEN> type from the +compiler's point of view. See the discussion on typecasts in Chapter 4. + +=head2 X<conj>conjC<(x)> + +conjugate of C<x>. The meaning of this +is clear, except that for real quadratic numbers, it means conjugation in the +real quadratic field. This function has no effect on integers, reals, +integermods, fractions or C<p>-adics. The only forbidden type is polmod +(see C<conjvec> for this). + +X<gconj>The library syntax is B<gconj>C<(x)>. + +=head2 X<conjvec>conjvecC<(x)> + +conjugate vector representation of C<x>. If C<x> is a +polmod, equal to C<Mod>C<(a,q)>, this gives a vector of length +C<degree(q)> containing the complex embeddings of the polmod if C<q> has +integral or rational coefficients, and the conjugates of the polmod if C<q> +has some integermod coefficients. The order is the same as that of the +C<polroots> functions. If C<x> is an integer or a rational number, the +result isS< >C<x>. If C<x> is a (row or column) vector, the result is a matrix +whose columns are the conjugate vectors of the individual elements of C<x>. + +X<conjvec>The library syntax is B<conjvec>C<(x,I<prec>)>. + +=head2 X<denominator>denominatorC<(x)> + +lowest denominator of C<x>. The meaning of this +is clear when C<x> is a rational number or function. When C<x> is an integer +or a polynomial, the result is equal to C<1>. When C<x> is a vector or a matrix, +the lowest common denominator of the components of C<x> is computed. All other +types are forbidden. + +X<denom>The library syntax is B<denom>C<(x)>. + +=head2 X<floor>floorC<(x)> + +floor of C<x>. When C<x> is in B<I<R>>, the result is the +largest integer smaller than or equal to C<x>. Applied to a rational function, +C<floor(x)> returns the euclidian quotient of the numerator by the +denominator. + +X<gfloor>The library syntax is B<gfloor>C<(x)>. + +=head2 X<frac>fracC<(x)> + +fractional part of C<x>. Identical to +C<x-floor(x)>. If C<x> is real, the result is in C<[0,1[>. + +X<gfrac>The library syntax is B<gfrac>C<(x)>. + +=head2 X<imag>imagC<(x)> + +imaginary part of C<x>. When +C<x> is a quadratic number, this is the coefficient of C<F<omega>> in +the ``canonical'' integral basis C<(1,F<omega>)>. + +X<gimag>The library syntax is B<gimag>C<(x)>. + +=head2 X<length>lengthC<(x)> + +number of non-code words in C<x> really used (i.e.S< >the +effective length minus 2 for integers and polynomials). In particular, +the degree of a polynomial is equal to its length minus 1. If C<x> has type +C<t_STR>, output number of letters. + +X<glength>The library syntax is B<glength>C<(x)> and the result is a C long. + +=head2 X<lift>liftC<(x,{v})> + +lifts an element C<x = a mod n> of C<B<I<Z>>/nB<I<Z>>> to +C<a> in B<I<Z>>, and similarly lifts a polmod to a polynomial if C<v> is omitted. +Otherwise, lifts only polmods with main variable C<v> (if C<v> does not occur +in C<x>, lifts only intmods). If C<x> is of type fraction, complex, quadratic, +polynomial, power series, rational function, vector or matrix, the lift is +done for each coefficient. Forbidden types for C<x> are reals and C<p>-adics. + +X<lift0>The library syntax is B<lift0>C<(x,v)>, where C<v> is a C<long> and an omitted C<v> is coded as +C<-1>. Also available is X<lift>B<lift>C<(x)> = C<lift0(x,-1)>. + +=head2 X<norm>normC<(x)> + +algebraic norm of C<x>, i.e.S< >the product of C<x> with +its conjugate (no square roots are taken), or conjugates for polmods. For +vectors and matrices, the norm is taken componentwise and hence is not the +C<L^2>-norm (see C<norml2>). Note that the norm of an element of +B<I<R>> is its square, so as to be compatible with the complex norm. + +X<gnorm>The library syntax is B<gnorm>C<(x)>. + +=head2 X<norml2>norml2C<(x)> + +square of the C<L^2>-norm of C<x>. C<x> must +be a (row or column) vector. + +X<gnorml2>The library syntax is B<gnorml2>C<(x)>. + +=head2 X<numerator>numeratorC<(x)> + +numerator of C<x>. When C<x> is a rational number +or function, the meaning is clear. When C<x> is an integer or a polynomial, +the result is C<x> itself. When C<x> is a vector or a matrix, then +C<numerator(x)> is defined to be C<denominator(x)*x>. All other types +are forbidden. + +X<numer>The library syntax is B<numer>C<(x)>. + +=head2 X<numtoperm>numtopermC<(n,k)> + +generates the C<k>-th permutation (as a +row vector of length C<n>) of the numbers C<1> to C<n>. The number C<k> is taken +modulo C<n!>, i.e.S< >inverse function of X<permtonum>C<permtonum>. + +X<permute>The library syntax is B<permute>C<(n,k)>, where C<n> is a C<long>. + +=head2 X<padicprec>padicprecC<(x,p)> + +absolute C<p>-adic precision of the object C<x>. +This is the minimum precision of the components of C<x>. The result is +C<VERYBIGINT> (C<2^{31}-1> for 32-bit machines or C<2^{63}-1> for 64-bit +machines) if C<x> is an exact object. + +X<padicprec>The library syntax is B<padicprec>C<(x,p)> and the result is a C<long> +integer. + +=head2 X<permtonum>permtonumC<(x)> + +given a permutation C<x> on C<n> elements, +gives the number C<k> such that C<x = numtoperm(n,k)>, i.e.S< >inverse +function of X<numtoperm>C<numtoperm>. + +X<permuteInv>The library syntax is B<permuteInv>C<(x)>. + +=head2 X<precision>precisionC<(x,{n})> + +gives the precision in decimal digits of the +PARI object C<x>. If C<x> is an exact object, the largest single precision +integer is returned. If C<n> is not omitted, creates a new object equal to C<x> +with a new precision C<n>. This is to be understood as follows: + +For exact types, no change. For C<x> a vector or a matrix, the operation +is done componentwise. + +For real C<x>, C<n> is the number of desired significant I<decimal> digits. +If C<n> is smaller than the precision of C<x>, C<x> is truncated, otherwise C<x> +is extended with zeros. + +For C<x> a C<p>-adic or a power series, C<n> is the desired number of +significant C<p>-adic or C<X>-adic digits, where C<X> is the main variable of +C<x>. + +Note that the function C<precision> never changes the type of the result. +In particular it is not possible to use it to obtain a polynomial from a +power series. For that, see C<truncate>. + +X<precision0>The library syntax is B<precision0>C<(x,n)>, where C<n> is a C<long>. Also available are +C<X<ggprecision>B<ggprecision>(x)> (result is a C<GEN>) and C<X<gprec>B<gprec>(x,n)>, where +C<n> is a C<long>. + +=head2 X<random>randomC<({N = 2^{31}})> + +gives a random integer between 0 and +C<N-1>. C<N> can be arbitrary large. This is an internal PARI function and does +not depend on the system's random number generator. Note that the resulting +integer is obtained by means of linear congruences and will not be well +distributed in arithmetic progressions. + +X<genrand>The library syntax is B<genrand>C<(N)>. + +=head2 X<real>realC<(x)> + +real part of C<x>. In the case where C<x> is a quadratic +number, this is the coefficient of C<1> in the ``canonical'' integral basis +C<(1,F<omega>)>. + +X<greal>The library syntax is B<greal>C<(x)>. + +=head2 X<round>roundC<(x,{&e})> + +If C<x> is in B<I<R>>, rounds C<x> to the nearest +integer and sets C<e> to the number of error bits, that is the binary exponent +of the difference between the original and the rounded value (the +``fractional part''). If the exponent of C<x> is too large compared to its +precision (i.e.S< >C<e E<gt> 0>), the result is undefined and an error occurs if C<e> +was not given. + +B<Important remark:> note that, contrary to the other truncation +functions, this function operates on every coefficient at every level of a +PARI object. For example + +S< >C<truncate((2.4*X^2-1.7)/(X)) = 2.4*X,> + +whereas + +S< >C<round((2.4*X^2-1.7)/(X)) = (2*X^2-2)/(X).> + +An important use of C<round> is to get exact results after a long +approximate computation, when theory tells you that the coefficients +must be integers. + +X<grndtoi>The library syntax is B<grndtoi>C<(x,&e)>, where C<e> is a C<long> integer. Also available is +C<X<ground>B<ground>(x)>. + +=head2 X<simplify>simplifyC<(x)> + +this function tries to simplify the object C<x> as +much as it can. The simplifications do not concern rational functions (which +PARI automatically tries to simplify), but type changes. Specifically, a +complex or quadratic number whose imaginary part is exactly equal to 0 +(i.e.S< >not a real zero) is converted to its real part, and a polynomial of +degree zero is converted to its constant term. For all types, this of course +occurs recursively. This function is useful in any case, but in particular +before the use of arithmetic functions which expect integer arguments, and +not for example a complex number of 0 imaginary part and integer real part +(which is however printed as an integer). + +X<simplify>The library syntax is B<simplify>C<(x)>. + +=head2 X<sizebyte>sizebyteC<(x)> + +outputs the total number of bytes occupied by the +tree representing the PARI object C<x>. + +X<taille2>The library syntax is B<taille2>C<(x)> which returns a C<long>. The +function X<taille>B<taille> returns the number of I<words> instead. + +=head2 X<sizedigit>sizedigitC<(x)> + +outputs a quick bound for the number of decimal +digits of (the components of) C<x>, off by at most C<1>. If you want the +exact value, you can use C<length(Str(x))>, which is much slower. + +X<sizedigit>The library syntax is B<sizedigit>C<(x)> which returns a C<long>. + +=head2 X<truncate>truncateC<(x,{&e})> + +truncates C<x> and sets C<e> to the number of +error bits. When C<x> is in B<I<R>>, this means that the part after the decimal +point is chopped away, C<e> is the binary exponent of the difference between +the original and the truncated value (the ``fractional part''). If the +exponent of C<x> is too large compared to its precision (i.e.S< >C<e E<gt> 0>), the +result is undefined and an error occurs if C<e> was not given. The function +applies componentwise on rational functions and vector / matrices; C<e> is +then the maximal number of error bits. + +Note a very special use of C<truncate>: when applied to a power series, it +transforms it into a polynomial or a rational function with denominator +a power of C<X>, by chopping away the C<O(X^k)>. Similarly, when applied to +a C<p>-adic number, it transforms it into an integer or a rational number +by chopping away the C<O(p^k)>. + +X<gcvtoi>The library syntax is B<gcvtoi>C<(x,&e)>, where C<e> is a C<long> integer. Also available is +X<gtrunc>B<gtrunc>C<(x)>. + +=head2 X<valuation>valuationC<(x,p)> + +X<Label se:valuation> computes the highest +exponent of C<p> dividing C<x>. If C<p> is of type integer, C<x> must be an +integer, an integermod whose modulus is divisible by C<p>, a fraction, a +C<q>-adic number with C<q = p>, or a polynomial or power series in which case the +valuation is the minimum of the valuation of the coefficients. + +If C<p> is of type polynomial, C<x> must be of type polynomial or rational +function, and also a power series if C<x> is a monomial. Finally, the +valuation of a vector, complex or quadratic number is the minimum of the +component valuations. + +If C<x = 0>, the result is C<VERYBIGINT> (C<2^{31}-1> for 32-bit machines or +C<2^{63}-1> for 64-bit machines) if C<x> is an exact object. If C<x> is a +C<p>-adic numbers or power series, the result is the exponent of the zero. +Any other type combinations gives an error. + +X<ggval>The library syntax is B<ggval>C<(x,p)>, and the result is a C<long>. + +=head2 X<variable>variableC<(x)> + +gives the main variable of the object C<x>, and +C<p> if C<x> is a C<p>-adic number. Gives an error if C<x> has no variable +associated to it. Note that this function is useful only in GP, since in +library mode the function C<gvar> is more appropriate. + +X<gpolvar>The library syntax is B<gpolvar>C<(x)>. However, in library mode, this function should not be used. +Instead, test whether C<x> is a C<p>-adic (type C<t_PADIC>), in which case C<p> +is in C<x[2]>, or call the function C<B<gvar>(x)> which returns the variable +I<number> of C<x> if it exists, C<BIGINT> otherwise. + +=head1 Transcendental functions + +X<Label se:trans> +As a general rule, which of course in some cases may have exceptions, +transcendental functions operate in the following way: + +C<B<*>> If the argument is either an integer, a real, a rational, a complex +or a quadratic number, it is, if necessary, first converted to a real (or +complex) number using the current X<precision>precision held in the default +C<realprecision>. Note that only exact arguments are converted, while +inexact arguments such as reals are not. + +Under GP this is transparent to the user, but when programming in library +mode, care must be taken to supply a meaningful parameter I<prec> as the +last argument of the function if the first argument is an exact object. +This parameter is ignored if the argument is inexact. + +Note that in library mode the precision argument I<prec> is a word +count including codewords, i.e.S< >represents the length in words of a real +number, while under GP the precision (which is changed by the metacommand +C<\p> or using C<default(realprecision,...)>) is the number of significant +decimal digits. + +Note that some accuracies attainable on 32-bit machines cannot be attained +on 64-bit machines for parity reasons. For example the default GP accuracy +is 28 decimal digits on 32-bit machines, corresponding to I<prec> having +the value 5, but this cannot be attained on 64-bit machines. + +After possible conversion, the function is computed. Note that even if the +argument is real, the result may be complex (e.g.S< >C<acos(2.0)> or +C<acosh(0.0)>). Note also that the principal branch is always chosen. + +C<B<*>> If the argument is an integermod or a C<p>-adic, at present only a +few functions like C<sqrt> (square root), C<sqr> (square), C<log>, +C<exp>, powering, C<teichmuller> (TeichmE<uuml>ller character) and +C<agm> (arithmetic-geometric mean) are implemented. + +Note that in the case of a C<2>-adic number, C<sqr(x)> may not be +identical to C<x*x>: for example if C<x = 1+O(2^5)> and C<y = 1+O(2^5)> then +C<x*y = 1+O(2^5)> while C<sqr(x) = 1+O(2^6)>. Here, C<x * x> yields the +same result as C<sqr(x)> since the two operands are known to be I< +identical>. The same statement holds true for C<p>-adics raised to the power +C<n>, where C<v_p(n) E<gt> 0>. + +B<Remark:> note that if we wanted to be strictly consistent with +the PARI philosophy, we should have C<x*y = (4 mod 8)> and C<sqr(x) = +(4 mod 32)> when both C<x> and C<y> are congruent to C<2> modulo C<4>. +However, since integermod is an exact object, PARI assumes that the modulus +must not change, and the result is hence C<(0 mod 4)> in both cases. On +the other hand, C<p>-adics are not exact objects, hence are treated +differently. + +C<B<*>> If the argument is a polynomial, power series or rational function, +it is, if necessary, first converted to a power series using the current +precision held in the variable X<precdl>C<precdl>. Under GP this again is +transparent to the user. When programming in library mode, however, the +global variable C<precdl> must be set before calling the function if the +argument has an exact type (i.e.S< >not a power series). Here C<precdl> is +not an argument of the function, but a global variable. + +Then the Taylor series expansion of the function around C<X = 0> (where C<X> is +the main variable) is computed to a number of terms depending on the number +of terms of the argument and the function being computed. + +C<B<*>> If the argument is a vector or a matrix, the result is the +componentwise evaluation of the function. In particular, transcendental +functions on square matrices, which are not implemented in the present +version B<2.2.0> (see AppendixS< >B however), will have a slightly different name +if they are implemented some day. + +=head2 ^ + +If C<y> is not of type integer, C<x^y> has the same +effect as C<exp(y*ln(x))>. It can be applied to C<p>-adic numbers as +well as to the more usual types.X<powering> + +X<gpow>The library syntax is B<gpow>C<(x,y,I<prec>)>. + +=head2 Euler + +Euler's constant C<0.57721...>. Note that C<Euler> +is one of the few special reserved names which cannot be used for variables +(the others are C<I> and C<Pi>, as well as all function names). +X<Label se:euler> + +X<mpeuler>The library syntax is B<mpeuler>C<(I<prec>)> where C<I<prec>> I<must> be given. Note that +this creates C<F<gamma>> on the PARI stack, but a copy is also created on the +heap for quicker computations next time the function is called. + +=head2 I + +the complex number C< F<sqrt> {-1}>. + +The library syntax is the global variable C<gi> (of type C<GEN>). + +=head2 Pi + +the constant C<F<Pi>> (C<3.14159...>).X<Label se:pi> + +X<mppi>The library syntax is B<mppi>C<(I<prec>)> where C<I<prec>> I<must> be given. Note that this +creates C<F<Pi>> on the PARI stack, but a copy is also created on the heap for +quicker computations next time the function is called. + +=head2 X<abs>absC<(x)> + +absolute value of C<x> (modulus if C<x> is complex). +Power series and rational functions are not allowed. Contrary to most +transcendental functions, an exact argument is I<not> converted to a real +number before applying C<abs> and an exact result is returned if possible. + + ? abs(-1) + %1 = 1 + ? abs(3/7 + 4/7*I) + %2 = 5/7 + ? abs(1 + I) + %3 = 1.414213562373095048801688724 + +If C<x> is a polynomial, returns C<-x> if the leading coefficient is +real and negative else returns C<x>. For a power series, the constant +coefficient is considered instead. + +X<gabs>The library syntax is B<gabs>C<(x,I<prec>)>. + +=head2 X<acos>acosC<(x)> + +principal branch of C<cos^{-1}(x)>, +i.e.S< >such that C<Re(acos(x)) belongs to [0,F<Pi>]>. If +C<x belongs to B<I<R>>> and C<|x| E<gt> 1>, then C<acos(x)> is complex. + +X<gacos>The library syntax is B<gacos>C<(x,I<prec>)>. + +=head2 X<acosh>acoshC<(x)> + +principal branch of C<cosh^{-1}(x)>, +i.e.S< >such that C<Im(acosh(x)) belongs to [0,F<Pi>]>. If +C<x belongs to B<I<R>>> and C<x E<lt> 1>, then C<acosh(x)> is complex. + +X<gach>The library syntax is B<gach>C<(x,I<prec>)>. + +=head2 X<agm>agmC<(x,y)> + +arithmetic-geometric mean of C<x> and C<y>. In the +case of complex or negative numbers, the principal square root is always +chosen. C<p>-adic or power series arguments are also allowed. Note that +a C<p>-adic agm exists only if C<x/y> is congruent to 1 modulo C<p> (modulo +16 for C<p = 2>). C<x> and C<y> cannot both be vectors or matrices. + +X<agm>The library syntax is B<agm>C<(x,y,I<prec>)>. + +=head2 X<arg>argC<(x)> + +argument of the complex number C<x>, such that +C<-F<Pi> E<lt> arg(x) E<lt>= F<Pi>>. + +X<garg>The library syntax is B<garg>C<(x,I<prec>)>. + +=head2 X<asin>asinC<(x)> + +principal branch of C<sin^{-1}(x)>, i.e.S< >such +that C<Re(asin(x)) belongs to [-F<Pi>/2,F<Pi>/2]>. If C<x belongs to B<I<R>>> and C<|x| E<gt> 1> then +C<asin(x)> is complex. + +X<gasin>The library syntax is B<gasin>C<(x,I<prec>)>. + +=head2 X<asinh>asinhC<(x)> + +principal branch of C<sinh^{-1}(x)>, i.e.S< >such +that C<Im(asinh(x)) belongs to [-F<Pi>/2,F<Pi>/2]>. + +X<gash>The library syntax is B<gash>C<(x,I<prec>)>. + +=head2 X<atan>atanC<(x)> + +principal branch of C<tan^{-1}(x)>, i.e.S< >such +that C<Re(atan(x)) belongs to ]-F<Pi>/2,F<Pi>/2[>. + +X<gatan>The library syntax is B<gatan>C<(x,I<prec>)>. + +=head2 X<atanh>atanhC<(x)> + +principal branch of C<tanh^{-1}(x)>, i.e.S< >such +that C<Im(atanh(x)) belongs to ]-F<Pi>/2,F<Pi>/2]>. If C<x belongs to B<I<R>>> and C<|x| E<gt> 1> then +C<atanh(x)> is complex. + +X<gath>The library syntax is B<gath>C<(x,I<prec>)>. + +=head2 X<bernfrac>bernfracC<(x)> + +Bernoulli numberX<Bernoulli numbers> C<B_x>, +where C<B_0 = 1>, C<B_1 = -1/2>, C<B_2 = 1/6>,..., expressed as a rational number. +The argument C<x> should be of type integer. + +X<bernfrac>The library syntax is B<bernfrac>C<(x)>. + +=head2 X<bernreal>bernrealC<(x)> + +Bernoulli numberX<Bernoulli numbers> +C<B_x>, as C<bernfrac>, but C<B_x> is returned as a real number +(with the current precision). + +X<bernreal>The library syntax is B<bernreal>C<(x,I<prec>)>. + +=head2 X<bernvec>bernvecC<(x)> + +creates a vector containing, as rational numbers, +the X<Bernoulli numbers>Bernoulli numbers C<B_0>, C<B_2>,..., C<B_{2x}>. These Bernoulli +numbers can then be used as follows. Assume that this vector has been put +into a variable, say C<bernint>. Then you can define under GP: + + bern(x) = + { + if (x == 1, return(-1/2)); + if (x < 0 || x % 2, return(0)); + bernint[x/2+1] + } + +and then C<bern(k)> gives the Bernoulli number of index C<k> as a +rational number, exactly as C<bernreal(k)> gives it as a real number. If +you need only a few values, calling C<bernfrac(k)> each time will be much +more efficient than computing the huge vector above. + +X<bernvec>The library syntax is B<bernvec>C<(x)>. + +=head2 X<besseljh>besseljhC<(n,x)> + +C<J>-Bessel function of half integral index. +More precisely, C<besseljh(n,x)> computes C<J_{n+1/2}(x)> where C<n> +must be of type integer, and C<x> is any element of B<I<C>>. In the +present version B<2.2.0>, this function is not very accurate when C<x> is +small. + +X<jbesselh>The library syntax is B<jbesselh>C<(n,x,I<prec>)>. + +=head2 X<besselk>besselkC<(I<nu>,x,{I<flag> = 0})> + +C<K>-Bessel function of index +I<nu> (which can be complex) and argument C<x>. Only real and positive +arguments +C<x> are allowed in the present version B<2.2.0>. If C<I<flag>> is equal to 1, +uses another implementation of this function which is often faster. + +X<kbessel>The library syntax is B<kbessel>C<(I<nu>,x,I<prec>)> and +C<X<kbessel2>B<kbessel2>(I<nu>,x,I<prec>)> respectively. + +=head2 X<cos>cosC<(x)> + +cosine of C<x>. + +X<gcos>The library syntax is B<gcos>C<(x,I<prec>)>. + +=head2 X<cosh>coshC<(x)> + +hyperbolic cosine of C<x>. + +X<gch>The library syntax is B<gch>C<(x,I<prec>)>. + +=head2 X<cotan>cotanC<(x)> + +cotangent of C<x>. + +X<gcotan>The library syntax is B<gcotan>C<(x,I<prec>)>. + +=head2 X<dilog>dilogC<(x)> + +principal branch of the dilogarithm of C<x>, +i.e.S< >analytic continuation of the power series C< F<log> _2(x) = F<sum>_{n E<gt>= 1}x^n/n^2>. + +X<dilog>The library syntax is B<dilog>C<(x,I<prec>)>. + +=head2 X<eint1>eint1C<(x,{n})> + +exponential integral +C<F<int>_x^ oo (e^{-t})/(t)dt> (C<x belongs to B<I<R>>>) + +If C<n> is present, outputs the C<n>-dimensional vector +C<[eint1(x),...,eint1(nx)]> (C<x E<gt>= 0>). This is faster than +repeatedly calling C<eint1(i * x)>. + +X<veceint1>The library syntax is B<veceint1>C<(x,n,I<prec>)>. Also available is +C<X<eint1>B<eint1>(x,I<prec>)>. + +=head2 X<erfc>erfcC<(x)> + +complementary error function +C<(2/ F<sqrt> F<Pi>)F<int>_x^ oo e^{-t^2}dt>. + +X<erfc>The library syntax is B<erfc>C<(x,I<prec>)>. + +=head2 X<eta>etaC<(x,{I<flag> = 0})> + +X<Dedekind>Dedekind's C<F<eta>> function, without the +C<q^{1/24}>. This means the following: if C<x> is a complex number with positive +imaginary part, the result is C<F<prod>_{n = 1}^ oo (1-q^n)>, where +C<q = e^{2iF<Pi> x}>. If C<x> is a power series (or can be converted to a power +series) with positive valuation, the result is C<F<prod>_{n = 1}^ oo (1-x^n)>. + +If C<I<flag> = 1> and C<x> can be converted to a complex number (i.e.S< >is not a power +series), computes the true C<F<eta>> function, including the leading C<q^{1/24}>. + +X<eta>The library syntax is B<eta>C<(x,I<prec>)>. + +=head2 X<exp>expC<(x)> + +exponential of C<x>. +C<p>-adic arguments with positive valuation are accepted. + +X<gexp>The library syntax is B<gexp>C<(x,I<prec>)>. + +=head2 X<gammah>gammahC<(x)> + +gamma function evaluated at the argument +C<x+1/2>. When C<x> is an integer, this is much faster than using +C<gamma(x+1/2)>. + +X<ggamd>The library syntax is B<ggamd>C<(x,I<prec>)>. + +=head2 X<gamma>gammaC<(x)> + +gamma function of C<x>. In the present version +B<2.2.0> the C<p>-adic gamma function is not implemented. + +X<ggamma>The library syntax is B<ggamma>C<(x,I<prec>)>. + +=head2 X<hyperu>hyperuC<(a,b,x)> + +C<U>-confluent hypergeometric function with +parameters C<a> and C<b>. The parameters C<a> and C<b> can be complex but +the present implementation requires C<x> to be positive. + +X<hyperu>The library syntax is B<hyperu>C<(a,b,x,I<prec>)>. + +=head2 X<incgam>incgamC<(s,x,{y})> + +incomplete gamma function. + +C<x> must be positive and C<s> real. The result returned is C<F<int>_x^ oo +e^{-t}t^{s-1}dt>. When C<y> is given, assume (of course without checking!) +that C<y = F<Gamma>(s)>. For small C<x>, this will tremendously speed up the +computation. + +X<incgam>The library syntax is B<incgam>C<(s,x,I<prec>)> and C<X<incgam4>B<incgam4>(s,x,y,I<prec>)>, +respectively. There exist also the functions X<incgam1>B<incgam1> and +X<incgam2>B<incgam2> which are used for internal purposes. + +=head2 X<incgamc>incgamcC<(s,x)> + +complementary incomplete gamma function. + +The arguments C<s> and C<x> must be positive. The result returned is +C<F<int>_0^x e^{-t}t^{s-1}dt>, when C<x> is not too large. + +X<incgam3>The library syntax is B<incgam3>C<(s,x,I<prec>)>. + +=head2 X<log>logC<(x,{I<flag> = 0})> + +principal branch of the natural logarithm of +C<x>, i.e.S< >such that C<Im(ln(x)) belongs to ]-F<Pi>,F<Pi>]>. The result is complex +(with imaginary part equal to C<F<Pi>>) if C<x belongs to B<I<R>>> and C<x E<lt> 0>. + +C<p>-adic arguments are also accepted for C<x>, with the convention that +C< F<ln> (p) = 0>. Hence in particular C< F<exp> ( F<ln> (x))/x> will not in general be +equal to 1 but to a C<(p-1)>-th root of unity (or C<F<+->1> if C<p = 2>) +times a power of C<p>. + +If C<I<flag>> is equal to 1, use an agm formula suggested by Mestre, when C<x> is +real, otherwise identical to C<log>. + +X<glog>The library syntax is B<glog>C<(x,I<prec>)> or C<X<glogagm>B<glogagm>(x,I<prec>)>. + +=head2 X<lngamma>lngammaC<(x)> + +principal branch of the logarithm of the gamma +function of C<x>. Can have much larger arguments than C<gamma> itself. +In the present version B<2.2.0>, the C<p>-adic C<lngamma> function is not +implemented. + +X<glngamma>The library syntax is B<glngamma>C<(x,I<prec>)>. + +=head2 X<polylog>polylogC<(m,x,{I<flag> = 0})> + +one of the different polylogarithms, +depending on I<flag>: + +If C<I<flag> = 0> or is omitted: C<m^th> polylogarithm of C<x>, i.e.S< >analytic +continuation of the power series C<Li_m(x) = F<sum>_{n E<gt>= 1}x^n/n^m>. The +program uses the power series when C<|x|^2 E<lt>= 1/2>, and the power series +expansion in C< F<log> (x)> otherwise. It is valid in a large domain (at least +C<|x| E<lt> 230>), but should not be used too far away from the unit circle since it +is then better to use the functional equation linking the value at C<x> to the +value at C<1/x>, which takes a trivial form for the variant below. Power +series, polynomial, rational and vector/matrix arguments are allowed. + +For the variants to follow we need a notation: let C< F<Re> _m> +denotes C< F<Re> > or C< F<Im> > depending whether C<m> is odd or even. + +If C<I<flag> = 1>: modified C<m^th> polylogarithm of C<x>, called +C<~ D_m(x)> in Zagier, defined for C<|x| E<lt>= 1> by + +S< >C< F<Re> _m(F<sum>_{k = 0}^{m-1} ((- F<log> |x|)^k)/(k!)Li_{m-k}(x) ++((- F<log> |x|)^{m-1})/(m!) F<log> |1-x|).> + +If C<I<flag> = 2>: modified C<m^th> polylogarithm of C<x>, +called C<D_m(x)> in Zagier, defined for C<|x| E<lt>= 1> by + +S< >C< F<Re> _m(F<sum>_{k = 0}^{m-1}((- F<log> |x|)^k)/(k!)Li_{m-k}(x) +-(1)/(2)((- F<log> |x|)^m)/(m!)).> + +If C<I<flag> = 3>: another modified C<m^th> +polylogarithm of C<x>, called C<P_m(x)> in Zagier, defined for C<|x| E<lt>= 1> by + +S< >C< F<Re> _m(F<sum>_{k = 0}^{m-1}(2^kB_k)/(k!)( F<log> |x|)^kLi_{m-k}(x) +-(2^{m-1}B_m)/(m!)( F<log> |x|)^m).> + +These three functions satisfy the functional equation +C<f_m(1/x) = (-1)^{m-1}f_m(x)>. + +X<polylog0>The library syntax is B<polylog0>C<(m,x,I<flag>,I<prec>)>. + +=head2 X<psi>psiC<(x)> + +the C<F<psi>>-function of C<x>, i.e.S< >the +logarithmic derivative C<F<Gamma>'(x)/F<Gamma>(x)>. + +X<gpsi>The library syntax is B<gpsi>C<(x,I<prec>)>. + +=head2 X<sin>sinC<(x)> + +sine of C<x>. + +X<gsin>The library syntax is B<gsin>C<(x,I<prec>)>. + +=head2 X<sinh>sinhC<(x)> + +hyperbolic sine of C<x>. + +X<gsh>The library syntax is B<gsh>C<(x,I<prec>)>. + +=head2 X<sqr>sqrC<(x)> + +square of C<x>. This operation is not completely +straightforward, i.e.S< >identical to C<x * x>, since it can usually be +computed more efficiently (roughly one-half of the elementary +multiplications can be saved). Also, squaring a C<2>-adic number increases +its precision. For example, + + ? (1 + O(2^4))^2 + %1 = 1 + O(2^5) + ? (1 + O(2^4)) * (1 + O(2^4)) + %2 = 1 + O(2^4) + +Note that this function is also called whenever one multiplies two objects +which are known to be I<identical>, e.g.S< >they are the value of the same +variable, or we are computing a power. + + ? x = (1 + O(2^4)); x * x + %3 = 1 + O(2^5) + ? (1 + O(2^4))^4 + %4 = 1 + O(2^6) + +(note the difference between C<%2> and C<%3> above). + +X<gsqr>The library syntax is B<gsqr>C<(x)>. + +=head2 X<sqrt>sqrtC<(x)> + +principal branch of the square root of C<x>, +i.e.S< >such that C<Arg(sqrt(x)) belongs to ]-F<Pi>/2, F<Pi>/2]>, or in other +words such that C< F<Re> (sqrt(x)) E<gt> 0> or C< F<Re> (sqrt(x)) = 0> and +C< F<Im> (sqrt(x)) E<gt>= 0>. If C<x belongs to B<I<R>>> and C<x E<lt> 0>, then the result is +complex with positive imaginary part. + +Integermod a prime and C<p>-adics are allowed as arguments. In that case, +the square root (if it exists) which is returned is the one whose +first C<p>-adic digit (or its unique C<p>-adic digit in the case of +integermods) is in the interval C<[0,p/2]>. When the argument is an +integermod a non-prime (or a non-prime-adic), the result is undefined. + +X<gsqrt>The library syntax is B<gsqrt>C<(x,I<prec>)>. + +=head2 X<sqrtn>sqrtnC<(x,n,{&z})> + +principal branch of the C<n>th root of C<x>, +i.e.S< >such that C<Arg(sqrt(x)) belongs to ]-F<Pi>/n, F<Pi>/n]>. + +Integermod a prime and C<p>-adics are allowed as arguments. + +If C<z> is present, it is set to a suitable root of unity allowing to +recover all the other roots. If it was not possible, z is +set to zero. + +The following script computes all roots in all possible cases: + + sqrtnall(x,n)= + { + local(V,r,z,r2); + r = sqrtn(x,n, &z); + if (!z, error("Impossible case in sqrtn")); + if (type(x) == "t_INTMOD" || type(x)=="t_PADIC" , + r2 = r*z; n = 1; + while (r2!=r, r2*=z;n++)); + V = vector(n); V[1] = r; + for(i=2, n, V[i] = V[i-1]*z); + V + } + addhelp(sqrtnall,"sqrtnall(x,n):compute the vector of nth-roots of x"); + +X<gsqrtn>The library syntax is B<gsqrtn>C<(x,n,&z,I<prec>)>. + +=head2 X<tan>tanC<(x)> + +tangent of C<x>. + +X<gtan>The library syntax is B<gtan>C<(x,I<prec>)>. + +=head2 X<tanh>tanhC<(x)> + +hyperbolic tangent of C<x>. + +X<gth>The library syntax is B<gth>C<(x,I<prec>)>. + +=head2 X<teichmuller>teichmullerC<(x)> + +TeichmE<uuml>ller character of the C<p>-adic number +C<x>. + +X<teich>The library syntax is B<teich>C<(x)>. + +=head2 X<theta>thetaC<(q,z)> + +Jacobi sine theta-function. + +X<theta>The library syntax is B<theta>C<(q,z,I<prec>)>. + +=head2 X<thetanullk>thetanullkC<(q,k)> + +C<k>-th derivative at C<z = 0> of +C<theta(q,z)>. + +X<thetanullk>The library syntax is B<thetanullk>C<(q,k,I<prec>)>, where C<k> is a C<long>. + +=head2 X<weber>weberC<(x,{I<flag> = 0})> + +one of Weber's three C<f> functions. +If C<I<flag> = 0>, returns + +S< >C<f(x) = F<exp> (-iF<Pi>/24).F<eta>((x+1)/2)/F<eta>(x) such that j = (f^{24}-16)^3/f^{24},> + +where C<j> is the elliptic C<j>-invariant (see the function C<ellj>). +If C<I<flag> = 1>, returns + +S< >C<f_1(x) = F<eta>(x/2)/F<eta>(x) such that j = (f_1^{24}+16)^3/f_1^{24}.> + +Finally, if C<I<flag> = 2>, returns + +S< >C<f_2(x) = F<sqrt> {2}F<eta>(2x)/F<eta>(x) such that j = (f_2^{24}+16)^3/f_2^{24}.> + +Note the identities C<f^8 = f_1^8+f_2^8> and C<ff_1f_2 = F<sqrt> 2>. + +X<weber0>The library syntax is B<weber0>C<(x,I<flag>,I<prec>)>, or +C<X<wf>B<wf>(x,I<prec>)>, C<X<wf1>B<wf1>(x,I<prec>)> or +C<X<wf2>B<wf2>(x,I<prec>)>. + +=head2 X<zeta>zetaC<(s)> + +Riemann's zeta functionX<Riemann zeta-function> +C<F<zeta>(s) = F<sum>_{n E<gt>= 1}n^{-s}>, computed using the X<Euler-Maclaurin>Euler-Maclaurin +summation formula, except when C<s> is of type integer, in which case it +is computed using Bernoulli numbersX<Bernoulli numbers> for +C<s E<lt>= 0> or C<s E<gt> 0> and even, and using modular forms for C<s E<gt> 0> and odd. + +X<gzeta>The library syntax is B<gzeta>C<(s,I<prec>)>. + +=head1 Arithmetic functions + +X<Label se:arithmetic> +These functions are by definition functions whose natural domain of +definition is either B<I<Z>> (or C<B<I<Z>>_{ E<gt> 0}>), or sometimes polynomials +over a base ring. Functions which concern polynomials exclusively will be +explained in the next section. The way these functions are used is +completely different from transcendental functions: in general only the types +integer and polynomial are accepted as arguments. If a vector or matrix type +is given, the function will be applied on each coefficient independently. + +In the present version B<2.2.0>, all arithmetic functions in the narrow sense +of the wordS< >--- Euler's totientX<Euler totient function> function, the +X<Moebius>Moebius function, the sums over divisors or powers of divisors +etc.--- call, after trial division by small primes, the same versatile +factoring machinery described under C<factorint>. It includes +X<Shanks SQUFOF>Shanks SQUFOF, X<Pollard Rho>Pollard Rho, X<ECM>ECM and X<MPQS>MPQS stages, and +has an early exit option for the functions X<moebius>B<moebius> and (the integer +function underlying) X<issquarefree>B<issquarefree>. Note that it relies on a (fairly +strong) probabilistic primality test: numbers found to be strong +pseudo-primes after 10 successful trials of the X<Rabin-Miller>Rabin-Miller test are +declared primes. + +=head2 X<addprimes>addprimesC<({x = []})> + +adds the primes contained in the vector +C<x> (or the single integer C<x>) to the table computed upon GP initialization +(by C<pari_init> in library mode), and returns a row vector whose first +entries contain all primes added by the user and whose last entries have been +filled up with 1's. In total the returned row vector has 100 components. +Whenever C<factor> or C<smallfact> is subsequently called, first the +primes in the table computed by C<pari_init> will be checked, and then +the additional primes in this table. If C<x> is empty or omitted, just returns +the current list of extra primes. + +The entries in C<x> are not checked for primality. They need only be positive +integers not divisible by any of the pre-computed primes. It's in fact a nice +trick to add composite numbers, which for example the function +C<factor(x,0)> was not able to factor. In case the message ``impossible +inverse modulo C<E<lt>>I<some integermod>C<E<gt>>'' shows up afterwards, +you have just stumbled over a non-trivial factor. Note that the arithmetic +functions in the narrow sense, like X<eulerphi>B<eulerphi>, do I<not> use this +extra table. + +The present PARI version B<2.2.0> allows up to 100 user-specified +primes to be appended to the table. This limit may be changed +by altering C<NUMPRTBELT> in file C<init.c>. To remove primes from the +list use C<removeprimes>. + +X<addprimes>The library syntax is B<addprimes>C<(x)>. + +=head2 X<bestappr>bestapprC<(x,k)> + +if C<x belongs to B<I<R>>>, finds the best rational +approximation to C<x> with denominator at most equal to C<k> using continued +fractions. + +X<bestappr>The library syntax is B<bestappr>C<(x,k)>. + +=head2 X<bezout>bezoutC<(x,y)> + +finds C<u> and C<v> minimal in a +natural sense such that C<x*u+y*v = gcd(x,y)>. The arguments +must be both integers or both polynomials, and the result is a +row vector with three components C<u>, C<v>, and C<gcd(x,y)>. + +X<vecbezout>The library syntax is B<vecbezout>C<(x,y)> to get the vector, or C<X<gbezout>B<gbezout>(x,y, &u, &v)> +which gives as result the address of the created gcd, and puts +the addresses of the corresponding created objects into C<u> and C<v>. + +=head2 X<bezoutres>bezoutresC<(x,y)> + +as C<bezout>, with the resultant of C<x> and +C<y> replacing the gcd. + +X<vecbezoutres>The library syntax is B<vecbezoutres>C<(x,y)> to get the vector, or C<X<subresext>B<subresext>(x,y, &u, +&v)> which gives as result the address of the created gcd, and puts the +addresses of the corresponding created objects into C<u> and C<v>. + +=head2 X<bigomega>bigomegaC<(x)> + +number of prime divisors of C<|x|> counted with +multiplicity. C<x> must be an integer. + +X<bigomega>The library syntax is B<bigomega>C<(x)>, the result is a C<long>. + +=head2 X<binomial>binomialC<(x,y)> + +X<binomial coefficient>binomial coefficient C<\binom x y>. +Here C<y> must be an integer, but C<x> can be any PARI object. + +X<binome>The library syntax is B<binome>C<(x,y)>, where C<y> must be a C<long>. + +=head2 X<chinese>chineseC<(x,y)> + +if C<x> and C<y> are both integermods or both +polmods, creates (with the same type) a C<z> in the same residue class +as C<x> and in the same residue class as C<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 +C<chinese(x,x) = x> regardless of the type of C<x>; this allows vector +arguments to contain other data, so long as they are identical in both +vectors. + +X<chinois>The library syntax is B<chinois>C<(x,y)>. + +=head2 X<content>contentC<(x)> + +computes the gcd of all the coefficients of C<x>, +when this gcd makes sense. If C<x> is a scalar, this simply returns C<x>. If C<x> +is a polynomial (and by extension a power series), it gives the usual content +of C<x>. If C<x> is a rational function, it gives the ratio of the contents of +the numerator and the denominator. Finally, if C<x> is a vector or a matrix, +it gives the gcd of all the entries. + +X<content>The library syntax is B<content>C<(x)>. + +=head2 X<contfrac>contfracC<(x,{b},{lmax})> + +creates the row vector whose +components are the partial quotients of the X<continued fraction>continued fraction +expansion of C<x>, the number of partial quotients being limited to C<lmax>. +If C<x> is a real number, the expansion stops at the last significant partial +quotient if C<lmax> is omitted. C<x> can also be a rational function or a power +series. + +If a vector C<b> is supplied, the numerators will be equal to the coefficients +of C<b>. The length of the result is then equal to the length of C<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 C<b> is too long, some partial +quotients may not be significant. + +If C<b> is an integer, the command is understood as C<contfrac(x,lmax)>. + +X<contfrac0>The library syntax is B<contfrac0>C<(x,b,lmax)>. Also available are +C<X<gboundcf>B<gboundcf>(x,lmax)>, C<X<gcf>B<gcf>(x)>, or C<X<gcf2>B<gcf2>(b,x)>, where C<lmax> +is a C integer. + +=head2 X<contfracpnqn>contfracpnqnC<(x)> + +when C<x> is a vector or a one-row matrix, C<x> +is considered as the list of partial quotients C<[a_0,a_1,...,a_n]> of a +rational number, and the result is the 2 by 2 matrix +C<[p_n,p_{n-1};q_n,q_{n-1}]> in the standard notation of continued fractions, +so C<p_n/q_n = a_0+1/(a_1+...+1/a_n)...)>. If C<x> is a matrix with two rows +C<[b_0,b_1,...,b_n]> and C<[a_0,a_1,...,a_n]>, this is then considered as a +generalized continued fraction and we have similarly +C<p_n/q_n = 1/b_0(a_0+b_1/(a_1+...+b_n/a_n)...)>. Note that in this case one +usually has C<b_0 = 1>. + +X<pnqn>The library syntax is B<pnqn>C<(x)>. + +=head2 X<core>coreC<(n,{I<flag> = 0})> + +if C<n> is a non-zero integer written as +C<n = df^2> with C<d> squarefree, returns C<d>. If C<I<flag>> is non-zero, +returns the two-element row vector C<[d,f]>. + +X<core0>The library syntax is B<core0>C<(n,I<flag>)>. +Also available are +C<X<core>B<core>(n)> ( = X<core>B<core>C<(n,0)>) and +C<X<core2>B<core2>(n)> ( = X<core>B<core>C<(n,1)>). + +=head2 X<coredisc>corediscC<(n,{I<flag>})> + +if C<n> is a non-zero integer written as +C<n = df^2> with C<d> fundamental discriminant (including 1), returns C<d>. If +C<I<flag>> is non-zero, returns the two-element row vector C<[d,f]>. Note that if +C<n> is not congruent to 0 or 1 modulo 4, C<f> will be a half integer and not +an integer. + +X<coredisc0>The library syntax is B<coredisc0>C<(n,I<flag>)>. +Also available are +C<X<coredisc>B<coredisc>(n)> ( = X<coredisc>B<coredisc>C<(n,0)>) and +C<X<coredisc2>B<coredisc2>(n)> ( = X<coredisc>B<coredisc>C<(n,1)>). + +=head2 X<dirdiv>dirdivC<(x,y)> + +C<x> and C<y> being vectors of perhaps different +lengths but with C<y[1] ! = 0> considered as X<Dirichlet series>Dirichlet series, computes +the quotient of C<x> by C<y>, again as a vector. + +X<dirdiv>The library syntax is B<dirdiv>C<(x,y)>. + +=head2 X<direuler>direulerC<(p = a,b,I<expr>,{c})> + +computes the +X<Dirichlet series>Dirichlet series to C<b> terms of the X<Euler product>Euler product of +expression I<expr> as C<p> ranges through the primes from C<a> to C<b>. +I<expr> must be a polynomial or rational function in another variable +than C<p> (say C<X>) and C<I<expr>(X)> is understood as the Dirichlet +series (or more precisely the local factor) C<I<expr>(p^{-s})>. If C<c> is +present, output only the first C<c> coefficients in the series. + +X<direuler>The library syntax is B<direuler>C<(entree *ep, GEN a, GEN b, char *expr)> + +=head2 X<dirmul>dirmulC<(x,y)> + +C<x> and C<y> being vectors of perhaps different +lengths considered as X<Dirichlet series>Dirichlet series, computes the product of +C<x> by C<y>, again as a vector. + +X<dirmul>The library syntax is B<dirmul>C<(x,y)>. + +=head2 X<divisors>divisorsC<(x)> + +creates a row vector whose components are the +positive divisors of the integer C<x> in increasing order. The factorization +of C<x> (as output by X<factor>C<factor>) can be used instead. + +X<divisors>The library syntax is B<divisors>C<(x)>. + +=head2 X<eulerphi>eulerphiC<(x)> + +Euler's C<F<phi>> +(totient)X<Euler totient function> function of C<|x|>, in other words +C<|(B<I<Z>>/xB<I<Z>>)^*|>. C<x> must be of type integer. + +X<phi>The library syntax is B<phi>C<(x)>. + +=head2 X<factor>factorC<(x,{I<lim> = -1})> + +general factorization function. +If C<x> is of type integer, rational, polynomial or rational function, the +result is a two-column matrix, the first column being the irreducibles +dividing C<x> (prime numbers or polynomials), and the second the exponents. +If C<x> is a vector or a matrix, the factoring is done componentwise (hence +the result is a vector or matrix of two-column matrices). By definition, +C<0> is factored as C<0^1>. + +If C<x> is of type integer or rational, an argument I<lim> can be +added, meaning that we look only for factors up to I<lim>, or to +C<primelimit>, whichever is lowest (except when C<I<lim> = 0> where the +effect is identical to setting C<I<lim> = primelimit>). Hence in this +case, the remaining part is not necessarily prime. See X<factorint>B<factorint> for +more information about the algorithms used. + +The polynomials or rational functions to be factored must have scalar +coefficients. In particular PARI does I<not> know how to factor +multivariate polynomials. + +Note that PARI tries to guess in a sensible way over which ring you want +to factor. Note also that factorization of polynomials is done up to +multiplication by a constant. In particular, the factors of rational +polynomials will have integer coefficients, and the content of a polynomial +or rational function is discarded and not included in the factorization. If +you need it, you can always ask for the content explicitly: + + ? factor(t^2 + 5/2*t + 1) + %1 = + [2*t + 1 1] + + [t + 2 1] + + ? content(t^2 + 5/2*t + 1) + %2 = 1/2 + +See also X<factornf>B<factornf>. + +X<factor0>The library syntax is B<factor0>C<(x,I<lim>)>, where I<lim> is a C integer. +Also available are +C<X<factor>B<factor>(x)> ( = C<X<factor0>B<factor0>(x,-1)>), +C<X<smallfact>B<smallfact>(x)> ( = C<X<factor0>B<factor0>(x,0)>). + +=head2 X<factorback>factorbackC<(f,{nf})> + +C<f> being any factorization, gives back +the factored object. If a second argument C<I<nf>> is supplied, C<f> is +assumed to be a prime ideal factorization in the number field C<I<nf>>. +The resulting ideal is given in HNFX<Hermite normal form> form. + +X<factorback>The library syntax is B<factorback>C<(f,I<nf>)>, where an omitted +C<I<nf>> is entered as C<NULL>. + +=head2 X<factorcantor>factorcantorC<(x,p)> + +factors the polynomial C<x> modulo the +prime C<p>, using distinct degree plus +X<Cantor-Zassenhaus>Cantor-ZassenhausX<Zassenhaus>. The coefficients of C<x> must be +operation-compatible with C<B<I<Z>>/pB<I<Z>>>. The result is a two-column matrix, the +first column being the irreducible polynomials dividing C<x>, and the second +the exponents. If you want only the I<degrees> of the irreducible +polynomials (for example for computing an C<L>-function), use +C<factormod(x,p,1)>. Note that the C<factormod> algorithm is +usually faster than C<factorcantor>. + +X<factcantor>The library syntax is B<factcantor>C<(x,p)>. + +=head2 X<factorff>factorffC<(x,p,a)> + +factors the polynomial C<x> in the field +C<B<I<F>>_q> defined by the irreducible polynomial C<a> over C<B<I<F>>_p>. The +coefficients of C<x> must be operation-compatible with C<B<I<Z>>/pB<I<Z>>>. The result +is a two-column matrix, the first column being the irreducible polynomials +dividing C<x>, and the second the exponents. It is recommended to use for +the variable of C<a> (which will be used as variable of a polmod) a name +distinct from the other variables used, so that a C<lift()> of the +result will be legible. If all the coefficients of C<x> are in C<B<I<F>>_p>, a much faster algorithm is applied, using the computation of isomorphisms between finite fields. + +X<factmod9>The library syntax is B<factmod9>C<(x,p,a)>. + +=head2 X<factorial>factorialC<(x)> or C<x!> + +factorial of C<x>. The expression C<x!> +gives a result which is an integer, while C<factorial(x)> gives a real +number. + +X<mpfact>The library syntax is B<mpfact>C<(x)> for C<x!> and +C<X<mpfactr>B<mpfactr>(x,I<prec>)> for C<factorial(x)>. C<x> must be a C<long> +integer and not a PARI integer. + +=head2 X<factorint>factorintC<(n,{I<flag> = 0})> + +factors the integer n using a +combination of the X<Shanks SQUFOF>Shanks SQUFOF and X<Pollard Rho>Pollard Rho method (with +modifications due to Brent), X<Lenstra>Lenstra's X<ECM>ECM (with modifications by +Montgomery), and X<MPQS>MPQS (the latter adapted from the X<LiDIA>LiDIA code +with the kind permission of the LiDIA maintainers), as well as a search for +pure powers with exponentsC< E<lt>= 10>. The output is a two-column matrix as for +C<factor>. + +This gives direct access to the integer factoring engine called by most +arithmetical functions. I<flag> is optional; its binary digits mean 1: avoid +MPQS, 2: skip first stage ECM (we may still fall back to it later), 4: avoid +Rho and SQUFOF, 8: don't run final ECM (as a result, a huge composite may be +declared to be prime). Note that a (strong) probabilistic primality test is +used; thus composites might (very rarely) not be detected. + +The machinery underlying this function is still in a somewhat experimental +state, but should be much faster on average than pure ECM as used by all +PARI versions up to 2.0.8, at the expense of heavier memory use. You are +invited to play with the flag settings and watch the internals at work by +using GP's X<debuglevel>C<debuglevel> default parameter (level 3 shows just the +outline, 4 turns on time keeping, 5 and above show an increasing amount +of internal details). If you see anything funny happening, please let +us know. + +X<factorint>The library syntax is B<factorint>C<(n,I<flag>)>. + +=head2 X<factormod>factormodC<(x,p,{I<flag> = 0})> + +factors the polynomial C<x> modulo +the prime integer C<p>, using X<Berlekamp>Berlekamp. The coefficients of C<x> must be +operation-compatible with C<B<I<Z>>/pB<I<Z>>>. The result is a two-column matrix, the +first column being the irreducible polynomials dividing C<x>, and the second +the exponents. If C<I<flag>> is non-zero, outputs only the I<degrees> of the +irreducible polynomials (for example, for computing an C<L>-function). A +different algorithm for computing the mod C<p> factorization is +C<factorcantor> which is sometimes faster. + +X<factormod>The library syntax is B<factormod>C<(x,p,I<flag>)>. Also available are +C<X<factmod>B<factmod>(x,p)> (which is equivalent to C<X<factormod>B<factormod>(x,p,0)>) and +C<X<simplefactmod>B<simplefactmod>(x,p)> ( = C<X<factormod>B<factormod>(x,p,1)>). + +=head2 X<fibonacci>fibonacciC<(x)> + +C<x^{th}> Fibonacci number. + +X<fibo>The library syntax is B<fibo>C<(x)>. C<x> must be a C<long>. + +=head2 X<ffinit>ffinitC<(p,n,{v = x})> + +computes a monic polynomial of degree +C<n> which is irreducible over C<B<I<F>>_p>. For instance if +C<P = ffinit(3,2,y)>, you can represent elements in C<B<I<F>>_{3^2}> as polmods +modulo C<P>. + +X<ffinit>The library syntax is B<ffinit>C<(p,n,v)>, where C<v> is a variable number. + +=head2 X<gcd>gcdC<(x,y,{I<flag> = 0})> + +creates the greatest common divisor of C<x> +and C<y>. C<x> and C<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, C<gcd> is not commutative. + +If C<I<flag> = 0>, use X<Euclid>Euclid's algorithm. + +If C<I<flag> = 1>, use the modular gcd algorithm (C<x> and C<y> have to be +polynomials, with integer coefficients). + +If C<I<flag> = 2>, use the X<subresultant algorithm>subresultant algorithm. + +X<gcd0>The library syntax is B<gcd0>C<(x,y,I<flag>)>. Also available are +C<X<ggcd>B<ggcd>(x,y)>, C<X<modulargcd>B<modulargcd>(x,y)>, and C<X<srgcd>B<srgcd>(x,y)> +corresponding to C<I<flag> = 0>, C<1> and C<2> respectively. + +=head2 X<hilbert>hilbertC<(x,y,{p})> + +X<Hilbert symbol>Hilbert symbol of C<x> and C<y> modulo +C<p>. If C<x> and C<y> are of type integer or fraction, an explicit third +parameter C<p> must be supplied, C<p = 0> meaning the place at infinity. +Otherwise, C<p> needs not be given, and C<x> and C<y> can be of compatible types +integer, fraction, real, integermod a prime (result is undefined if the +modulus is not prime), or C<p>-adic. + +X<hil>The library syntax is B<hil>C<(x,y,p)>. + +=head2 X<isfundamental>isfundamentalC<(x)> + +true (1) if C<x> is equal to 1 or to the +discriminant of a quadratic field, false (0) otherwise. + +X<gisfundamental>The library syntax is B<gisfundamental>C<(x)>, but the +simpler function C<X<isfundamental>B<isfundamental>(x)> which returns a C<long> +should be used if C<x> is known to be of type integer. + +=head2 X<isprime>isprimeC<(x,{I<flag> = 0})> + +if C<I<flag> = 0> (default), true (1) if C<x> is a strong pseudo-prime +for 10 randomly chosen bases, false (0) otherwise. + +If C<I<flag> = 1>, use Pocklington-Lehmer ``P-1'' test. true (1) if C<x> is +prime, false (0) otherwise. + +If C<I<flag> = 2>, use Pocklington-Lehmer ``P-1'' test and output a primality +certificate as follows: return 0 if C<x> is composite, 1 if C<x> is a +small prime (currently strictly less than C<341 550 071 728 321>), and +a matrix if C<x> is a large prime. The matrix has three columns. The +first contains the prime factors C<p>, the second the corresponding +elements C<a_p> as in PropositionS< >8.3.1 in GTMS< >138, and the third the +output of isprime(p,2). + +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. + +X<gisprime>The library syntax is B<gisprime>C<(x,I<flag>)>, but the simpler function C<X<isprime>B<isprime>(x)> +which returns a C<long> should be used if C<x> is known to be of +type integer. Also available is C<X<plisprime>B<plisprime>(N,I<flag>)>, +corresponding to C<X<gisprime>B<gisprime>(x,I<flag>+1)> if C<x> is known to be of +type integer. + +=head2 X<ispseudoprime>ispseudoprimeC<(x)> + +true (1) if C<x> is a strong +pseudo-prime for a randomly chosen base, false (0) otherwise. + +X<gispsp>The library syntax is B<gispsp>C<(x)>, but the +simpler function C<X<ispsp>B<ispsp>(x)> which returns a C<long> +should be used if C<x> is known to be of type integer. + +=head2 X<issquare>issquareC<(x,{&n})> + +true (1) if C<x> is square, false (0) if +not. C<x> can be of any type. If C<n> is given and an exact square root had to +be computed in the checking process, puts that square root in C<n>. This is in +particular the case when C<x> is an integer or a polynomial. This is I<not> +the case for intmods (use quadratic reciprocity) or series (only check the +leading coefficient). + +X<gcarrecomplet>The library syntax is B<gcarrecomplet>C<(x,&n)>. Also available is C<X<gcarreparfait>B<gcarreparfait>(x)>. + +=head2 X<issquarefree>issquarefreeC<(x)> + +true (1) if C<x> is squarefree, false (0) if not. +Here C<x> can be an integer or a polynomial. + +X<gissquarefree>The library syntax is B<gissquarefree>C<(x)>, but the simpler function C<X<issquarefree>B<issquarefree>(x)> +which returns a C<long> should be used if C<x> is known to be of type +integer. This X<issquarefree>B<issquarefree> is just the square of the +X<Moebius>Moebius function, and is computed as a multiplicative +arithmetic function much like the latter. + +=head2 X<kronecker>kroneckerC<(x,y)> + +KroneckerX<Kronecker symbol>X<Legendre symbol> +(i.e.S< >generalized Legendre) symbol C<((x)/(y))>. C<x> and C<y> +must be of type integer. + +X<kronecker>The library syntax is B<kronecker>C<(x,y)>, the result (C<0> or C<F<+-> 1>) is a C<long>. + +=head2 X<lcm>lcmC<(x,y)> + +least common multiple of C<x> and C<y>, i.e.S< >such +that C<lcm(x,y)*gcd(x,y) = abs(x*y)>. + +X<glcm>The library syntax is B<glcm>C<(x,y)>. + +=head2 X<moebius>moebiusC<(x)> + +X<Moebius>Moebius C<F<mu>>-function of C<|x|>. C<x> must +be of type integer. + +X<mu>The library syntax is B<mu>C<(x)>, the result (C<0> or C<F<+-> 1>) is a C<long>. + +=head2 X<nextprime>nextprimeC<(x)> + +finds the smallest prime greater than or +equal to C<x>. C<x> can be of any real type. Note that if C<x> is a prime, +this function returns C<x> and not the smallest prime strictly larger than C<x>. + +X<nextprime>The library syntax is B<nextprime>C<(x)>. + +=head2 X<numdiv>numdivC<(x)> + +number of divisors of C<|x|>. C<x> must be of type +integer, and the result is a C<long>. + +X<numbdiv>The library syntax is B<numbdiv>C<(x)>. + +=head2 X<omega>omegaC<(x)> + +number of distinct prime divisors of C<|x|>. C<x> +must be of type integer. + +X<omega>The library syntax is B<omega>C<(x)>, the result is a C<long>. + +=head2 X<precprime>precprimeC<(x)> + +finds the largest prime less than or equal to +C<x>. C<x> can be of any real type. Returns 0 if C<x E<lt>= 1>. +Note that if C<x> is a prime, this function returns C<x> and not the largest +prime strictly smaller than C<x>. + +X<precprime>The library syntax is B<precprime>C<(x)>. + +=head2 X<prime>primeC<(x)> + +the C<x^{th}> prime number, which must be among +the precalculated primes. + +X<prime>The library syntax is B<prime>C<(x)>. C<x> must be a C<long>. + +=head2 X<primes>primesC<(x)> + +creates a row vector whose components +are the first C<x> prime numbers, which must be among the precalculated primes. + +X<primes>The library syntax is B<primes>C<(x)>. C<x> must be a C<long>. + +=head2 X<qfbclassno>qfbclassnoC<(x,{I<flag> = 0})> + +class number of the quadratic field +of discriminant C<x>. In the present version B<2.2.0>, a simple algorithm is used +for C<x E<gt> 0>, so C<x> should not be too large (say C<x E<lt> 10^7>) for the time to be +reasonable. On the other hand, for C<x E<lt> 0> one can reasonably compute +classno(C<x>) for C<|x| E<lt> 10^{25}>, since the method used is X<Shanks>Shanks' method +which is in C<O(|x|^{1/4})>. For larger values of C<|D|>, see +C<quadclassunit>. + +If C<I<flag> = 1>, compute the class number using X<Euler product>Euler products and the +functional equation. However, it is in C<O(|x|^{1/2})>. + +B<Important warning.> For C<D E<lt> 0>, this function often gives +incorrect results when the class group is non-cyclic, because the authors +were too lazy to implement X<Shanks>Shanks' method completely. It is therefore +strongly recommended to use either the version with C<I<flag> = 1>, the function +C<qfbhclassno(-x)> if C<x> is known to be a fundamental discriminant, or +the function C<quadclassunit>. + +X<qfbclassno0>The library syntax is B<qfbclassno0>C<(x,I<flag>)>. Also available are +C<X<classno>B<classno>(x)> ( = C<X<qfbclassno>B<qfbclassno>(x)>), +C<X<classno2>B<classno2>(x)> ( = C<X<qfbclassno>B<qfbclassno>(x,1)>), and finally +there exists the function C<X<hclassno>B<hclassno>(x)> which computes the class +number of an imaginary quadratic field by counting reduced forms, an C<O(|x|)> +algorithm. See also C<qfbhclassno>. + +=head2 X<qfbcompraw>qfbcomprawC<(x,y)> + +X<composition>composition of the binary quadratic forms +C<x> and C<y>, without X<reduction>reduction of the result. This is useful e.g.S< >to +compute a generating element of an ideal. + +X<compraw>The library syntax is B<compraw>C<(x,y)>. + +=head2 X<qfbhclassno>qfbhclassnoC<(x)> + +X<Hurwitz class number>Hurwitz class number of C<x>, where C<x> is +non-negative and congruent to 0 or 3 modulo 4. See also C<qfbclassno>. + +X<hclassno>The library syntax is B<hclassno>C<(x)>. + +=head2 X<qfbnucomp>qfbnucompC<(x,y,l)> + +X<composition>composition of the primitive positive +definite binary quadratic forms C<x> and C<y> using the NUCOMP and NUDUPL +algorithms of X<Shanks>Shanks (E<agrave> la Atkin). C<l> is any positive constant, +but for optimal speed, one should take C<l = |D|^{1/4}>, where C<D> is the common +discriminant of C<x> and C<y>. When C<x> and C<y> do not have the same +discriminant, the result is undefined. + +X<nucomp>The library syntax is B<nucomp>C<(x,y,l)>. The auxiliary function +C<X<nudupl>B<nudupl>(x,l)> should be used instead for speed when C<x = y>. + +=head2 X<qfbnupow>qfbnupowC<(x,n)> + +C<n>-th power of the primitive positive definite +binary quadratic form C<x> using the NUCOMP and NUDUPL algorithms (see +C<qfbnucomp>). + +X<nupow>The library syntax is B<nupow>C<(x,n)>. + +=head2 X<qfbpowraw>qfbpowrawC<(x,n)> + +C<n>-th power of the binary quadratic form +C<x>, computed without doing any X<reduction>reduction (i.e.S< >using C<qfbcompraw>). +Here C<n> must be non-negative and C<n E<lt> 2^{31}>. + +X<powraw>The library syntax is B<powraw>C<(x,n)> where C<n> must be a C<long> +integer. + +=head2 X<qfbprimeform>qfbprimeformC<(x,p)> + +prime binary quadratic form of discriminant +C<x> whose first coefficient is the prime number C<p>. By abuse of notation, +C<p = 1> is a valid special case which returns the unit form. Returns an +error if C<x> is not a quadratic residue mod C<p>. In the case where C<x E<gt> 0>, +the ``distance'' component of the form is set equal to zero according to +the current precision. + +X<primeform>The library syntax is B<primeform>C<(x,p,I<prec>)>, where the third variable C<I<prec>> is a +C<long>, but is only taken into account when C<x E<gt> 0>. + +=head2 X<qfbred>qfbredC<(x,{I<flag> = 0},{D},{I<isqrtD>},{I<sqrtD>})> + +reduces the binary quadratic form C<x> (updating Shanks's distance function +if C<x> is indefinite). The binary digits of C<I<flag>> are toggles meaning + +S< >S< >1: perform a single X<reduction>reduction step + +S< >S< >2: don't update X<Shanks>Shanks's distance + +C<D>, I<isqrtD>, I<sqrtD>, if present, supply the values of the +discriminant, C<\lfloor F<sqrt> {D}\rfloor>, and C< F<sqrt> {D}> respectively +(no checking is done of these facts). If C<D E<lt> 0> these values are useless, +and all references to Shanks's distance are irrelevant. + +X<qfbred0>The library syntax is B<qfbred0>C<(x,I<flag>,D,I<isqrtD>,I<sqrtD>)>. Use C<NULL> +to omit any of C<D>, I<isqrtD>, I<sqrtD>. + +Also available are + +C<X<redimag>B<redimag>(x)> ( = C<X<qfbred>B<qfbred>(x)> where C<x> is definite), + +and for indefinite forms: + +C<X<redreal>B<redreal>(x)> ( = C<X<qfbred>B<qfbred>(x)>), + +C<X<rhoreal>B<rhoreal>(x)> ( = C<X<qfbred>B<qfbred>(x,1)>), + +C<X<redrealnod>B<redrealnod>(x,sq)> ( = C<X<qfbred>B<qfbred>(x,2,,isqrtD)>), + +C<X<rhorealnod>B<rhorealnod>(x,sq)> ( = C<X<qfbred>B<qfbred>(x,3,,isqrtD)>). + +=head2 X<quadclassunit>quadclassunitC<(D,{I<flag> = 0},{I<tech> = []})> + +X<Buchmann-McCurley>Buchmann-McCurley's sub-exponential algorithm for computing the class +group of a quadratic field of discriminant C<D>. If C<D> is not fundamental, +the function may or may not be defined, but usually is, and often gives the +right answer (a warning is issued). The more general function X<bnrinit>C<bnrinit> +should be used to compute the class group of an order. + +This function should be used instead of C<qfbclassno> or C<quadregula> +when C<D E<lt> -10^{25}>, C<D E<gt> 10^{10}>, or when the I<structure> is wanted. + +If C<I<flag>> is non-zero I<and> C<D E<gt> 0>, computes the narrow class group and +regulator, instead of the ordinary (or wide) ones. In the current version +B<2.2.0>, this doesn't work at allS< >: use the general function X<bnfnarrow>C<bnfnarrow>. + +Optional parameter I<tech> is a row vector of the form +C<[c_1,c_2]>, where C<c_1> and C<c_2> are positive real numbers which +control the execution time and the stack size. To get maximum speed, +set C<c_2 = c>. To get a rigorous result (under X<GRH>GRH) you must take +C<c_2 = 6>. Reasonable values for C<c> are between C<0.1> and C<2>. + +The result of this function is a vector C<v> with 4 components if C<D E<lt> 0>, and +C<5> otherwise. The correspond respectively to + +C<B<*>> C<v[1]>S< >: the class number + +C<B<*>> C<v[2]>S< >: a vector giving the structure of the class group as a +product of cyclic groups; + +C<B<*>> C<v[3]>S< >: a vector giving generators of those cyclic groups (as +binary quadratic forms). + +C<B<*>> C<v[4]>S< >: (omitted if C<D E<lt> 0>) the regulator, computed to an +accuracy which is the maximum of an internal accuracy determined by the +program and the current default (note that once the regulator is known to a +small accuracy it is trivial to compute it to very high accuracy, see the +tutorial). + +C<B<*>> C<v[5]>S< >: a measure of the correctness of the result. If it is +close to 1, the result is correct (under X<GRH>GRH). If it is close to a +larger integer, this shows that the class number is off by a factor equal +to this integer, and you must start again with a larger value for C<c_1> or +a different random seed. In this case, a warning message is printed. + +X<quadclassunit0>The library syntax is B<quadclassunit0>C<(D,I<flag>,tech)>. Also available are +C<X<buchimag>B<buchimag>(D,c_1,c_2)> and C<X<buchreal>B<buchreal>(D,I<flag>,c_1,c_2)>. + +=head2 X<quaddisc>quaddiscC<(x)> + +discriminant of the quadratic field +C<B<I<Q>>( F<sqrt> {x})>, where C<x belongs to B<I<Q>>>. + +X<quaddisc>The library syntax is B<quaddisc>C<(x)>. + +=head2 X<quadhilbert>quadhilbertC<(D,{I<flag> = 0})> + +relative equation defining the +X<Hilbert class field>Hilbert class field of the quadratic field of discriminant C<D>. +If C<I<flag>> is non-zero +and C<D E<lt> 0>, outputs C<[I<form>,I<root>(I<form>)]> (to be used for +constructing subfields). If C<I<flag>> is non-zero and C<D E<gt> 0>, try hard to +get the best modulus. +Uses complex multiplication in the imaginary case and X<Stark units>Stark units +in the real case. + +X<quadhilbert>The library syntax is B<quadhilbert>C<(D,I<flag>,I<prec>)>. + +=head2 X<quadgen>quadgenC<(x)> + +creates the quadratic numberX<omega> +C<F<omega> = (a+ F<sqrt> {x})/2> where C<a = 0> if C<x = 0 mod 4>, +C<a = 1> if C<x = 1 mod 4>, so that C<(1,F<omega>)> is an integral basis for +the quadratic order of discriminant C<x>. C<x> must be an integer congruent to +0 or 1 modulo 4. + +X<quadgen>The library syntax is B<quadgen>C<(x)>. + +=head2 X<quadpoly>quadpolyC<(D,{v = x})> + +creates the ``canonical'' quadratic +polynomial (in the variable C<v>) corresponding to the discriminant C<D>, +i.e.S< >the minimal polynomial of C<quadgen(x)>. C<D> must be an integer +congruent to 0 or 1 modulo 4. + +X<quadpoly0>The library syntax is B<quadpoly0>C<(x,v)>. + +=head2 X<quadray>quadrayC<(D,f,{I<flag> = 0})> + +relative equation for the ray class +field of conductor C<f> for the quadratic field of discriminant C<D> (which +can also be a C<bnf>), using analytic methods. + +For C<D E<lt> 0>, uses the C<F<sigma>> function. C<I<flag>> has the following meaning: if +it's an odd integer, outputs instead the vector of C<[I<ideal>, +I<corresponding root>]>. It can also be a two-component vector +C<[F<lambda>,I<flag>]>, where I<flag> is as above and C<F<lambda>> is the technical +element of C<bnf> necessary for Schertz's method. In that case, returns +0 if C<F<lambda>> is not suitable. + +For C<D E<gt> 0>, uses Stark's conjecture. If C<I<flag>> is non-zero, try hard to +get the best modulus. The function may fail with the following message + + "Cannot find a suitable modulus in FindModulus" + +See X<bnrstark>C<bnrstark> for more details about the real case. + +X<quadray>The library syntax is B<quadray>C<(D,f,I<flag>)>. + +=head2 X<quadregulator>quadregulatorC<(x)> + +regulator of the quadratic field of +positive discriminant C<x>. Returns an error if C<x> is not a discriminant +(fundamental or not) or if C<x> is a square. See also C<quadclassunit> if +C<x> is large. + +X<regula>The library syntax is B<regula>C<(x,I<prec>)>. + +=head2 X<quadunit>quadunitC<(x)> + +fundamental unitX<fundamental units> of the +real quadratic field C<B<I<Q>>( F<sqrt> x)> where C<x> is the positive discriminant +of the field. If C<x> is not a fundamental discriminant, this probably gives +the fundamental unit of the corresponding order. C<x> must be of type +integer, and the result is a quadratic number. + +X<fundunit>The library syntax is B<fundunit>C<(x)>. + +=head2 X<removeprimes>removeprimesC<({x = []})> + +removes the primes listed in C<x> from +the prime number table. In particular C<removeprimes(addprimes)> empties +the extra prime table. C<x> can also be a single integer. List the current +extra primes if C<x> is omitted. + +X<removeprimes>The library syntax is B<removeprimes>C<(x)>. + +=head2 X<sigma>sigmaC<(x,{k = 1})> + +sum of the C<k^{th}> powers of the +positive divisors of C<|x|>. C<x> must be of type integer. + +X<sumdiv>The library syntax is B<sumdiv>C<(x)> ( = C<X<sigma>B<sigma>(x)>) or C<X<gsumdivk>B<gsumdivk>(x,k)> ( = +C<X<sigma>B<sigma>(x,k)>), where C<k> is a C long integer. + +=head2 X<sqrtint>sqrtintC<(x)> + +integer square root of C<x>, which must be of PARI +type integer. The result is non-negative and rounded towards zero. A +negative C<x> is allowed, and the result in that case is C<I*sqrtint(-x)>. + +X<racine>The library syntax is B<racine>C<(x)>. + +=head2 X<znlog>znlogC<(x,g)> + +C<g> must be a primitive root mod a prime C<p>, and +the result is the discrete log of C<x> in the multiplicative group +C<(B<I<Z>>/pB<I<Z>>)^*>. This function using a simple-minded baby-step/giant-step +approach and requires C<O( F<sqrt> {p})> storage, hence it cannot be used for +C<p> greater than about C<10^{13}>. + +X<znlog>The library syntax is B<znlog>C<(x,g)>. + +=head2 X<znorder>znorderC<(x)> + +C<x> must be an integer mod C<n>, and the result is the +order of C<x> in the multiplicative group C<(B<I<Z>>/nB<I<Z>>)^*>. Returns an error if C<x> +is not invertible. + +X<order>The library syntax is B<order>C<(x)>. + +=head2 X<znprimroot>znprimrootC<(x)> + +returns a primitive root of C<x>, where C<x> +is a prime power. + +X<gener>The library syntax is B<gener>C<(x)>. + +=head2 X<znstar>znstarC<(n)> + +gives the structure of the multiplicative group +C<(B<I<Z>>/nB<I<Z>>)^*> as a 3-component row vector C<v>, where C<v[1] = F<phi>(n)> is the +order of that group, C<v[2]> is a C<k>-component row-vector C<d> of integers +C<d[i]> such that C<d[i] E<gt> 1> and C<d[i] | d[i-1]> for C<i E<gt>= 2> and +C<(B<I<Z>>/nB<I<Z>>)^* ~ F<prod>_{i = 1}^k(B<I<Z>>/d[i]B<I<Z>>)>, and C<v[3]> is a C<k>-component row +vector giving generators of the image of the cyclic groups C<B<I<Z>>/d[i]B<I<Z>>>. + +X<znstar>The library syntax is B<znstar>C<(n)>. + +=head1 Functions related to elliptic curves + +We have implemented a number of functions which are useful for number +theorists working on elliptic curves. We always use X<Tate>Tate's notations. +The functions assume that the curve is given by a general Weierstrass +modelX<Weierstrass equation> + +S< >C< +y^2+a_1xy+a_3y = x^3+a_2x^2+a_4x+a_6, +> + +where a priori the C<a_i> can be of any scalar type. This curve can be +considered as a five-component vector C<E = [a1,a2,a3,a4,a6]>. Points on +C<E> are represented as two-component vectors C<[x,y]>, except for the +point at infinity, i.e.S< >the identity element of the group law, represented by +the one-component vector C<[0]>. + +It is useful to have at one's disposal more information. This is given by +the function X<ellinit>C<ellinit> (see there), which usually gives a 19 component +vector (which we will call a long vector in this section). If a specific flag +is added, a vector with only 13 component will be output (which we will call +a medium vector). A medium vector just gives the first 13 components of the +long vector corresponding to the same curve, but is of course faster to +compute. The following X<member functions>member functions are available to deal with the +output of C<ellinit>: + +S< > C<a1>--C<a6>, C<b2>--C<b8>, C<c4>--C<c6> : +coefficients of the elliptic curve. + +S< > X<area>C<area> : volume of the complex lattice defining C<E>. + +S< > X<disc>C<disc> : discriminant of the curve. + +S< > X<j>C<j> : C<j>-invariant of the curve. + +S< > X<omega>C<omega> : C<[F<omega>_1,F<omega>_2]>, periods forming a basis of +the complex lattice defining C<E> (C<F<omega>_1> is the + +S< > real period, and C<F<omega>_2/F<omega>_1> belongs to +PoincarE<eacute>'s half-plane). + +S< > X<eta>C<eta> : quasi-periods C<[F<eta>_1, F<eta>_2]>, such that +C<F<eta>_1F<omega>_2-F<eta>_2F<omega>_1 = iF<Pi>>. + +S< > X<roots>C<roots> : roots of the associated Weierstrass equation. + +S< > X<tate>C<tate> : C<[u^2,u,v]> in the notation of Tate. + +S< > X<w>C<w> : Mestre's C<w> (this is technical). + +Their use is best described by an example: assume that C<E> was output by +C<ellinit>, then typing C<E.disc> will retrieve the curve's +discriminant. The member functions C<area>, C<eta> and C<omega> are +only available for curves over B<I<Q>>. Conversely, C<tate> and C<w> are +only available for curves defined over C<B<I<Q>>_p>. + +Some functions, in particular those relative to height computations (see +C<ellheight>) require also that the curve be in minimal Weierstrass +form. This is achieved by the function C<ellglobalred>. + +All functions related to elliptic curves share the prefix C<ell>, and the +precise curve we are interested in is always the first argument, in either +one of the three formats discussed above, unless otherwise specified. For +instance, in functions which do not use the extra information given by long +vectors, the curve can be given either as a five-component vector, or by one +of the longer vectors computed by C<ellinit>. + +=head2 X<elladd>elladdC<(E,z1,z2)> + +sum of the points C<z1> and C<z2> on the +elliptic curve corresponding to the vector C<E>. + +X<addell>The library syntax is B<addell>C<(E,z1,z2)>. + +=head2 X<ellak>ellakC<(E,n)> + +computes the coefficient C<a_n> of the +C<L>-function of the elliptic curve C<E>, i.e.S< >in principle coefficients of a +newform of weight 2 assuming X<Taniyama-Weil conjecture>Taniyama-Weil conjecture (which is now +known to hold in full generality thanks to the work of X<Breuil>Breuil, +X<Conrad>Conrad, X<Diamond>Diamond, X<Taylor>Taylor and X<Wiles>Wiles). C<E> must be a +medium or long vector of the type given by C<ellinit>. For this function +to work for every C<n> and not just those prime to the conductor, C<E> must +be a minimal Weierstrass equation. If this is not the case, use the +function C<ellglobalred> first before using C<ellak>. + +X<akell>The library syntax is B<akell>C<(E,n)>. + +=head2 X<ellan>ellanC<(E,n)> + +computes the vector of the first C<n> C<a_k> +corresponding to the elliptic curve C<E>. All comments in C<ellak> +description remain valid. + +X<anell>The library syntax is B<anell>C<(E,n)>, where C<n> is a C integer. + +=head2 X<ellap>ellapC<(E,p,{I<flag> = 0})> + +computes the C<a_p> corresponding to the +elliptic curve C<E> and the prime number C<p>. These are defined by the +equation C<#E(B<I<F>>_p) = p+1 - a_p>, where C<#E(B<I<F>>_p)> stands for the number +of points of the curve C<E> over the finite field C<B<I<F>>_p>. When C<I<flag>> is C<0>, +this uses the baby-step giant-step method and a trick due to Mestre. This +runs in time C<O(p^{1/4})> and requires C<O(p^{1/4})> storage, hence becomes +unreasonable when C<p> has about 30 digits. + +If C<I<flag>> is C<1>, computes the C<a_p> as a sum of Legendre symbols. This is +slower than the previous method as soon as C<p> is greater than 100, say. + +No checking is done that C<p> is indeed prime. C<E> must be a medium or long +vector of the type given by C<ellinit>, defined over B<I<Q>>, C<B<I<F>>_p> or +C<B<I<Q>>_p>. C<E> must be given by a Weierstrass equation minimal at C<p>. + +X<ellap0>The library syntax is B<ellap0>C<(E,p,I<flag>)>. Also available are C<X<apell>B<apell>(E,p)>, corresponding +to C<I<flag> = 0>, and C<X<apell2>B<apell2>(E,p)> (C<I<flag> = 1>). + +=head2 X<ellbil>ellbilC<(E,z1,z2)> + +if C<z1> and C<z2> are points on the elliptic +curve C<E>, this function computes the value of the canonical bilinear form on +C<z1>, C<z2>: + +S< >C< +ellheight(E,z1+z2) - ellheight(E,z1) - ellheight(E,z2) +> + +where C<+> denotes of course addition on C<E>. In addition, C<z1> or C<z2> +(but not both) can be vectors or matrices. Note that this is equal to twice +some normalizations. C<E> is assumed to be integral, given by a minimal model. + +X<bilhell>The library syntax is B<bilhell>C<(E,z1,z2,I<prec>)>. + +=head2 X<ellchangecurve>ellchangecurveC<(E,v)> + +changes the data for the elliptic curve C<E> +by changing the coordinates using the vector C<v = [u,r,s,t]>, i.e.S< >if C<x'> +and C<y'> are the new coordinates, then C<x = u^2x'+r>, C<y = u^3y'+su^2x'+t>. +The vector C<E> must be a medium or long vector of the type given by +C<ellinit>. + +X<coordch>The library syntax is B<coordch>C<(E,v)>. + +=head2 X<ellchangepoint>ellchangepointC<(x,v)> + +changes the coordinates of the point or +vector of points C<x> using the vector C<v = [u,r,s,t]>, i.e.S< >if C<x'> and +C<y'> are the new coordinates, then C<x = u^2x'+r>, C<y = u^3y'+su^2x'+t> (see also +C<ellchangecurve>). + +X<pointch>The library syntax is B<pointch>C<(x,v)>. + +=head2 X<elleisnum>elleisnumC<(E,k,{I<flag> = 0})> + +C<E> being an elliptic curve as +output by C<ellinit> (or, alternatively, given by a 2-component vector +C<[F<omega>_1,F<omega>_2]>), and C<k> being an even positive integer, computes +the numerical value of the Eisenstein series of weight C<k> at C<E>. When +I<flag> is non-zero and C<k = 4> or 6, returns C<g_2> or C<g_3> with the correct +normalization. + +X<elleisnum>The library syntax is B<elleisnum>C<(E,k,I<flag>)>. + +=head2 X<elleta>elletaC<(om)> + +returns the two-component row vector +C<[F<eta>_1,F<eta>_2]> of quasi-periods associated to C<om = [F<omega>_1, +F<omega>_2]> + +X<elleta>The library syntax is B<elleta>C<(om, I<prec>)> + +=head2 X<ellglobalred>ellglobalredC<(E)> + +calculates the arithmetic conductor, the global +minimal model of C<E> and the global X<Tamagawa number>Tamagawa number C<c>. Here C<E> is an +elliptic curve given by a medium or long vector of the type given by +C<ellinit>, I<and is supposed to have all its coefficients C<a_i> in> +B<I<Q>>. The result is a 3 component vector C<[N,v,c]>. C<N> is the arithmetic +conductor of the curve, C<v> is itself a vector C<[u,r,s,t]> with rational +components. It gives a coordinate change for C<E> over B<I<Q>> such that the +resulting model has integral coefficients, is everywhere minimal, C<a_1> is 0 +or 1, C<a_2> is 0, 1 or C<-1> and C<a_3> is 0 or 1. Such a model is unique, and +the vector C<v> is unique if we specify that C<u> is positive. To get the new +model, simply type C<ellchangecurve(E,v)>. Finally C<c> is the product of +the local Tamagawa numbers C<c_p>, a quantity which enters in the +X<Birch and Swinnerton-Dyer conjecture>Birch and Swinnerton-Dyer conjecture. + +X<globalreduction>The library syntax is B<globalreduction>C<(E)>. + +=head2 X<ellheight>ellheightC<(E,z,{I<flag> = 0})> + +global X<NE<eacute>ron-Tate height>NE<eacute>ron-Tate height of +the point C<z> on the elliptic curve C<E>. The vector C<E> must be a long vector +of the type given by C<ellinit>, with C<I<flag> = 1>. If C<I<flag> = 0>, this +computation is done using sigma and theta-functions and a trick due to J. +Silverman. If C<I<flag> = 1>, use Tate's C<4^n> algorithm, which is much slower. +C<E> is assumed to be integral, given by a minimal model. + +X<ellheight0>The library syntax is B<ellheight0>C<(E,z,I<flag>,I<prec>)>. The Archimedean +contribution alone is given by the library function +C<X<hell>B<hell>(E,z,I<prec>)>. +Also available are C<X<ghell>B<ghell>(E,z,I<prec>)> (C<I<flag> = 0>) and +C<X<ghell2>B<ghell2>(E,z,I<prec>)> (C<I<flag> = 1>). + +=head2 X<ellheightmatrix>ellheightmatrixC<(E,x)> + +C<x> being a vector of points, this +function outputs the Gram matrix of C<x> with respect to the NE<eacute>ron-Tate +height, in other words, the C<(i,j)> component of the matrix is equal to +C<ellbil(E,x[i],x[j])>. The rank of this matrix, at least in some +approximate sense, gives the rank of the set of points, and if C<x> is a +basis of the X<Mordell-Weil group>Mordell-Weil group of C<E>, its determinant is equal to +the regulator of C<E>. Note that this matrix should be divided by 2 to be in +accordance with certain normalizations. C<E> is assumed to be integral, +given by a minimal model. + +X<mathell>The library syntax is B<mathell>C<(E,x,I<prec>)>. + +=head2 X<ellinit>ellinitC<(E,{I<flag> = 0})> + +computes some fixed data concerning the +elliptic curve given by the five-component vector C<E>, which will be +essential for most further computations on the curve. The result is a +19-component vector E (called a long vector in this section), shortened +to 13 components (medium vector) if C<I<flag> = 1>. Both contain the +following information in the first 13 components: + +S< >C< a_1,a_2,a_3,a_4,a_6,b_2,b_4,b_6,b_8,c_4,c_6,F<Delta>,j.> + +In particular, the discriminant is C<E[12]> (or C<E.disc>), and the +C<j>-invariant is C<E[13]> (or C<E.j>). + +The other six components are only present if C<I<flag>> is C<0> (or omitted!). +Their content depends on whether the curve is defined over B<I<R>> or not: + +C<B<*>> When C<E> is defined over B<I<R>>, C<E[14]> (C<E.roots>) is a +vector whose three components contain the roots of the associated Weierstrass +equation. If the roots are all real, then they are ordered by decreasing +value. If only one is real, it is the first component of C<E[14]>. + +C<E[15]> (C<E.omega[1]>) is the real period of C<E> (integral of +C<dx/(2y+a_1x+a_3)> over the connected component of the identity element of +the real points of the curve), and C<E[16]> (C<E.omega[2]>) is a complex +period. In other words, C<F<omega>_1 = E[15]> and C<F<omega>_2 = E[16]> form a basis of +the complex lattice defining C<E> (C<E.omega>), with +C<F<tau> = (F<omega>_2)/(F<omega>_1)> having positive imaginary part. + +C<E[17]> and C<E[18]> are the corresponding values C<F<eta>_1> and C<F<eta>_2> such +that C<F<eta>_1F<omega>_2-F<eta>_2F<omega>_1 = iF<Pi>>, and both can be retrieved by +typing C<E.eta> (as a row vector whose components are the C<F<eta>_i>). + +Finally, C<E[19]> (C<E.area>) is the volume of the complex lattice defining +C<E>. + +C<B<*>> When C<E> is defined over C<B<I<Q>>_p>, the C<p>-adic valuation of C<j> +must be negative. Then C<E[14]> (C<E.roots>) is the vector with a single +component equal to the C<p>-adic root of the associated Weierstrass equation +corresponding to C<-1> under the Tate parametrization. + +C<E[15]> is equal to the square of the C<u>-value, in the notation of Tate. + +C<E[16]> is the C<u>-value itself, if it belongs to C<B<I<Q>>_p>, otherwise zero. + +C<E[17]> is the value of Tate's C<q> for the curve C<E>. + +C<E.tate> will yield the three-component vector C<[u^2,u,q]>. + +C<E[18]> (C<E.w>) is the value of Mestre's C<w> (this is technical), and +C<E[19]> is arbitrarily set equal to zero. + +For all other base fields or rings, the last six components are arbitrarily +set equal to zero (see also the description of member functions related to +elliptic curves at the beginning of this section). + +X<ellinit0>The library syntax is B<ellinit0>C<(E,I<flag>,I<prec>)>. Also available are +C<X<initell>B<initell>(E,I<prec>)> (C<I<flag> = 0>) and +C<X<smallinitell>B<smallinitell>(E,I<prec>)> (C<I<flag> = 1>). + +=head2 X<ellisoncurve>ellisoncurveC<(E,z)> + +gives 1 (i.e.S< >true) if the point C<z> is on +the elliptic curve C<E>, 0 otherwise. If C<E> or C<z> have imprecise coefficients, +an attempt is made to take this into account, i.e.S< >an imprecise equality is +checked, not a precise one. + +X<oncurve>The library syntax is B<oncurve>C<(E,z)>, and the result is a C<long>. + +=head2 X<ellj>elljC<(x)> + +elliptic C<j>-invariant. C<x> must be a complex number +with positive imaginary part, or convertible into a power series or a +C<p>-adic number with positive valuation. + +X<jell>The library syntax is B<jell>C<(x,I<prec>)>. + +=head2 X<elllocalred>elllocalredC<(E,p)> + +calculates the X<Kodaira>Kodaira type of the +local fiber of the elliptic curve C<E> at the prime C<p>. +C<E> must be given by a medium or +long vector of the type given by C<ellinit>, and is assumed to have all +its coefficients C<a_i> in B<I<Z>>. The result is a 4-component vector +C<[f,kod,v,c]>. Here C<f> is the exponent of C<p> in the arithmetic conductor of +C<E>, and C<kod> is the Kodaira type which is coded as follows: + +1 means good reduction (type IC<_0>), 2, 3 and 4 mean types II, III and IV +respectively, C<4+F<nu>> with C<F<nu> E<gt> 0> means type IC<_F<nu>>; +finally the opposite values C<-1>, C<-2>, etc.S< >refer to the starred types +IC<_0^*>, IIC<^*>, etc. The third component C<v> is itself a vector C<[u,r,s,t]> +giving the coordinate changes done during the local reduction. Normally, this +has no use if C<u> is 1, that is, if the given equation was already minimal. +Finally, the last component C<c> is the local X<Tamagawa number>Tamagawa number C<c_p>. + +X<localreduction>The library syntax is B<localreduction>C<(E,p)>. + +=head2 X<elllseries>elllseriesC<(E,s,{A = 1})> + +C<E> being a medium or long vector +given by C<ellinit>, this computes the value of the L-series of C<E> at +C<s>. It is assumed that C<E> is a minimal model over B<I<Z>> and that the curve +is a modular elliptic curve. The optional parameter C<A> is a cutoff point for +the integral, which must be chosen close to 1 for best speed. The result +must be independent of C<A>, so this allows some internal checking of the +function. + +Note that if the conductor of the curve is large, say greater than C<10^{12}>, +this function will take an unreasonable amount of time since it uses an +C<O(N^{1/2})> algorithm. + +X<lseriesell>The library syntax is B<lseriesell>C<(E,s,A,I<prec>)> where C<I<prec>> is a C<long> and an +omitted C<A> is coded as C<NULL>. + +=head2 X<ellorder>ellorderC<(E,z)> + +gives the order of the point C<z> on the elliptic +curve C<E> if it is a torsion point, zero otherwise. In the present version +B<2.2.0>, this is implemented only for elliptic curves defined over B<I<Q>>. + +X<orderell>The library syntax is B<orderell>C<(E,z)>. + +=head2 X<ellordinate>ellordinateC<(E,x)> + +gives a 0, 1 or 2-component vector containing +the C<y>-coordinates of the points of the curve C<E> having C<x> as +C<x>-coordinate. + +X<ordell>The library syntax is B<ordell>C<(E,x)>. + +=head2 X<ellpointtoz>ellpointtozC<(E,z)> + +if C<E> is an elliptic curve with coefficients +in B<I<R>>, this computes a complex number C<t> (modulo the lattice defining +C<E>) corresponding to the point C<z>, i.e.S< >such that, in the standard +Weierstrass model, C< F<wp> (t) = z[1], F<wp> '(t) = z[2]>. In other words, this is the +inverse function of C<ellztopoint>. + +If C<E> has coefficients in C<B<I<Q>>_p>, then either Tate's C<u> is in C<B<I<Q>>_p>, in +which case the output is a C<p>-adic number C<t> corresponding to the point C<z> +under the Tate parametrization, or only its square is, in which case the +output is C<t+1/t>. C<E> must be a long vector output by C<ellinit>. + +X<zell>The library syntax is B<zell>C<(E,z,I<prec>)>. + +=head2 X<ellpow>ellpowC<(E,z,n)> + +computes C<n> times the point C<z> for the +group law on the elliptic curve C<E>. Here, C<n> can be in B<I<Z>>, or C<n> +can be a complex quadratic integer if the curve C<E> has complex multiplication +by C<n> (if not, an error message is issued). + +X<powell>The library syntax is B<powell>C<(E,z,n)>. + +=head2 X<ellrootno>ellrootnoC<(E,{p = 1})> + +C<E> being a medium or long vector given +by C<ellinit>, this computes the local (if C<p ! = 1>) or global (if C<p = 1>) +root number of the L-series of the elliptic curve C<E>. Note that the global +root number is the sign of the functional equation and conjecturally is the +parity of the rank of the X<Mordell-Weil group>Mordell-Weil group. +The equation for C<E> must have +coefficients in B<I<Q>> but need I<not> be minimal. + +X<ellrootno>The library syntax is B<ellrootno>C<(E,p)> and the result (equal to C<F<+->1>) is a C<long>. + +=head2 X<ellsigma>ellsigmaC<(E,z,{I<flag> = 0})> + +value of the Weierstrass C<F<sigma>> +function of the lattice associated to C<E> as given by C<ellinit> +(alternatively, C<E> can be given as a lattice C<[F<omega>_1,F<omega>_2]>). + +If C<I<flag> = 1>, computes an (arbitrary) determination of C< F<log> (F<sigma>(z))>. + +If C<I<flag> = 2,3>, same using the product expansion instead of theta series. +X<ellsigma>The library syntax is B<ellsigma>C<(E,z,I<flag>)> + +=head2 X<ellsub>ellsubC<(E,z1,z2)> + +difference of the points C<z1> and C<z2> on the +elliptic curve corresponding to the vector C<E>. + +X<subell>The library syntax is B<subell>C<(E,z1,z2)>. + +=head2 X<elltaniyama>elltaniyamaC<(E)> + +computes the modular parametrization of the +elliptic curve C<E>, where C<E> is given in the (long or medium) format output +by C<ellinit>, in the form of a two-component vector C<[u,v]> of power +series, given to the current default series precision. This vector is +characterized by the following two properties. First the point C<(x,y) = (u,v)> +satisfies the equation of the elliptic curve. Second, the differential +C<du/(2v+a_1u+a_3)> is equal to C<f(z)dz>, a differential form on +C<H/F<Gamma>_0(N)> where C<N> is the conductor of the curve. The variable used in +the power series for C<u> and C<v> is C<x>, which is implicitly understood to be +equal to C< F<exp> (2iF<Pi> z)>. It is assumed that the curve is a I<strong> +X<Weil curve>Weil curve, and the Manin constant is equal to 1. The equation of +the curve C<E> must be minimal (use C<ellglobalred> to get a minimal +equation). + +X<taniyama>The library syntax is B<taniyama>C<(E)>, and the precision of the result is determined by the +global variable C<precdl>. + +=head2 X<elltors>elltorsC<(E,{I<flag> = 0})> + +if C<E> is an elliptic curve I<defined +over B<I<Q>>>, outputs the torsion subgroup of C<E> as a 3-component vector +C<[t,v1,v2]>, where C<t> is the order of the torsion group, C<v1> +gives the structure of the torsion group as a product of cyclic groups +(sorted by decreasing order), and C<v2> gives generators for these cyclic +groups. C<E> must be a long vector as output by C<ellinit>. + + ? E = ellinit([0,0,0,-1,0]); + ? elltors(E) + %1 = [4, [2, 2], [[0, 0], [1, 0]]] + +Here, the torsion subgroup is isomorphic to C<B<I<Z>>/2B<I<Z>> x B<I<Z>>/2B<I<Z>>>, with +generators C<[0,0]> and C<[1,0]>. + +If C<I<flag> = 0>, use Doud's algorithmS< >: bound torsion by computing C<#E(B<I<F>>_p)> +for small primes of good reduction, then look for torsion points using +Weierstrass parametrization (and Mazur's classification). + +If C<I<flag> = 1>, use Lutz--Nagell (I<much> slower), C<E> is allowed to be a +medium vector. + +X<elltors0>The library syntax is B<elltors0>C<(E,flag)>. + +=head2 X<ellwp>ellwpC<(E,{z = x},{I<flag> = 0})> + +Computes the value at C<z> of the Weierstrass C< F<wp> > function attached to the +elliptic curve C<E> as given by C<ellinit> (alternatively, C<E> can be +given as a lattice C<[F<omega>_1,F<omega>_2]>). + +If C<z> is omitted or is a simple variable, computes the I<power series> +expansion in C<z> (starting C<z^{-2}+O(z^2)>). The number of terms to an +I<even> power in the expansion is the default serieslength in GP, and the +second argument (C long integer) in library mode. + +Optional I<flag> is (for now) only taken into account when C<z> is numeric, and +means 0: compute only C< F<wp> (z)>, 1: compute C<[ F<wp> (z), F<wp> '(z)]>. + +X<ellwp0>The library syntax is B<ellwp0>C<(E,z,I<flag>,I<prec>,I<precdl>)>. Also available is +X<weipell>B<weipell>C<(E,I<precdl>)> for the power series (in +C<x = polx[0]>). + +=head2 X<ellzeta>ellzetaC<(E,z)> + +value of the Weierstrass C<F<zeta>> function of the +lattice associated to C<E> as given by C<ellinit> (alternatively, C<E> can +be given as a lattice C<[F<omega>_1,F<omega>_2]>). + +X<ellzeta>The library syntax is B<ellzeta>C<(E,z)>. + +=head2 X<ellztopoint>ellztopointC<(E,z)> + +C<E> being a long vector, computes the +coordinates C<[x,y]> on the curve C<E> corresponding to the complex number C<z>. +Hence this is the inverse function of C<ellpointtoz>. In other words, if +the curve is put in Weierstrass form, C<[x,y]> represents the +X<Weierstrass F<wp> -function>Weierstrass C< F<wp> >-function and its derivative. +If C<z> is in the lattice defining C<E> over +B<I<C>>, the result is the point at infinity C<[0]>. + +X<pointell>The library syntax is B<pointell>C<(E,z,I<prec>)>. + +=head1 Functions related to general number fields + +In this section can be found functions which are used almost exclusively for +working in general number fields. Other less specific functions can be found +in the next section on polynomials. Functions related to quadratic number +fields can be found in the section L<Label se:arithmetic> (Arithmetic +functions). + +We shall use the following conventions: + +C<B<*>> C<X<nf>I<nf>> denotes a number field, i.e.S< >a 9-component vector +in the format output by X<nfinit>C<nfinit>. This contains the basic arithmetic data +associated to the number field: signature, maximal order, discriminant, etc. + +C<B<*>> C<X<bnf>I<bnf>> denotes a big number field, i.e.S< >a 10-component +vector in the format output by X<bnfinit>C<bnfinit>. This contains C<I<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 C<bnfisprincipal>. + +C<B<*>> C<X<bnr>I<bnr>> denotes a big ``ray number field'', i.e.S< >some data +structure output by C<bnrinit>, even more complicated than C<I<bnf>>, +corresponding to the ray class group structure of the field, for some +modulus. + +C<B<*>> C<X<rnf>I<rnf>> denotes a relative number field (see below). + +C<B<*>> C<X<ideal>I<ideal>> can mean any of the following: + +S< >S< >-- a B<I<Z>>-basis, in X<Hermite normal form>Hermite normal form +(HNF) or not. In this case C<x> is a square matrix. + +S< >S< >-- an X<idele>I<idele>, i.e.S< >a 2-component vector, the first being an +ideal given as a B<I<Z>>--basis, the second being a C<r_1+r_2>-component row +vector giving the complex logarithmic Archimedean information. + +S< >S< >-- a C<B<I<Z>>_K>-generating system for an ideal. + +S< >S< >-- a I<column> vector C<x> expressing an element of the number field +on the integral basis, in which case the ideal is treated as being the +principal idele (or ideal) generated by C<x>. + +S< >S< >-- a prime ideal, i.e.S< >a 5-component vector in the format output by +C<idealprimedec>. + +S< >S< >-- a polmod C<x>, i.e.S< >an algebraic integer, in which case the ideal +is treated as being the principal idele generated by C<x>. + +S< >S< >-- an integer or a rational number, also treated as a principal idele. + +C<B<*>> a I<{character>} on the Abelian group +C<\bigoplus (B<I<Z>>/N_iB<I<Z>>) g_i> +is given by a row vector C<F<chi> = [a_1,...,a_n]> such that +C<F<chi>(F<prod> g_i^{n_i}) = exp(2iF<Pi>F<sum> a_i n_i / N_i)>. + +B<Warnings:> + +1) An element in C<I<nf>> can be expressed either as a polmod or as a +vector of components on the integral basis C<I<nf>.zk>. It is absolutely +essential that all such vectors be I<column> vectors. + +2) When giving an ideal by a C<B<I<Z>>_K> generating system to a function expecting +an ideal, it must be ensured that the function understands that it is a +C<B<I<Z>>_K>-generating system and not a B<I<Z>>-generating system. When the number of +generators is strictly less than the degree of the field, there is no +ambiguity and the program assumes that one is giving a C<B<I<Z>>_K>-generating set. +When the number of generators is greater than or equal to the degree of the +field, however, the program assumes on the contrary that you are giving a +B<I<Z>>-generating set. If this is not the case, you I<must> absolutely +change it into a B<I<Z>>-generating set, the simplest manner being to use +C<idealhnf(I<nf>,x)>. + +Concerning relative extensions, some additional definitions are necessary. + +C<B<*>> A I<{relative matrix>} will be a matrix whose entries are +elements of a (given) number field C<I<nf>>, always expressed as column +vectors on the integral basis C<I<nf>.zk>. Hence it is a matrix of +vectors. + +C<B<*>> An X<ideal list>I<ideal list> will be a row vector of (fractional) +ideals of the number field C<I<nf>>. + +C<B<*>> A X<pseudo-matrix>I<pseudo-matrix> will be a pair C<(A,I)> where C<A> is a +relative matrix and C<I> an ideal list whose length is the same as the number +of columns of C<A>. This pair will be represented by a 2-component row vector. + +C<B<*>> The X<module>I<module> generated by a pseudo-matrix C<(A,I)> is +the sum C<F<sum>_i{B<I<a>>}_jA_j> where the C<{B<I<a>>}_j> are the ideals of C<I> +and C<A_j> is the C<j>-th column of C<A>. + +C<B<*>> A pseudo-matrix C<(A,I)> is a X<pseudo-basis>I<pseudo-basis> of the module +it generates if C<A> is a square matrix with non-zero determinant and all the +ideals of C<I> are non-zero. We say that it is in Hermite Normal +FormX<Hermite normal form> (HNF) if it is upper triangular and all the +elements of the diagonal are equal to 1. + +C<B<*>> The I<determinant> of a pseudo-basis C<(A,I)> is the ideal +equal to the product of the determinant of C<A> by all the ideals of C<I>. The +determinant of a pseudo-matrix is the determinant of any pseudo-basis of the +module it generates. + +Finally, when defining a relative extension, the base field should be +defined by a variable having a lower priority (i.e.S< >a higher number) +than the variable defining the extension. For example, under GP you can +use the variable name C<y> (or C<t>) to define the base field, and the +variable name C<x> to define the relative extension. + +Now a last set of definitions concerning the way big ray number fields +(or I<bnr>) are input, using class field theory. +These are defined by a triple +C<a1>, C<a2>, C<a3>, where the defining set C<[a1,a2,a3]> can have any of the +following forms: C<[I<bnr>]>, C<[I<bnr>,I<subgroup>]>, +C<[I<bnf>,I<module>]>, C<[I<bnf>,I<module>,I<subgroup>]>, where: + +C<B<*>> C<I<bnf>> is as output by C<bnfclassunit> or C<bnfinit>, +where units are mandatory unless the ideal is trivial; I<bnr> by +C<bnrclass> (with C<I<flag> E<gt> 0>) or C<bnrinit>. This is the ground field. + +C<B<*>> I<module> is either an ideal in any form (see above) or a +two-component row vector containing an ideal and an C<r_1>-component row +vector of flags indicating which real Archimedean embeddings to take in the +module. + +C<B<*>> I<subgroup> is the HNF matrix of a subgroup of the ray class group +of the ground field for the modulus I<module>. This is input as a square +matrix expressing generators of a subgroup of the ray class group +C<I<bnr>.clgp> on the given generators. + +The corresponding I<bnr> is then the subfield of the ray class field of the +ground field for the given modulus, associated to the given subgroup. + +All the functions which are specific to relative extensions, number fields, +big number fields, big number rays, share the prefix C<rnf>, C<nf>, +C<bnf>, C<bnr> respectively. They are meant to take as first argument a +number field of that precise type, respectively output by C<rnfinit>, +C<nfinit>, C<bnfinit>, and C<bnrinit>. + +However, and even though it may not be specified in the descriptions of the +functions below, it is permissible, if the function expects a C<I<nf>>, to +use a C<I<bnf>> instead (which contains much more information). The program +will make the effort of converting to what it needs. On the other hand, if +the program requires a big number field, the program will I<not> launch +C<bnfinit> for you, which can be a costly operation. Instead, it will give +you a specific error message. + +The data types corresponding to the structures described above are rather +complicated. Thus, as we already have seen it with elliptic curves, GP +provides you with some ``member functions'' to retrieve the data you need +from these structures (once they have been initialized of course). The +relevant types of number fields are indicated between parentheses: + +X<member functions> +S< >X<bnf>C<bnf> (I<bnr>, I<bnf> ) : big number field. + +S< >X<clgp>C<clgp> (I<bnr>, I<bnf> ) : classgroup. This one admits the +following three subclasses: + +S< > X<cyc>C<cyc> : cyclic decomposition +(SNF)X<Smith normal form>. + +S< > C<gen>X<gen (member function)> : +generators. + +S< > X<no>C<no> : number of elements. + +S< >X<diff>C<diff> (I<bnr>, I<bnf>, I<nf> ) : the different ideal. + +S< >X<codiff>C<codiff> (I<bnr>, I<bnf>, I<nf> ) : the codifferent +(inverse of the different in the ideal group). + +S< >X<disc>C<disc> (I<bnr>, I<bnf>, I<nf> ) : discriminant. + +S< >X<fu>C<fu> (I<bnr>, I<bnf>, I<nf> ) : +X<fundamental units>fundamental units. + +S< >X<futu>C<futu> (I<bnr>, I<bnf> ) : C<[u,w]>, C<u> is a vector of +fundamental units, C<w> generates the torsion. + +S< >X<nf>C<nf> (I<bnr>, I<bnf>, I<nf> ) : number field. + +S< >X<reg>C<reg> (I<bnr>, I<bnf>, ) : regulator. + +S< >X<roots>C<roots> (I<bnr>, I<bnf>, I<nf> ) : roots of the +polnomial generating the field. + +S< >X<sign>C<sign> (I<bnr>, I<bnf>, I<nf> ) : C<[r_1,r_2]> the +signature of the field. This means that the field has C<r_1> real +S< > embeddings, C<2r_2> complex ones. + +S< >X<t2>C<t2> (I<bnr>, I<bnf>, I<nf> ) : the T2 matrix (see +C<nfinit>). + +S< >X<tu>C<tu> (I<bnr>, I<bnf>, ) : a generator for the torsion +units. + +S< >X<tufu>C<tufu> (I<bnr>, I<bnf>, ) : as C<futu>, but outputs +C<[w,u]>. + +S< >X<zk>C<zk> (I<bnr>, I<bnf>, I<nf> ) : integral basis, i.e.S< >a +B<I<Z>>-basis of the maximal order. + +S< >X<zkst>C<zkst> (I<bnr> ) : structure of C<(B<I<Z>>_K/m)^*> (can be +extracted also from an I<idealstar>). + +For instance, assume that C<I<bnf> = bnfinit(I<pol>)>, for some +polynomial. Then C<I<bnf>.clgp> retrieves the class group, and +C<I<bnf>.clgp.no> the class number. If we had set C<I<bnf> = +nfinit(I<pol>)>, both would have output an error message. All these +functions are completely recursive, thus for instance +C<I<bnr>.bnf.nf.zk> will yield the maximal order of I<bnr> (which +you could get directly with a simple C<I<bnr>.zk> of course). + +The following functions, starting with C<buch> in library mode, and with +C<bnf> under GP, are implementations of the sub-exponential algorithms for +finding class and unit groups under X<GRH>GRH, due to Hafner-McCurley, +X<Buchmann>Buchmann and Cohen-Diaz-Olivier. + +The general call to the functions concerning class groups of general number +fields (i.e.S< >excluding C<quadclassunit>) involves a polynomial C<P> and a +technical vector + +S< >C<I<tech> = [c,c2,I<nrel>,I<borne>,I<nrpid>,I<minsfb>],> + +where the parameters are to be understood as follows: + +C<P> is the defining polynomial for the number field, which must be in +C<B<I<Z>>[X]>, irreducible and, preferably, monic. In fact, if you supply a +non-monic polynomial at this point, GP will issue a warning, then +I<transform your polynomial> so that it becomes monic. Instead of the +normal result, say C<res>, you then get a vector C<[res,Mod(a,Q)]>, +where C<Mod(a,Q) = Mod(X,P)> gives the change of variables. + +The numbers C<c> and C<c2> are positive real numbers which control the +execution time and the stack size. To get maximum speed, set C<c2 = c>. To get a +rigorous result (under X<GRH>GRH) you must take C<c2 = 12> (or C<c2 = 6> in the +quadratic case, but then you should use the much faster function +C<quadclassunit>). Reasonable values for C<c> are between C<0.1> and +C<2>. (The defaults are C<c = c2 = 0.3>). + +C<I<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). + +C<I<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 C<0.5> and C<2.0>. (The default is C<1.0>). + +C<I<nrpid>> is the maximal number of small norm relations associated to each +ideal in the factor base. Irrelevant when C<I<borne> = 0>. Otherwise, +reasonable values are between 4 and 20. (The default is 4). + +C<I<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 C<\g 2>), increase this number. Reasonable values +are between 2 and 5. (The default is 3). + +B<Remarks.> + +Apart from the polynomial C<P>, you don't need to supply any of the technical +parameters (under the library you still need to send at least an empty +vector, C<cgetg(1,t_VEC)>). However, should you choose to set some of +them, they I<must> be given in the requested order. For example, if you +want to specify a given value of C<nrel>, you must give some values as well +for C<c> and C<c2>, and provide a vector C<[c,c2,nrel]>. + +Note also that you can use an C<I<nf>> instead of C<P>, which avoids +recomputing the integral basis and analogous quantities. + +=head2 X<bnfcertify>bnfcertifyC<(I<bnf>)> + +C<I<bnf>> being a big number field +as output by C<bnfinit> or C<bnfclassunit>, checks whether the result +is correct, i.e.S< >whether it is possible to remove the assumption of the +Generalized Riemann HypothesisX<GRH>. If it is correct, the answer is 1. +If not, the program may output some error message, but more probably will loop +indefinitely. In I<no> occasion can the program give a wrong answer +(barring bugs of course): if the program answers 1, the answer is certified. + +X<certifybuchall>The library syntax is B<certifybuchall>C<(I<bnf>)>, and the result is a C long. + +=head2 X<bnfclassunit>bnfclassunitC<(P,{I<flag> = 0},{I<tech> = []})> + +X<Buchmann>Buchmann's +sub-exponential algorithm for computing the class group, the regulator and a +system of X<fundamental units>fundamental units of the general algebraic number field C<K> +defined by the irreducible polynomial C<P> with integer coefficients. + +The result of this function is a vector C<v> with 10 components (it is +I<not> a C<I<bnf>>, you need C<bnfinit> for that), which for ease of +presentation is in fact output as a one column matrix. First we describe the +default behaviour (C<I<flag> = 0>): + +C<v[1]> is equal to the polynomial C<P>. Note that for optimum performance, +C<P> should have gone through C<polred> or C<nfinit(x,2)>. + +C<v[2]> is the 2-component vector C<[r1,r2]>, where C<r1> and C<r2> are as usual +the number of real and half the number of complex embeddings of the number +field C<K>. + +C<v[3]> is the 2-component vector containing the field discriminant and the +index. + +C<v[4]> is an integral basis in Hermite normal form. + +C<v[5]> (C<v.clgp>) is a 3-component vector containing the class number +(C<v.clgp.no>), the structure of the class group as a product of cyclic +groups of order C<n_i> (C<v.clgp.cyc>), and the corresponding generators +of the class group of respective orders C<n_i> (C<v.clgp.gen>). + +C<v[6]> (C<v.reg>) is the regulator computed to an accuracy which is the +maximum of an internally determined accuracy and of the default. + +C<v[7]> is a measure of the correctness of the result. If it is close to 1, +the results are correct (under X<GRH>GRH). If it is close to a larger integer, +this shows that the product of the class number by the regulator is off by a +factor equal to this integer, and you must start again with a larger value +for C<c> or a different random seed, i.e.S< >use the function C<setrand>. +(Since the computation involves a random process, starting again with exactly +the same parameters may give the correct result.) In this case a warning +message is printed. + +C<v[8]> (C<v.tu>) a vector with 2 components, the first being the number +C<w> of roots of unity in C<K> and the second a primitive C<w>-th root of unity +expressed as a polynomial. + +C<v[9]> (C<v.fu>) is a system of fundamental units also expressed as +polynomials. + +C<v[10]> gives a measure of the correctness of the computations of the +fundamental units (not of the regulator), expressed as a number of bits. If +this number is greater than C<20>, say, everything is OK. If C<v[10] E<lt>= 0>, +then we have lost all accuracy in computing the units (usually an error +message will be printed and the units not given). In the intermediate cases, +one must proceed with caution (for example by increasing the current +precision). + +If C<I<flag> = 1>, and the precision happens to be insufficient for obtaining the +fundamental units exactly, the internal precision is doubled and the +computation redone, until the exact results are obtained. The user should be +warned that this can take a very long time when the coefficients of the +fundamental units on the integral basis are very large, for example in the +case of large real quadratic fields. In that case, there are alternate +methods for representing algebraic numbers which are not implemented in PARI. + +If C<I<flag> = 2>, the fundamental units and roots of unity are not computed. +Hence the result has only 7 components, the first seven ones. + +C<I<tech>> is a technical vector (empty by default) containing C<c>, C<c2>, +I<nrel>, I<borne>, I<nbpid>, I<minsfb>, in this order (see +the beginning of the section or the keyword C<bnf>). +You can supply any number of these I<provided you give an actual value to +each of them> (the ``empty arg'' trick won't work here). Careful use of these +parameters may speed up your computations considerably. + +X<bnfclassunit0>The library syntax is B<bnfclassunit0>C<(P,I<flag>,I<tech>,I<prec>)>. + +=head2 X<bnfclgp>bnfclgpC<(P,{I<tech> = []})> + +as C<bnfclassunit>, but only +outputs C<v[5]>, i.e.S< >the class group. + +X<bnfclassgrouponly>The library syntax is B<bnfclassgrouponly>C<(P,I<tech>,I<prec>)>, where I<tech> +is as described under C<bnfclassunit>. + +=head2 X<bnfdecodemodule>bnfdecodemoduleC<(I<nf>,m)> + +if C<m> is a module as output in the +first component of an extension given by C<bnrdisclist>, outputs the +true module. + +X<decodemodule>The library syntax is B<decodemodule>C<(I<nf>,m)>. + +=head2 X<bnfinit>bnfinitC<(P,{I<flag> = 0},{I<tech> = []})> + +essentially identical +to C<bnfclassunit> except that the output contains a lot of technical data, +and should not be printed out explicitly in general. The result of +C<bnfinit> is used in programs such as C<bnfisprincipal>, +C<bnfisunit> or C<bnfnarrow>. The result is a 10-component vector +C<I<bnf>>. + +C<B<*>> The first 6 and last 2 components are technical and in +principle are not used by the casual user. However, for the sake of +completeness, their description is as follows. We use the notations explained +in the book by H. Cohen, I<A Course in Computational Algebraic Number +Theory>, Graduate Texts in Maths B<138>, Springer-Verlag, 1993, Section +6.5, and subsection 6.5.5 in particular. + +C<I<bnf>[1]> contains the matrix C<W>, i.e.S< >the matrix in Hermite normal +form giving relations for the class group on prime ideal generators +C<(B<I<p>>_i)_{1 E<lt>= i E<lt>= r}>. + +C<I<bnf>[2]> contains the matrix C<B>, i.e.S< >the matrix containing the +expressions of the prime ideal factorbase in terms of the C<B<I<p>>_i>. It is an +C<r x c> matrix. + +C<I<bnf>[3]> contains the complex logarithmic embeddings of the system of +fundamental units which has been found. It is an C<(r_1+r_2) x (r_1+r_2-1)> +matrix. + +C<I<bnf>[4]> contains the matrix C<M''_C> of Archimedean components of the +relations of the matrix C<(W|B)>. + +C<I<bnf>[5]> contains the prime factor base, i.e.S< >the list of prime +ideals used in finding the relations. + +C<I<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 GTMS< >138 (i.e.S< >with a big C<c x 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. + +C<I<bnf>[9]> is a 3-element row vector used in X<bnfisprincipal>C<bnfisprincipal> only +and obtained as follows. Let C<D = U W V> obtained by applying the +X<Smith normal form>Smith normal form algorithm to the matrix C<W> ( = C<I<bnf>[1]>) and +let C<U_r> be the reduction of C<U> modulo C<D>. The first elements of the +factorbase are given (in terms of C<bnf.gen>) by the columns of C<U_r>, +with archimedian component C<g_a>; let also C<GD_a> be the archimedian +components of the generators of the (principal) ideals defined by the +C<bnf.gen[i]^bnf.cyc[i]>. Then C<I<bnf>[9] = [U_r, g_a, GD_a]>. + +Finally, C<I<bnf>[10]> is by default unused and set equal to 0. This +field is used to store further information about the field as it becomes +available (which is rarely needed, hence would be too expensive to compute +during the initial C<bnfinit> call). For instance, the generators of the +principal ideals C<bnf.gen[i]^bnf.cyc[i]> (during a call to +X<bnrisprincipal>C<bnrisprincipal>), or those corresponding to the relations in C<W> and +C<B> (when the C<bnf> internal precision needs to be increased). + +C<B<*>> The less technical components are as follows: + +C<I<bnf>[7]> or C<I<bnf>.nf> is equal to the number field data +C<I<nf>> as would be given by C<nfinit>. + +C<I<bnf>[8]> is a vector containing the last 6 components of +C<bnfclassunit[,1]>, i.e.S< >the classgroup C<I<bnf>.clgp>, the +regulator C<I<bnf>.reg>, the general ``check'' number which should be +close to 1, the number of roots of unity and a generator C<I<bnf>.tu>, +the fundamental units C<I<bnf>.fu>, and finally the check on their +computation. If the precision becomes insufficient, GP outputs a warning +(C<fundamental units too large, not given>) and does not strive to +compute the units by default (C<I<flag> = 0>). + +When C<I<flag> = 1>, GP insists on finding the fundamental units exactly, the +internal precision being doubled and the computation redone, until the exact +results are obtained. The user should be warned that this can take a very +long time when the coefficients of the fundamental units on the integral +basis are very large. + +When C<I<flag> = 2>, on the contrary, it is initially agreed that GP +will not compute units. + +When C<I<flag> = 3>, computes a very small version of C<bnfinit>, a ``small big +number field'' (or I<sbnf> for short) which contains enough information +to recover the full C<I<bnf>> vector very rapidly, but which is much +smaller and hence easy to store and print. It is supposed to be used in +conjunction with C<bnfmake>. The output is a 12 component vector C<v>, as +follows. Let C<I<bnf>> be the result of a full C<bnfinit>, complete with +units. Then C<v[1]> is the polynomial C<P>, C<v[2]> is the number of real +embeddings C<r_1>, C<v[3]> is the field discriminant, C<v[4]> is the integral +basis, C<v[5]> is the list of roots as in the sixth component of C<nfinit>, +C<v[6]> is the matrix C<MD> of C<nfinit> giving a B<I<Z>>-basis of the +different, C<v[7]> is the matrix C<W = I<bnf>[1]>, C<v[8]> is the +matrix C<matalpha = I<bnf>[2]>, C<v[9]> is the prime ideal factor base +C<I<bnf>[5]> coded in a compact way, and ordered according to the +permutation C<I<bnf>[6]>, C<v[10]> is the 2-component vector giving the +number of roots of unity and a generator, expressed on the integral basis, +C<v[11]> is the list of fundamental units, expressed on the integral basis, +C<v[12]> is a vector containing the algebraic numbers alpha corresponding to +the columns of the matrix C<matalpha>, expressed on the integral basis. + +Note that all the components are exact (integral or rational), except for +the roots in C<v[5]>. In practice, this is the only component which a user +is allowed to modify, by recomputing the roots to a higher accuracy if +desired. Note also that the member functions will I<not> work on +I<sbnf>, you have to use C<bnfmake> explicitly first. + +X<bnfinit0>The library syntax is B<bnfinit0>C<(P,I<flag>,I<tech>,I<prec>)>. + +=head2 X<bnfisintnorm>bnfisintnormC<(I<bnf>,x)> + +computes a complete system of +solutions (modulo units of positive norm) of the absolute norm equation +C<Norm(a) = x>, +where C<a> is an integer in C<I<bnf>>. If C<I<bnf>> has not been certified, +the correctness of the result depends on the validity of X<GRH>GRH. + +X<bnfisintnorm>The library syntax is B<bnfisintnorm>C<(I<bnf>,x)>. + +=head2 X<bnfisnorm>bnfisnormC<(I<bnf>,x,{I<flag> = 1})> + +tries to tell whether the +rational number C<x> is the norm of some element y in C<I<bnf>>. Returns a +vector C<[a,b]> where C<x = Norm(a)*b>. Looks for a solution which is an C<S>-unit, +with C<S> a certain set of prime ideals containing (among others) all primes +dividing C<x>. If C<I<bnf>> is known to be X<Galois>Galois, set C<I<flag> = 0> (in +this case, +C<x> is a norm iff C<b = 1>). If C<I<flag>> is non zero the program adds to C<S> the +following prime ideals, depending on the sign of C<I<flag>>. If C<I<flag> E<gt> 0>, the +ideals of norm less than C<I<flag>>. And if C<I<flag> E<lt> 0> the ideals dividing C<I<flag>>. + +If you are willing to assume X<GRH>GRH, the answer is guaranteed +(i.e.S< >C<x> is a norm iff C<b = 1>), if C<S> contains all primes less than +C<12 F<log> (I<disc>(I<Bnf>))^2>, +where C<I<Bnf>> is the Galois closure of C<I<bnf>>. + +X<bnfisnorm>The library syntax is B<bnfisnorm>C<(I<bnf>,x,I<flag>,I<prec>)>, where C<I<flag>> and +C<I<prec>> are C<long>s. + +=head2 X<bnfissunit>bnfissunitC<(I<bnf>,I<sfu>,x)> + +C<I<bnf>> being output by +C<bnfinit>, I<sfu> by C<bnfsunit>, gives the column vector of +exponents of C<x> on the fundamental C<S>-units and the roots of unity. +If C<x> is not a unit, outputs an empty vector. + +X<bnfissunit>The library syntax is B<bnfissunit>C<(I<bnf>,I<sfu>,x)>. + +=head2 X<bnfisprincipal>bnfisprincipalC<(I<bnf>,x,{I<flag> = 1})> + +C<I<bnf>> being the +number field data output by C<bnfinit>, and C<x> being either a B<I<Z>>-basis +of an ideal in the number field (not necessarily in HNF) or a prime ideal in +the format output by the function C<idealprimedec>, this function tests +whether the ideal is principal or not. The result is more complete than a +simple true/false answer: it gives a row vector C<[v_1,v_2,check]>, where + +C<v_1> is the vector of components C<c_i> of the class of the ideal C<x> in the +class group, expressed on the generators C<g_i> given by C<bnfinit> +(specifically C<I<bnf>.clgp.gen> which is the same as +C<I<bnf>[8][1][3]>). The C<c_i> are chosen so that C<0 E<lt>= c_i E<lt> n_i> +where C<n_i> is the order of C<g_i> (the vector of C<n_i> being +C<I<bnf>.clgp.cyc>, that is C<I<bnf>[8][1][2]>). + +C<v_2> gives on the integral basis the components of C<F<alpha>> such that +C<x = F<alpha>F<prod>_ig_i^{c_i}>. In particular, C<x> is principal if and only if +C<v_1> is equal to the zero vector, and if this the case C<x = F<alpha>B<I<Z>>_K> where +C<F<alpha>> is given by C<v_2>. Note that if C<F<alpha>> is too large to be given, a +warning message will be printed and C<v_2> will be set equal to the empty +vector. + +Finally the third component I<check> is analogous to the last component of +C<bnfclassunit>: it gives a check on the accuracy of the result, in bits. +I<check> should be at least C<10>, and preferably much more. In any case, the +result is checked for correctness. + +If C<I<flag> = 0>, outputs only C<v_1>, which is much easier to compute. + +If C<I<flag> = 2>, does as if C<I<flag>> were C<0>, but doubles the precision until a +result is obtained. + +If C<I<flag> = 3>, as in the default behaviour (C<I<flag> = 1>), but doubles the precision +until a result is obtained. + +The user is warned that these two last setting may induce I<very> lengthy +computations. + +X<isprincipalall>The library syntax is B<isprincipalall>C<(I<bnf>,x,I<flag>)>. + +=head2 X<bnfisunit>bnfisunitC<(I<bnf>,x)> + +C<I<bnf>> being the number field data +output by +C<bnfinit> and C<x> being an algebraic number (type integer, rational or +polmod), this outputs the decomposition of C<x> on the fundamental units and +the roots of unity if C<x> is a unit, the empty vector otherwise. More +precisely, if C<u_1>,...,C<u_r> are the fundamental units, and C<F<zeta>> is +the generator of the group of roots of unity (found by C<bnfclassunit> or +C<bnfinit>), the output is a vector C<[x_1,...,x_r,x_{r+1}]> such that +C<x = u_1^{x_1}...u_r^{x_r}.F<zeta>^{x_{r+1}}>. The C<x_i> are integers for +C<i E<lt>= r> and is an integer modulo the order of C<F<zeta>> for C<i = r+1>. + +X<isunit>The library syntax is B<isunit>C<(I<bnf>,x)>. + +=head2 X<bnfmake>bnfmakeC<(I<sbnf>)> + +I<sbnf> being a ``small C<I<bnf>>'' +as output by C<bnfinit>C<(x,3)>, computes the complete C<bnfinit> +information. The result is I<not> identical to what C<bnfinit> would +yield, but is functionally identical. The execution time is very small +compared to a complete C<bnfinit>. Note that if the default precision in +GP (or C<I<prec>> in library mode) is greater than the precision of the +roots C<I<sbnf>[5]>, these are recomputed so as to get a result with +greater accuracy. + +Note that the member functions are I<not> available for I<sbnf>, you +have to use C<bnfmake> explicitly first. + +X<makebigbnf>The library syntax is B<makebigbnf>C<(I<sbnf>,I<prec>)>, where C<I<prec>> is a +C long integer. + +=head2 X<bnfnarrow>bnfnarrowC<(I<bnf>)> + +C<I<bnf>> being a big number field as +output by C<bnfinit>, computes the narrow class group of C<I<bnf>>. The +output is a 3-component row vector C<v> analogous to the corresponding +class group component C<I<bnf>.clgp> (C<I<bnf>[8][1]>): the +first component is the narrow class number C<v.no>, the second component +is a vector containing the SNFX<Smith normal form> cyclic components +C<v.cyc> of the narrow +class group, and the third is a vector giving the generators of the +corresponding C<v.gen> cyclic groups. Note that this function is a +special case of C<bnrclass>. + +X<buchnarrow>The library syntax is B<buchnarrow>C<(I<bnf>)>. + +=head2 X<bnfsignunit>bnfsignunitC<(I<bnf>)> + +C<I<bnf>> being a big number field +output by C<bnfinit>, this computes an C<r_1 x (r_1+r_2-1)> matrix +having C<F<+->1> components, giving the signs of the real embeddings of the +fundamental units. + +X<signunits>The library syntax is B<signunits>C<(I<bnf>)>. + +=head2 X<bnfreg>bnfregC<(I<bnf>)> + +C<I<bnf>> being a big number field +output by C<bnfinit>, computes its regulator. + +X<regulator>The library syntax is B<regulator>C<(I<bnf>,I<tech>,I<prec>)>, where I<tech> is as in +C<bnfclassunit>. + +=head2 X<bnfsunit>bnfsunitC<(I<bnf>,S)> + +computes the fundamental C<S>-units of the +number field C<I<bnf>> (output by C<bnfinit>), where C<S> is a list of +prime ideals (output by C<idealprimedec>). The output is a vector C<v> with +6 components. + +C<v[1]> gives a minimal system of (integral) generators of the C<S>-unit group +modulo the unit group. + +C<v[2]> contains technical data needed by C<bnfissunit>. + +C<v[3]> is an empty vector (used to give the logarithmic embeddings of the +generators in C<v[1]> in version 2.0.16). + +C<v[4]> is the C<S>-regulator (this is the product of the regulator, the +determinant of C<v[2]> and the natural logarithms of the norms of the ideals +in C<S>). + +C<v[5]> gives the C<S>-class group structure, in the usual format +(a row vector whose three components give in order the C<S>-class number, +the cyclic components and the generators). + +C<v[6]> is a copy of C<S>. + +X<bnfsunit>The library syntax is B<bnfsunit>C<(I<bnf>,S,I<prec>)>. + +=head2 X<bnfunit>bnfunitC<(I<bnf>)> + +C<I<bnf>> being a big number field as +output by +C<bnfinit>, outputs a two-component row vector giving in the first +component the vector of fundamental units of the number field, and in the +second component the number of bit of accuracy which remained in the +computation (which is always correct, otherwise an error message is printed). +This function is mainly for people who used the wrong flag in C<bnfinit> +and would like to skip part of a lengthy C<bnfinit> computation. + +X<buchfu>The library syntax is B<buchfu>C<(I<bnf>)>. + +=head2 X<bnrL1>bnrL1C<(I<bnr>,I<subgroup>,{I<flag> = 0})> + +I<bnr> being the number field data which is output by +C<bnrinit(,,1)> and I<subgroup> being a square matrix defining a +congruence subgroup of the ray class group corresponding to I<bnr> +(or C<0> for the trivial congruence subgroup), returns for each +X<character>character C<F<chi>> of the ray class group which is trivial on this +subgroup, the value at C<s = 1> (or C<s = 0>) of the abelian +C<L>-function associated to C<F<chi>>. For the value at C<s = 0>, the +function returns in fact for each character C<F<chi>> a vector C<[r_F<chi> , +c_F<chi>]> where C<r_F<chi>> is the order of C<L(s, F<chi>)> at C<s = 0> and +C<c_F<chi>> the first non-zero term in the expansion of C<L(s, +F<chi>)> at C<s = 0>; in other words + +S< >C<L(s, F<chi>) = c_F<chi>.s^{r_F<chi>} + O(s^{r_F<chi> + 1})> + +near C<0>. I<flag> is optional, default value is 0; its binary digits +mean 1: compute at C<s = 1> if set to 1 or C<s = 0> if set to 0, 2: compute +the primitive C<L>-functions associated to C<F<chi>> if set to 0 or the +C<L>-function with Euler factors at prime ideals dividing the modulus of +I<bnr> removed if set to 1 (this is the so-called C<L_S(s, F<chi>)> +function where C<S> is the set of infinite places of the number field +together with the finite prime ideals dividing the modulus of I<bnr>, +see the example below), 3: returns also the character. + +Example: + + bnf = bnfinit(x^2 - 229); + bnr = bnrinit(bnf,1,1); + bnrL1(bnr, 0) + +returns the order and the first non-zero term of the abelian +C<L>-functions C<L(s, F<chi>)> at C<s = 0> where C<F<chi>> runs through the +characters of the class group of C<B<I<Q>>( F<sqrt> {229})>. Then + + bnr2 = bnrinit(bnf,2,1); + bnrL1(bnr2,0,2) + +returns the order and the first non-zero terms of the abelian +C<L>-functions C<L_S(s, F<chi>)> at C<s = 0> where C<F<chi>> runs through the +characters of the class group of C<B<I<Q>>( F<sqrt> {229})> and C<S> is the set +of infinite places of C<B<I<Q>>( F<sqrt> {229})> together with the finite prime +C<2> (note that the ray class group modulo C<2> is in fact the class +group, so C<bnrL1(bnr2,0)> returns exactly the same answer as +C<bnrL1(bnr,0)>!). + +X<bnrL1>The library syntax is B<bnrL1>C<(I<bnr>,I<subgroup>,I<flag>,I<prec>)> + +=head2 X<bnrclass>bnrclassC<(I<bnf>,I<ideal>,{I<flag> = 0})> + +C<I<bnf>> being a big number field +as output by C<bnfinit> (the units are mandatory unless the ideal is +trivial), and I<ideal> being either an ideal in any form or a two-component +row vector containing an ideal and an C<r_1>-component row vector of flags +indicating which real Archimedean embeddings to take in the module, computes +the ray class group of the number field for the module I<ideal>, as a +3-component vector as all other finite Abelian groups (cardinality, vector of +cyclic components, corresponding generators). + +If C<I<flag> = 2>, the output is different. It is a 6-component vector C<w>. C<w[1]> +is C<I<bnf>>. C<w[2]> is the result of applying +C<idealstar(I<bnf>,I,2)>. C<w[3]>, C<w[4]> and C<w[6]> are technical +components used only by the function C<bnrisprincipal>. C<w[5]> is the +structure of the ray class group as would have been output with C<I<flag> = 0>. + +If C<I<flag> = 1>, as above, except that the generators of the ray class group are +not computed, which saves time. + +X<bnrclass0>The library syntax is B<bnrclass0>C<(I<bnf>,I<ideal>,I<flag>,I<prec>)>. + +=head2 X<bnrclassno>bnrclassnoC<(I<bnf>,I)> + +C<I<bnf>> being a big number field +as output +by C<bnfinit> (units are mandatory unless the ideal is trivial), and C<I> +being either an ideal in any form or a two-component row vector containing an +ideal and an C<r_1>-component row vector of flags indicating which real +Archimedean embeddings to take in the modulus, computes the ray class number +of the number field for the modulus C<I>. This is faster than C<bnrclass> +and should be used if only the ray class number is desired. + +X<rayclassno>The library syntax is B<rayclassno>C<(I<bnf>,I)>. + +=head2 X<bnrclassnolist>bnrclassnolistC<(I<bnf>,I<list>)> + +C<I<bnf>> being a +big number field as output by C<bnfinit> (units are mandatory unless +the ideal is trivial), and I<list> being a list of modules as output +by C<ideallist> of C<ideallistarch>, +outputs the list of the class numbers of the corresponding ray class groups. + +X<rayclassnolist>The library syntax is B<rayclassnolist>C<(I<bnf>,I<list>)>. + +=head2 X<bnrconductor>bnrconductorC<(a_1,{a_2},{a_3}, {I<flag> = 0})> + +conductor of the +subfield of a ray class field as defined by C<[a_1,a_2,a_3]> (see C<bnr> +at the beginning of this section). + +X<bnrconductor>The library syntax is B<bnrconductor>C<(a_1,a_2,a_3,I<flag>,I<prec>)>, where an omitted argument +among the C<a_i> is input as C<gzero>, and C<I<flag>> is a C long. + +=head2 X<bnrconductorofchar>bnrconductorofcharC<(I<bnr>,I<chi>)> + +I<bnr> being a +big ray number field +as output by C<bnrclass>, and I<chi> being a row vector representing a +X<character>character as expressed on the generators of the ray class group, gives +the conductor of this character as a modulus. + +X<bnrconductorofchar>The library syntax is B<bnrconductorofchar>C<(I<bnr>,I<chi>,I<prec>)> where C<I<prec>> +is a C<long>. + +=head2 X<bnrdisc>bnrdiscC<(a1,{a2},{a3},{I<flag> = 0})> + +C<a1>, C<a2>, C<a3> +defining a big ray number field C<L> over a groud field C<K> (see C<bnr> +at the beginning of this section for the +meaning of C<a1>, C<a2>, C<a3>), outputs a 3-component row vector C<[N,R_1,D]>, +where C<N> is the (absolute) degree of C<L>, C<R_1> the number of real places of +C<L>, and C<D> the discriminant of C<L/B<I<Q>>>, including sign (if C<I<flag> = 0>). + +If C<I<flag> = 1>, as above but outputs relative data. C<N> is now the degree of +C<L/K>, C<R_1> is the number of real places of C<K> unramified in C<L> (so that +the number of real places of C<L> is equal to C<R_1> times the relative degree +C<N>), and C<D> is the relative discriminant ideal of C<L/K>. + +If C<I<flag> = 2>, does as in case 0, except that if the modulus is not the exact +conductor corresponding to the C<L>, no data is computed and the result is C<0> +(C<gzero>). + +If C<I<flag> = 3>, as case 2, outputting relative data. + +X<bnrdisc0>The library syntax is B<bnrdisc0>C<(a1,a2,a3,I<flag>,I<prec>)>. + +=head2 X<bnrdisclist>bnrdisclistC<(I<bnf>,I<bound>,{I<arch>},{I<flag> = 0})> + +C<I<bnf>> being a big +number field as output by C<bnfinit> (the units are mandatory), computes a +list of discriminants of Abelian extensions of the number field by increasing +modulus norm up to bound I<bound>, where the ramified Archimedean places are +given by I<arch> (unramified at infinity if I<arch> is void or +omitted). If +I<flag> is non-zero, give I<arch> all the possible values. (See C<bnr> +at the beginning of this section for the meaning of C<a1>, C<a2>, C<a3>.) + +The alternative syntax C<bnrdisclist(I<bnf>,I<list>)> +is supported, where I<list> is as output by C<ideallist> or +C<ideallistarch> (with units). + +The output format is as follows. The output C<v> is a row vector of row +vectors, allowing the bound to be greater than C<2^{16}> for 32-bit machines, +and C<v[i][j]> is understood to be in fact C<V[2^{15}(i-1)+j]> of a unique big +vector C<V> (note that C<2^{15}> is hardwired and can be increased in the +source code only on 64-bit machines and higher). + +Such a component C<V[k]> is itself a vector C<W> (maybe of length 0) whose +components correspond to each possible ideal of norm C<k>. Each component +C<W[i]> corresponds to an Abelian extension C<L> of C<I<bnf>> whose modulus is +an ideal of norm C<k> and no Archimedean components (hence the extension is +unramified at infinity). The extension C<W[i]> is represented by a 4-component +row vector C<[m,d,r,D]> with the following meaning. C<m> is the prime ideal +factorization of the modulus, C<d = [L:B<I<Q>>]> is the absolute degree of C<L>, +C<r> is the number of real places of C<L>, and C<D> is the factorization of the +absolute discriminant. Each prime ideal C<pr = [p,F<alpha>,e,f,F<beta>]> in the +prime factorization C<m> is coded as C<p.n^2+(f-1).n+(j-1)>, where +C<n> is the degree of the base field and C<j> is such that + +C<pr = idealprimedec(I<nf>,p)[j]>. + +C<m> can be decoded using C<bnfdecodemodule>. + +X<bnrdisclist0>The library syntax is B<bnrdisclist0>C<(a1,a2,a3,I<bound>,I<arch>,I<flag>)>. + +=head2 X<bnrinit>bnrinitC<(I<bnf>,I<ideal>,{I<flag> = 0})> + +C<I<bnf>> is as +output by C<bnfinit>, I<ideal> is a valid ideal (or a module), +initializes data linked +to the ray class group structure corresponding to this module. This is the +same as C<bnrclass(I<bnf>,I<ideal>,I<flag>+1)>. + +X<bnrinit0>The library syntax is B<bnrinit0>C<(I<bnf>,I<ideal>,I<flag>,I<prec>)>. + +=head2 X<bnrisconductor>bnrisconductorC<(a1,{a2},{a3})> + +C<a1>, C<a2>, C<a3> represent +an extension of the base field, given by class field theory for some modulus +encoded in the parameters. Outputs 1 if this modulus is the conductor, and 0 +otherwise. This is slightly faster than C<bnrconductor>. + +X<bnrisconductor>The library syntax is B<bnrisconductor>C<(a1,a2,a3)> and the result is a C<long>. + +=head2 X<bnrisprincipal>bnrisprincipalC<(I<bnr>,x,{I<flag> = 1})> + +I<bnr> being the +number field data which is output by C<bnrinit>C<(,,1)> and C<x> being an +ideal in any form, outputs the components of C<x> on the ray class group +generators in a way similar to C<bnfisprincipal>. That is a 3-component +vector C<v> where C<v[1]> is the vector of components of C<x> on the ray class +group generators, C<v[2]> gives on the integral basis an element C<F<alpha>> such +that C<x = F<alpha>F<prod>_ig_i^{x_i}>. Finally C<v[3]> indicates the number of bits +of accuracy left in the result. In any case the result is checked for +correctness, but C<v[3]> is included to see if it is necessary to increase the +accuracy in other computations. + +If C<I<flag> = 0>, outputs only C<v_1>. In that case, I<bnr> need not contain the +ray class group generators, i.e.S< >it may be created with C<bnrinit>C<(,,0)> + +X<isprincipalrayall>The library syntax is B<isprincipalrayall>C<(I<bnr>,x,I<flag>)>. + +=head2 X<bnrrootnumber>bnrrootnumberC<(I<bnr>,I<chi>,{I<flag> = 0})> + +if C<F<chi> = I<chi>> is a (not necessarily primitive) +X<character>character over I<bnr>, let +C<L(s,F<chi>) = F<sum>_{id} F<chi>(id) N(id)^{-s}> be the associated +X<Artin L-function>Artin L-function. Returns the so-called X<Artin root number>Artin root number, i.e.S< >the +complex number C<W(F<chi>)> of modulus 1 such that + +S< >C<F<Lambda>(1-s,F<chi>) = W(F<chi>) F<Lambda>(s,\overline{F<chi>})> + +where C<F<Lambda>(s,F<chi>) = A(F<chi>)^{s/2}F<gamma>_F<chi>(s) L(s,F<chi>)> is +the enlarged L-function associated to C<L>. + +The generators of the ray class group are needed, and you can set C<I<flag> = 1> if +the character is known to be primitive. Example: + + bnf = bnfinit(x^2 - 145); + bnr = bnrinit(bnf,7,1); + bnrrootnumber(bnr, [5]) + +returns the root number of the character C<F<chi>> of C<Cl_7(B<I<Q>>( F<sqrt> {145}))> +such that C<F<chi>(g) = F<zeta>^5>, where C<g> is the generator of the ray-class +field and C<F<zeta> = e^{2iF<Pi>/N}> where C<N> is the order of C<g> (C<N = 12> as +C<bnr.cyc> readily tells us). + +X<bnrrootnumber>The library syntax is B<bnrrootnumber>C<(I<bnf>,I<chi>,I<flag>)> + +=head2 bnrstarkC<{(I<bnr>,I<subgroup>,{I<flag> = 0})}> + +I<bnr> +being as output by C<bnrinit(,,1)>, finds a relative equation for the +class field corresponding to the modulus in I<bnr> and the given +congruence subgroup using X<Stark units>Stark units (set C<I<subgroup> = 0> if you +want the whole ray class group). The main variable of I<bnr> must not be +C<x>, and the ground field and the class field must be totally real and not +isomorphic to B<I<Q>> (over the rationnals, use X<polsubcyclo>C<polsubcyclo> or +X<galoissubcyclo>C<galoissubcyclo>). I<flag> is optional and may be set to 0 to obtain a +reduced relative polynomial, 1 to be satisfied with any relative +polynomial, 2 to obtain an absolute polynomial and 3 to obtain the +irreducible relative polynomial of the Stark unit, 0 being default. +Example: + + bnf = bnfinit(y^2 - 3); + bnr = bnrinit(bnf, 5, 1); + bnrstark(bnr, 0) + +returns the ray class field of C<B<I<Q>>( F<sqrt> {3})> modulo C<5>. + +B<Remark.> The result of the computation depends on the choice of +a modulus verifying special conditions. By default the function will try +few moduli, choosing the one giving the smallest result. In some cases +where the result is however very large, you can tell the function to +try more moduli by adding C<4> to the value of flag. Whether this flag is +set or not, the function may fail in some extreme cases, returning the +error message + +C<"Cannot find a suitable modulus in FindModule">. + +In this case, the corresponding congruence group is a product of cyclic +groups and, for the time being, the class field has to be obtained by +splitting this group into its cyclic components. + +X<bnrstark>The library syntax is B<bnrstark>C<(I<bnr>,I<subgroup>,I<flag>)>. + +=head2 X<dirzetak>dirzetakC<(I<nf>,b)> + +gives as a vector the first C<b> +coefficients of the X<Dedekind>Dedekind zeta function of the number field C<I<nf>> +considered as a X<Dirichlet series>Dirichlet series. + +X<dirzetak>The library syntax is B<dirzetak>C<(I<nf>,b)>. + +=head2 X<factornf>factornfC<(x,t)> + +factorization of the univariate polynomial C<x> +over the number field defined by the (univariate) polynomial C<t>. C<x> may +have coefficients in B<I<Q>> or in the number field. The main variable of +C<t> must be of I<lower> priority than that of C<x> (in other words the +variable number of C<t> must be I<greater> than that of C<x>). However if +the coefficients of the number field occur explicitly (as polmods) as +coefficients of C<x>, the variable of these polmods I<must> be the same as +the main variable of C<t>. For example + + ? factornf(x^2 + Mod(y, y^2+1), y^2+1); + ? factornf(x^2 + 1, y^2+1); \\ these two are OK + ? factornf(x^2 + Mod(z,z^2+1), y^2+1) + *** incorrect type in gmulsg + +X<polfnf>The library syntax is B<polfnf>C<(x,t)>. + +=head2 X<galoisfixedfield>galoisfixedfieldC<(I<gal>,I<perm>,{fl = 0},{v = y}))> + +I<gal> being be a Galois field as output by X<galoisinit>C<galoisinit> and +I<perm> an element of C<I<gal>.group> or a vector of such elements, +computes the fixed field of I<gal> by the automorphism defined by the +permutations I<perm> of the roots C<I<gal>.roots>. C<P> is guaranteed to +be squarefree modulo C<I<gal>.p>. + +If no flags or C<I<flag> = 0>, output format is the same as for X<nfsubfield>C<nfsubfield>, +returning C<[P,x]> such that C<P> is a polynomial defining the fixed field, and +C<x> is a root of C<P> expressed as a polmod in C<I<gal>.pol>. + +If C<I<flag> = 1> return only the polynomial C<P>. + +If C<I<flag> = 2> return C<[P,x,F]> where C<P> and C<x> are as above and C<F> is the +factorization of C<I<gal>.pol> over the field defined by C<P>, where +variable C<v> (C<y> by default) stands for a root of C<P>. The priority of C<v> +must be less than the priority of the variable of C<I<gal>.pol>. + +Example: + + G = galoisinit(x^4+1); + galoisfixedfield(G,G.group[2],2) + [x^2 + 2, Mod(x^3 + x, x^4 + 1), [x^2 - y*x - 1, x^2 + y*x - 1]] + +computes the factorization C<x^4+1 = (x^2- F<sqrt> {-2}x-1)(x^2+ F<sqrt> {-2}x-1)> + +X<galoisfixedfield>The library syntax is B<galoisfixedfield>C<(I<gal>,I<perm>,p)>. + +=head2 X<galoisinit>galoisinitC<(I<pol>,{den})> + +computes the Galois group +and all neccessary information for computing the fixed fields of the +Galois extension C<K/B<I<Q>>> where C<K> is the number field defined by +C<I<pol>> (monic irreducible polynomial in C<B<I<Z>>[X]> or +a number field as output by X<nfinit>C<nfinit>). The extension C<K/B<I<Q>>> must be +Galois with Galois group ``weakly'' super-solvable (see X<nfgaloisconj>C<nfgaloisconj>) + +B<Warning:> The interface of this function is experimental, +so the described output can be subject to important changes in the +near future. However the function itself should work as described. For any +remarks about this interface, please mail C<allomber@math.u-bordeaux.fr>. + +The output is an 8-component vector I<gal>. + +C<I<gal>[1]> contains the polynomial I<pol> +(C<I<gal>.pol>). + +C<I<gal>[2]> is a three--components vector C<[p,e,q]> where C<p> is a +prime number (C<I<gal>.p>) such that I<pol> totally split +modulo C<p> , C<e> is an integer and C<q = p^e> (C<I<gal>.mod>) is the +modulus of the roots in C<I<gal>.roots>. + +C<I<gal>[3]> is a vector C<L> containing the C<p>-adic roots of +I<pol> as integers implicitly modulo C<I<gal>.mod>. +(C<I<gal>.roots>). + +C<I<gal>[4]> is the inverse of the Van der Monde matrix of the +C<p>-adic roots of I<pol>, multiplied by C<I<gal>[5]>. + +C<I<gal>[5]> is a multiple of the least common denominator of the +automorphisms expressed as polynomial in a root of I<pol>. + +C<I<gal>[6]> is the Galois group C<G> expressed as a vector of +permutations of C<L> (C<I<gal>.group>). + +C<I<gal>[7]> is a generating subset C<S = [s_1,...,s_g]> of C<G> +expressed as a vector of permutations of C<L> (C<I<gal>.gen>). + +C<I<gal>[8]> contains the relative orders C<[o_1,...,o_g]> of +the generators of C<S> (C<I<gal>.orders>). + +Let C<H> be the maximal normal supersolvable subgroup of C<G>, we have the +following properties: + +S< >S< >C<B<*>> if C<G/H ~ A_4> then C<[o_1,...,o_g]> ends by +C<[2,2,3]>. + +S< >S< >C<B<*>> if C<G/H ~ S_4> then C<[o_1,...,o_g]> ends by +C<[2,2,3,2]>. + +S< >S< >C<B<*>> else C<G> is super-solvable. + +S< >S< >C<B<*>> for C<1 E<lt>= i E<lt>= g> the subgroup of C<G> generated by +C<[s_1,...,s_g]> is normal, with the exception of C<i = g-2> in the +second case and of C<i = g-3> in the third. + +S< >S< >C<B<*>> the relative order C<o_i> of C<s_i> is its order in the +quotient group C<G/E<lt>s_1,...,s_{i-1}E<gt>>, with the same +exceptions. + +S< >S< >C<B<*>> for any C<x belongs to G> there exists a unique family +C<[e_1,...,e_g]> such that (no exceptions): + +-- for C<1 E<lt>= i E<lt>= g> we have C<0 E<lt>= e_i E<lt> o_i> + +-- C<x = g_1^{e_1}g_2^{e_2}...g_n^{e_n}> + +If present C<den> must be a suitable value for C<I<gal>[5]>. + +X<galoisinit>The library syntax is B<galoisinit>C<(I<gal>,I<den>)>. + +=head2 X<galoispermtopol>galoispermtopolC<(I<gal>,I<perm>)> + +I<gal> being a +galois field as output by C<galoisinit> and I<perm> a element of +C<I<gal>.group>, return the polynomial defining the Galois +automorphism, as output by C<nfgaloisconj>, associated with the +permutation I<perm> of the roots C<I<gal>.roots>. I<perm> can +also be a vector or matrix, in this case, C<galoispermtopol> is +applied to all components recursively. + +Note that + + G = galoisinit(pol); + galoispermtopol(G, G[6])~ + +is equivalent to C<nfgaloisconj(pol)>, if degree of I<pol> +is greater or equal to C<2>. + +X<galoispermtopol>The library syntax is B<galoispermtopol>C<(I<gal>,I<perm>)>. + +=head2 X<galoissubcyclo>galoissubcycloC<(n,H,{Z},{v})> + +compute a polynomial +defining the subfield of C<B<I<Q>>(F<zeta>_n)> fixed by the subgroup I<H> of +C<B<I<Z>>/nB<I<Z>>>. The subgroup I<H> can be given by a generator, a set of +generators given by a vector or a HNF matrix. If present C<Z> must be +C<znstar(n)>, and is currently only used when I<H> is a HNF matrix. If +I<v> is given, the polynomial is given in the variable I<v>. + +The following function can be used to compute all subfields of +C<B<I<Q>>(F<zeta>_n)> (of order less than C<d>, if C<d> is set): + + subcyclo(n, d = -1)= + { + local(Z,G,S); + if (d < 0, d = n); + Z = znstar(n); + G = matdiagonal(Z[2]); + S = []; + forsubgroup(H = G, d, + S = concat(S, galoissubcyclo(n, mathnf(concat(G,H)),Z)); + ); + S + } + +X<galoissubcyclo>The library syntax is B<galoissubcyclo>C<(n,H,Z,v)> where n is a C long integer. + +=head2 X<idealadd>idealaddC<(I<nf>,x,y)> + +sum of the two ideals C<x> and C<y> in the +number field C<I<nf>>. When C<x> and C<y> are given by B<I<Z>>-bases, this does +not depend on C<I<nf>> and can be used to compute the sum of any two +B<I<Z>>-modules. The result is given in HNF. + +X<idealadd>The library syntax is B<idealadd>C<(I<nf>,x,y)>. + +=head2 X<idealaddtoone>idealaddtooneC<(I<nf>,x,{y})> + +C<x> and C<y> being two co-prime +integral ideals (given in any form), this gives a two-component row vector +C<[a,b]> such that C<a belongs to x>, C<b belongs to y> and C<a+b = 1>. + +The alternative syntax C<idealaddtoone(I<nf>,v)>, is supported, where +C<v> is a C<k>-component vector of ideals (given in any form) which sum to +C<B<I<Z>>_K>. This outputs a C<k>-component vector C<e> such that C<e[i] belongs to x[i]> for +C<1 E<lt>= i E<lt>= k> and C<F<sum>_{1 E<lt>= i E<lt>= k}e[i] = 1>. + +X<idealaddtoone0>The library syntax is B<idealaddtoone0>C<(I<nf>,x,y)>, where an omitted C<y> is coded as +C<NULL>. + +=head2 X<idealappr>idealapprC<(I<nf>,x,{I<flag> = 0})> + +if C<x> is a fractional ideal +(given in any form), gives an element C<F<alpha>> in C<I<nf>> such that for +all prime ideals C<B<I<p>>> such that the valuation of C<x> at C<B<I<p>>> is non-zero, we +have C<v_{B<I<p>>}(F<alpha>) = v_{B<I<p>>}(x)>, and. C<v_{B<I<p>>}(F<alpha>) E<gt>= 0> for all other +C<{B<I<p>>}>. + +If C<I<flag>> is non-zero, C<x> must be given as a prime ideal factorization, as +output by C<idealfactor>, but possibly with zero or negative exponents. +This yields an element C<F<alpha>> such that for all prime ideals C<B<I<p>>> occurring +in C<x>, C<v_{B<I<p>>}(F<alpha>)> is equal to the exponent of C<B<I<p>>> in C<x>, and for all +other prime ideals, C<v_{B<I<p>>}(F<alpha>) E<gt>= 0>. This generalizes +C<idealappr(I<nf>,x,0)> since zero exponents are allowed. Note that +the algorithm used is slightly different, so that +C<idealapp(I<nf>,idealfactor(I<nf>,x))> may not be the same as +C<idealappr(I<nf>,x,1)>. + +X<idealappr0>The library syntax is B<idealappr0>C<(I<nf>,x,I<flag>)>. + +=head2 X<idealchinese>idealchineseC<(I<nf>,x,y)> + +C<x> being a prime ideal factorization +(i.e.S< >a 2 by 2 matrix whose first column contain prime ideals, and the second +column integral exponents), C<y> a vector of elements in C<I<nf>> indexed by +the ideals in C<x>, computes an element C<b> such that + +C<v_B<I<p>>(b - y_B<I<p>>) E<gt>= v_B<I<p>>(x)> for all prime ideals in C<x> and C<v_B<I<p>>(b) E<gt>= 0> +for all other C<B<I<p>>>. + +X<idealchinese>The library syntax is B<idealchinese>C<(I<nf>,x,y)>. + +=head2 X<idealcoprime>idealcoprimeC<(I<nf>,x,y)> + +given two integral ideals C<x> and C<y> +in the number field C<I<nf>>, finds a C<F<beta>> in the field, expressed on the +integral basis C<I<nf>[7]>, such that C<F<beta>.y> is an integral ideal +coprime to C<x>. + +X<idealcoprime>The library syntax is B<idealcoprime>C<(I<nf>,x)>. + +=head2 X<idealdiv>idealdivC<(I<nf>,x,y,{I<flag> = 0})> + +quotient C<x.y^{-1}> of the +two ideals C<x> and C<y> in the number field C<I<nf>>. The result is given in +HNF. + +If C<I<flag>> is non-zero, the quotient C<x.y^{-1}> is assumed to be an +integral ideal. This can be much faster when the norm of the quotient is +small even though the norms of C<x> and C<y> are large. + +X<idealdiv0>The library syntax is B<idealdiv0>C<(I<nf>,x,y,I<flag>)>. Also available +are C<X<idealdiv>B<idealdiv>(I<nf>,x,y)> (C<I<flag> = 0>) and +C<X<idealdivexact>B<idealdivexact>(I<nf>,x,y)> (C<I<flag> = 1>). + +=head2 X<idealfactor>idealfactorC<(I<nf>,x)> + +factors into prime ideal powers the +ideal C<x> in the number field C<I<nf>>. The output format is similar to the +C<factor> function, and the prime ideals are represented in the form +output by the C<idealprimedec> function, i.e.S< >as 5-element vectors. + +X<idealfactor>The library syntax is B<idealfactor>C<(I<nf>,x)>. + +=head2 X<idealhnf>idealhnfC<(I<nf>,a,{b})> + +gives the X<Hermite normal form>Hermite normal form +matrix of the ideal C<a>. The ideal can be given in any form whatsoever +(typically by an algebraic number if it is principal, by a C<B<I<Z>>_K>-system of +generators, as a prime ideal as given by C<idealprimedec>, or by a +B<I<Z>>-basis). + +If C<b> is not omitted, assume the ideal given was C<aB<I<Z>>_K+bB<I<Z>>_K>, where C<a> +and C<b> are elements of C<K> given either as vectors on the integral basis +C<I<nf>[7]> or as algebraic numbers. + +X<idealhnf0>The library syntax is B<idealhnf0>C<(I<nf>,a,b)> where an omitted C<b> is coded as C<NULL>. +Also available is C<X<idealhermite>B<idealhermite>(I<nf>,a)> (C<b> omitted). + +=head2 X<idealintersect>idealintersectC<(I<nf>,x,y)> + +intersection of the two ideals +C<x> and C<y> in the number field C<I<nf>>. When C<x> and C<y> are given by +B<I<Z>>-bases, this does not depend on C<I<nf>> and can be used to compute the +intersection of any two B<I<Z>>-modules. The result is given in HNF. + +X<idealintersect>The library syntax is B<idealintersect>C<(I<nf>,x,y)>. + +=head2 X<idealinv>idealinvC<(I<nf>,x)> + +inverse of the ideal C<x> in the +number field C<I<nf>>. The result is the Hermite normal form of the inverse +of the ideal, together with the opposite of the Archimedean information if it +is given. + +X<idealinv>The library syntax is B<idealinv>C<(I<nf>,x)>. + +=head2 X<ideallist>ideallistC<(I<nf>,I<bound>,{I<flag> = 4})> + +computes the list +of all ideals of norm less or equal to I<bound> in the number field +I<nf>. The result is a row vector with exactly I<bound> components. +Each component is itself a row vector containing the information about +ideals of a given norm, in no specific order. This information can be +either the HNF of the ideal or the C<idealstar> with possibly some +additional information. + +If C<I<flag>> is present, its binary digits are toggles meaning + +S< >S< >1: give also the generators in the C<idealstar>. + +S< >S< >2: output C<[L,U]>, where C<L> is as before and C<U> is a vector of +C<zinternallog>s of the units. + +S< >S< >4: give only the ideals and not the C<idealstar> or the C<ideallog> +of the units. + +X<ideallist0>The library syntax is B<ideallist0>C<(I<nf>,I<bound>,I<flag>)>, where I<bound> must +be a C long integer. Also available is C<X<ideallist>B<ideallist>(I<nf>,I<bound>)>, +corresponding to the case C<I<flag> = 0>. + +=head2 X<ideallistarch>ideallistarchC<(I<nf>,I<list>,{I<arch> = []},{I<flag> = 0})> + +vector of vectors of all C<idealstarinit> (see C<idealstar>) of all +modules in I<list>, with Archimedean part I<arch> added (void if +omitted). I<list> is a vector of big ideals, as output by +C<ideallist>C<(..., I<flag>)> for instance. C<I<flag>> is optional; its binary +digits are toggles meaning: 1: give generators as well, 2: list format is +C<[L,U]> (see C<ideallist>). + +X<ideallistarch0>The library syntax is B<ideallistarch0>C<(I<nf>,I<list>,I<arch>,I<flag>)>, where an omitted +I<arch> is coded as C<NULL>. + +=head2 X<ideallog>ideallogC<(I<nf>,x,I<bid>)> + +C<I<nf>> being a number field, +I<bid> being a ``big ideal'' as output by C<idealstar> and C<x> being a +non-necessarily integral element of I<nf> which must have valuation +equal to 0 at all prime ideals dividing C<I = I<bid>[1]>, computes the +``discrete logarithm'' of C<x> on the generators given in C<I<bid>[2]>. +In other words, if C<g_i> are these generators, of orders C<d_i> respectively, +the result is a column vector of integers C<(x_i)> such that C<0 E<lt>= x_i E<lt> d_i> and + +S< >C<x = F<prod>_ig_i^{x_i} (mod ^*I) .> + +Note that when C<I> is a module, this implies also sign conditions on the +embeddings. + +X<zideallog>The library syntax is B<zideallog>C<(I<nf>,x,I<bid>)>. + +=head2 X<idealmin>idealminC<(I<nf>,x,{I<vdir>})> + +computes a minimum of +the ideal C<x> in the direction I<vdir> in the number field I<nf>. + +X<minideal>The library syntax is B<minideal>C<(I<nf>,x,I<vdir>,I<prec>)>, where an omitted +I<vdir> is coded as C<NULL>. + +=head2 X<idealmul>idealmulC<(I<nf>,x,y,{I<flag> = 0})> + +ideal multiplication of the +ideals C<x> and C<y> in the number field I<nf>. The result is a generating +set for the ideal product with at most C<n> elements, and is in Hermite normal +form if either C<x> or C<y> is in HNF or is a prime ideal as output by +C<idealprimedec>, and this is given together with the sum of the +Archimedean information in C<x> and C<y> if both are given. + +If C<I<flag>> is non-zero, reduce the result using C<idealred>. + +X<idealmul>The library syntax is B<idealmul>C<(I<nf>,x,y)> (C<I<flag> = 0>) or +C<X<idealmulred>B<idealmulred>(I<nf>,x,y,I<prec>)> (C<I<flag> ! = 0>), where as usual, +C<I<prec>> is a C long integer representing the precision. + +=head2 X<idealnorm>idealnormC<(I<nf>,x)> + +computes the norm of the idealS< >C<x> +in the number fieldS< >C<I<nf>>. + +X<idealnorm>The library syntax is B<idealnorm>C<(I<nf>, x)>. + +=head2 X<idealpow>idealpowC<(I<nf>,x,k,{I<flag> = 0})> + +computes the C<k>-th power of +the ideal C<x> in the number field C<I<nf>>. C<k> can be positive, negative +or zero. The result is NOT reduced, it is really the C<k>-th ideal power, and +is given in HNF. + +If C<I<flag>> is non-zero, reduce the result using C<idealred>. Note however +that this is NOT the same as as C<idealpow(I<nf>,x,k)> followed by +reduction, since the reduction is performed throughout the powering process. + +The library syntax corresponding to C<I<flag> = 0> is +C<X<idealpow>B<idealpow>(I<nf>,x,k)>. If C<k> is a C<long>, you can use +C<X<idealpows>B<idealpows>(I<nf>,x,k)>. Corresponding to C<I<flag> = 1> is +C<X<idealpowred>B<idealpowred>(I<nf>,vp,k,I<prec>)>, where C<I<prec>> is a +C<long>. + +=head2 X<idealprimedec>idealprimedecC<(I<nf>,p)> + +computes the prime ideal +decomposition of the prime number C<p> in the number field C<I<nf>>. C<p> +must be a (positive) prime number. Note that the fact that C<p> is prime is +not checked, so if a non-prime number C<p> is given it may lead to +unpredictable results. + +The result is a vector of 5-component vectors, each representing one of the +prime ideals above C<p> in the number field C<I<nf>>. The representation +C<vp = [p,a,e,f,b]> of a prime ideal means the following. The prime ideal is +equal to C<pB<I<Z>>_K+F<alpha>B<I<Z>>_K> where C<B<I<Z>>_K> is the ring of integers of the field +and C<F<alpha> = F<sum>_i a_iF<omega>_i> where the C<F<omega>_i> form the integral basis +C<I<nf>.zk>, C<e> is the ramification index, C<f> is the residual index, +and C<b> is an C<n>-component column vector representing a C<F<beta> belongs to B<I<Z>>_K> such +that C<vp^{-1} = B<I<Z>>_K+F<beta>/pB<I<Z>>_K> which will be useful for computing +valuations, but which the user can ignore. The number C<F<alpha>> is guaranteed +to have a valuation equal to 1 at the prime ideal (this is automatic if +C<e E<gt> 1>). + +X<idealprimedec>The library syntax is B<idealprimedec>C<(I<nf>,p)>. + +=head2 X<idealprincipal>idealprincipalC<(I<nf>,x)> + +creates the principal ideal +generated by the algebraic number C<x> (which must be of type integer, +rational or polmod) in the number field C<I<nf>>. The result is a +one-column matrix. + +X<principalideal>The library syntax is B<principalideal>C<(I<nf>,x)>. + +=head2 X<idealred>idealredC<(I<nf>,I,{I<vdir> = 0})> + +X<LLL>LLL reduction of +the ideal C<I> in the number field I<nf>, along the direction I<vdir>. +If I<vdir> is present, it must be an C<r1+r2>-component vector (C<r1> and +C<r2> number of real and complex places of I<nf> as usual). + +This function finds a ``small'' C<a> in C<I> (it is an LLL pseudo-minimum +along direction I<vdir>). The result is the X<Hermite normal form>Hermite normal form of +the LLL-reduced ideal C<r I/a>, where C<r> is a rational number such that the +resulting ideal is integral and primitive. This is often, but not always, a +reduced ideal in the sense of X<Buchmann>Buchmann. If C<I> is an idele, the +logarithmic embeddings of C<a> are subtracted to the Archimedean part. + +More often than not, a X<principal ideal>principal ideal will yield the identity +matrix. This is a quick and dirty way to check if ideals are principal +without computing a full C<bnf> structure, but it's not a necessary +condition; hence, a non-trivial result doesn't prove the ideal is +non-trivial in the class group. + +Note that this is I<not> the same as the LLL reduction of the lattice +C<I> since ideal operations are involved. + +X<ideallllred>The library syntax is B<ideallllred>C<(I<nf>,x,I<vdir>,I<prec>)>, where an omitted +I<vdir> is coded as C<NULL>. + +=head2 X<idealstar>idealstarC<(I<nf>,I,{I<flag> = 1})> + +I<nf> being a number +field, and C<I> +either and ideal in any form, or a row vector whose first component is an +ideal and whose second component is a row vector of C<r_1> 0 or 1, outputs +necessary data for computing in the group C<(B<I<Z>>_K/I)^*>. + +If C<I<flag> = 2>, the result is a 5-component vector C<w>. C<w[1]> is the ideal +or module C<I> itself. C<w[2]> is the structure of the group. The other +components are difficult to describe and are used only in conjunction with +the function C<ideallog>. + +If C<I<flag> = 1> (default), as C<I<flag> = 2>, but do not compute explicit generators +for the cyclic components, which saves time. + +If C<I<flag> = 0>, computes the structure of C<(B<I<Z>>_K/I)^*> as a 3-component vector +C<v>. C<v[1]> is the order, C<v[2]> is the vector of SNFX<Smith normal form> +cyclic components and +C<v[3]> the corresponding generators. When the row vector is explicitly +included, the +non-zero elements of this vector are considered as real embeddings of +I<nf> in the order given by C<polroots>, i.e.S< >in I<nf>[6] +(C<I<nf>.roots>), and then C<I> is a module with components at infinity. + +To solve discrete logarithms (using C<ideallog>), you have to choose +C<I<flag> = 2>. + +X<idealstar0>The library syntax is B<idealstar0>C<(I<nf>,I,I<flag>)>. + +=head2 X<idealtwoelt>idealtwoeltC<(I<nf>,x,{a})> + +computes a two-element +representation of the ideal C<x> in the number field C<I<nf>>, using a +straightforward (exponential time) search. C<x> can be an ideal in any form, +(including perhaps an Archimedean part, which is ignored) and the result is a +row vector C<[a,F<alpha>]> with two components such that C<x = aB<I<Z>>_K+F<alpha>B<I<Z>>_K> +and C<a belongs to B<I<Z>>>, where C<a> is the one passed as argument if any. If C<x> is given +by at least two generators, C<a> is chosen to be the positive generator of +C<x F<cap> B<I<Z>>>. + +Note that when an explicit C<a> is given, we use an asymptotically faster +method, however in practice it is usually slower. + +X<ideal_two_elt0>The library syntax is B<ideal_two_elt0>C<(I<nf>,x,a)>, where an omitted C<a> is entered as +C<NULL>. + +=head2 X<idealval>idealvalC<(I<nf>,x,I<vp>)> + +gives the valuation of the +ideal C<x> at the prime ideal I<vp> in the number field C<I<nf>>, +where I<vp> must be a +5-component vector as given by C<idealprimedec>. + +X<idealval>The library syntax is B<idealval>C<(I<nf>,x,I<vp>)>, and the result is a C<long> +integer. + +=head2 X<ideleprincipal>ideleprincipalC<(I<nf>,x)> + +creates the principal idele +generated by the algebraic number C<x> (which must be of type integer, +rational or polmod) in the number field C<I<nf>>. The result is a +two-component vector, the first being a one-column matrix representing the +corresponding principal ideal, and the second being the vector with C<r_1+r_2> +components giving the complex logarithmic embedding of C<x>. + +X<principalidele>The library syntax is B<principalidele>C<(I<nf>,x)>. + +=head2 X<matalgtobasis>matalgtobasisC<(I<nf>,x)> + +C<I<nf>> being a number field in +C<nfinit> format, and C<x> a matrix whose coefficients are expressed as +polmods in C<I<nf>>, transforms this matrix into a matrix whose +coefficients are expressed on the integral basis of C<I<nf>>. This is the +same as applying C<nfalgtobasis> to each entry, but it would be dangerous +to use the same name. + +X<matalgtobasis>The library syntax is B<matalgtobasis>C<(I<nf>,x)>. + +=head2 X<matbasistoalg>matbasistoalgC<(I<nf>,x)> + +C<I<nf>> being a number field in +C<nfinit> format, and C<x> a matrix whose coefficients are expressed as +column vectors on the integral basis of C<I<nf>>, transforms this matrix +into a matrix whose coefficients are algebraic numbers expressed as +polmods. This is the same as applying C<nfbasistoalg> to each entry, but +it would be dangerous to use the same name. + +X<matbasistoalg>The library syntax is B<matbasistoalg>C<(I<nf>,x)>. + +=head2 X<modreverse>modreverseC<(a)> + +C<a> being a polmod C<A(X)> modulo C<T(X)>, finds +the ``reverse polmod'' C<B(X)> modulo C<Q(X)>, where C<Q> is the minimal +polynomial of C<a>, which must be equal to the degree of C<T>, and such that if +C<F<theta>> is a root of C<T> then C<F<theta> = B(F<alpha>)> for a certain root C<F<alpha>> +of C<Q>. + +This is very useful when one changes the generating element in algebraic +extensions. + +X<polmodrecip>The library syntax is B<polmodrecip>C<(x)>. + +=head2 X<newtonpoly>newtonpolyC<(x,p)> + +gives the vector of the slopes of the Newton +polygon of the polynomial C<x> with respect to the prime number C<p>. The C<n> +components of the vector are in decreasing order, where C<n> is equal to the +degree of C<x>. Vertical slopes occur iff the constant coefficient of C<x> is +zero and are denoted by C<VERYBIGINT>, the biggest single precision +integer representable on the machine (C<2^{31}-1> (resp.S< >C<2^{63}-1>) on 32-bit +(resp.S< >64-bit) machines), see L<Label se:valuation>. + +X<newtonpoly>The library syntax is B<newtonpoly>C<(x,p)>. + +=head2 X<nfalgtobasis>nfalgtobasisC<(I<nf>,x)> + +this is the inverse function of +C<nfbasistoalg>. Given an object C<x> whose entries are expressed as +algebraic numbers in the number field C<I<nf>>, transforms it so that the +entries are expressed as a column vector on the integral basis +C<I<nf>.zk>. + +X<algtobasis>The library syntax is B<algtobasis>C<(I<nf>,x)>. + +=head2 X<nfbasis>nfbasisC<(x,{I<flag> = 0},{p})> + +X<integral basis>integral basis of the number +field defined by the irreducible, preferably monic, polynomial C<x>, +using a modified version of the X<round 4>round 4 algorithm by +default. The binary digits of C<I<flag>> have the following meaning: + +1: assume that no square of a prime greater than the default C<primelimit> +divides the discriminant of C<x>, i.e.S< >that the index of C<x> has only small +prime divisors. + +2: use X<round 2>round 2 algorithm. For small degrees and coefficient size, this is +sometimes a little faster. (This program is the translation into C of a program +written by David X<Ford>Ford in Algeb.) + +Thus for instance, if C<I<flag> = 3>, this uses the round 2 algorithm and outputs +an order which will be maximal at all the small primes. + +If C<p> is present, we assume (without checking!) that it is the two-column +matrix of the factorization of the discriminant of the polynomial C<x>. Note +that it does I<not> have to be a complete factorization. This is +especially useful if only a local integral basis for some small set of places +is desired: only factors with exponents greater or equal to 2 will be +considered. + +X<nfbasis0>The library syntax is B<nfbasis0>C<(x,I<flag>,p)>. An extended version +is C<X<nfbasis>B<nfbasis>(x,&d,I<flag>,p)>, where C<d> will receive the discriminant of +the number field (I<not> of the polynomial C<x>), and an omitted C<p> should +be input as C<gzero>. Also available are C<X<base>B<base>(x,&d)> (C<I<flag> = 0>), +C<X<base2>B<base2>(x,&d)> (C<I<flag> = 2>) and C<X<factoredbase>B<factoredbase>(x,p,&d)>. + +=head2 X<nfbasistoalg>nfbasistoalgC<(I<nf>,x)> + +this is the inverse function of +C<nfalgtobasis>. Given an object C<x> whose entries are expressed on the +integral basis C<I<nf>.zk>, transforms it into an object whose entries +are algebraic numbers (i.e.S< >polmods). + +X<basistoalg>The library syntax is B<basistoalg>C<(I<nf>,x)>. + +=head2 X<nfdetint>nfdetintC<(I<nf>,x)> + +given a pseudo-matrix C<x>, computes a +non-zero ideal contained in (i.e.S< >multiple of) the determinant of C<x>. This +is particularly useful in conjunction with C<nfhnfmod>. + +X<nfdetint>The library syntax is B<nfdetint>C<(I<nf>,x)>. + +=head2 X<nfdisc>nfdiscC<(x,{I<flag> = 0},{p})> + +X<field discriminant>field discriminant of the +number field defined by the integral, preferably monic, irreducible +polynomial C<x>. C<I<flag>> and C<p> are exactly as in C<nfbasis>. That is, C<p> +provides the matrix of a partial factorization of the discriminant of C<x>, +and binary digits of C<I<flag>> are as follows: + +1: assume that no square of a prime greater than C<primelimit> +divides the discriminant. + +2: use the round 2 algorithm, instead of the default X<round 4>round 4. +This should be +slower except maybe for polynomials of small degree and coefficients. + +X<nfdiscf0>The library syntax is B<nfdiscf0>C<(x,I<flag>,p)> where, to omit C<p>, you should input C<gzero>. You +can also use C<X<discf>B<discf>(x)> (C<I<flag> = 0>). + +=head2 X<nfeltdiv>nfeltdivC<(I<nf>,x,y)> + +given two elements C<x> and C<y> in +I<nf>, computes their quotient C<x/y> in the number field C<I<nf>>. + +X<element_div>The library syntax is B<element_div>C<(I<nf>,x,y)>. + +=head2 X<nfeltdiveuc>nfeltdiveucC<(I<nf>,x,y)> + +given two elements C<x> and C<y> in +I<nf>, computes an algebraic integer C<q> in the number field C<I<nf>> +such that the components of C<x-qy> are reasonably small. In fact, this is +functionally identical to C<round(nfeltdiv(I<nf>,x,y))>. + +X<nfdiveuc>The library syntax is B<nfdiveuc>C<(I<nf>,x,y)>. + +=head2 X<nfeltdivmodpr>nfeltdivmodprC<(I<nf>,x,y,I<pr>)> + +given two elements C<x> +and C<y> in I<nf> and I<pr> a prime ideal in C<modpr> format (see +X<nfmodprinit>C<nfmodprinit>), computes their quotient C<x / y> modulo the prime ideal +I<pr>. + +X<element_divmodpr>The library syntax is B<element_divmodpr>C<(I<nf>,x,y,I<pr>)>. + +=head2 X<nfeltdivrem>nfeltdivremC<(I<nf>,x,y)> + +given two elements C<x> and C<y> in +I<nf>, gives a two-element row vector C<[q,r]> such that C<x = qy+r>, C<q> is +an algebraic integer in C<I<nf>>, and the components of C<r> are +reasonably small. + +X<nfdivres>The library syntax is B<nfdivres>C<(I<nf>,x,y)>. + +=head2 X<nfeltmod>nfeltmodC<(I<nf>,x,y)> + +given two elements C<x> and C<y> in +I<nf>, computes an element C<r> of C<I<nf>> of the form C<r = x-qy> with +C<q> and algebraic integer, and such that C<r> is small. This is functionally +identical to + +S< >C<x - nfeltmul(I<nf>,round(nfeltdiv(I<nf>,x,y)),y).> + +X<nfmod>The library syntax is B<nfmod>C<(I<nf>,x,y)>. + +=head2 X<nfeltmul>nfeltmulC<(I<nf>,x,y)> + +given two elements C<x> and C<y> in +I<nf>, computes their product C<x*y> in the number field C<I<nf>>. + +X<element_mul>The library syntax is B<element_mul>C<(I<nf>,x,y)>. + +=head2 X<nfeltmulmodpr>nfeltmulmodprC<(I<nf>,x,y,I<pr>)> + +given two elements C<x> and +C<y> in I<nf> and I<pr> a prime ideal in C<modpr> format (see +X<nfmodprinit>C<nfmodprinit>), computes their product C<x*y> modulo the prime ideal +I<pr>. + +X<element_mulmodpr>The library syntax is B<element_mulmodpr>C<(I<nf>,x,y,I<pr>)>. + +=head2 X<nfeltpow>nfeltpowC<(I<nf>,x,k)> + +given an element C<x> in I<nf>, +and a positive or negative integer C<k>, computes C<x^k> in the number field +C<I<nf>>. + +X<element_pow>The library syntax is B<element_pow>C<(I<nf>,x,k)>. + +=head2 X<nfeltpowmodpr>nfeltpowmodprC<(I<nf>,x,k,I<pr>)> + +given an element C<x> in +I<nf>, an integer C<k> and a prime ideal I<pr> in C<modpr> format +(see X<nfmodprinit>C<nfmodprinit>), computes C<x^k> modulo the prime ideal I<pr>. + +X<element_powmodpr>The library syntax is B<element_powmodpr>C<(I<nf>,x,k,I<pr>)>. + +=head2 X<nfeltreduce>nfeltreduceC<(I<nf>,x,I<ideal>)> + +given an ideal in +Hermite normal form and an element C<x> of the number field C<I<nf>>, +finds an element C<r> in C<I<nf>> such that C<x-r> belongs to the ideal +and C<r> is small. + +X<element_reduce>The library syntax is B<element_reduce>C<(I<nf>,x,I<ideal>)>. + +=head2 X<nfeltreducemodpr>nfeltreducemodprC<(I<nf>,x,I<pr>)> + +given +an element C<x> of the number field C<I<nf>> and a prime ideal I<pr> in +C<modpr> format compute a canonical representative for the class of C<x> +modulo I<pr>. + +X<nfreducemodpr2>The library syntax is B<nfreducemodpr2>C<(I<nf>,x,I<pr>)>. + +=head2 X<nfeltval>nfeltvalC<(I<nf>,x,I<pr>)> + +given an element C<x> in +I<nf> and a prime ideal I<pr> in the format output by +C<idealprimedec>, computes their the valuation at I<pr> of the +element C<x>. The same result could be obtained using +C<idealval(I<nf>,x,I<pr>)> (since C<x> would then be converted to a +principal ideal), but it would be less efficient. + +X<element_val>The library syntax is B<element_val>C<(I<nf>,x,I<pr>)>, and the result is a C<long>. + +=head2 X<nffactor>nffactorC<(I<nf>,x)> + +factorization of the univariate +polynomial C<x> over the number field C<I<nf>> given by C<nfinit>. C<x> +has coefficients in C<I<nf>> (i.e.S< >either scalar, polmod, polynomial or +column vector). The main variable of C<I<nf>> must be of I<lower> +priority than that of C<x> (in other words, the variable number of C<I<nf>> +must be I<greater> than that of C<x>). However if the polynomial defining +the number field occurs explicitly in the coefficients of C<x> (as modulus of +a C<t_POLMOD>), its main variable must be I<the same> as the main +variable of C<x>. For example, + + ? nf = nfinit(y^2 + 1); + ? nffactor(nf, x^2 + y); \\ OK + ? nffactor(nf, x^2 + Mod(y, y^2+1)); \\ OK + ? nffactor(nf, x^2 + Mod(z, z^2+1)); \\ WRONG + +X<nffactor>The library syntax is B<nffactor>C<(I<nf>,x)>. + +=head2 X<nffactormod>nffactormodC<(I<nf>,x,I<pr>)> + +factorization of the +univariate polynomial C<x> modulo the prime ideal I<pr> in the number +field C<I<nf>>. C<x> can have coefficients in the number field (scalar, +polmod, polynomial, column vector) or modulo the prime ideal (integermod +modulo the rational prime under I<pr>, polmod or polynomial with +integermod coefficients, column vector of integermod). The prime ideal +I<pr> I<must> be in the format output by C<idealprimedec>. The +main variable of C<I<nf>> must be of lower priority than that of C<x> (in +other words the variable number of C<I<nf>> must be greater than that of +C<x>). However if the coefficients of the number field occur explicitly (as +polmods) as coefficients of C<x>, the variable of these polmods I<must> +be the same as the main variable of C<t> (see C<nffactor>). + +X<nffactormod>The library syntax is B<nffactormod>C<(I<nf>,x,I<pr>)>. + +=head2 X<nfgaloisapply>nfgaloisapplyC<(I<nf>,I<aut>,x)> + +C<I<nf>> being a +number field as output by C<nfinit>, and I<aut> being a X<Galois>Galois +automorphism of C<I<nf>> expressed either as a polynomial or a polmod +(such automorphisms being found using for example one of the variants of +C<nfgaloisconj>), computes the action of the automorphism I<aut> on +the object C<x> in the number field. C<x> can be an element (scalar, polmod, +polynomial or column vector) of the number field, an ideal (either given by +C<B<I<Z>>_K>-generators or by a B<I<Z>>-basis), a prime ideal (given as a 5-element +row vector) or an idele (given as a 2-element row vector). Because of +possible confusion with elements and ideals, other vector or matrix +arguments are forbidden. + +X<galoisapply>The library syntax is B<galoisapply>C<(I<nf>,I<aut>,x)>. + +=head2 X<nfgaloisconj>nfgaloisconjC<(I<nf>,{I<flag> = 0},{d})> + +C<I<nf>> being a +number field as output by C<nfinit>, computes the conjugates of a root +C<r> of the non-constant polynomial C<x = I<nf>[1]> expressed as +polynomials in C<r>. This can be used even if the number field C<I<nf>> is +not X<Galois>Galois since some conjugates may lie in the field. As a note to +old-timers of PARI, starting with version 2.0.17 this function works much +better than in earlier versions. + +C<I<nf>> can simply be a polynomial if C<I<flag> ! = 1>. + +If no flags or C<I<flag> = 0>, if C<I<nf>> is a number field use a +combination of flag C<4> and C<1> and the result is always complete, +else use a combination of flag C<4> and C<2> and the result is subject +to the restriction of C<I<flag> = 2>, but a warning is issued when it is not +proven complete. + +If C<I<flag> = 1>, use C<nfroots> (require a number field). + +If C<I<flag> = 2>, use complex approximations to the roots and an integral +X<LLL>LLL. The result is not guaranteed to be complete: some +conjugates may be missing (no warning issued), especially so if the +corresponding polynomial has a huge index. In that case, increasing +the default precision may help. + +If C<I<flag> = 4>, use Allombert's algorithm and permutation testing. If the +field is Galois with ``weakly'' super solvable Galois group, return +the complete list of automorphisms, else only the identity element. If +present, C<d> is assumed to be a multiple of the least common +denominator of the conjugates expressed as polynomial in a root of +I<pol>. + +A group G is ``weakly'' super solvable if it contains a super solvable +normal subgroup C<H> such that C<G = H> , or C<G/H ~ A_4> , or C<G/H ~ +S_4>. Abelian and nilpotent groups are ``weakly'' super solvable. In +practice, almost all groups of small order are ``weakly'' super solvable, the +exceptions having order 36(1 exception), 48(2), 56(1), 60(1), 72(5), 75(1), +80(1), 96(10) and C< E<gt>= 108>. + +Hence C<I<flag> = 4> permits to quickly check whether a polynomial of order +strictly less than C<36> is Galois or not. This method is much faster than +C<nfroots> and can be applied to polynomials of degree larger than C<50>. + +X<galoisconj0>The library syntax is B<galoisconj0>C<(I<nf>,I<flag>,d,I<prec>)>. Also available are +C<X<galoisconj>B<galoisconj>(I<nf>)> for C<I<flag> = 0>, +C<X<galoisconj2>B<galoisconj2>(I<nf>,n,I<prec>)> for C<I<flag> = 2> where C<n> is a bound +on the number of conjugates, and C<X<galoisconj4>B<galoisconj4>(I<nf>,d)> +corresponding to C<I<flag> = 4>. + +=head2 X<nfhilbert>nfhilbertC<(I<nf>,a,b,{I<pr>})> + +if I<pr> is omitted, +compute the global X<Hilbert symbol>Hilbert symbol C<(a,b)> in C<I<nf>>, that is C<1> +if C<x^2 - a y^2 - b z^2> has a non trivial solution C<(x,y,z)> in C<I<nf>>, +and C<-1> otherwise. Otherwise compute the local symbol modulo the prime ideal +I<pr> (as output by C<idealprimedec>). + +X<nfhilbert>The library syntax is B<nfhilbert>C<(I<nf>,a,b,I<pr>)>, where an omitted I<pr> is coded +as C<NULL>. + +=head2 X<nfhnf>nfhnfC<(I<nf>,x)> + +given a pseudo-matrix C<(A,I)>, finds a +pseudo-basis in X<Hermite normal form>Hermite normal form of the module it generates. + +X<nfhermite>The library syntax is B<nfhermite>C<(I<nf>,x)>. + +=head2 X<nfhnfmod>nfhnfmodC<(I<nf>,x,I<detx>)> + +given a pseudo-matrix C<(A,I)> +and an ideal I<detx> which is contained in (read integral multiple of) the +determinant of C<(A,I)>, finds a pseudo-basis in X<Hermite normal form>Hermite normal form +of the module generated by C<(A,I)>. This avoids coefficient explosion. +I<detx> can be computed using the function C<nfdetint>. + +X<nfhermitemod>The library syntax is B<nfhermitemod>C<(I<nf>,x,I<detx>)>. + +=head2 X<nfinit>nfinitC<(I<pol>,{I<flag> = 0})> + +I<pol> being a non-constant, +preferably monic, irreducible polynomial in C<B<I<Z>>[X]>, initializes a +I<number field> structure (C<nf>) associated to the field C<K> defined +by I<pol>. As such, it's a technical object passed as the first argument +to most C<nf>I<xxx> functions, but it contains some information which +may be directly useful. Access to this information via I<member +functions> is prefered since the specific data organization specified below +may change in the future. Currently, C<nf> is a row vector with 9 +components: + +C<I<nf>[1]> contains the polynomial I<pol> (C<I<nf>.pol>). + +C<I<nf>[2]> contains C<[r1,r2]> (C<I<nf>.sign>), the number of real +and complex places of C<K>. + +C<I<nf>[3]> contains the discriminant C<d(K)> (C<I<nf>.disc>) of C<K>. + +C<I<nf>[4]> contains the index of C<I<nf>[1]>, +i.e.S< >C<[B<I<Z>>_K : B<I<Z>>[F<theta>]]>, where C<F<theta>> is any root of C<I<nf>[1]>. + +C<I<nf>[5]> is a vector containing 7 matrices C<M>, C<MC>, C<T2>, C<T>, +C<MD>, C<TI>, C<MDI> useful for certain computations in the number field C<K>. + +S< >S< >C<B<*>> C<M> is the C<(r1+r2) x n> matrix whose columns represent +the numerical values of the conjugates of the elements of the integral +basis. + +S< >S< >C<B<*>> C<MC> is essentially the conjugate of the transpose of C<M>, +except that the last C<r2> columns are also multiplied by 2. + +S< >S< >C<B<*>> C<T2> is an C<n x n> matrix equal to the real part of the +product C<MC.M> (which is a real positive definite symmetric matrix), the +so-called C<T_2>-matrix (C<I<nf>.t2>). + +S< >S< >C<B<*>> C<T> is the C<n x n> matrix whose coefficients are +C<Tr(F<omega>_iF<omega>_j)> where the C<F<omega>_i> are the elements of the +integral basis. Note that C<T = \overline{MC}.M> and in particular that +C<T = T_2> if the field is totally real (in practice C<T_2> will have real +approximate entries and C<T> will have integer entries). Note also that +C< F<det> (T)> is equal to the discriminant of the field C<K>. + +S< >S< >C<B<*>> The columns of C<MD> (C<I<nf>.diff>) express a B<I<Z>>-basis +of the different of C<K> on the integral basis. + +S< >S< >C<B<*>> C<TI> is equal to C<d(K)T^{-1}>, which has integral +coefficients. Note that, understood as as ideal, the matrix C<T^{-1}> +generates the codifferent ideal. + +S< >S< >C<B<*>> Finally, C<MDI> is a two-element representation (for faster +ideal product) of C<d(K)> times the codifferent ideal +(C<I<nf>.disc*I<nf>.codiff>, which is an integral ideal). C<MDI> +is only used in X<idealinv>C<idealinv>. + +C<I<nf>[6]> is the vector containing the C<r1+r2> roots +(C<I<nf>.roots>) of C<I<nf>[1]> corresponding to the C<r1+r2> +embeddings of the number field into B<I<C>> (the first C<r1> components are real, +the next C<r2> have positive imaginary part). + +C<I<nf>[7]> is an integral basis in Hermite normal form for C<B<I<Z>>_K> +(C<I<nf>.zk>) expressed on the powers ofS< >C<F<theta>>. + +C<I<nf>[8]> is the C<n x n> integral matrix expressing the power +basis in terms of the integral basis, and finally + +C<I<nf>[9]> is the C<n x n^2> matrix giving the multiplication table +of the integral basis. + +If a non monic polynomial is input, C<nfinit> will transform it into a +monic one, then reduce it (see C<I<flag> = 3>). It is allowed, though not very +useful given the existence of X<nfnewprec>B<nfnewprec>, to input a C<nf> or a +C<bnf> instead of a polynomial. + +The special input format C<[x,B]> is also accepted where C<x> is a polynomial +as above and C<B> is the integer basis, as computed by X<nfbasis>C<nfbasis>. This can +be useful since C<nfinit> uses the round 4 algorithm by default, which can +be very slow in pathological cases where round 2 (C<nfbasis(x,2)>) would +succeed very quickly. + +If C<I<flag> = 2>: I<pol> is changed into another polynomial C<P> defining the same +number field, which is as simple as can easily be found using the +C<polred> algorithm, and all the subsequent computations are done using +this new polynomial. In particular, the first component of the result is the +modified polynomial. + +If C<I<flag> = 3>, does a C<polred> as in case 2, but outputs +C<[I<nf>,Mod(a,P)]>, where C<I<nf>> is as before and +C<Mod(a,P) = Mod(x,I<pol>)> gives the change of +variables. This is implicit when I<pol> is not monic: first a linear change +of variables is performed, to get a monic polynomial, then a C<polred> +reduction. + +If C<I<flag> = 4>, as C<2> but uses a partial C<polred>. + +If C<I<flag> = 5>, as C<3> using a partial C<polred>. + +X<nfinit0>The library syntax is B<nfinit0>C<(x,I<flag>,I<prec>)>. + +=head2 X<nfisideal>nfisidealC<(I<nf>,x)> + +returns 1 if C<x> is an ideal in +the number field C<I<nf>>, 0 otherwise. + +X<isideal>The library syntax is B<isideal>C<(x)>. + +=head2 X<nfisincl>nfisinclC<(x,y)> + +tests whether the number field C<K> defined +by the polynomial C<x> is conjugate to a subfield of the field C<L> defined +by C<y> (where C<x> and C<y> must be in C<B<I<Q>>[X]>). If they are not, the output +is the number 0. If they are, the output is a vector of polynomials, each +polynomial C<a> representing an embedding of C<K> into C<L>, i.e.S< >being such +that C<y | x o a>. + +If C<y> is a number field (I<nf>), a much faster algorithm is used +(factoring C<x> over C<y> using X<nffactor>C<nffactor>). Before version 2.0.14, this +wasn't guaranteed to return all the embeddings, hence was triggered by a +special flag. This is no more the case. + +X<nfisincl>The library syntax is B<nfisincl>C<(x,y,I<flag>)>. + +=head2 X<nfisisom>nfisisomC<(x,y)> + +as X<nfisincl>C<nfisincl>, but tests +for isomorphism. If either C<x> or C<y> is a number field, a much faster +algorithm will be used. + +X<nfisisom>The library syntax is B<nfisisom>C<(x,y,I<flag>)>. + +=head2 X<nfnewprec>nfnewprecC<(I<nf>)> + +transforms the number field C<I<nf>> +into the corresponding data using current (usually larger) precision. This +function works as expected if C<I<nf>> is in fact a C<I<bnf>> (update +C<I<bnf>> to current precision) but may be quite slow (many generators of +principal ideals have to be computed). + +X<nfnewprec>The library syntax is B<nfnewprec>C<(I<nf>,I<prec>)>. + +=head2 X<nfkermodpr>nfkermodprC<(I<nf>,a,I<pr>)> + +kernel of the matrix C<a> in +C<B<I<Z>>_K/I<pr>>, where I<pr> is in B<modpr> format +(see C<nfmodprinit>). + +X<nfkermodpr>The library syntax is B<nfkermodpr>C<(I<nf>,a,I<pr>)>. + +=head2 X<nfmodprinit>nfmodprinitC<(I<nf>,I<pr>)> + +transforms the prime ideal +I<pr> into X<modpr>C<modpr> format necessary for all operations modulo +I<pr> in the number field I<nf>. Returns a two-component vector +C<[P,a]>, where C<P> is the X<Hermite normal form>Hermite normal form of I<pr>, and C<a> is +an integral element congruent to C<1> modulo I<pr>, and congruent to C<0> +modulo C<p / pr^e>. Here C<p = B<I<Z>> F<cap> I<pr>> and C<e> +is the absolute ramification index.X<Label se:nfmodprinit> + +X<nfmodprinit>The library syntax is B<nfmodprinit>C<(I<nf>,I<pr>)>. + +=head2 X<nfsubfields>nfsubfieldsC<(I<nf>,{d = 0})> + +finds all subfields of degree C<d> +of the number field C<I<nf>> (all subfields if C<d> is null or omitted). +The result is a vector of subfields, each being given by C<[g,h]>, where C<g> is an +absolute equation and C<h> expresses one of the roots of C<g> in terms of the +root C<x> of the polynomial defining C<I<nf>>. This is a crude +implementation by M.S< >Olivier of an algorithm due to J.S< >KlE<uuml>ners. + +X<subfields>The library syntax is B<subfields>C<(I<nf>,d)>. + +=head2 X<nfroots>nfrootsC<(I<nf>,x)> + +roots of the polynomial C<x> in the number +field C<I<nf>> given by C<nfinit> without multiplicity. C<x> has +coefficients in the number field (scalar, polmod, polynomial, column +vector). The main variable of C<I<nf>> must be of lower priority than that +of C<x> (in other words the variable number of C<I<nf>> must be greater than +that of C<x>). However if the coefficients of the number field occur +explicitly (as polmods) as coefficients of C<x>, the variable of these +polmods I<must> be the same as the main variable of C<t> (see +C<nffactor>). + +X<nfroots>The library syntax is B<nfroots>C<(I<nf>,x)>. + +=head2 X<nfrootsof1>nfrootsof1C<(I<nf>)> + +computes the number of roots of unity +C<w> and a primitive C<w>-th root of unity (expressed on the integral basis) +belonging to the number field C<I<nf>>. The result is a two-component +vector C<[w,z]> where C<z> is a column vector expressing a primitive C<w>-th +root of unity on the integral basis C<I<nf>.zk>. + +X<rootsof1>The library syntax is B<rootsof1>C<(I<nf>)>. + +=head2 X<nfsnf>nfsnfC<(I<nf>,x)> + +given a torsion module C<x> as a 3-component +row +vector C<[A,I,J]> where C<A> is a square invertible C<n x n> matrix, C<I> and +C<J> are two ideal lists, outputs an ideal list C<d_1,...,d_n> which is the +X<Smith normal form>Smith normal form of C<x>. In other words, C<x> is isomorphic to +C<B<I<Z>>_K/d_1 F<oplus> ... F<oplus> B<I<Z>>_K/d_n> and C<d_i> divides C<d_{i-1}> for C<i E<gt>= 2>. +The link between C<x> and C<[A,I,J]> is as follows: if C<e_i> is the canonical +basis of C<K^n>, C<I = [b_1,...,b_n]> and C<J = [a_1,...,a_n]>, then C<x> is +isomorphic to + +S< >C< (b_1e_1 F<oplus> ... F<oplus> b_ne_n) / (a_1A_1 F<oplus> ... F<oplus> a_nA_n) + , > + +where the C<A_j> are the columns of the matrix C<A>. Note that every finitely +generated torsion module can be given in this way, and even with C<b_i = Z_K> +for all C<i>. + +X<nfsmith>The library syntax is B<nfsmith>C<(I<nf>,x)>. + +=head2 X<nfsolvemodpr>nfsolvemodprC<(I<nf>,a,b,I<pr>)> + +solution of C<a.x = b> +in C<B<I<Z>>_K/I<pr>>, where C<a> is a matrix and C<b> a column vector, and where +I<pr> is in B<modpr> format (see C<nfmodprinit>). + +X<nfsolvemodpr>The library syntax is B<nfsolvemodpr>C<(I<nf>,a,b,I<pr>)>. + +=head2 X<polcompositum>polcompositumC<(x,y,{I<flag> = 0})> + +C<x> and C<y> being polynomials +in C<B<I<Z>>[X]> in the same variable, outputs a vector giving the list of all +possible composita of the number fields defined by C<x> and C<y>, if C<x> and +C<y> are irreducible, or of the corresponding E<eacute>tale algebras, if they are +only squarefree. Returns an error if one of the polynomials is not +squarefree. When one of the polynomials is irreducible (say C<x>), it is +often I<much> faster to use C<nffactor(nfinit(x), y)> then +X<rnfequation>C<rnfequation>. + +If C<I<flag> = 1>, outputs a vector of 4-component vectors C<[z,a,b,k]>, where C<z> +ranges through the list of all possible compositums as above, and C<a> +(resp. C<b>) expresses the root of C<x> (resp. C<y>) as a polmod in a root of +C<z>, and C<k> is a small integer k such that C<a+kb> is the chosen root of +C<z>. + +The compositum will quite often be defined by a complicated polynomial, +which it is advisable to reduce before further work. Here is a simple +example involving the field C<B<I<Q>>(F<zeta>_5, 5^{1/5})>: + + ? z = polcompositum(x^5 - 5, polcyclo(5), 1)[1]; + ? pol = z[1] \\ pol defines the compositum + %2 = x^20 + 5*x^19 + 15*x^18 + 35*x^17 + 70*x^16 + 141*x^15 + 260*x^14 \ + + 355*x^13 + 95*x^12 - 1460*x^11 - 3279*x^10 - 3660*x^9 - 2005*x^8 \ + + 705*x^7 + 9210*x^6 + 13506*x^5 + 7145*x^4 - 2740*x^3 + 1040*x^2 \ + - 320*x + 256 + ? a = z[2]; a^5 - 5 \\ a is a fifth root of 5 + %3 = 0 + ? z = polredabs(pol, 1); \\ look for a simpler polynomial + ? pol = z[1] + %5 = x^20 + 25*x^10 + 5 + ? a = subst(a.pol, x, z[2]) \\ a in the new coordinates + %6 = Mod(-5/22*x^19 + 1/22*x^14 - 123/22*x^9 + 9/11*x^4, x^20 + 25*x^10 + 5) + +X<polcompositum0>The library syntax is B<polcompositum0>C<(x,y,I<flag>)>. + +=head2 X<polgalois>polgaloisC<(x)> + +X<Galois>Galois group of the non-constant polynomial +C<x belongs to B<I<Q>>[X]>. In the present version B<2.2.0>, C<x> must be irreducible and +the degree of C<x> must be less than or equal to 7. On certain versions for +which the data file of Galois resolvents has been installed (available +in the Unix distribution as a separate package), degrees 8, 9, 10 and 11 +are also implemented. + +The output is a 3-component vector C<[n,s,k]> with the following meaning: C<n> +is the cardinality of the group, C<s> is its signature (C<s = 1> if the group is +a subgroup of the alternating group C<A_n>, C<s = -1> otherwise), and C<k> is the +number of the group corresponding to a given pair C<(n,s)> (C<k = 1> except in 2 +cases). Specifically, the groups are coded as follows, using standard +notations (see GTM 138, quoted at the beginning of this section; see also +``The transitive groups of degree up to eleven'', by G.S< >Butler and J.S< >McKay +in Communications in Algebra, vol.S< >11, 1983, pp.S< >863--911): + +In degree 1: C<S_1 = [1,-1,1]>. + +In degree 2: C<S_2 = [2,-1,1]>. + +In degree 3: C<A_3 = C_3 = [3,1,1]>, C<S_3 = [6,-1,1]>. + +In degree 4: C<C_4 = [4,-1,1]>, C<V_4 = [4,1,1]>, C<D_4 = [8,-1,1]>, C<A_4 = [12,1,1]>, +C<S_4 = [24,-1,1]>. + +In degree 5: C<C_5 = [5,1,1]>, C<D_5 = [10,1,1]>, C<M_{20} = [20,-1,1]>, +C<A_5 = [60,1,1]>, C<S_5 = [120,-1,1]>. + +In degree 6: C<C_6 = [6,-1,1]>, C<S_3 = [6,-1,2]>, C<D_6 = [12,-1,1]>, C<A_4 = [12,1,1]>, +C<G_{18} = [18,-1,1]>, C<S_4^ -= [24,-1,1]>, C<A_4 x C_2 = [24,-1,2]>, +C<S_4^ += [24,1,1]>, C<G_{36}^ -= [36,-1,1]>, C<G_{36}^ += [36,1,1]>, +C<S_4 x C_2 = [48,-1,1]>, C<A_5 = PSL_2(5) = [60,1,1]>, C<G_{72} = [72,-1,1]>, +C<S_5 = PGL_2(5) = [120,-1,1]>, C<A_6 = [360,1,1]>, C<S_6 = [720,-1,1]>. + +In degree 7: C<C_7 = [7,1,1]>, C<D_7 = [14,-1,1]>, C<M_{21} = [21,1,1]>, +C<M_{42} = [42,-1,1]>, C<PSL_2(7) = PSL_3(2) = [168,1,1]>, C<A_7 = [2520,1,1]>, +C<S_7 = [5040,-1,1]>. + +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. + +X<galois>The library syntax is B<galois>C<(x,I<prec>)>. + +=head2 X<polred>polredC<(x,{I<flag> = 0},{p})> + +finds polynomials with reasonably +small coefficients defining subfields of the number field defined by C<x>. +One of the polynomials always defines B<I<Q>> (hence is equal to C<x-1>), +and another always defines the same number field as C<x> if C<x> is irreducible. +All C<x> accepted by X<nfinit>C<nfinit> are also allowed here (e.g. non-monic +polynomials, C<nf>, C<bnf>, C<[x,Z_K_basis]>). + +The following binary digits of C<I<flag>> are significant: + +1: does a partial reduction only. This means that only a suborder of the +maximal order may be used. + +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 C<p> is given, it is assumed that it is the two-column matrix of the +factorization of the discriminant of the polynomial C<x>. + +X<polred0>The library syntax is B<polred0>C<(x,I<flag>,p,I<prec>)>, where an omitted C<p> is +coded by C<gzero>. Also available are C<X<polred>B<polred>(x,I<prec>)> and +C<X<factoredpolred>B<factoredpolred>(x,p,I<prec>)>, both corresponding to C<I<flag> = 0>. + +=head2 X<polredabs>polredabsC<(x,{I<flag> = 0})> + +finds one of the polynomial defining +the same number field as the one defined by C<x>, and such that the sum of the +squares of the modulus of the roots (i.e.S< >the C<T_2>-norm) is minimal. +All C<x> accepted by X<nfinit>C<nfinit> are also allowed here (e.g. non-monic +polynomials, C<nf>, C<bnf>, C<[x,Z_K_basis]>). + +The binary digits of C<I<flag>> mean + +1: outputs a two-component row vector C<[P,a]>, where C<P> is the default +output and C<a> is an element expressed on a root of the polynomial C<P>, +whose minimal polynomial is equal to C<x>. + +4: gives I<all> polynomials of minimal C<T_2> norm (of the two polynomials +C<P(x)> and C<P(-x)>, only one is given). + +X<polredabs0>The library syntax is B<polredabs0>C<(x,I<flag>,I<prec>)>. + +=head2 X<polredord>polredordC<(x)> + +finds polynomials with reasonably small +coefficients and of the same degree as that of C<x> defining suborders of the +order defined by C<x>. One of the polynomials always defines B<I<Q>> (hence +is equal to C<(x-1)^n>, where C<n> is the degree), and another always defines +the same order as C<x> if C<x> is irreducible. + +X<ordred>The library syntax is B<ordred>C<(x)>. + +=head2 X<poltschirnhaus>poltschirnhausC<(x)> + +applies a random Tschirnhausen +transformation to the polynomial C<x>, which is assumed to be non-constant +and separable, so as to obtain a new equation for the E<eacute>tale algebra +defined by C<x>. This is for instance useful when computing resolvents, +hence is used by the C<polgalois> function. + +X<tschirnhaus>The library syntax is B<tschirnhaus>C<(x)>. + +=head2 X<rnfalgtobasis>rnfalgtobasisC<(I<rnf>,x)> + +C<I<rnf>> being a relative number +field extension C<L/K> as output by C<rnfinit> and C<x> being an element of +C<L> expressed as a polynomial or polmod with polmod coefficients, expresses +C<x> on the relative integral basis. + +X<rnfalgtobasis>The library syntax is B<rnfalgtobasis>C<(I<rnf>,x)>. + +=head2 X<rnfbasis>rnfbasisC<(I<bnf>,x)> + +given a big number field C<I<bnf>> as +output by C<bnfinit>, and either a polynomial C<x> with coefficients in +C<I<bnf>> defining a relative extension C<L> of C<I<bnf>>, or a +pseudo-basis C<x> of such an extension, gives either a true C<I<bnf>>-basis +of C<L> if it exists, or an C<n+1>-element generating set of C<L> if not, where +C<n> is the rank of C<L> over C<I<bnf>>. + +X<rnfbasis>The library syntax is B<rnfbasis>C<(I<bnf>,x)>. + +=head2 X<rnfbasistoalg>rnfbasistoalgC<(I<rnf>,x)> + +C<I<rnf>> being a relative number +field extension C<L/K> as output by C<rnfinit> and C<x> being an element of +C<L> expressed on the relative integral basis, computes the representation of +C<x> as a polmod with polmods coefficients. + +X<rnfbasistoalg>The library syntax is B<rnfbasistoalg>C<(I<rnf>,x)>. + +=head2 X<rnfcharpoly>rnfcharpolyC<(I<nf>,T,a,{v = x})> + +characteristic polynomial of +C<a> over C<I<nf>>, where C<a> belongs to the algebra defined by C<T> over +C<I<nf>>, i.e.S< >C<I<nf>[X]/(T)>. Returns a polynomial in variable C<v> +(C<x> by default). + +X<rnfcharpoly>The library syntax is B<rnfcharpoly>C<(I<nf>,T,a,v)>, where C<v> is a variable number. + +=head2 X<rnfconductor>rnfconductorC<(I<bnf>,I<pol>)> + +C<I<bnf>> being a big number +field as output by C<bnfinit>, and I<pol> a relative polynomial defining +an X<Abelian extension>Abelian extension, computes the class field theory conductor of this +Abelian extension. The result is a 3-component vector +C<[I<conductor>,I<rayclgp>,I<subgroup>]>, where I<conductor> is +the conductor of the extension given as a 2-component row vector +C<[f_0,f_ oo ]>, I<rayclgp> is the full ray class group corresponding to +the conductor given as a 3-component vector [h,cyc,gen] as usual for a group, +and I<subgroup> is a matrix in HNF defining the subgroup of the ray class +group on the given generators gen. + +X<rnfconductor>The library syntax is B<rnfconductor>C<(I<rnf>,I<pol>,I<prec>)>. + +=head2 X<rnfdedekind>rnfdedekindC<(I<nf>,I<pol>,I<pr>)> + +given a number field +C<I<nf>> as output by C<nfinit> and a polynomial I<pol> with +coefficients in C<I<nf>> defining a relative extension C<L> of C<I<nf>>, +evaluates the relative X<Dedekind>Dedekind criterion over the order defined by a +root of I<pol> for the prime ideal I<pr> and outputs a 3-component +vector as the result. The first component is a flag equal to 1 if the +enlarged order could be proven to be I<pr>-maximal and to 0 otherwise (it +may be maximal in the latter case if I<pr> is ramified in C<L>), the second +component is a pseudo-basis of the enlarged order and the third component is +the valuation at I<pr> of the order discriminant. + +X<rnfdedekind>The library syntax is B<rnfdedekind>C<(I<nf>,I<pol>,I<pr>)>. + +=head2 X<rnfdet>rnfdetC<(I<nf>,M)> + +given a pseudomatrix C<M> over the maximal +order of C<I<nf>>, computes its pseudodeterminant. + +X<rnfdet>The library syntax is B<rnfdet>C<(I<nf>,M)>. + +=head2 X<rnfdisc>rnfdiscC<(I<nf>,I<pol>)> + +given a number field C<I<nf>> as +output by C<nfinit> and a polynomial I<pol> with coefficients in +C<I<nf>> defining a relative extension C<L> of C<I<nf>>, computes +the relative +discriminant of C<L>. This is a two-element row vector C<[D,d]>, where C<D> is +the relative ideal discriminant and C<d> is the relative discriminant +considered as an element of C<I<nf>^*/{I<nf>^*}^2>. The main variable of +C<I<nf>> I<must> be of lower priority than that of I<pol>. + +Note: As usual, C<I<nf>> can be a C<I<bnf>> as output by C<nfinit>. + +X<rnfdiscf>The library syntax is B<rnfdiscf>C<(I<bnf>,I<pol>)>. + +=head2 X<rnfeltabstorel>rnfeltabstorelC<(I<rnf>,x)> + +C<I<rnf>> being a relative +number field +extension C<L/K> as output by C<rnfinit> and C<x> being an element of C<L> +expressed as a polynomial modulo the absolute equation C<I<rnf>[11][1]>, +computes C<x> as an element of the relative extension C<L/K> as a polmod with +polmod coefficients. + +X<rnfelementabstorel>The library syntax is B<rnfelementabstorel>C<(I<rnf>,x)>. + +=head2 X<rnfeltdown>rnfeltdownC<(I<rnf>,x)> + +C<I<rnf>> being a relative number +field extension C<L/K> as output by C<rnfinit> and C<x> being an element of +C<L> expressed as a polynomial or polmod with polmod coefficients, computes +C<x> as an element of C<K> as a polmod, assuming C<x> is in C<K> (otherwise an +error will occur). If C<x> is given on the relative integral basis, apply +C<rnfbasistoalg> first, otherwise PARI will believe you are dealing with a +vector. + +X<rnfelementdown>The library syntax is B<rnfelementdown>C<(I<rnf>,x)>. + +=head2 X<rnfeltreltoabs>rnfeltreltoabsC<(I<rnf>,x)> + +C<I<rnf>> being a relative +number field extension C<L/K> as output by C<rnfinit> and C<x> being an +element of C<L> expressed as a polynomial or polmod with polmod +coefficients, computes C<x> as an element of the absolute extension C<L/B<I<Q>>> as +a polynomial modulo the absolute equation C<I<rnf>[11][1]>. If C<x> is +given on the relative integral basis, apply C<rnfbasistoalg> first, +otherwise PARI will believe you are dealing with a vector. + +X<rnfelementreltoabs>The library syntax is B<rnfelementreltoabs>C<(I<rnf>,x)>. + +=head2 X<rnfeltup>rnfeltupC<(I<rnf>,x)> + +C<I<rnf>> being a relative number +field extension C<L/K> as output by C<rnfinit> and C<x> being an element of +C<K> expressed as a polynomial or polmod, computes C<x> as an element of the +absolute extension C<L/B<I<Q>>> as a polynomial modulo the absolute equation +C<I<rnf>[11][1]>. Note that it is unnecessary to compute C<x> as an +element of the relative extension C<L/K> (its expression would be identical to +itself). If C<x> is given on the integral basis of C<K>, apply +C<nfbasistoalg> first, otherwise PARI will believe you are dealing with a +vector. + +X<rnfelementup>The library syntax is B<rnfelementup>C<(I<rnf>,x)>. + +=head2 X<rnfequation>rnfequationC<(I<nf>,I<pol>,{I<flag> = 0})> + +given a number field +C<I<nf>> as output by C<nfinit> (or simply a polynomial) and a +polynomial I<pol> with coefficients in C<I<nf>> defining a relative +extension C<L> of C<I<nf>>, computes the absolute equation of C<L> over +B<I<Q>>. + +If C<I<flag>> is non-zero, outputs a 3-component row vector C<[z,a,k]>, where +C<z> is the absolute equation of C<L> over B<I<Q>>, as in the default behaviour, +C<a> expresses as an element of C<L> a root C<F<alpha>> of the polynomial +defining the base field C<I<nf>>, and C<k> is a small integer such that +C<F<theta> = F<beta>+kF<alpha>> where C<F<theta>> is a root of C<z> and C<F<beta>> a root +of C<I<pol>>. + +The main variable of C<I<nf>> I<must> be of lower priority than that +of I<pol>. Note that for efficiency, this does not check whether the +relative equation is irreducible over C<I<nf>>, but only if it is +squarefree. If it is reducible but squarefree, the result will be the +absolute equation of the E<eacute>tale algebra defined by I<pol>. If I<pol> +is not squarefree, an error message will be issued. + +X<rnfequation0>The library syntax is B<rnfequation0>C<(I<nf>,I<pol>,I<flag>)>. + +=head2 X<rnfhnfbasis>rnfhnfbasisC<(I<bnf>,x)> + +given a big number field C<I<bnf>> +as output by C<bnfinit>, and either a polynomial C<x> with coefficients in +C<I<bnf>> defining a relative extension C<L> of C<I<bnf>>, or a +pseudo-basis C<x> of such an extension, gives either a true C<I<bnf>>-basis +of C<L> in upper triangular Hermite normal form, if it exists, +zero otherwise. + +X<rnfhermitebasis>The library syntax is B<rnfhermitebasis>C<(I<nf>,x)>. + +=head2 X<rnfidealabstorel>rnfidealabstorelC<(I<rnf>,x)> + +C<I<rnf>> being a relative +number field extension C<L/K> as output by C<rnfinit> and C<x> being an +ideal of the absolute extension C<L/B<I<Q>>> given in HNFX<Hermite normal form> +(if it is not, apply C<idealhnf> first), computes the relative pseudomatrix +in HNF giving the ideal C<x> considered as an ideal of the relative extension +C<L/K>. + +X<rnfidealabstorel>The library syntax is B<rnfidealabstorel>C<(I<rnf>,x)>. + +=head2 X<rnfidealdown>rnfidealdownC<(I<rnf>,x)> + +C<I<rnf>> being a relative number +field extension C<L/K> as output by C<rnfinit> and C<x> being an ideal of +the absolute extension C<L/B<I<Q>>> given in HNF (if it is not, apply +C<idealhnf> first), gives the ideal of C<K> below C<x>, i.e.S< >the +intersection of C<x> with C<K>. Note that, if C<x> is given as a relative ideal +(i.e.S< >a pseudomatrix in HNF), then it is not necessary to use this function +since the result is simply the first ideal of the ideal list of the +pseudomatrix. + +X<rnfidealdown>The library syntax is B<rnfidealdown>C<(I<rnf>,x)>. + +=head2 X<rnfidealhnf>rnfidealhnfC<(I<rnf>,x)> + +C<I<rnf>> being a relative number +field extension C<L/K> as output by C<rnfinit> and C<x> being a relative +ideal (which can be, as in the absolute case, of many different types, +including of course elements), computes as a 2-component row vector the +relative Hermite normal form of C<x>, the first component being the HNF matrix +(with entries on the integral basis), and the second component the ideals. + +X<rnfidealhermite>The library syntax is B<rnfidealhermite>C<(I<rnf>,x)>. + +=head2 X<rnfidealmul>rnfidealmulC<(I<rnf>,x,y)> + +C<I<rnf>> being a relative number +field extension C<L/K> as output by C<rnfinit> and C<x> and C<y> being ideals +of the relative extension C<L/K> given by pseudo-matrices, outputs the ideal +product, again as a relative ideal. + +X<rnfidealmul>The library syntax is B<rnfidealmul>C<(I<rnf>,x,y)>. + +=head2 X<rnfidealnormabs>rnfidealnormabsC<(I<rnf>,x)> + +C<I<rnf>> being a relative +number field extension C<L/K> as output by C<rnfinit> and C<x> being a +relative ideal (which can be, as in the absolute case, of many different +types, including of course elements), computes the norm of the ideal C<x> +considered as an ideal of the absolute extension C<L/B<I<Q>>>. This is identical to +C<idealnorm(rnfidealnormrel(I<rnf>,x))>, only faster. + +X<rnfidealnormabs>The library syntax is B<rnfidealnormabs>C<(I<rnf>,x)>. + +=head2 X<rnfidealnormrel>rnfidealnormrelC<(I<rnf>,x)> + +C<I<rnf>> being a relative +number field +extension C<L/K> as output by C<rnfinit> and C<x> being a relative ideal +(which can be, as in the absolute case, of many different types, including +of course elements), computes the relative norm of C<x> as a ideal of C<K> +in HNF. + +X<rnfidealnormrel>The library syntax is B<rnfidealnormrel>C<(I<rnf>,x)>. + +=head2 X<rnfidealreltoabs>rnfidealreltoabsC<(I<rnf>,x)> + +C<I<rnf>> being a relative +number field +extension C<L/K> as output by C<rnfinit> and C<x> being a relative ideal +(which can be, as in the absolute case, of many different types, including +of course elements), computes the HNF matrix of the ideal C<x> considered +as an ideal of the absolute extension C<L/B<I<Q>>>. + +X<rnfidealreltoabs>The library syntax is B<rnfidealreltoabs>C<(I<rnf>,x)>. + +=head2 X<rnfidealtwoelt>rnfidealtwoeltC<(I<rnf>,x)> + +C<I<rnf>> being a relative +number field +extension C<L/K> as output by C<rnfinit> and C<x> being an ideal of the +relative extension C<L/K> given by a pseudo-matrix, gives a vector of +two generators of C<x> over C<B<I<Z>>_L> expressed as polmods with polmod +coefficients. + +X<rnfidealtwoelement>The library syntax is B<rnfidealtwoelement>C<(I<rnf>,x)>. + +=head2 X<rnfidealup>rnfidealupC<(I<rnf>,x)> + +C<I<rnf>> being a relative number +field +extension C<L/K> as output by C<rnfinit> and C<x> being an ideal of +C<K>, gives the ideal C<xB<I<Z>>_L> as an absolute ideal of C<L/B<I<Q>>> (the relative +ideal representation is trivial: the matrix is the identity matrix, and +the ideal list starts with C<x>, all the other ideals being C<B<I<Z>>_K>). + +X<rnfidealup>The library syntax is B<rnfidealup>C<(I<rnf>,x)>. + +=head2 X<rnfinit>rnfinitC<(I<nf>,I<pol>)> + +C<I<nf>> being a number field in +C<nfinit> +format considered as base field, and I<pol> a polynomial defining a relative +extension over C<I<nf>>, this computes all the necessary data to work in the +relative extension. The main variable of I<pol> must be of higher priority +(i.e.S< >lower number) than that of C<I<nf>>, and the coefficients of I<pol> +must be in C<I<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 C<nfinit>. In +the following description, we let C<K> be the base field defined by +C<I<nf>>, C<m> the degree of the base field, C<n> the relative degree, C<L> +the large field (of relative degree C<n> or absolute degree C<nm>), C<r_1> and +C<r_2> the number of real and complex places of C<K>. + +C<I<rnf>[1]> contains the relative polynomial I<pol>. + +C<I<rnf>[2]> is a row vector with C<r_1+r_2> entries, entry C<j> being +a 2-component row vector C<[r_{j,1},r_{j,2}]> where C<r_{j,1}> and C<r_{j,2}> +are the number of real and complex places of C<L> above the C<j>-th place of +C<K> so that C<r_{j,1} = 0> and C<r_{j,2} = n> if C<j> is a complex place, while if +C<j> is a real place we have C<r_{j,1}+2r_{j,2} = n>. + +C<I<rnf>[3]> is a two-component row vector C<[B<I<d>>(L/K),s]> where C<B<I<d>>(L/K)> +is the relative ideal discriminant of C<L/K> and C<s> is the discriminant of +C<L/K> viewed as an element of C<K^*/(K^*)^2>, in other words it is the output +of C<rnfdisc>. + +C<I<rnf>[4]> is the ideal index C<B<I<f>>>, i.e.S< >such that +C<d(pol)B<I<Z>>_K = B<I<f>>^2B<I<d>>(L/K)>. + +C<I<rnf>[5]> is a vector I<vm> with 7 entries useful for certain +computations in the relative extension C<L/K>. C<I<vm>[1]> is a vector of +C<r_1+r_2> matrices, the C<j>-th matrix being an C<(r_{1,j}+r_{2,j}) x n> +matrix C<M_j> representing the numerical values of the conjugates of the +C<j>-th embedding of the elements of the integral basis, where C<r_{i,j}> is as +in C<I<rnf>[2]>. C<I<vm>[2]> is a vector of C<r_1+r_2> matrices, the +C<j>-th matrix C<MC_j> being essentially the conjugate of the matrix C<M_j> +except that the last C<r_{2,j}> columns are also multiplied by 2. +C<I<vm>[3]> is a vector of C<r_1+r_2> matrices C<T2_j>, where C<T2_j> is +an C<n x n> matrix equal to the real part of the product C<MC_j.M_j> +(which is a real positive definite matrix). C<I<vm>[4]> is the C<n x n> +matrix C<T> whose entries are the relative traces of C<F<omega>_iF<omega>_j> +expressed as polmods in C<I<nf>>, where the C<F<omega>_i> are the elements +of the relative integral basis. Note that the C<j>-th embedding of C<T> is +equal to C<\overline{MC_j}.M_j>, and in particular will be equal to +C<T2_j> if C<r_{2,j} = 0>. Note also that the relative ideal discriminant of +C<L/K> is equal to C< F<det> (T)> times the square of the product of the ideals +in the relative pseudo-basis (in C<I<rnf>[7][2]>). The last 3 entries +C<I<vm>[5]>, C<I<vm>[6]> and C<I<vm>[7]> are linked to the different +as in C<nfinit>, but have not yet been implemented. + +C<I<rnf>[6]> is a row vector with C<r_1+r_2> entries, the C<j>-th entry +being the +row vector with C<r_{1,j}+r_{2,j}> entries of the roots of the C<j>-th embedding +of the relative polynomial I<pol>. + +C<I<rnf>[7]> is a two-component row vector, where the first component is +the relative integral pseudo basis expressed as polynomials (in the variable of +C<pol>) with polmod coefficients in C<I<nf>>, and the second component is the +ideal list of the pseudobasis in HNF. + +C<I<rnf>[8]> is the inverse matrix of the integral basis matrix, with +coefficients polmods in C<I<nf>>. + +C<I<rnf>[9]> may be the multiplication table of the integral basis, but +is not implemented at present. + +C<I<rnf>[10]> is C<I<nf>>. + +C<I<rnf>[11]> is a vector I<vabs> with 5 entries describing the +I<absolute> extension C<L/B<I<Q>>>. C<I<vabs>[1]> is an absolute equation. +C<I<vabs>[2]> expresses the generator C<F<alpha>> of the number field +C<I<nf>> as a polynomial modulo the absolute equation C<I<vabs>[1]>. +C<I<vabs>[3]> is a small integer C<k> such that, if C<F<beta>> is an abstract +root of I<pol> and C<F<alpha>> the generator of C<I<nf>>, the generator +whose root is I<vabs> will be C<F<beta> + k F<alpha>>. Note that one must +be very careful if C<k ! = 0> when dealing simultaneously with absolute and +relative quantities since the generator chosen for the absolute extension +is not the same as for the relative one. If this happens, one can of course +go on working, but we strongly advise to change the relative polynomial so +that its root will be C<F<beta> + k F<alpha>>. Typically, the GP instruction would +be + +C<pol = subst(pol, x, x - k*Mod(y,I<nf>.pol))> + +Finally, C<I<vabs>[4]> is the absolute integral basis of C<L> expressed in HNF +(hence as would be output by C<nfinit(vabs[1])>), and C<I<vabs>[5]> the +inverse matrix of the integral basis, allowing to go from polmod to integral +basis representation. + +X<rnfinitalg>The library syntax is B<rnfinitalg>C<(I<nf>,I<pol>,I<prec>)>. + +=head2 X<rnfisfree>rnfisfreeC<(I<bnf>,x)> + +given a big number field C<I<bnf>> as +output by C<bnfinit>, and either a polynomial C<x> with coefficients in +C<I<bnf>> defining a relative extension C<L> of C<I<bnf>>, or a +pseudo-basis C<x> of such an extension, returns true (1) if C<L/I<bnf>> is +free, false (0) if not. + +X<rnfisfree>The library syntax is B<rnfisfree>C<(I<bnf>,x)>, and the result is a C<long>. + +=head2 X<rnfisnorm>rnfisnormC<(I<bnf>,I<ext>,I<el>,{I<flag> = 1})> + +similar to +C<bnfisnorm> but in the relative case. This tries to decide whether the +element I<el> in I<bnf> is the norm of some C<y> in I<ext>. +C<I<bnf>> is as output by C<bnfinit>. + +C<I<ext>> is a relative extension which has to be a row vector whose +components are: + +C<I<ext>[1]>: a relative equation of the number field I<ext> over +I<bnf>. As usual, the priority of the variable of the polynomial +defining the ground field I<bnf> (say C<y>) must be lower than the +main variable of C<I<ext>[1]>, say C<x>. + +C<I<ext>[2]>: the generator C<y> of the base field as a polynomial in C<x> (as +given by C<rnfequation> with C<I<flag> = 1>). + +C<I<ext>[3]>: is the C<bnfinit> of the absolute extension C<I<ext>/B<I<Q>>>. + +This returns a vector C<[a,b]>, where C<I<el> = I<Norm>(a)*b>. It looks for a +solution which is an C<S>-integer, with C<S> a list of places (of I<bnf>) +containing the ramified primes, the generators of the class group of +I<ext>, as well as those primes dividing I<el>. If C<I<ext>/I<bnf>> +is known to be X<Galois>Galois, set C<I<flag> = 0> (here I<el> is a norm iff C<b = 1>). +If C<I<flag>> is non zero add to C<S> all the places above the primes which: divide +C<I<flag>> if C<I<flag> E<lt> 0>, or are less than C<I<flag>> if C<I<flag> E<gt> 0>. The answer is guaranteed +(i.e.S< >I<el> is a norm iff C<b = 1>) under X<GRH>GRH, if C<S> contains all +primes less than C<12 F<log> ^2|disc(I<Ext>)|>, where +I<Ext> is the normal closure of C<I<ext> / I<bnf>>. Example: + + 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) + +checks whether C<17> is a norm in the Galois extension C<B<I<Q>>(F<beta>) / +B<I<Q>>(F<alpha>)>, where C<F<alpha>^3 + F<alpha>^2 - 2F<alpha> - 1 = 0> and C<F<beta>^2 + +F<alpha>^2 + 2*F<alpha> + 1 = 0> (it is). + +X<rnfisnorm>The library syntax is B<rnfisnorm>C<(I<bnf>,ext,x,I<flag>,I<prec>)>. + +=head2 X<rnfkummer>rnfkummerC<(I<bnr>,I<subgroup>,{deg = 0})> + +I<bnr> +being as output by C<bnrinit>, finds a relative equation for the +class field corresponding to the module in I<bnr> and the given +congruence subgroup. If I<deg> is positive, outputs the list of all +relative equations of degree I<deg> contained in the ray class field +defined by I<bnr>. + +(THIS PROGRAM IS STILL IN DEVELOPMENT STAGE) + +X<rnfkummer>The library syntax is B<rnfkummer>C<(I<bnr>,I<subgroup>,I<deg>,I<prec>)>, +where I<deg> is a C<long>. + +=head2 X<rnflllgram>rnflllgramC<(I<nf>,I<pol>,I<order>)> + +given a polynomial +I<pol> with coefficients in I<nf> and an order I<order> as output +by C<rnfpseudobasis> or similar, gives C<[[I<neworder>],U]>, where +I<neworder> is a reduced order and C<U> is the unimodular transformation +matrix. + +X<rnflllgram>The library syntax is B<rnflllgram>C<(I<nf>,I<pol>,I<order>,I<prec>)>. + +=head2 X<rnfnormgroup>rnfnormgroupC<(I<bnr>,I<pol>)> + +I<bnr> being a big ray +class field as output by C<bnrinit> and I<pol> a relative polynomial +defining an X<Abelian extension>Abelian extension, computes the norm group (alias Artin +or Takagi group) corresponding to the Abelian extension of C<I<bnf> = bnr[1]> +defined by I<pol>, where the module corresponding to I<bnr> is assumed +to be a multiple of the conductor (i.e.S< >polrel defines a subextension of +bnr). The result is the HNF defining the norm group on the given generators +of C<I<bnr>[5][3]>. Note that neither the fact that I<pol> defines an +Abelian extension nor the fact that the module is a multiple of the conductor +is checked. The result is undefined if the assumption is not correct. + +X<rnfnormgroup>The library syntax is B<rnfnormgroup>C<(I<bnr>,I<pol>)>. + +=head2 X<rnfpolred>rnfpolredC<(I<nf>,I<pol>)> + +relative version of C<polred>. +Given a monic polynomial I<pol> with coefficients in C<I<nf>>, finds a +list of relative polynomials defining some subfields, hopefully simpler and +containing the original field. In the present version B<2.2.0>, this is slower +than C<rnfpolredabs>. + +X<rnfpolred>The library syntax is B<rnfpolred>C<(I<nf>,I<pol>,I<prec>)>. + +=head2 X<rnfpolredabs>rnfpolredabsC<(I<nf>,I<pol>,{I<flag> = 0})> + +relative version of +C<polredabs>. Given a monic polynomial I<pol> with coefficients in +C<I<nf>>, finds a simpler relative polynomial defining the same field. If +C<I<flag> = 1>, returns C<[P,a]> where C<P> is the default output and C<a> is an +element expressed on a root of C<P> whose characteristic polynomial is +I<pol>, if C<I<flag> = 2>, returns an absolute polynomial (same as + +C<rnfequation(I<nf>,rnfpolredabs(I<nf>,I<pol>))> + +but faster). + +B<Remark.> In the present implementation, this is both faster and +much more efficient than C<rnfpolred>, the difference being more +dramatic than in the absolute case. This is because the implementation of +C<rnfpolred> is based on (a partial implementation of) an incomplete +reduction theory of lattices over number fields (i.e.S< >the function +C<rnflllgram>) which deserves to be improved. + +X<rnfpolredabs>The library syntax is B<rnfpolredabs>C<(I<nf>,I<pol>,I<flag>,I<prec>)>. + +=head2 X<rnfpseudobasis>rnfpseudobasisC<(I<nf>,I<pol>)> + +given a number field +C<I<nf>> as output by C<nfinit> and a polynomial I<pol> with +coefficients in C<I<nf>> defining a relative extension C<L> of C<I<nf>>, +computes a pseudo-basis C<(A,I)> and the relative discriminant of C<L>. +This is output as +a four-element row vector C<[A,I,D,d]>, where C<D> is the relative ideal +discriminant and C<d> is the relative discriminant considered as an element of +C<I<nf>^*/{I<nf>^*}^2>. + +Note: As usual, C<I<nf>> can be a C<I<bnf>> as output by C<bnfinit>. + +X<rnfpseudobasis>The library syntax is B<rnfpseudobasis>C<(I<nf>,I<pol>)>. + +=head2 X<rnfsteinitz>rnfsteinitzC<(I<nf>,x)> + +given a number field C<I<nf>> as +output by C<nfinit> and either a polynomial C<x> with coefficients in +C<I<nf>> defining a relative extension C<L> of C<I<nf>>, or a pseudo-basis +C<x> of such an extension as output for example by C<rnfpseudobasis>, +computes another pseudo-basis C<(A,I)> (not in HNF in general) such that all +the ideals of C<I> except perhaps the last one are equal to the ring of +integers of C<I<nf>>, and outputs the four-component row vector C<[A,I,D,d]> +as in C<rnfpseudobasis>. The name of this function comes from the fact +that the ideal class of the last ideal of C<I> (which is well defined) is +called the X<Steinitz class>I<Steinitz class> of the module C<B<I<Z>>_L>. + +Note: C<I<nf>> can be a C<I<bnf>> as output by C<bnfinit>. + +X<rnfsteinitz>The library syntax is B<rnfsteinitz>C<(I<nf>,x)>. + +=head2 X<subgrouplist>subgrouplistC<(I<bnr>,{I<bound>},{I<flag> = 0})> + +I<bnr> being as output by C<bnrinit> or a list of cyclic components +of a finite Abelian group C<G>, outputs the list of subgroups of C<G> +(of index bounded by I<bound>, if not omitted). Subgroups are given +as HNFX<Hermite normal form> left divisors of the +SNFX<Smith normal form> matrix corresponding to C<G>. If C<I<flag> = 0> +(default) and I<bnr> is as output by +C<bnrinit>, gives only the subgroups whose modulus is the conductor. + +X<subgrouplist0>The library syntax is B<subgrouplist0>C<(I<bnr>,I<bound>,I<flag>,I<prec>)>, where +I<bound>, C<I<flag>> and C<I<prec>> are long integers. + +=head2 X<zetak>zetakC<(I<znf>,x,{I<flag> = 0})> + +I<znf> being a number +field initialized by C<zetakinit> (I<not> by C<nfinit>), +computes the value of the X<Dedekind>Dedekind zeta function of the number +field at the complex number C<x>. If C<I<flag> = 1> computes Dedekind C<F<Lambda>> +function instead (i.e.S< >the product of the +Dedekind zeta function by its gamma and exponential factors). + +The accuracy of the result depends in an essential way on the accuracy of +both the C<zetakinit> program and the current accuracy, but even so the +result may be off by up to 5 or 10 decimal digits. + +X<glambdak>The library syntax is B<glambdak>C<(I<znf>,x,I<prec>)> or +C<X<gzetak>B<gzetak>(I<znf>,x,I<prec>)>. + +=head2 X<zetakinit>zetakinitC<(x)> + +computes a number of initialization data +concerning the number field defined by the polynomial C<x> so as to be able +to compute the X<Dedekind>Dedekind zeta and lambda functions (respectively +C<zetak(x)> and C<zetak(x,1)>). This function calls in particular +the C<bnfinit> program. The result is a 9-component vector C<v> whose +components are very technical and cannot really be used by the user except +through the C<zetak> function. The only component which can be used if +it has not been computed already is C<v[1][4]> which is the result of the +C<bnfinit> call. + +This function is very inefficient and should be rewritten. It needs to +computes millions of coefficients of the corresponding Dirichlet series if +the precision is big. Unless the discriminant is small it will not be able +to handle more than 9 digits of relative precision +(e.gS< >C<zetakinit(x^8 - 2)> needs 440MB of memory at default +precision). + +X<initzeta>The library syntax is B<initzeta>C<(x)>. + +=head1 Polynomials and power series + +We group here all functions which are specific to polynomials or power +series. Many other functions which can be applied on these objects are +described in the other sections. Also, some of the functions described here +can be applied to other types. + +=head2 X<O>OC<(a>C<^>C<b)> + +C<p>-adic (if C<a> is an integer greater or +equal to 2) or power series zero (in all other cases), with precision given +by C<b>. + +X<ggrandocp>The library syntax is B<ggrandocp>C<(a,b)>, where C<b> is a C<long>. + +=head2 X<deriv>derivC<(x,{v})> + +derivative of C<x> with respect to the main +variable if C<v> is omitted, and with respect to C<v> otherwise. C<x> can be any +type except polmod. The derivative of a scalar type is zero, and the +derivative of a vector or matrix is done componentwise. One can use C<x'> as a +shortcut if the derivative is with respect to the main variable of C<x>. + +X<deriv>The library syntax is B<deriv>C<(x,v)>, where C<v> is a C<long>, and an omitted C<v> is coded as +C<-1>. + +=head2 X<eval>evalC<(x)> + +replaces in C<x> the formal variables by the values that +have been assigned to them after the creation of C<x>. This is mainly useful +in GP, and not in library mode. Do not confuse this with substitution (see +C<subst>). Applying this function to a character string yields the +output from the corresponding GP command, as if directly input from the +keyboard (see L<Label se:strings>).X<Label se:eval> + +X<geval>The library syntax is B<geval>C<(x)>. The more basic functions C<X<poleval>B<poleval>(q,x)>, +C<X<qfeval>B<qfeval>(q,x)>, and C<X<hqfeval>B<hqfeval>(q,x)> evaluate C<q> at C<x>, where C<q> +is respectively assumed to be a polynomial, a quadratic form (a symmetric +matrix), or an Hermitian form (an Hermitian complex matrix). + +=head2 X<factorpadic>factorpadicC<(I<pol>,p,r,{I<flag> = 0})> + +C<p>-adic factorization +of the polynomial I<pol> to precision C<r>, the result being a +two-column matrix as in C<factor>. The factors are normalized so that +their leading coefficient is a power of C<p>. C<r> must be strictly larger than +the C<p>-adic valuation of the discriminant of I<pol> for the result to +make any sense. The method used is a modified version of the X<round 4>round 4 +algorithm of X<Zassenhaus>Zassenhaus. + +If C<I<flag> = 1>, use an algorithm due to X<Buchmann>Buchmann and X<Lenstra>Lenstra, which is +usually less efficient. + +X<factorpadic4>The library syntax is B<factorpadic4>C<(I<pol>,p,r)>, where C<r> is a C<long> integer. + +=head2 X<intformal>intformalC<(x,{v})> + +X<formal integration>formal integration of C<x> with +respect to the main variable if C<v> is omitted, with respect to the variable +C<v> otherwise. Since PARI does not know about ``abstract'' logarithms (they +are immediately evaluated, if only to a power series), logarithmic terms in +the result will yield an error. C<x> can be of any type. When C<x> is a +rational function, it is assumed that the base ring is an integral domain of +characteristic zero. + +X<integ>The library syntax is B<integ>C<(x,v)>, where C<v> is a C<long> and an omitted C<v> is coded +as C<-1>. + +=head2 X<padicappr>padicapprC<(I<pol>,a)> + +vector of C<p>-adic roots of the +polynomial +C<pol> congruent to the C<p>-adic number C<a> modulo C<p> (or modulo 4 if C<p = 2>), +and with the same C<p>-adic precision as C<a>. The number C<a> can be an +ordinary C<p>-adic number (type C<t_PADIC>, i.e.S< >an element of C<B<I<Q>>_p>) or +can be an element of a finite extension of C<B<I<Q>>_p>, in which case it is of +type C<t_POLMOD>, where at least one of the coefficients of the polmod is a +C<p>-adic number. In this case, the result is the vector of roots belonging to +the same extension of C<B<I<Q>>_p> as C<a>. + +X<apprgen9>The library syntax is B<apprgen9>C<(I<pol>,a)>, but if C<a> is known to be simply a C<p>-adic number +(type C<t_PADIC>), the syntax C<X<apprgen>B<apprgen>(I<pol>,a)> can be used. + +=head2 X<polcoeff>polcoeffC<(x,s,{v})> + +coefficient of degree C<s> of the +polynomial C<x>, with respect to the main variable if C<v> is omitted, with +respect to C<v> otherwise. + +X<polcoeff0>The library syntax is B<polcoeff0>C<(x,s,v)>, where C<v> is a C<long> and an omitted C<v> is coded +as C<-1>. Also available is X<truecoeff>B<truecoeff>C<(x,v)>. + +=head2 X<poldegree>poldegreeC<(x,{v})> + +degree of the polynomial C<x> in the main +variable if C<v> is omitted, in the variable C<v> otherwise. This is to be +understood as follows. When C<x> is a polynomial or a rational function, it +gives the degree of C<x>, the degree of C<0> being C<-1> by convention. When C<x> +is a non-zero scalar, it gives 0, and when C<x> is a zero scalar, it gives +C<-1>. Return an error otherwise. + +X<poldegree>The library syntax is B<poldegree>C<(x,v)>, where C<v> and the result are C<long>s (and an +omitted C<v> is coded as C<-1>). Also available is X<degree>B<degree>C<(x)>, which is +equivalent to C<poldegree(x,-1)>. + +=head2 X<polcyclo>polcycloC<(n,{v = x})> + +C<n>-th cyclotomic polynomial, in variable +C<v> (C<x> by default). The integer C<n> must be positive. + +X<cyclo>The library syntax is B<cyclo>C<(n,v)>, where C<n> and C<v> are C<long> +integers (C<v> is a variable number, usually obtained through C<varn>). + +=head2 X<poldisc>poldiscC<(I<pol>,{v})> + +discriminant of the polynomial +I<pol> in the main variable is C<v> is omitted, in C<v> otherwise. The +algorithm used is the X<subresultant algorithm>subresultant algorithm. + +X<poldisc0>The library syntax is B<poldisc0>C<(x,v)>. Also available is X<discsr>B<discsr>C<(x)>, equivalent +to C<poldisc0(x,-1)>. + +=head2 X<poldiscreduced>poldiscreducedC<(f)> + +reduced discriminant vector of the +(integral, monic) polynomial C<f>. This is the vector of elementary divisors +of C<B<I<Z>>[F<alpha>]/f'(F<alpha>)B<I<Z>>[F<alpha>]>, where C<F<alpha>> is a root of the +polynomial C<f>. The components of the result are all positive, and their +product is equal to the absolute value of the discriminant ofS< >C<f>. + +X<reduceddiscsmith>The library syntax is B<reduceddiscsmith>C<(x)>. + +=head2 X<polhensellift>polhenselliftC<(x, y, p, e)> + +given a vector C<y> of +polynomials that are pairwise relatively prime modulo the prime C<p>, +and whose product is congruent to C<x> modulo C<p>, lift the elements of +C<y> to polynomials whose product is congruent to C<x> modulo C<p^e>. + +X<polhensellift>The library syntax is B<polhensellift>C<(x,y,p,e)> where C<e> must be a C<long>. + +=head2 X<polinterpolate>polinterpolateC<(xa,{ya},{v = x},{&e})> + +given the data vectors +C<xa> and C<ya> of the same length C<n> (C<xa> containing the C<x>-coordinates, +and C<ya> the corresponding C<y>-coordinates), this function finds the +X<interpolating polynomial>interpolating polynomial passing through these points and evaluates it +atS< >C<v>. If C<ya> is omitted, return the polynomial interpolating the +C<(i,xa[i])>. If present, C<e> will contain an error estimate on the returned +value. + +X<polint>The library syntax is B<polint>C<(xa,ya,v,&e)>, where C<e> will contain an error estimate on the +returned value. + +=head2 X<polisirreducible>polisirreducibleC<(I<pol>)> + +I<pol> being a polynomial +(univariate in the present version B<2.2.0>), returns 1 if I<pol> is +non-constant and irreducible, 0 otherwise. Irreducibility is checked over +the smallest base field over which I<pol> seems to be defined. + +X<gisirreducible>The library syntax is B<gisirreducible>C<(I<pol>)>. + +=head2 X<pollead>polleadC<(x,{v})> + +leading coefficient of the polynomial or +power series C<x>. This is computed with respect to the main variable of C<x> +if C<v> is omitted, with respect to the variable C<v> otherwise. + +X<pollead>The library syntax is B<pollead>C<(x,v)>, where C<v> is a C<long> and an omitted C<v> is coded as +C<-1>. Also available is X<leadingcoeff>B<leadingcoeff>C<(x)>. + +=head2 X<pollegendre>pollegendreC<(n,{v = x})> + +creates the C<n^{th}> +X<Legendre polynomial>Legendre polynomial, in variable C<v>. + +X<legendre>The library syntax is B<legendre>C<(n)>, where C<x> is a C<long>. + +=head2 X<polrecip>polrecipC<(I<pol>)> + +reciprocal polynomial of I<pol>, +i.e.S< >the coefficients are in reverse order. I<pol> must be a polynomial. + +X<polrecip>The library syntax is B<polrecip>C<(x)>. + +=head2 X<polresultant>polresultantC<(x,y,{v},{I<flag> = 0})> + +resultant of the two +polynomials C<x> and C<y> with exact entries, with respect to the main +variables of C<x> and C<y> if C<v> is omitted, with respect to the variable C<v> +otherwise. The algorithm used is the X<subresultant algorithm>subresultant algorithm by default. + +If C<I<flag> = 1>, uses the determinant of Sylvester's matrix instead (here C<x> and +C<y> may have non-exact coefficients). + +If C<I<flag> = 2>, uses Ducos's modified subresultant algorithm. It should be much +faster than the default if the coefficient ring is complicated (e.g +multivariate polynomials or huge coefficients), and slightly slower +otherwise. + +X<polresultant0>The library syntax is B<polresultant0>C<(x,y,v,I<flag>)>, where C<v> is a C<long> and an omitted C<v> +is coded as C<-1>. Also available are C<X<subres>B<subres>(x,y)> (C<I<flag> = 0>) and +C<X<resultant2>B<resultant2>(x,y)> (C<I<flag> = 1>). + +=head2 X<polroots>polrootsC<(I<pol>,{I<flag> = 0})> + +complex roots of the polynomial +I<pol>, given as a column vector where each root is repeated according to +its multiplicity. The precision is given as for transcendental functions: under +GP it is kept in the variable C<realprecision> and is transparent to the +user, but it must be explicitly given as a second argument in library mode. + +The algorithm used is a modification of A.S< >X<SchE<ouml>nhage>SchE<ouml>nhage's remarkable +root-finding algorithm, due to and implemented by X.S< >Gourdon. Barring bugs, +it is guaranteed to converge and to give the roots to the required accuracy. + +If C<I<flag> = 1>, use a variant of the Newton-Raphson method, which is I<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.S< >no flag or C<I<flag> = 0>). This used to be the +default root-finding function in PARI until version 1.39.06. + +X<roots>The library syntax is B<roots>C<(I<pol>,I<prec>)> or C<X<rootsold>B<rootsold>(I<pol>,I<prec>)>. + +=head2 X<polrootsmod>polrootsmodC<(I<pol>,p,{I<flag> = 0})> + +row vector of roots modulo +C<p> of the polynomial I<pol>. The particular non-prime value C<p = 4> is +accepted, mainly for C<2>-adic computations. Multiple roots are I<not> +repeated. + +If C<p E<lt> 100>, you may try setting C<I<flag> = 1>, which uses a naive search. In this +case, multiple roots I<are> repeated with their order of multiplicity. + +X<rootmod>The library syntax is B<rootmod>C<(I<pol>,p)> (C<I<flag> = 0>) or +C<X<rootmod2>B<rootmod2>(I<pol>,p)> (C<I<flag> = 1>). + +=head2 X<polrootspadic>polrootspadicC<(I<pol>,p,r)> + +row vector of C<p>-adic roots of the +polynomial I<pol> with C<p>-adic precision equal to C<r>. Multiple roots are +I<not> repeated. C<p> is assumed to be a prime. + +X<rootpadic>The library syntax is B<rootpadic>C<(I<pol>,p,r)>, where C<r> is a C<long>. + +=head2 X<polsturm>polsturmC<(I<pol>,{a},{b})> + +number of real roots of the real +polynomial I<pol> in the interval C<]a,b]>, using Sturm's algorithm. C<a> +(resp.S< >C<b>) is taken to be C<- oo > (resp.S< >C<+ oo >) if omitted. + +X<sturmpart>The library syntax is B<sturmpart>C<(I<pol>,a,b)>. Use C<NULL> to omit an argument. +X<sturm>B<sturm>C<(I<pol>)> is equivalent to +B<sturmpart>C<(I<pol>,NULL,NULL)>. The result is a C<long>. + +=head2 X<polsubcyclo>polsubcycloC<(n,d,{v = x})> + +gives a polynomial (in variable +C<v>) defining the sub-Abelian extension of degree C<d> of the cyclotomic +field C<B<I<Q>>(F<zeta>_n)>, where C<d | F<phi>(n)>. C<(B<I<Z>>/nB<I<Z>>)^*> has to be cyclic +(i.e.S< >C<n = 2>, C<4>, C<p^k> or C<2p^k> for an odd prime C<p>). The function +X<galoissubcyclo>C<galoissubcyclo> covers the general case. + +X<subcyclo>The library syntax is B<subcyclo>C<(n,d,v)>, where C<v> is a variable number. + +=head2 X<polsylvestermatrix>polsylvestermatrixC<(x,y)> + +forms the Sylvester matrix +corresponding to the two polynomials C<x> and C<y>, where the coefficients of +the polynomials are put in the columns of the matrix (which is the natural +direction for solving equations afterwards). The use of this matrix can be +essential when dealing with polynomials with inexact entries, since +polynomial Euclidean division doesn't make much sense in this case. + +X<sylvestermatrix>The library syntax is B<sylvestermatrix>C<(x,y)>. + +=head2 X<polsym>polsymC<(x,n)> + +creates the vector of the X<symmetric powers>symmetric powers +of the roots of the polynomial C<x> up to power C<n>, using Newton's +formula. + +X<polsym>The library syntax is B<polsym>C<(x)>. + +=head2 X<poltchebi>poltchebiC<(n,{v = x})> + +creates the C<n^{th}> +X<Chebyshev>Chebyshev polynomial, in variable C<v>. + +X<tchebi>The library syntax is B<tchebi>C<(n,v)>, where C<n> and C<v> are C<long> +integers (C<v> is a variable number). + +=head2 X<polzagier>polzagierC<(n,m)> + +creates Zagier's polynomial C<P_{n,m}> used in +the functions C<sumalt> and C<sumpos> (with C<I<flag> = 1>). The exact +definition can be found in a forthcoming paper. One must have C<m E<lt>= n>. + +X<polzagreel>The library syntax is B<polzagreel>C<(n,m,I<prec>)> if the result is only wanted as a polynomial +with real coefficients to the precision C<I<prec>>, or C<X<polzag>B<polzag>(n,m)> +if the result is wanted exactly, where C<n> and C<m> are C<long>s. + +=head2 X<serconvol>serconvolC<(x,y)> + +convolution (or X<Hadamard product>Hadamard product) of the +two power series C<x> and C<y>; in other words if C<x = F<sum> a_k*X^k> and C<y = F<sum> +b_k*X^k> then C<serconvol(x,y) = F<sum> a_k*b_k*X^k>. + +X<convol>The library syntax is B<convol>C<(x,y)>. + +=head2 X<serlaplace>serlaplaceC<(x)> + +C<x> must be a power series with only +non-negative exponents. If C<x = F<sum> (a_k/k!)*X^k> then the result is C<F<sum> +a_k*X^k>. + +X<laplace>The library syntax is B<laplace>C<(x)>. + +=head2 X<serreverse>serreverseC<(x)> + +reverse power series (i.e.S< >C<x^{-1}>, not C<1/x>) +of C<x>. C<x> must be a power series whose valuation is exactly equal to one. + +X<recip>The library syntax is B<recip>C<(x)>. + +=head2 X<subst>substC<(x,y,z)> + +replace the simple variable C<y> by the argument C<z> in the ``polynomial'' +expression C<x>. Every type is allowed for C<x>, but if it is not a genuine +polynomial (or power series, or rational function), the substitution will be +done as if the scalar components were polynomials of degree one. In +particular, beware that: + + ? subst(1, x, [1,2; 3,4]) + %1 = + [1 0] + + [0 1] + + ? subst(1, x, Mat([0,1])) + *** forbidden substitution by a non square matrix + +If C<x> is a power series, C<z> must be either a polynomial, a power series, or +a rational function. C<y> must be a simple variable name. + +X<gsubst>The library syntax is B<gsubst>C<(x,v,z)>, where C<v> is the number of +the variable C<y>. + +=head2 X<taylor>taylorC<(x,y)> + +Taylor expansion around C<0> of C<x> with respect +toX<Label se:taylor> +the simple variable C<y>. C<x> can be of any reasonable type, for example a +rational function. The number of terms of the expansion is transparent to the +user under GP, but must be given as a second argument in library mode. + +X<tayl>The library syntax is B<tayl>C<(x,y,n)>, where the C<long> integer C<n> is the desired number of +terms in the expansion. + +=head2 X<thue>thueC<(I<tnf>,a,{I<sol>})> + +solves the equation +C<P(x,y) = a> in integers C<x> and C<y>, where I<tnf> was created with +C<thueinit(P)>. I<sol>, if present, contains the solutions of +C<Norm(x) = a> modulo units of positive norm in the number field +defined by C<P> (as computed by C<bnfisintnorm>). If I<tnf> was +computed without assuming X<GRH>GRH (C<I<flag> = 1> in C<thueinit>), the +result is unconditional. For instance, here's how to solve the Thue +equation C<x^{13} - 5y^{13} = - 4>: + + ? tnf = thueinit(x^13 - 5); + ? thue(tnf, -4) + %1 = [[1, 1]] + +Hence, assuming GRH, the only solution is C<x = 1>, C<y = 1>. + +X<thue>The library syntax is B<thue>C<(I<tnf>,a,I<sol>)>, where an omitted I<sol> is coded +as C<NULL>. + +=head2 X<thueinit>thueinitC<(P,{I<flag> = 0})> + +initializes the I<tnf> +corresponding to C<P>. It is meant to be used in conjunction with X<thue>C<thue> +to solve Thue equations C<P(x,y) = a>, where C<a> is an integer. If C<I<flag>> is +non-zero, certify the result unconditionnaly, Otherwise, assume X<GRH>GRH, +this being much faster of course. + +X<thueinit>The library syntax is B<thueinit>C<(P,I<flag>,I<prec>)>. + +=head1 Vectors, matrices, linear algebra and sets + +X<Label se:linear_algebra> +Note that most linear algebra functions operating on subspaces defined by +generating sets (such as X<mathnf>C<mathnf>, X<qflll>C<qflll>, etc.) take matrices as +arguments. As usual, the generating vectors are taken to be the +I<columns> of the given matrix. + +=head2 X<algdep>algdepC<(x,k,{I<flag> = 0})> + +X<algebraic dependence>C<x> being +real, complex, or C<p>-adic, finds a polynomial of degree at most C<k> with +integer coefficients having C<x> as approximate root. Note that the polynomial +which is obtained is not necessarily the ``correct'' one (it's not even +guaranteed to be irreducible!). One can check the closeness either by a +polynomial evaluation or substitution, or by computing the roots of the +polynomial given by algdep. + +If C<x> is padic, C<I<flag>> is meaningless and the algorithm LLL-reduces the +``dual lattice'' corresponding to the powers of C<x>. + +Otherwise, if C<I<flag>> is zero, the algorithm used is a variant of the X<LLL>LLL +algorithm due to Hastad, Lagarias and Schnorr (STACS 1986). If the precision +is too low, the routine may enter an infinite loop. + +If C<I<flag>> is non-zero, use a standard LLL. C<I<flag>> then indicates a precision, +which should be between C<0.5> and C<1.0> times the number of decimal digits +to which C<x> was computed. + +X<algdep0>The library syntax is B<algdep0>C<(x,k,I<flag>,I<prec>)>, where C<k> and C<I<flag>> are C<long>s. +Also available is C<X<algdep>B<algdep>(x,k,I<prec>)> (C<I<flag> = 0>). + +=head2 X<charpoly>charpolyC<(A,{v = x},{I<flag> = 0})> + +X<characteristic polynomial>characteristic polynomial +of C<A> with respect to the variable C<v>, i.e.S< >determinant of C<v*I-A> if C<A> +is a square matrix, determinant of the map ``multiplication by C<A>'' if C<A> +is a scalar, in particular a polmod (e.g.S< >C<charpoly(I,x) = x^2+1>). +Note that in the latter case, the X<minimal polynomial>minimal polynomial can be obtained +as + + minpoly(A)= + { + local(y); + y = charpoly(A); + y / gcd(y,y') + } + +The value of C<I<flag>> is only significant for matrices. + +If C<I<flag> = 0>, the method used is essentially the same as for computing the +adjoint matrix, i.e.S< >computing the traces of the powers of C<A>. + +If C<I<flag> = 1>, uses Lagrange interpolation which is almost always slower. + +If C<I<flag> = 2>, uses the Hessenberg form. This is faster than the default when +the coefficients are integermod a prime or real numbers, but is usually +slower in other base rings. + +X<charpoly0>The library syntax is B<charpoly0>C<(A,v,I<flag>)>, where C<v> is the variable number. Also available +are the functions C<X<caract>B<caract>(A,v)> (C<I<flag> = 1>), C<X<carhess>B<carhess>(A,v)> +(C<I<flag> = 2>), and C<X<caradj>B<caradj>(A,v,I<pt>)> where, in this last case, +I<pt> is a C<GEN*> which, if not equal to C<NULL>, will receive +the address of the adjoint matrix of C<A> (see C<matadjoint>), so both +can be obtained at once. + +=head2 X<concat>concatC<(x,{y})> + +concatenation of C<x> and C<y>. If C<x> or C<y> is +not a vector or matrix, it is considered as a one-dimensional vector. All +types are allowed for C<x> and C<y>, but the sizes must be compatible. Note +that matrices are concatenated horizontally, i.e.S< >the number of rows stays +the same. Using transpositions, it is easy to concatenate them vertically. + +To concatenate vectors sideways (i.e.S< >to obtain a two-row or two-column +matrix), first transform the vector into a one-row or one-column matrix using +the function X<Mat>C<Mat>. Concatenating a row vector to a matrix having the +same number of columns will add the row to the matrix (top row if the vector +is C<x>, i.e.S< >comes first, and bottom row otherwise). + +The empty matrix C<[;]> is considered to have a number of rows compatible +with any operation, in particular concatenation. (Note that this is +definitely I<not> the case for empty vectors C<[S< >]> or C<[S< >]~>.) + +If C<y> is omitted, C<x> has to be a row vector or a list, in which case its +elements are concatenated, from left to right, using the above rules. + + ? concat([1,2], [3,4]) + %1 = [1, 2, 3, 4] + ? a = [[1,2]~, [3,4]~]; concat(a) + %2 = [1, 2, 3, 4]~ + ? a[1] = Mat(a[1]); concat(a) + %3 = + [1 3] + + [2 4] + + ? concat([1,2; 3,4], [5,6]~) + %4 = + [1 2 5] + + [3 4 6] + ? concat([%, [7,8]~, [1,2,3,4]]) + %5 = + [1 2 5 7] + + [3 4 6 8] + + [1 2 3 4] + +X<concat>The library syntax is B<concat>C<(x,y)>. + +=head2 X<lindep>lindepC<(x,{I<flag> = 0})> + +X<linear dependence>C<x> being a +vector with real or complex coefficients, finds a small integral linear +combination among these coefficients. + +If C<I<flag> = 0>, uses a variant of the X<LLL>LLL algorithm due to Hastad, Lagarias +and Schnorr (STACS 1986). + +If C<I<flag> E<gt> 0>, uses the LLL algorithm. C<I<flag>> is a parameter which should be +between one half the number of decimal digits of precision and that number +(see C<algdep>). + +If C<I<flag> E<lt> 0>, returns as soon as one relation has been found. + +X<lindep0>The library syntax is B<lindep0>C<(x,I<flag>,I<prec>)>. Also available is +C<X<lindep>B<lindep>(x,I<prec>)> (C<I<flag> = 0>). + +=head2 X<listcreate>listcreateC<(n)> + +creates an empty list of maximal length C<n>. + +This function is useless in library mode. + +=head2 X<listinsert>listinsertC<(I<list>,x,n)> + +inserts the object C<x> at +position C<n> in I<list> (which must be of type C<t_LIST>). All the +remaining elements of I<list> (from position C<n+1> onwards) are shifted +to the right. This and C<listput> are the only commands which enable +you to increase a list's effective length (as long as it remains under +the maximal length specified at the time of the C<listcreate>). + +This function is useless in library mode. + +=head2 X<listkill>listkillC<(I<list>)> + +kill I<list>. This deletes all +elements from I<list> and sets its effective length to C<0>. The maximal +length is not affected. + +This function is useless in library mode. + +=head2 X<listput>listputC<(I<list>,x,{n})> + +sets the C<n>-th element of the list +I<list> (which must be of type C<t_LIST>) equal to C<x>. If C<n> is omitted, +or greater than the list current effective length, just appends C<x>. This and +C<listinsert> are the only commands which enable you to increase a list's +effective length (as long as it remains under the maximal length specified at +the time of the C<listcreate>). + +If you want to put an element into an occupied cell, i.e.S< >if you don't want to +change the effective length, you can consider the list as a vector and use +the usual C<list[n] = x> construct. + +This function is useless in library mode. + +=head2 X<listsort>listsortC<(I<list>,{I<flag> = 0})> + +sorts I<list> (which must +be of type C<t_LIST>) in place. If C<I<flag>> is non-zero, suppresses all repeated +coefficients. This is much faster than the C<vecsort> command since no +copy has to be made. + +This function is useless in library mode. + +=head2 X<matadjoint>matadjointC<(x)> + +X<adjoint matrix>adjoint matrix of C<x>, i.e.S< >the matrix C<y> +of cofactors of C<x>, satisfying C<x*y = F<det> (x)*Id>. C<x> must be a +(non-necessarily invertible) square matrix. + +X<adj>The library syntax is B<adj>C<(x)>. + +=head2 X<matcompanion>matcompanionC<(x)> + +the left companion matrix to the polynomial C<x>. + +X<assmat>The library syntax is B<assmat>C<(x)>. + +=head2 X<matdet>matdetC<(x,{I<flag> = 0})> + +determinant of C<x>. C<x> must be a +square matrix. + +If C<I<flag> = 0>, uses Gauss-Bareiss. + +If C<I<flag> = 1>, uses classical Gaussian elimination, which is better when the +entries of the matrix are reals or integers for example, but usually much +worse for more complicated entries like multivariate polynomials. + +X<det>The library syntax is B<det>C<(x)> (C<I<flag> = 0>) and C<X<det2>B<det2>(x)> +(C<I<flag> = 1>). + +=head2 X<matdetint>matdetintC<(x)> + +C<x> being an C<m x n> matrix with integer +coefficients, this function computes a multiple of the determinant of the +lattice generated by the columns of C<x> if it is of rank C<m>, and returns +zero otherwise. This function can be useful in conjunction with the function +C<mathnfmod> which needs to know such a multiple. Other ways to obtain +this determinant (assuming the rank is maximal) is +C<matdet(qflll(x,4)[2]*x)> or more simply C<matdet(mathnf(x))>. +Experiment to see which is faster for your applications. + +X<detint>The library syntax is B<detint>C<(x)>. + +=head2 X<matdiagonal>matdiagonalC<(x)> + +C<x> being a vector, creates the diagonal matrix +whose diagonal entries are those of C<x>. + +X<diagonal>The library syntax is B<diagonal>C<(x)>. + +=head2 X<mateigen>mateigenC<(x)> + +gives the eigenvectors of C<x> as columns of a +matrix. + +X<eigen>The library syntax is B<eigen>C<(x)>. + +=head2 X<mathess>mathessC<(x)> + +Hessenberg form of the square matrix C<x>. + +X<hess>The library syntax is B<hess>C<(x)>. + +=head2 X<mathilbert>mathilbertC<(x)> + +C<x> being a C<long>, creates the X<Hilbert +matrix>Hilbert +matrix of order C<x>, i.e.S< >the matrix whose coefficient (C<i>,C<j>) is C<1/ +(i+j-1)>. + +X<mathilbert>The library syntax is B<mathilbert>C<(x)>. + +=head2 X<mathnf>mathnfC<(x,{I<flag> = 0})> + +if C<x> is a (not necessarily square) +matrix of maximal rank, finds the I<upper triangular> +X<Hermite normal form>Hermite normal form of C<x>. If the rank of C<x> is equal to its number +of rows, the result is a square matrix. In general, the columns of the +result form a basis of the lattice spanned by the columns of C<x>. + +If C<I<flag> = 0>, uses the naive algorithm. If the B<I<Z>>-module generated by the +columns is a lattice, it is recommanded to use +C<mathnfmod(x, matdetint(x))> instead (much faster). + +If C<I<flag> = 1>, uses Batut's algorithm. Outputs a two-component row vector +C<[H,U]>, where C<H> is the I<upper triangular> Hermite normal form +of C<x> (i.e.S< >the default result) and C<U> is the unimodular transformation +matrix such that C<xU = [0|H]>. If the rank of C<x> is equal to its number of +rows, C<H> is a square matrix. In general, the columns of C<H> form a basis +of the lattice spanned by the columns of C<x>. + +If C<I<flag> = 2>, uses Havas's algorithm. Outputs C<[H,U,P]>, such that +C<H> and C<U> are as before and C<P> is a permutation of the rows such that C<P> +applied to C<xU> gives C<H>. This does not work very well in present version +B<2.2.0>. + +If C<I<flag> = 3>, uses Batut's algorithm, and outputs C<[H,U,P]> as in the previous +case. + +If C<I<flag> = 4>, as in case 1 above, but uses X<LLL>LLL reduction along the way. + +X<mathnf0>The library syntax is B<mathnf0>C<(x,I<flag>)>. Also available are C<X<hnf>B<hnf>(x)> (C<I<flag> = 0>) and +C<X<hnfall>B<hnfall>(x)> (C<I<flag> = 1>). To reduce I<huge> (say C<400 x 400> and +more) relation matrices (sparse with small entries), you can use the pair +C<hnfspec> / C<hnfadd>. Since this is rather technical and the +calling interface may change, they are not documented yet. Look at the code +in C<basemath/alglin1.c>. + +=head2 X<mathnfmod>mathnfmodC<(x,d)> + +if C<x> is a (not necessarily square) matrix of +maximal rank with integer entries, and C<d> is a multiple of the (non-zero) +determinant of the lattice spanned by the columns of C<x>, finds the +I<upper triangular> X<Hermite normal form>Hermite normal form of C<x>. + +If the rank of C<x> is equal to its number of rows, the result is a square +matrix. In general, the columns of the result form a basis of the lattice +spanned by the columns of C<x>. This is much faster than C<mathnf> when C<d> +is known. + +X<hnfmod>The library syntax is B<hnfmod>C<(x,d)>. + +=head2 X<mathnfmodid>mathnfmodidC<(x,d)> + +outputs the (upper triangular) +X<Hermite normal form>Hermite normal form of C<x> concatenated with C<d> times +the identity matrix. + +X<hnfmodid>The library syntax is B<hnfmodid>C<(x,d)>. + +=head2 X<matid>matidC<(n)> + +creates the C<n x n> identity matrix. + +X<idmat>The library syntax is B<idmat>C<(n)> where C<n> is a C<long>. + +Related functions are C<X<gscalmat>B<gscalmat>(x,n)>, which creates C<x> times the +identity matrix (C<x> being a C<GEN> and C<n> a C<long>), and +C<X<gscalsmat>B<gscalsmat>(x,n)> which is the same when C<x> is a C<long>. + +=head2 X<matimage>matimageC<(x,{I<flag> = 0})> + +gives a basis for the image of the +matrix C<x> as columns of a matrix. A priori the matrix can have entries of +any type. If C<I<flag> = 0>, use standard Gauss pivot. If C<I<flag> = 1>, use +C<matsupplement>. + +X<matimage0>The library syntax is B<matimage0>C<(x,I<flag>)>. Also available is C<X<image>B<image>(x)> (C<I<flag> = 0>). + +=head2 X<matimagecompl>matimagecomplC<(x)> + +gives the vector of the column indices which +are not extracted by the function C<matimage>. Hence the number of +components of C<matimagecompl(x)> plus the number of columns of +C<matimage(x)> is equal to the number of columns of the matrix C<x>. + +X<imagecompl>The library syntax is B<imagecompl>C<(x)>. + +=head2 X<matindexrank>matindexrankC<(x)> + +C<x> being a matrix of rank C<r>, gives two +vectors C<y> and C<z> of length C<r> giving a list of rows and columns +respectively (starting from 1) such that the extracted matrix obtained from +these two vectors using C<X<vecextract>vecextract(x,y,z)> is invertible. + +X<indexrank>The library syntax is B<indexrank>C<(x)>. + +=head2 X<matintersect>matintersectC<(x,y)> + +C<x> and C<y> being two matrices with the same +number of rows each of whose columns are independent, finds a basis of the +B<I<Q>>-vector space equal to the intersection of the spaces spanned by the +columns of C<x> and C<y> respectively. See also the function +X<idealintersect>C<idealintersect>, which does the same for free B<I<Z>>-modules. + +X<intersect>The library syntax is B<intersect>C<(x,y)>. + +=head2 X<matinverseimage>matinverseimageC<(x,y)> + +gives a column vector belonging to the +inverse image of the column vector C<y> by the matrix C<x> if one exists, the +empty vector otherwise. To get the complete inverse image, it suffices to add +to the result any element of the kernel of C<x> obtained for example by +C<matker>. + +X<inverseimage>The library syntax is B<inverseimage>C<(x,y)>. + +=head2 X<matisdiagonal>matisdiagonalC<(x)> + +returns true (1) if C<x> is a diagonal matrix, +false (0) if not. + +X<isdiagonal>The library syntax is B<isdiagonal>C<(x)>, and this returns a C<long> +integer. + +=head2 X<matker>matkerC<(x,{I<flag> = 0})> + +gives a basis for the kernel of the +matrix C<x> as columns of a matrix. A priori the matrix can have entries of +any type. + +If C<x> is known to have integral entries, set C<I<flag> = 1>. + +Note: The library function C<X<ker_mod_p>ker_mod_p(x, p)>, where C<x> has +integer entries and C<p> is prime, which is equivalent to but many orders of +magnitude faster than C<matker(x*Mod(1,p))> and needs much less stack +space. To use it under GP, type C<install(ker_mod_p, GG)> first. + +X<matker0>The library syntax is B<matker0>C<(x,I<flag>)>. Also available are C<X<ker>B<ker>(x)> (C<I<flag> = 0>), +C<X<keri>B<keri>(x)> (C<I<flag> = 1>) and C<ker_mod_p(x,p)>. + +=head2 X<matkerint>matkerintC<(x,{I<flag> = 0})> + +gives an X<LLL>LLL-reduced B<I<Z>>-basis +for the lattice equal to the kernel of the matrix C<x> as columns of the +matrix C<x> with integer entries (rational entries are not permitted). + +If C<I<flag> = 0>, uses a modified integer LLL algorithm. + +If C<I<flag> = 1>, uses C<matrixqz(x,-2)>. If LLL reduction of the final result +is not desired, you can save time using C<matrixqz(matker(x),-2)> instead. + +If C<I<flag> = 2>, uses another modified LLL. In the present version B<2.2.0>, only +independent rows are allowed in this case. + +X<matkerint0>The library syntax is B<matkerint0>C<(x,I<flag>)>. Also available is +C<X<kerint>B<kerint>(x)> (C<I<flag> = 0>). + +=head2 X<matmuldiagonal>matmuldiagonalC<(x,d)> + +product of the matrix C<x> by the diagonal +matrix whose diagonal entries are those of the vector C<d>. Equivalent to, +but much faster than C<x*matdiagonal(d)>. + +X<matmuldiagonal>The library syntax is B<matmuldiagonal>C<(x,d)>. + +=head2 X<matmultodiagonal>matmultodiagonalC<(x,y)> + +product of the matrices C<x> and C<y> +knowing that the result is a diagonal matrix. Much faster than C<x*y> in +that case. + +X<matmultodiagonal>The library syntax is B<matmultodiagonal>C<(x,y)>. + +=head2 X<matpascal>matpascalC<(x,{q})> + +creates as a matrix the lower triangular +X<Pascal triangle>Pascal triangle of order C<x+1> (i.e.S< >with binomial coefficients +up to C<x>). If C<q> is given, compute the C<q>-Pascal triangle (i.e.S< >using +C<q>-binomial coefficients). + +X<matqpascal>The library syntax is B<matqpascal>C<(x,q)>, where C<x> is a C<long> and C<q = NULL> is used +to omit C<q>. Also available is X<matpascal>B<matpascal>{x}. + +=head2 X<matrank>matrankC<(x)> + +rank of the matrix C<x>. + +X<rank>The library syntax is B<rank>C<(x)>, and the result is a C<long>. + +=head2 X<matrix>matrixC<(m,n,{X},{Y},{I<expr> = 0})> + +creation of the +C<m x n> matrix whose coefficients are given by the expression +I<expr>. There are two formal parameters in I<expr>, the first one +(C<X>) corresponding to the rows, the second (C<Y>) to the columns, and C<X> +goes from 1 to C<m>, C<Y> goes from 1 to C<n>. If one of the last 3 parameters +is omitted, fill the matrix with zeroes. + +X<matrice>The library syntax is B<matrice>C<(GEN nlig,GEN ncol,entree *e1,entree *e2,char *expr)>. + +=head2 X<matrixqz>matrixqzC<(x,p)> + +C<x> being an C<m x n> matrix with C<m E<gt>= n> +with rational or integer entries, this function has varying behaviour +depending on the sign of C<p>: + +If C<p E<gt>= 0>, C<x> is assumed to be of maximal rank. This function returns a +matrix having only integral entries, having the same image as C<x>, such that +the GCD of all its C<n x n> subdeterminants is equal to 1 when C<p> is +equal to 0, or not divisible by C<p> otherwise. Here C<p> must be a prime +number (when it is non-zero). However, if the function is used when C<p> has +no small prime factors, it will either work or give the message ``impossible +inverse modulo'' and a non-trivial divisor of C<p>. + +If C<p = -1>, this function returns a matrix whose columns form a basis of the +lattice equal to C<B<I<Z>>^n> intersected with the lattice generated by the +columns of C<x>. + +If C<p = -2>, returns a matrix whose columns form a basis of the lattice equal +to C<B<I<Z>>^n> intersected with the B<I<Q>>-vector space generated by the +columns of C<x>. + +X<matrixqz0>The library syntax is B<matrixqz0>C<(x,p)>. + +=head2 X<matsize>matsizeC<(x)> + +C<x> being a vector or matrix, returns a row vector +with two components, the first being the number of rows (1 for a row vector), +the second the number of columns (1 for a column vector). + +X<matsize>The library syntax is B<matsize>C<(x)>. + +=head2 X<matsnf>matsnfC<(X,{I<flag> = 0})> + +if C<X> is a (singular or non-singular) +square matrix outputs the vector of elementary divisors of C<X> (i.e.S< >the +diagonal of the X<Smith normal form>Smith normal form of C<X>). + +The binary digits of I<flag> mean: + +1 (complete output): if set, outputs C<[U,V,D]>, where C<U> and C<V> are two +unimodular matrices such that C<UXV> is the diagonal matrix C<D>. Otherwise +output only the diagonal of C<D>. + +2 (generic input): if set, allows polynomial entries. Otherwise, assume +that C<X> has integer coefficients. + +4 (cleanup): if set, cleans up the output. This means that elementary +divisors equal to C<1> will be deleted, i.e.S< >outputs a shortened vector C<D'> +instead of C<D>. If complete output was required, returns C<[U',V',D']> so +that C<U'XV' = D'> holds. If this flag is set, C<X> is allowed to be of the +form C<D> or C<[U,V,D]> as would normally be output with the cleanup flag +unset. + +X<matsnf0>The library syntax is B<matsnf0>C<(X,I<flag>)>. Also available is C<X<smith>B<smith>(X)> (C<I<flag> = 0>). + +=head2 X<matsolve>matsolveC<(x,y)> + +C<x> being an invertible matrix and C<y> a column +vector, finds the solution C<u> of C<x*u = y>, using Gaussian elimination. This +has the same effect as, but is a bit faster, than C<x^{-1}*y>. + +X<gauss>The library syntax is B<gauss>C<(x,y)>. + +=head2 X<matsolvemod>matsolvemodC<(m,d,y,{I<flag> = 0})> + +C<m> being any integral matrix, +C<d> a vector of positive integer moduli, and C<y> an integral +column vector, gives a small integer solution to the system of congruences +C<F<sum>_i m_{i,j}x_j = y_i (mod d_i)> if one exists, otherwise returns +zero. Shorthand notation: C<y> (resp.S< >C<d>) can be given as a single integer, +in which case all the C<y_i> (resp.S< >C<d_i>) above are taken to be equal to C<y> +(resp.S< >C<d>). + +If C<I<flag> = 1>, all solutions are returned in the form of a two-component row +vector C<[x,u]>, where C<x> is a small integer solution to the system of +congruences and C<u> is a matrix whose columns give a basis of the homogeneous +system (so that all solutions can be obtained by adding C<x> to any linear +combination of columns of C<u>). If no solution exists, returns zero. + +X<matsolvemod0>The library syntax is B<matsolvemod0>C<(m,d,y,I<flag>)>. Also available +are C<X<gaussmodulo>B<gaussmodulo>(m,d,y)> (C<I<flag> = 0>) +and C<X<gaussmodulo2>B<gaussmodulo2>(m,d,y)> (C<I<flag> = 1>). + +=head2 X<matsupplement>matsupplementC<(x)> + +assuming that the columns of the matrix C<x> +are linearly independent (if they are not, an error message is issued), finds +a square invertible matrix whose first columns are the columns of C<x>, +i.e.S< >supplement the columns of C<x> to a basis of the whole space. + +X<suppl>The library syntax is B<suppl>C<(x)>. + +=head2 X<mattranspose>mattransposeC<(x)> or C<x~> + +transpose of C<x>. +This has an effect only on vectors and matrices. + +X<gtrans>The library syntax is B<gtrans>C<(x)>. + +=head2 X<qfgaussred>qfgaussredC<(q)> + +X<decomposition into squares>decomposition into squares of the +quadratic form represented by the symmetric matrix C<q>. The result is a +matrix whose diagonal entries are the coefficients of the squares, and the +non-diagonal entries represent the bilinear forms. More precisely, if +C<(a_{ij})> denotes the output, one has + +S< >C< q(x) = F<sum>_i a_{ii} (x_i + F<sum>_{j E<gt> i} a_{ij} x_j)^2 > + +X<sqred>The library syntax is B<sqred>C<(x)>. + +=head2 X<qfjacobi>qfjacobiC<(x)> + +C<x> being a real symmetric matrix, this gives a +vector having two components: the first one is the vector of eigenvalues of +C<x>, the second is the corresponding orthogonal matrix of eigenvectors of +C<x>. The method used is Jacobi's method for symmetric matrices. + +X<jacobi>The library syntax is B<jacobi>C<(x)>. + +=head2 X<qflll>qflllC<(x,{I<flag> = 0})> + +X<LLL>LLL algorithm applied to the +I<columns> of the (not necessarily square) matrix C<x>. The columns of C<x> +must however be linearly independent, unless specified otherwise below. The +result is a transformation matrix C<T> such that C<x.T> is an LLL-reduced +basis of the lattice generated by the column vectors of C<x>. + +If C<I<flag> = 0> (default), the computations are done with real numbers (i.e.S< >not +with rational numbers) hence are fast but as presently programmed (version +B<2.2.0>) are numerically unstable. + +If C<I<flag> = 1>, it is assumed that the corresponding Gram matrix is integral. +The computation is done entirely with integers and the algorithm is both +accurate and quite fast. In this case, C<x> needs not be of maximal rank, but +if it is not, C<T> will not be square. + +If C<I<flag> = 2>, similar to case 1, except C<x> should be an integer matrix whose +columns are linearly independent. The lattice generated by the columns of +C<x> is first partially reduced before applying the LLL algorithm. [A basis +is said to be I<partially reduced> if C<|v_i F<+-> v_j| E<gt>= |v_i|> for any +two distinct basis vectors C<v_i, v_j>.] + +This can be significantly faster than C<I<flag> = 1> when one row is huge compared +to the other rows. + +If C<I<flag> = 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 C<I<flag> = 4>, C<x> is assumed to have integral entries, but needs not be of +maximal rank. The result is a two-component vector of matricesS< >: the +columns of the first matrix represent a basis of the integer kernel of C<x> +(not necessarily LLL-reduced) and the second matrix is the transformation +matrix C<T> such that C<x.T> is an LLL-reduced B<I<Z>>-basis of the image +of the matrix C<x>. + +If C<I<flag> = 5>, case as case C<4>, but C<x> may have polynomial coefficients. + +If C<I<flag> = 7>, uses an older version of case C<0> above. + +If C<I<flag> = 8>, same as case C<0>, where C<x> may have polynomial coefficients. + +If C<I<flag> = 9>, variation on case C<1>, using content. + +X<qflll0>The library syntax is B<qflll0>C<(x,I<flag>,I<prec>)>. Also available are +C<X<lll>B<lll>(x,I<prec>)> (C<I<flag> = 0>), C<X<lllint>B<lllint>(x)> (C<I<flag> = 1>), and +C<X<lllkerim>B<lllkerim>(x)> (C<I<flag> = 4>). + +=head2 X<qflllgram>qflllgramC<(x,{I<flag> = 0})> + +same as C<qflll> except that the +matrix C<x> which must now be a square symmetric real matrix is the Gram +matrix of the lattice vectors, and not the coordinates of the vectors +themselves. The result is again the transformation matrix C<T> which gives (as +columns) the coefficients with respect to the initial basis vectors. The +flags have more or less the same meaning, but some are missing. In brief: + +C<I<flag> = 0>: numerically unstable in the present version B<2.2.0>. + +C<I<flag> = 1>: C<x> has integer entries, the computations are all done in integers. + +C<I<flag> = 4>: C<x> has integer entries, gives the kernel and reduced image. + +C<I<flag> = 5>: same as C<4> for generic C<x>. + +C<I<flag> = 7>: an older version of case C<0>. + +X<qflllgram0>The library syntax is B<qflllgram0>C<(x,I<flag>,I<prec>)>. Also available are +C<X<lllgram>B<lllgram>(x,I<prec>)> (C<I<flag> = 0>), C<X<lllgramint>B<lllgramint>(x)> (C<I<flag> = 1>), and +C<X<lllgramkerim>B<lllgramkerim>(x)> (C<I<flag> = 4>). + +=head2 X<qfminim>qfminimC<(x,b,m,{I<flag> = 0})> + +C<x> being a square and symmetric +matrix representing a positive definite quadratic form, this function +deals with the minimal vectors of C<x>, depending on C<I<flag>>. + +If C<I<flag> = 0> (default), seeks vectors of square norm less than or equal to C<b> +(for the norm defined by C<x>), and at most C<2m> of these vectors. The result +is a three-component vector, the first component being the number of vectors, +the second being the maximum norm found, and the last vector is a matrix +whose columns are the vectors found, only one being given for each +pair C<F<+-> v> (at most C<m> such pairs). + +If C<I<flag> = 1>, ignores C<m> and returns the first vector whose norm is less than +C<b>. + +In both these cases, C<x> I<is assumed to have integral entries>, and the +function searches for the minimal non-zero vectors whenever C<b = 0>. + +If C<I<flag> = 2>, C<x> can have non integral real entries, but C<b = 0> is now +meaningless (uses Fincke-Pohst algorithm). + +X<qfminim0>The library syntax is B<qfminim0>C<(x,b,m,I<flag>,I<prec>)>, also available are C< B<minim>(x,b,m)>X<minim> +(C<I<flag> = 0>), C< B<minim2>(x,b,m)>X<minim2> (C<I<flag> = 1>), and finally +C< B<fincke_pohst>(x,b,m,I<prec>)>X<fincke_pohst> (C<I<flag> = 2>). + +=head2 X<qfperfection>qfperfectionC<(x)> + +C<x> being a square and symmetric matrix with +integer entries representing a positive definite quadratic form, outputs the +perfection rank of the form. That is, gives the rank of the family of the C<s> +symmetric matrices C<v_iv_i^t>, where C<s> is half the number of minimal +vectors and the C<v_i> (C<1 E<lt>= i E<lt>= s>) are the minimal vectors. + +As a side note to old-timers, this used to fail bluntly when C<x> had more +than C<5000> minimal vectors. Beware that the computations can now be very +lengthy when C<x> has many minimal vectors. + +X<perf>The library syntax is B<perf>C<(x)>. + +=head2 X<qfsign>qfsignC<(x)> + +signature of the quadratic form represented by the +symmetric matrix C<x>. The result is a two-component vector. + +X<signat>The library syntax is B<signat>C<(x)>. + +=head2 X<setintersect>setintersectC<(x,y)> + +intersection of the two sets C<x> and C<y>. + +X<setintersect>The library syntax is B<setintersect>C<(x,y)>. + +=head2 X<setisset>setissetC<(x)> + +returns true (1) if C<x> is a set, false (0) if +not. In PARI, a set is simply a row vector whose entries are strictly +increasing. To convert any vector (and other objects) into a set, use the +function C<Set>. + +X<setisset>The library syntax is B<setisset>C<(x)>, and this returns a C<long>. + +=head2 X<setminus>setminusC<(x,y)> + +difference of the two sets C<x> and C<y>, +i.e.S< >set of elements of C<x> which do not belong to C<y>. + +X<setminus>The library syntax is B<setminus>C<(x,y)>. + +=head2 X<setsearch>setsearchC<(x,y,{I<flag> = 0})> + +searches if C<y> belongs to the set +C<x>. If it does and C<I<flag>> is zero or omitted, returns the index C<j> such that +C<x[j] = y>, otherwise returns 0. If C<I<flag>> is non-zero returns the index C<j> +where C<y> should be inserted, and C<0> if it already belongs to C<x> (this is +meant to be used in conjunction with C<listinsert>). + +This function works also if C<x> is a I<sorted> list (see C<listsort>). + +X<setsearch>The library syntax is B<setsearch>C<(x,y,I<flag>)> which returns a C<long> +integer. + +=head2 X<setunion>setunionC<(x,y)> + +union of the two sets C<x> and C<y>. + +X<setunion>The library syntax is B<setunion>C<(x,y)>. + +=head2 X<trace>traceC<(x)> + +this applies to quite general C<x>. If C<x> is not a +matrix, it is equal to the sum of C<x> and its conjugate, except for polmods +where it is the trace as an algebraic number. + +For C<x> a square matrix, it is the ordinary trace. If C<x> is a +non-square matrix (but not a vector), an error occurs. + +X<gtrace>The library syntax is B<gtrace>C<(x)>. + +=head2 X<vecextract>vecextractC<(x,y,{z})> + +extraction of components of the +vector or matrix C<x> according to C<y>. In case C<x> is a matrix, its +components are as usual the I<columns> of C<x>. The parameter C<y> is a +component specifier, which is either an integer, a string describing a +range, or a vector. + +If C<y> is an integer, it is considered as a mask: the binary bits of C<y> are +read from right to left, but correspond to taking the components from left to +right. For example, if C<y = 13 = (1101)_2> then the components 1,3 and 4 are +extracted. + +If C<y> is a vector, which must have integer entries, these entries correspond +to the component numbers to be extracted, in the order specified. + +If C<y> is a string, it can be + +C<B<*>> a single (non-zero) index giving a component number (a negative +index means we start counting from the end). + +C<B<*>> a range of the form C<"a..b">, where C<a> and C<b> are +indexes as above. Any of C<a> and C<b> can be omitted; in this case, we take +as default values C<a = 1> and C<b = -1>, i.e.S< >the first and last components +respectively. We then extract all components in the interval C<[a,b]>, in +reverse order if C<b E<lt> a>. + +In addition, if the first character in the string is C<^>, the +complement of the given set of indices is taken. + +If C<z> is not omitted, C<x> must be a matrix. C<y> is then the I<line> +specifier, and C<z> the I<column> specifier, where the component specifier +is as explained above. + + ? v = [a, b, c, d, e]; + ? vecextract(v, 5) \\ mask + %1 = [a, c] + ? vecextract(v, [4, 2, 1]) \\ component list + %2 = [d, b, a] + ? vecextract(v, "2..4") \\ interval + %3 = [b, c, d] + ? vecextract(v, "-1..-3") \\ interval + reverse order + %4 = [e, d, c] + ? vecextract([1,2,3], "^2") \\ complement + %5 = [1, 3] + ? vecextract(matid(3), "2..", "..") + %6 = + [0 1 0] + + [0 0 1] + +X<extract>The library syntax is B<extract>C<(x,y)> or C<X<matextract>B<matextract>(x,y,z)>. + +=head2 X<vecsort>vecsortC<(x,{k},{I<flag> = 0})> + +sorts the vector C<x> in ascending +order, using the heapsort method. C<x> must be a vector, and its components +integers, reals, or fractions. + +If C<k> is present and is an integer, sorts according to the value of the +C<k>-th subcomponents of the components ofS< >C<x>. C<k> can also be a vector, +in which case the +sorting is done lexicographically according to the components listed in the +vector C<k>. For example, if C<k = [2,1,3]>, sorting will be done with respect +to the second component, and when these are equal, with respect to the +first, and when these are equal, with respect to the third. + +The binary digits of I<flag> mean: + +C<B<*>> 1: indirect sorting of the vector C<x>, i.e.S< >if C<x> is an +C<n>-component vector, returns a permutation of C<[1,2,...,n]> which +applied to the components of C<x> sorts C<x> in increasing order. +For example, C<vecextract(x, vecsort(x,,1))> is equivalent to +C<vecsort(x)>. + +C<B<*>> 2: sorts C<x> by ascending lexicographic order (as per the +C<lex> comparison function). + +C<B<*>> 4: use decreasing instead of ascending order. + +X<vecsort0>The library syntax is B<vecsort0>C<(x,k,flag)>. To omit C<k>, use C<NULL> instead. You can also +use the simpler functions + +C<X<sort>B<sort>(x)> ( = C<vecsort0(x,NULL,0)>). + +C<X<indexsort>B<indexsort>(x)> ( = C<vecsort0(x,NULL,1)>). + +C<X<lexsort>B<lexsort>(x)> ( = C<vecsort0(x,NULL,2)>). + +Also available are X<sindexsort>B<sindexsort> and X<sindexlexsort>B<sindexlexsort> which return a +vector of C-long integers (private type C<t_VECSMALL>) C<v>, where +C<v[1]...v[n]> contain the indices. Note that the resulting C<v> is +I<not> a generic PARI object, but is in general easier to use in C +programs! + +=head2 X<vector>vectorC<(n,{X},{I<expr> = 0})> + +creates a row vector (type +C<t_VEC>) with C<n> components whose components are the expression +I<expr> evaluated at the integer points between 1 and C<n>. If one of the +last two arguments is omitted, fill the vector with zeroes. + +X<vecteur>The library syntax is B<vecteur>C<(GEN nmax, entree *ep, char *expr)>. + +=head2 X<vectorv>vectorvC<(n,X,I<expr>)> + +as X<vector>B<vector>, but returns a +column vector (type C<t_COL>). + +X<vvecteur>The library syntax is B<vvecteur>C<(GEN nmax, entree *ep, char *expr)>. + +=head1 Sums, products, integrals and similar functions + +X<Label se:sums> +Although the GP calculator is programmable, it is useful to have +preprogrammed a number of loops, including sums, products, and a certain +number of recursions. Also, a number of functions from numerical analysis +like numerical integration and summation of series will be described here. + +One of the parameters in these loops must be the control variable, hence a +simple variable name. The last parameter can be any legal PARI expression, +including of course expressions using loops. Since it is much easier to +program directly the loops in library mode, these functions are mainly +useful for GP programming. The use of these functions in library mode is a +little tricky and its explanation will be mostly omitted, although the +reader can try and figure it out by himself by checking the example given +for the X<sum>C<sum> function. In this section we only give the library +syntax, with no semantic explanation. + +The letter C<X> will always denote any simple variable name, and represents +the formal parameter used in the function. + +B<(numerical) integration>:X<numerical integration> A number +of Romberg-like integration methods are implemented (see C<intnum> as +opposed to C<intformal> which we already described). The user should not +require too much accuracy: 18 or 28 decimal digits is OK, but not much more. +In addition, analytical cleanup of the integral must have been done: there +must be no singularities in the interval or at the boundaries. In practice +this can be accomplished with a simple change of variable. Furthermore, for +improper integrals, where one or both of the limits of integration are plus +or minus infinity, the function must decrease sufficiently rapidly at +infinity. This can often be accomplished through integration by parts. +Finally, the function to be integrated should not be very small +(compared to the current precision) on the entire interval. This can +of course be accomplished by just multiplying by an appropriate +constant. + +Note that X<infinity>infinity can be represented with essentially no loss of +accuracy by 1e4000. However beware of real underflow when dealing with +rapidly decreasing functions. For example, if one wants to compute the +C<F<int>_0^ oo e^{-x^2}dx> to 28 decimal digits, then one should set +infinity equal to 10 for example, and certainly not to 1e4000. + +The integrand may have values belonging to a vector space over the real +numbers; in particular, it can be complex-valued or vector-valued. + +See also the discrete summation methods below (sharing the prefix C<sum>). + +=head2 X<intnum>intnumC<(X = a,b,I<expr>,{I<flag> = 0})> + +numerical integration of +I<expr> (smooth in C<]a,b[>), with respect to C<X>. + +Set C<I<flag> = 0> (or omit it altogether) when C<a> and C<b> are not too large, the +function is smooth, and can be evaluated exactly everywhere on the interval +C<[a,b]>. + +If C<I<flag> = 1>, uses a general driver routine for doing numerical integration, +making no particular assumption (slow). + +C<I<flag> = 2> is tailored for being used when C<a> or C<b> are infinite. One +I<must> have C<ab E<gt> 0>, and in fact if for example C<b = + oo >, then it is +preferable to have C<a> as large as possible, at least C<a E<gt>= 1>. + +If C<I<flag> = 3>, the function is allowed to be undefined (but continuous) at C<a> +or C<b>, for example the function C< F<sin> (x)/x> at C<x = 0>. + +X<intnum0>The library syntax is B<intnum0>C<(entree*e,GEN a,GEN b,char*expr,long I<flag>,long prec)>. + +=head2 X<prod>prodC<(X = a,b,I<expr>,{x = 1})> + +product of expression I<expr>, +initialized at C<x>, the formal parameter C<X> going from C<a> to C<b>. As for +C<sum>, the main purpose of the initialization parameter C<x> is to force +the type of the operations being performed. For example if it is set equal to +the integer 1, operations will start being done exactly. If it is set equal +to the real C<1.>, they will be done using real numbers having the default +precision. If it is set equal to the power series C<1+O(X^k)> for a certain +C<k>, they will be done using power series of precision at most C<k>. These +are the three most common initializations. + +As an extreme example, compare + + ? prod(i=1, 100, 1 - X^i); \\ this has degree 5050 !! + time = 3,335 ms. + ? prod(i=1, 100, 1 - X^i, 1 + O(X^101)) + time = 43 ms. + %2 = 1 - X - X^2 + X^5 + X^7 - X^12 - X^15 + X^22 + X^26 - X^35 - X^40 + \ + X^51 + X^57 - X^70 - X^77 + X^92 + X^100 + O(X^101) + +X<produit>The library syntax is B<produit>C<(entree *ep, GEN a, GEN b, char *expr, GEN x)>. + +=head2 X<prodeuler>prodeulerC<(X = a,b,I<expr>)> + +product of expression I<expr>, +initialized at 1. (i.e.S< >to a I<real> number equal to 1 to the current +C<realprecision>), the formal parameter C<X> ranging over the prime numbers +between C<a> and C<b>.X<Euler product> + +X<prodeuler>The library syntax is B<prodeuler>C<(entree *ep, GEN a, GEN b, char *expr, long prec)>. + +=head2 X<prodinf>prodinfC<(X = a,I<expr>,{I<flag> = 0})> + +X<infinite product>infinite product of +expression I<expr>, the formal parameter C<X> starting at C<a>. The evaluation +stops when the relative error of the expression minus 1 is less than the +default precision. The expressions must always evaluate to an element of +B<I<C>>. + +If C<I<flag> = 1>, do the product of the (C<1+I<expr>>) instead. + +X<prodinf>The library syntax is B<prodinf>C<(entree *ep, GEN a, char *expr, long prec)> (C<I<flag> = 0>), or +X<prodinf1>B<prodinf1> with the same arguments (C<I<flag> = 1>). + +=head2 X<solve>solveC<(X = a,b,I<expr>)> + +find a real root of expression +I<expr> between C<a> and C<b>, under the condition +C<I<expr>(X = a) * I<expr>(X = b) E<lt>= 0>. +This routine uses Brent's method and can fail miserably if I<expr> is +not defined in the whole of C<[a,b]> (try C<solve(x = 1, 2, tan(x)>). + +X<zbrent>The library syntax is B<zbrent>C<(entree *ep, GEN a, GEN b, char *expr, long prec)>. + +=head2 X<sum>sumC<(X = a,b,I<expr>,{x = 0})> + +sum of expression I<expr>, +initialized at C<x>, the formal parameter going from C<a> to C<b>. As for +C<prod>, the initialization parameter C<x> may be given to force the type +of the operations being performed. + +As an extreme example, compare + + ? sum(i=1, 5000, 1/i); \\ rational number: denominator has 2166 digits. + time = 1,241 ms. + ? sum(i=1, 5000, 1/i, 0.) + time = 158 ms. + %2 = 9.094508852984436967261245533 + +X<somme>The library syntax is B<somme>C<(entree *ep, GEN a, GEN b, char *expr, GEN x)>. This is to be +used as follows: C<ep> represents the dummy variable used in the +expression C<expr> + + /* compute a^2 + ... + b^2 */ + { + /* define the dummy variable "i" */ + entree *ep = is_entry("i"); + /* sum for a <= i <= b */ + return somme(ep, a, b, "i^2", gzero); + } + +=head2 X<sumalt>sumaltC<(X = a,I<expr>,{I<flag> = 0})> + +numerical summation of the +series I<expr>, which should be an X<alternating series>alternating series, the formal +variable C<X> starting at C<a>. + +If C<I<flag> = 0>, use an algorithm of F.S< >Villegas as modified by D.S< >Zagier. This +is much better than X<Euler>Euler-Van Wijngaarden's method which was used +formerly. +Beware that the stopping criterion is that the term gets small enough, hence +terms which are equal to 0 will create problems and should be removed. + +If C<I<flag> = 1>, use a variant with slightly different polynomials. Sometimes +faster. + +Divergent alternating series can sometimes be summed by this method, as well +as series which are not exactly alternating (see for example +L<Label se:user_defined>). + +B<Important hint:> a significant speed gain can be obtained by +writing the C<(-1)^X> which may occur in the expression as +C<(1.S< >- X%2*2)>. + +X<sumalt>The library syntax is B<sumalt>C<(entree *ep, GEN a, char *expr, long I<flag>, long prec)>. + +=head2 X<sumdiv>sumdivC<(n,X,I<expr>)> + +sum of expression I<expr> over +the positive divisors of C<n>. + +Arithmetic functions like X<sigma>B<sigma> use the multiplicativity of the +underlying expression to speed up the computation. In the present version +B<2.2.0>, there is no way to indicate that I<expr> is multiplicative in +C<n>, hence specialized functions should be prefered whenever possible. + +X<divsum>The library syntax is B<divsum>C<(entree *ep, GEN num, char *expr)>. + +=head2 X<suminf>suminfC<(X = a,I<expr>)> + +X<infinite sum>infinite sum of expression +I<expr>, the formal parameter C<X> starting at C<a>. The evaluation stops +when the relative error of the expression is less than the default precision. +The expressions must always evaluate to a complex number. + +X<suminf>The library syntax is B<suminf>C<(entree *ep, GEN a, char *expr, long prec)>. + +=head2 X<sumpos>sumposC<(X = a,I<expr>,{I<flag> = 0})> + +numerical summation of the +series I<expr>, which must be a series of terms having the same sign, +the formal +variable C<X> starting at C<a>. The algorithm used is Van Wijngaarden's trick +for converting such a series into an alternating one, and is quite slow. +Beware that the stopping criterion is that the term gets small enough, hence +terms which are equal to 0 will create problems and should be removed. + +If C<I<flag> = 1>, use slightly different polynomials. Sometimes faster. + +X<sumpos>The library syntax is B<sumpos>C<(entree *ep, GEN a, char *expr, long I<flag>, long prec)>. + +=head1 Plotting functions + +Although plotting is not even a side purpose of PARI, a number of plotting +functions are provided. Moreover, a lot of people felt like suggesting +ideas or submitting huge patches for this section of the code. Among these, +special thanks go to Klaus-Peter Nischke who suggested the recursive plotting +and the forking/resizing stuff under X11, and Ilya Zakharevich who +undertook a complete rewrite of the graphic code, so that most of it is now +platform-independent and should be relatively easy to port or expand. + +These graphic functions are either + +C<B<*>> high-level plotting functions (all the functions starting with +C<ploth>) in which the user has little to do but explain what type of plot +he wants, and whose syntax is similar to the one used in the preceding +section (with somewhat more complicated flags). + +C<B<*>> low-level plotting functions, where every drawing primitive (point, +line, box, etc.) must be specified by the user. These low-level functions +(called I<rectplot> functions, sharing the prefix C<plot>) work as +follows. You have at your disposal 16 virtual windows which are filled +independently, and can then be physically ORed on a single window at +user-defined positions. These windows are numbered from 0 to 15, and must be +initialized before being used by the function C<plotinit>, which specifies +the height and width of the virtual window (called a I<rectwindow> in the +sequel). At all times, a virtual cursor (initialized at C<[0,0]>) is +associated to the window, and its current value can be obtained using the +function C<plotcursor>. + +A number of primitive graphic objects (called I<rect> objects) can then +be drawn in these windows, using a default color associated to that window +(which can be changed under X11, using the C<plotcolor> function, black +otherwise) and only the part of the object which is inside the window will be +drawn, with the exception of polygons and strings which are drawn entirely +(but the virtual cursor can move outside of the window). The ones sharing the +prefix C<plotr> draw relatively to the current position of the virtual +cursor, the others use absolute coordinates. Those having the prefix +C<plotrecth> put in the rectwindow a large batch of rect objects +corresponding to the output of the related C<ploth> function. + +Finally, the actual physical drawing is done using the function +C<plotdraw>. Note that the windows are preserved so that further drawings +using the same windows at different positions or different windows can be +done without extra work. If you want to erase a window (and free the +corresponding memory), use the function C<plotkill>. It is not possible to +partially erase a window. Erase it completely, initialize it again and then +fill it with the graphic objects that you want to keep. + +In addition to initializing the window, you may want to have a scaled +window to avoid unnecessary conversions. For this, use the function +C<plotscale> below. As long as this function is not called, the scaling is +simply the number of pixels, the origin being at the upper left and the +C<y>-coordinates going downwards. + +Note that in the present version B<2.2.0> all these plotting functions +(both low and high level) have been written for the X11-window system +(hence also for GUI's based on X11 such as Openwindows and Motif) only, +though very little code remains which is actually platform-dependent. A +Suntools/Sunview, Macintosh, and an Atari/Gem port were provided for +previous versions. These I<may> be adapted in future releases. + +Under X11/Suntools, the physical window (opened by C<plotdraw> or any +of the C<ploth*> functions) is completely separated from GP (technically, +a C<fork> is done, and the non-graphical memory is immediately freed in +the child process), which means you can go on working in the current GP +session, without having to kill the window first. Under X11, this window can +be closed, enlarged or reduced using the standard window manager functions. +No zooming procedure is implemented though (yet). + +C<B<*>> Finally, note that in the same way that C<printtex> allows you +to have a TeX output corresponding to printed results, the functions +starting with C<ps> allow you to have X<PostScript>C<PostScript> output of the +plots. This will not be absolutely identical with the screen output, but will +be sufficiently close. Note that you can use PostScript output even if you do +not have the plotting routines enabled. The PostScript output is written in a +file whose name is derived from the X<psfile>C<psfile> default (C<./pari.ps> if +you did not tamper with it). Each time a new PostScript output is asked for, +the PostScript output is appended to that file. Hence the user must remove +this file, or change the value of C<psfile>, first if he does not want +unnecessary drawings from preceding sessions to appear. On the other hand, in +this manner as many plots as desired can be kept in a single file. + +I<None of the graphic functions are available within the PARI library, you +must be under GP to use them>. The reason for that is that you really should +not use PARI for heavy-duty graphical work, there are much better specialized +alternatives around. This whole set of routines was only meant as a +convenient, but simple-minded, visual aid. If you really insist on using +these in your program (we warned you), the source (C<plot*.c>) should be +readable enough for you to achieve something. + +=head2 X<plot>plotC<(X = a,b,I<expr>,{I<Ymin>},{I<Ymax>})> + +crude +(ASCII) plot of the function represented by expression I<expr> from +C<a> to C<b>, with I<Y> ranging from I<Ymin> to I<Ymax>. If +I<Ymin> (resp. I<Ymax>) is not given, the minima (resp. the +maxima) of the computed values of the expression is used instead. + +=head2 X<plotbox>plotboxC<(w,x2,y2)> + +let C<(x1,y1)> be the current position of the +virtual cursor. Draw in the rectwindow C<w> the outline of the rectangle which +is such that the points C<(x1,y1)> and C<(x2,y2)> are opposite corners. Only +the part of the rectangle which is in C<w> is drawn. The virtual cursor does +I<not> move. + +=head2 X<plotclip>plotclipC<(w)> + +`clips' the content of rectwindow C<w>, i.e +remove all parts of the drawing that would not be visible on the screen. +Together with X<plotcopy>C<plotcopy> this function enables you to draw on a +scratchpad before commiting the part you're interested in to the final +picture. + +=head2 X<plotcolor>plotcolorC<(w,c)> + +set default color to C<c> in rectwindow C<w>. +In present version B<2.2.0>, this is only implemented for X11 window system, +and you only have the following palette to choose from: + +1 = black, 2 = blue, 3 = sienna, 4 = red, 5 = cornsilk, 6 = grey, 7 = gainsborough. + +Note that it should be fairly easy for you to hardwire some more colors by +tweaking the files C<rect.h> and C<plotX.c>. User-defined +colormaps would be nice, and I<may> be available in future versions. + +=head2 X<plotcopy>plotcopyC<(w1,w2,dx,dy)> + +copy the contents of rectwindow +C<w1> to rectwindow C<w2>, with offset C<(dx,dy)>. + +=head2 X<plotcursor>plotcursorC<(w)> + +give as a 2-component vector the current +(scaled) position of the virtual cursor corresponding to the rectwindow C<w>. + +=head2 X<plotdraw>plotdrawC<(list)> + +physically draw the rectwindows given in C<list> +which must be a vector whose number of components is divisible by 3. If +C<list = [w1,x1,y1,w2,x2,y2,...]>, the windows C<w1>, C<w2>, etc.S< >are +physically placed with their upper left corner at physical position +C<(x1,y1)>, C<(x2,y2)>,...respectively, and are then drawn together. +Overlapping regions will thus be drawn twice, and the windows are considered +transparent. Then display the whole drawing in a special window on your +screen. + +=head2 X<plotfile>plotfileC<(s)> + +set the output file for plotting output. Special +filename C<-> redirects to the same place as PARI output. + +=head2 X<ploth>plothC<(X = a,b,I<expr>,{I<flag> = 0},{n = 0})> + +high precision +plot of the function C<y = f(x)> represented by the expression I<expr>, C<x> +going from C<a> to C<b>. This opens a specific window (which is killed +whenever you click on it), and returns a four-component vector giving the +coordinates of the bounding box in the form +C<[I<xmin>,I<xmax>,I<ymin>,I<ymax>]>. + +B<Important note>: Since this may involve a lot of function calls, +it is advised to keep the current precision to a minimum (e.g.S< >9) before +calling this function. + +C<n> specifies the number of reference point on the graph (0 means use the +hardwired default values, that is: 1000 for general plot, 1500 for +parametric plot, and 15 for recursive plot). + +If no C<I<flag>> is given, I<expr> is either a scalar expression C<f(X)>, in which +case the plane curve C<y = f(X)> will be drawn, or a vector +C<[f_1(X),...,f_k(X)]>, and then all the curves C<y = f_i(X)> will be drawn in +the same window. + +The binary digits of C<I<flag>> mean: + +C<B<*>> 1: X<parametric plot>I<parametric plot>. Here I<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: + +C<ploth(X = 0,2*Pi,[sin(X),cos(X)],1)> will draw a circle. + +C<ploth(X = 0,2*Pi,[sin(X),cos(X)])> will draw two entwined sinusoidal +curves. + +C<ploth(X = 0,2*Pi,[X,X,sin(X),cos(X)],1)> will draw a circle and the line +C<y = x>. + +C<B<*>> 2: X<recursive plot>I<recursive plot>. If this flag is set, only I<one> +curve can be drawn at time, i.e.S< >I<expr> must be either a two-component +vector (for a single parametric curve, and the parametric flag I<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 + +S< >C<ploth(X = -1,1,sin(1/X),2) and ploth(X = -1,1,sin(1/X))> + +for instance. But beware that if you are extremely unlucky, or choose too few +reference points, you may draw some nice polygon bearing little resemblance +to the original curve. For instance you should I<never> plot recursively +an odd function in a symmetric interval around 0. Try + + ploth(x = -20, 20, sin(x), 2) + +to see why. Hence, it's usually a good idea to try and plot the same +curve with slightly different parameters. + +The other values toggle various display options: + +C<B<*>> 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 +X<plotrecth>C<plotrecth> call), in conjuction with X<plotscale>C<plotscale>. + +C<B<*>> 8: do not print the C<x>-axis. + +C<B<*>> 16: do not print the C<y>-axis. + +C<B<*>> 32: do not print frame. + +C<B<*>> 64: only plot reference points, do not join them. + +C<B<*>> 256: use splines to interpolate the points. + +C<B<*>> 512: plot no C<x>-ticks. + +C<B<*>> 1024: plot no C<y>-ticks. + +C<B<*>> 2048: plot all ticks with the same length. + +=head2 X<plothraw>plothrawC<(I<listx>,I<listy>,{I<flag> = 0})> + +given +I<listx> and I<listy> two vectors of equal length, plots (in high +precision) the points whose C<(x,y)>-coordinates are given in I<listx> +and I<listy>. Automatic positioning and scaling is done, but with the +same scaling factor on C<x> and C<y>. If C<I<flag>> is 1, join points, other non-0 +flags toggle display options and should be combinations of bits C<2^k>, C<k + E<gt>= 3> as in C<ploth>. + +=head2 X<plothsizes>plothsizesC<()> + +return data corresponding to the output window +in the form of a 6-component vector: window width and height, sizes for ticks +in horizontal and vertical directions (this is intended for the C<gnuplot> +interface and is currently not significant), width and height of characters. + +=head2 X<plotinit>plotinitC<(w,x,y)> + +initialize the rectwindow C<w> to width C<x> and +height C<y>, and position the virtual cursor at C<(0,0)>. This destroys any rect +objects you may have already drawn in C<w>. + +The plotting device imposes an upper bound for C<x> and C<y>, for instance the +number of pixels for screen output. These bounds are available through the +X<plothsizes>C<plothsizes> function. The following sequence initializes in a portable way +(i.e independant of the output device) a window of maximal size, accessed through +coordinates in the C<[0,1000] x [0,1000]> rangeS< >: + + s = plothsizes(); + plotinit(0, s[1]-1, s[2]-1); + plotscale(0, 0,1000, 0,1000); + +=head2 X<plotkill>plotkillC<(w)> + +erase rectwindow C<w> and free the corresponding +memory. Note that if you want to use the rectwindow C<w> again, you have to +use C<initrect> first to specify the new size. So it's better in this case +to use C<initrect> directly as this throws away any previous work in the +given rectwindow. + +=head2 X<plotlines>plotlinesC<(w,X,Y,{I<flag> = 0})> + +draw on the rectwindow C<w> +the polygon such that the (x,y)-coordinates of the vertices are in the +vectors of equal length C<X> and C<Y>. For simplicity, the whole +polygon is drawn, not only the part of the polygon which is inside the +rectwindow. If C<I<flag>> is non-zero, close the polygon. In any case, the +virtual cursor does not move. + +C<X> and C<Y> are allowed to be scalars (in this case, both have to). +There, a single segment will be drawn, between the virtual cursor current +position and the point C<(X,Y)>. And only the part thereof which +actually lies within the boundary of C<w>. Then I<move> the virtual cursor +to C<(X,Y)>, even if it is outside the window. If you want to draw a +line from C<(x1,y1)> to C<(x2,y2)> where C<(x1,y1)> is not necessarily the +position of the virtual cursor, use C<plotmove(w,x1,y1)> before using this +function. + +=head2 X<plotlinetype>plotlinetypeC<(w,I<type>)> + +change the type of lines +subsequently plotted in rectwindow C<w>. I<type> C<-2> corresponds to +frames, C<-1> to axes, larger values may correspond to something else. C<w = +-1> changes highlevel plotting. This is only taken into account by the +C<gnuplot> interface. + +=head2 X<plotmove>plotmoveC<(w,x,y)> + +move the virtual cursor of the rectwindow C<w> +to position C<(x,y)>. + +=head2 X<plotpoints>plotpointsC<(w,X,Y)> + +draw on the rectwindow C<w> the +points whose C<(x,y)>-coordinates are in the vectors of equal length C<X> and +C<Y> and which are inside C<w>. The virtual cursor does I<not> move. This +is basically the same function as C<plothraw>, but either with no scaling +factor or with a scale chosen using the function C<plotscale>. + +As was the case with the C<plotlines> function, C<X> and C<Y> are allowed to +be (simultaneously) scalar. In this case, draw the single point C<(X,Y)> on +the rectwindow C<w> (if it is actually inside C<w>), and in any case +I<move> the virtual cursor to position C<(x,y)>. + +=head2 X<plotpointsize>plotpointsizeC<(w,size)> + +changes the ``size'' of following +points in rectwindow C<w>. If C<w = -1>, change it in all rectwindows. +This only works in the C<gnuplot> interface. + +=head2 X<plotpointtype>plotpointtypeC<(w,I<type>)> + +change the type of +points subsequently plotted in rectwindow C<w>. C<I<type> = -1> +corresponds to a dot, larger values may correspond to something else. C<w = -1> +changes highlevel plotting. This is only taken into account by the +C<gnuplot> interface. + +=head2 X<plotrbox>plotrboxC<(w,dx,dy)> + +draw in the rectwindow C<w> the outline of +the rectangle which is such that the points C<(x1,y1)> and C<(x1+dx,y1+dy)> are +opposite corners, where C<(x1,y1)> is the current position of the cursor. +Only the part of the rectangle which is in C<w> is drawn. The virtual cursor +does I<not> move. + +=head2 X<plotrecth>plotrecthC<(w,X = a,b,I<expr>,{I<flag> = 0},{n = 0})> + +writes to +rectwindow C<w> the curve output of C<ploth>C<(w,X = a,b,I<expr>,I<flag>,n)>. + +=head2 X<plotrecthraw>plotrecthrawC<(w,I<data>,{I<flag> = 0})> + +plot graph(s) for +I<data> in rectwindow C<w>. C<I<flag>> has the same significance here as in +C<ploth>, though recursive plot is no more significant. + +I<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 +the C<x> coordinates, and the other ones contain the C<y>-coordinates +of curves to plot. + +=head2 X<plotrline>plotrlineC<(w,dx,dy)> + +draw in the rectwindow C<w> the part of the +segment C<(x1,y1)-(x1+dx,y1+dy)> which is inside C<w>, where C<(x1,y1)> is the +current position of the virtual cursor, and move the virtual cursor to +C<(x1+dx,y1+dy)> (even if it is outside the window). + +=head2 X<plotrmove>plotrmoveC<(w,dx,dy)> + +move the virtual cursor of the rectwindow +C<w> to position C<(x1+dx,y1+dy)>, where C<(x1,y1)> is the initial position of +the cursor (i.e.S< >to position C<(dx,dy)> relative to the initial cursor). + +=head2 X<plotrpoint>plotrpointC<(w,dx,dy)> + +draw the point C<(x1+dx,y1+dy)> on the +rectwindow C<w> (if it is inside C<w>), where C<(x1,y1)> is the current position +of the cursor, and in any case move the virtual cursor to position +C<(x1+dx,y1+dy)>. + +=head2 X<plotscale>plotscaleC<(w,x1,x2,y1,y2)> + +scale the local coordinates of the +rectwindow C<w> so that C<x> goes from C<x1> to C<x2> and C<y> goes from C<y1> to +C<y2> (C<x2 E<lt> x1> and C<y2 E<lt> y1> being allowed). Initially, after the initialization +of the rectwindow C<w> using the function C<plotinit>, the default scaling +is the graphic pixel count, and in particular the C<y> axis is oriented +downwards since the origin is at the upper left. The function C<plotscale> +allows to change all these defaults and should be used whenever functions are +graphed. + +=head2 X<plotstring>plotstringC<(w,x,{I<flag> = 0})> + +draw on the rectwindow C<w> the +String C<x> (see L<Label se:strings>), at the current position of the cursor. + +I<flag> is used for justification: bits 1 and 2 regulate horizontal alignment: +left if 0, right if 2, center if 1. Bits 4 and 8 regulate vertical +alignment: bottom if 0, top if 8, v-center if 4. Can insert additional +small gap between point and string: horizontal if bit 16 is set, vertical +if bit 32 is set (see the tutorial for an example). + +=head2 X<plotterm>plottermC<(I<term>)> + +sets terminal where high resolution +plots go (this is currently only taken into account by the C<gnuplot> +graphical driver). Using the C<gnuplot> driver, possible terminals are +the same as in gnuplot. If I<term> is "?", lists possible values. + +Terminal options can be appended to the terminal name and space; terminal +size can be put immediately after the name, as in C<"gif = 300,200">. +Positive return value means success. + +=head2 X<psdraw>psdrawC<(I<list>)> + +same as C<plotdraw>, except that the +output is a PostScript program appended to the C<psfile>. + +=head2 X<psploth>psplothC<(X = a,b,I<expr>)> + +same as C<ploth>, except that the +output is a PostScript program appended to the C<psfile>. + +=head2 X<psplothraw>psplothrawC<(I<listx>,I<listy>)> + +same as C<plothraw>, +except that the output is a PostScript program appended to the C<psfile>. + +=head1 Programming under GP + +X<programming>X<Label se:programming> +=head2 Control statements. + +A number of control statements are available under GP. They are simpler and +have a syntax slightly different from their C counterparts, but are quite +powerful enough to write any kind of program. Some of them are specific to +GP, since they are made for number theorists. As usual, C<X> will denote any +simple variable name, and I<seq> will always denote a sequence of +expressions, including the empty sequence. + +=item X<break>breakC<({n = 1})> + +interrupts execution of current I<seq>, and +immediately exits from the C<n> innermost enclosing loops, within the +current function call (or the top level loop). C<n> must be bigger than 1. +If C<n> is greater than the number of enclosing loops, all enclosing loops +are exited. + +=item X<for>forC<(X = a,b,I<seq>)> + +the formal variable C<X> going from +C<a> to C<b>, the I<seq> is evaluated. Nothing is done if C<a E<gt> b>. +C<a> and C<b> must be in B<I<R>>. + +=item X<fordiv>fordivC<(n,X,I<seq>)> + +the formal variable C<X> ranging +through the positive divisors of C<n>, the sequence I<seq> is evaluated. +C<n> must be of type integer. + +=item X<forprime>forprimeC<(X = a,b,I<seq>)> + +the formal variable C<X> +ranging over the prime numbers between C<a> to C<b> (including C<a> and C<b> +if they are prime), the I<seq> is evaluated. More precisely, the value +of C<X> is incremented to the smallest prime strictly larger than C<X> at the +end of each iteration. Nothing is done if C<a E<gt> b>. Note that C<a> and C<b> must +be in B<I<R>>. + + ? { forprime(p = 2, 12, + print(p); + if (p == 3, p = 6); + ) + } + 2 + 3 + 7 + 11 + +=item X<forstep>forstepC<(X = a,b,s,I<seq>)> + +the formal variable C<X> +going from C<a> to C<b>, in increments of C<s>, the I<seq> is evaluated. +Nothing is done if C<s E<gt> 0> and C<a E<gt> b> or if C<s E<lt> 0> and C<a E<lt> b>. C<s> must be in +C<B<I<R>>^*> or a vector of steps C<[s_1,...,s_n]>. In the latter case, the +successive steps are used in the order they appear in C<s>. + + ? forstep(x=5, 20, [2,4], print(x)) + 5 + 7 + 11 + 13 + 17 + 19 + +=item X<forsubgroup>forsubgroupC<(H = G,{B},I<seq>)> + +executes I<seq> for +each subgroup C<H> of the I<abelian> group C<G> (given in +SNFX<Smith normal form> form or as a vector of elementary divisors), +whose index is bounded by bound. The subgroups are not ordered in any +obvious way, unless C<G> is a C<p>-group in which case Birkhoff's algorithm +produces them by decreasing index. A X<subgroup>subgroup is given as a matrix +whose columns give its generators on the implicit generators of C<G>. For +example, the following prints all subgroups of index less than 2 in C<G = +B<I<Z>>/2B<I<Z>> g_1 x B<I<Z>>/2B<I<Z>> g_2>S< >: + + ? G = [2,2]; forsubgroup(H=G, 2, print(H)) + [1; 1] + [1; 2] + [2; 1] + [1, 0; 1, 1] + +The last one, for instance is generated by C<(g_1, g_1 + g_2)>. This +routine is intended to treat huge groups, when X<subgrouplist>B<subgrouplist> is not an +option due to the sheer size of the output. + +For maximal speed the subgroups have been left as produced by the algorithm. +To print them in canonical form (as left divisors of C<G> in +HNFX<Hermite normal form> form), one can for instance use + + ? G = matdiagonal([2,2]); forsubgroup(H=G, 2, print(mathnf(concat(G,H)))) + [2, 1; 0, 1] + [1, 0; 0, 2] + [2, 0; 0, 1] + [1, 0; 0, 1] + +Note that in this last representation, the index C<[G:H]> is given by the +determinant. + +=item X<forvec>forvecC<(X = v,I<seq>,{I<flag> = 0})> + +C<v> being an C<n>-component +vector (where C<n> is arbitrary) of two-component vectors C<[a_i,b_i]> +for C<1 E<lt>= i E<lt>= n>, the I<seq> is evaluated with the formal variable +C<X[1]> going from C<a_1> to C<b_1>,...,C<X[n]> going from C<a_n> to C<b_n>. +The formal variable with the highest index moves the fastest. If C<I<flag> = 1>, +generate only nondecreasing vectors C<X>, and if C<I<flag> = 2>, generate only +strictly increasing vectors C<X>. + +=item X<if>ifC<(a,{I<seq1>},{I<seq2>})> + +if C<a> is non-zero, +the expression sequence I<seq1> is evaluated, otherwise the expression +I<seq2> is evaluated. Of course, I<seq1> or I<seq2> may be empty, +so C<if (a,I<seq>)> evaluates I<seq> if C<a> is not equal to zero +(you don't have to write the second comma), and does nothing otherwise, +whereas C<if (a,,I<seq>)> evaluates I<seq> if C<a> is equal to +zero, and does nothing otherwise. You could get the same result using +the C<!> (C<not>) operator: C<if (!a,I<seq>)>. + +Note that the boolean operators C<&&> and C<||> are evaluated +according to operator precedence as explained in L<Label se:operators>, but +that, contrary to other operators, the evaluation of the arguments is +stopped as soon as the final truth value has been determined. For instance + + if (reallydoit && longcomplicatedfunction(), ...)% + +is a perfectly safe statement. + +Recall that functions such as C<break> and C<next> operate on +I<loops> (such as C<forxxx>, C<while>, C<until>). The C<if> +statement is I<not> a loop (obviously!). + +=item X<next>nextC<({n = 1})> + +interrupts execution of current C<seq>, +resume the next iteration of the innermost enclosing loop, within the +current fonction call (or top level loop). If C<n> is specified, resume at +the C<n>-th enclosing loop. If C<n> is bigger than the number of enclosing +loops, all enclosing loops are exited. + +=item X<return>returnC<({x = 0})> + +returns from current subroutine, with +result C<x>. + +=item X<until>untilC<(a,I<seq>)> + +evaluates expression sequence I<seq> +until C<a> is not equal to 0 (i.e.S< >until C<a> is true). If C<a> is initially +not equal to 0, I<seq> is evaluated once (more generally, the condition +on C<a> is tested I<after> execution of the I<seq>, not before as in +C<while>). + +=item X<while>whileC<(a,I<seq>)> + +while C<a> is non-zero evaluate the +expression sequence I<seq>. The test is made I<before> evaluating +the C<seq>, hence in particular if C<a> is initially equal to zero the +I<seq> will not be evaluated at all. + +=head2 Specific functions used in GP programming + +X<Label se:gp_program> +In addition to the general PARI functions, it is necessary to have some +functions which will be of use specifically for GP, though a few of these can +be accessed under library mode. Before we start describing these, we recall +the difference between I<strings> and I<keywords> (see +L<Label se:strings>): the latter don't get expanded at all, and you can type +them without any enclosing quotes. The former are dynamic objects, where +everything outside quotes gets immediately expanded. + +We need an additional notation for this chapter. An argument between braces, +followed by a star, like C<{I<str>}*>, means that any number of such +arguments (possibly none) can be given. + +=item X<addhelp>addhelpC<(S,I<str>)> + +X<Label se:addhelp> changes the help +message for the symbol C<S>. The string I<str> is expanded on the spot +and stored as the online help for C<S>. If C<S> is a function I<you> have +defined, its definition will still be printed before the message I<str>. +It is recommended that you document global variables and user functions in +this way. Of course GP won't protest if you don't do it. + +There's nothing to prevent you from modifying the help of built-in PARI +functions (but if you do, we'd like to hear why you needed to do it!). + +=item X<alias>aliasC<(I<newkey>,I<key>)> + +defines the keyword +I<newkey> as an alias for keyword I<key>. I<key> must correspond +to an existing I<function> name. This is different from the general user +macros in that alias expansion takes place immediately upon execution, +without having to look up any function code, and is thus much faster. A +sample alias file C<misc/gpalias> is provided with the standard +distribution. Alias commands are meant to be read upon startup from the +C<.gprc> file, to cope with function names you are dissatisfied with, and +should be useless in interactive usage. + +=item X<allocatemem>allocatememC<({x = 0})> + +this is a very special operation which +allows the user to change the stack size I<after> initialization. C<x> +must be a non-negative integer. If C<x! = 0>, a new stack of size C<16*\lceil +x/16\rceil> bytes will be allocated, all the PARI data on the old stack will +be moved to the new one, and the old stack will be discarded. If C<x = 0>, the +size of the new stack will be twice the size of the old one. + +Although it is a function, this must be the I<last> instruction in any GP +sequence. The technical reason is that this routine usually moves the stack, +so objects from the current sequence might not be correct anymore. Hence, to +prevent such problems, this routine terminates by a C<longjmp> (just as an +error would) and not by a return. + +X<allocatemoremem>The library syntax is B<allocatemoremem>C<(x)>, where C<x> is an unsigned long, and the return type +is void. GP uses a variant which ends by a C<longjmp>. + +=item X<default>defaultC<({I<key>},{I<val>},{I<flag>})> + +sets the default +corresponding to keyword I<key> to value I<val>. I<val> is a string +(which of course accepts numeric arguments without adverse effects, due to the +expansion mechanism). See L<Label se:defaults> for a list of available +defaults, and L<Label se:meta> for some shortcut alternatives. Typing +C<default()> (or C<\d>) yields the complete default list as well as +their current values.X<Label se:default> + +If I<val> is omitted, prints the current value of default I<key>. +If C<I<flag>> is set, returns the result instead of printing it. + +=item X<error>errorC<({I<str>}*)> + +outputs its argument list (each of +them interpreted as a string), then interrupts the running GP program, +returning to the input prompt. + +Example: C<error("n = ", n, " is not squarefree !")>. + +Note that, due to the automatic concatenation of strings, you could in fact +use only one argument, just by suppressing the commas. + +=item X<extern>externC<(I<str>)> + +the string I<str> is the name +of an external command (i.e.S< >one you would type from your UNIX shell prompt). +This command is immediately run and its input fed into GP, just as if read +from a file. + +=item X<getheap>getheapC<()> + +returns a two-component row vector giving the +number of objects on the heap and the amount of memory they occupy in long +words. Useful mainly for debugging purposes. + +X<getheap>The library syntax is B<getheap>C<()>. + +=item X<getrand>getrandC<()> + +returns the current value of the random number +seed. Useful mainly for debugging purposes. + +X<getrand>The library syntax is B<getrand>C<()>, returns a C long. + +=item X<getstack>getstackC<()> + +returns the current value of +C<top-avma>, +i.e.S< >the number of bytes used up to now on the stack. Should be equal to 0 +in between commands. Useful mainly for debugging purposes. + +X<getstack>The library syntax is B<getstack>C<()>, returns a C long. + +=item X<gettime>gettimeC<()> + +returns the time (in milliseconds) elapsed since +either the last call to C<gettime>, or to the beginning of the containing +GP instruction (if inside GP), whichever came last. + +X<gettime>The library syntax is B<gettime>C<()>, returns a C long. + +=item X<global>globalC<({I<list of variables>})> + +X<Label se:global> +declares the corresponding variables to be global. From now on, you will be +forbidden to use them as formal parameters for function definitions or as +loop indexes. This is especially useful when patching together various +scripts, possibly written with different naming conventions. For instance the +following situation is dangerous: + + p = 3 \\ fix characteristic + ... + forprime(p = 2, N, ...) + f(p) = ... + +since within the loop or within the function's body (even worse: in the +subroutines called in that scope), the true global value of C<p> will be +hidden. If the statement C<global(p = 3)> appears at the beginning of +the script, then both expressions will trigger syntax errors. + +Calling C<global> without arguments prints the list of global variables in +use. In particular, C<eval(global)> will output the values of all local +variables. + +=item X<input>inputC<()> + +reads a string, interpreted as a GP expression, +from the input file, usually standard input (i.e.S< >the keyboard). If a +sequence of expressions is given, the result is the result of the last +expression of the sequence. When using this instruction, it is useful to +prompt for the string by using the C<print1> function. Note that in the +present version 2.19 of C<pari.el>, when using GP under GNU Emacs (see +L<Label se:emacs>) one I<must> prompt for the string, with a string +which ends with the same prompt as any of the previous ones (a C<"? "> +will do for instance). + +=item X<install>installC<(I<name>,I<code>,{I<gpname>},{I<lib>})> + +loads from dynamic library I<lib> the function I<name>. Assigns to it +the name I<gpname> in this GP session, with argument code I<code> (see +L<Label se:gp.interface> for an explanation of those). If I<lib> is +omitted, uses C<libpari.so>. If I<gpname> is omitted, uses +I<name>.X<Label se:install> + +This function is useful for adding custom functions to the GP interpreter, +or picking useful functions from unrelated libraries. For instance, it +makes the function X<system>C<system> obsolete: + + ? install(system, vs, sys, "libc.so") + ? sys("ls gp*") + gp.c gp.h gp_rl.c + +But it also gives you access to all (non static) functions defined in the +PARI library. For instance, the function C<GEN addii(GEN x, GEN y)> adds +two PARI integers, and is not directly accessible under GP (it's eventually +called by the C<+> operator of course): + + ? install("addii", "GG") + ? addii(1, 2) + %1 = 3 + +B<Caution:> This function may not work on all systems, especially +when GP has been compiled statically. In that case, the first use of an +installed function will provoke a Segmentation Fault, i.e.S< >a major internal +blunder (this should never happen with a dynamically linked executable). +Hence, if you intend to use this function, please check first on some +harmless example such as the ones above that it works properly on your +machine. + +=item X<kill>killC<(s)> + +X<Label se:kill> kills the present value of the +variable, alias or user-defined function C<s>. The corresponding identifier +can now be used to name any GP object (variable or function). This is the +only way to replace a variable by a function having the same name (or the +other way round), as in the following example: + + ? f = 1 + %1 = 1 + ? f(x) = 0 + *** unused characters: f(x)=0 + ^---- + ? kill(f) + ? f(x) = 0 + ? f() + %2 = 0 + +When you kill a variable, all objects that used it become invalid. You +can still display them, even though the killed variable will be printed in a +funny way (following the same convention as used by the library function +C<fetch_var>, seeS< >L<Label se:vars>). For example: + + ? a^2 + 1 + %1 = a^2 + 1 + ? kill(a) + ? %1 + %2 = #<1>^2 + 1 + +If you simply want to restore a variable to its ``undefined'' value +(monomial of degree one), use the X<quote>quote operator: C<a = 'a>. +Predefined symbols (C<x> and GP function names) cannot be killed. + +=item X<print>printC<({I<str>}*)> + +outputs its (string) arguments in raw +format, ending with a newline. + +=item X<print1>print1C<({I<str>}*)> + +outputs its (string) arguments in raw +format, without ending with a newline (note that you can still embed newlines +within your strings, using the C<\n> notationS< >!). + +=item X<printp>printpC<({I<str>}*)> + +outputs its (string) arguments in +prettyprint (beautified) format, ending with a newline. + +=item X<printp1>printp1C<({I<str>}*)> + +outputs its (string) arguments in +prettyprint (beautified) format, without ending with a newline. + +=item X<printtex>printtexC<({I<str>}*)> + +outputs its (string) arguments in +TeX format. This output can then be used in a TeX manuscript. +The printing is done on the standard output. If you want to print it to a +file you should use C<writetex> (see there). + +Another possibility is to enable the X<log>C<log> default +(seeS< >L<Label se:defaults>). +You could for instance do:X<logfile> + + default(logfile, "new.tex"); + default(log, 1); + printtex(result); + +(You can use the automatic string expansion/concatenation process to have +dynamic file names if you wish). + +=item X<quit>quitC<()> + +exits GP.X<Label se:quit> + +=item X<read>readC<({I<str>})> + +reads in the file whose name results +from the expansion of the string I<str>. If I<str> is omitted, +re-reads the last file that was fed into GP. The return value is the result of +the last expression evaluated.X<Label se:read> + +=item X<reorder>reorderC<({x = []})> + +C<x> must be a vector. If C<x> is the +empty vector, this gives the vector whose components are the existing +variables in increasing order (i.e.S< >in decreasing importance). Killed +variables (see C<kill>) will be shown as C<0>. If C<x> is +non-empty, it must be a permutation of variable names, and this permutation +gives a new order of importance of the variables, I<for output only>. For +example, if the existing order is C<[x,y,z]>, then after +C<reorder([z,x])> the order of importance of the variables, with respect +to output, will be C<[z,y,x]>. The internal representation is unaffected. +X<Label se:reorder> + +=item X<setrand>setrandC<(n)> + +reseeds the random number generator to the value +C<n>. The initial seed is C<n = 1>. + +X<setrand>The library syntax is B<setrand>C<(n)>, where C<n> is a C<long>. Returns C<n>. + +=item X<system>systemC<(I<str>)> + +I<str> is a string representing +a system command. This command is executed, its output written to the +standard output (this won't get into your logfile), and control returns +to the PARI system. This simply calls the C C<system> command. + +=item X<trap>trapC<({e}, {I<rec>}, {I<seq>})> + +tries to +execute I<seq>, trapping error C<e>, that is effectively preventing it +from aborting computations in the usual way; the recovery sequence +I<rec> is executed if the error occurs and the evaluation of I<rec> +becomes the result of the command. If C<e> is omitted, all exceptions are +trapped. Note in particular that hitting C<^C> (Control-C) raises an +exception. + + ? \\ trap division by 0 + ? inv(x) = trap (gdiver2, INFINITY, 1/x) + ? inv(2) + %1 = 1/2 + ? inv(0) + %2 = INFINITY + +If I<seq> is omitted, defines I<rec> as a default action when +encountering exception C<e>. The error message is printed, as well as the +result of the evaluation of I<rec>, and the control is given back to the +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: + + ? { trap( , + print(reorder); + write("crash", reorder); + write("crash", eval(reorder))) } + +If no recovery code is given (I<rec> is omitted) a so-called +I<X<break loop>break loop> will be started. During a break loop, all commands are +read and evaluated as during the main GP loop (except that no history of +results is kept). + +To get out of the break loop, you can use X<next>C<next>, X<break>C<break> or +X<return>C<return>; reading in a file by C<\r> will also terminate the loop once +the file has been read (C<read> will remain in the break loop). If the +error is not fatal (C<^C> is the only non-fatal error), C<next> +will continue the computation as if nothing had happened (except of course, +you may have changed GP state during the break loop); otherwise control +will come back to the GP prompt. After a user interrupt (C<^C>), +entering an empty input line (i.e hitting the return key) has the same +effect as C<next>. + +Break loops are useful as a debugging tool to inspect the values of GP +variables to understand why a problem occurred, or to change GP behaviour +(increase debugging level, start storing results in a logfile, modify +parameters...) in the middle of a long computation (hit C<^C>, type +in your modifications, then type C<next>). + +If I<rec> is the empty string C<""> the last default handler is popped +out, and replaced by the previous one for that error. + +B<Note:> The interface is currently not adequate for trapping +individual exceptions. In the current version B<2.2.0>, the following keywords +are recognized, but the name list will be expanded and changed in the +future (all library mode errors can be trapped: it's a matter of defining +the keywords to GP, and there are currently far too many useless ones): + +C<accurer>: accuracy problem + +C<gdiver2>: division by 0 + +C<archer>: not available on this architecture or operating system + +C<typeer>: wrong type + +C<errpile>: the PARI stack overflows + +=item X<type>typeC<(x,{t})> + +this is useful only under GP. If C<t> is +not present, returns the internal type number of the PARI object C<x>. +Otherwise, makes a copy of C<x> and sets its type equal to type C<t>, which +can be either a number or, preferably since internal codes may eventually +change, a symbolic name such as C<t_FRACN> (you can skip the C<t_> +part here, so that C<FRACN> by itself would also be all right). Check out +existing type names with the metacommand C<\t>.X<Label se:gptype> + +GP won't let you create meaningless objects in this way where the internal +structure doesn't match the type. This function can be useful to create +reducible rationals (type C<t_FRACN>) or rational functions (type +C<t_RFRACN>). In fact it's the only way to do so in GP. In this case, the +created object, as well as the objects created from it, will not be reduced +automatically, making some operations a bit faster. + +There is no equivalent library syntax, since the internal functions C<typ> +and C<settyp> are available. Note that C<settyp> does I<not> +create a copy of C<x>, contrary to most PARI functions. It also doesn't +check for consistency. C<settyp> just changes the type in place and +returns nothing. C<typ> returns a C long integer. Note also the different +spellings of the internal functions (C<set>)C<typ> and of the GP +function C<type>, which is due to the fact that C<type> is a reserved +identifier for some C compilers. + +=item X<whatnow>whatnowC<(I<key>)> + +if keyword I<key> is the name +of a function that was present in GP version 1.39.15 or lower, outputs +the new function name and syntax, if it changed at all (C<387> out of C<560> +did).X<Label se:whatnow> + +=item X<write>writeC<(I<filename>,{I<str>*})> + +writes (appends) +to I<filename> the remaining arguments, and appends a newline (same output +as C<print>).X<Label se:write> + +=item X<write1>write1C<(I<filename>,{I<str>*})> + +writes (appends) to +I<filename> the remaining arguments without a trailing newline +(same output as C<print1>). + +=item X<writetex>writetexC<(I<filename>,{I<str>*})> + +as C<write>, +in TeX format.X<Label se:writetex> + |