+"/"-

The library syntax is gneg"(x)" for "-""x".

+, "-"

The library syntax is gadd"(x,y)" "x" "+" "y", " gsub(x,y)" for "x" "-" "y".

*

If "x" and "y" are binary quadratic forms, compose them. See also "qfbnucomp" and "qfbnupow".

The library syntax is gmul"(x,y)" for "x" "*" "y". Also available is " gsqr(x)" for "x" "*" "x" (faster of course!).

/

The library syntax is gdiv"(x,y)" for "x" "/" "y".

\

Note that when "y" is an integer and "x" a polynomial, "y" is first promoted to a polynomial of degree 0. When "x" is a vector or matrix, the operator is applied componentwise.

The library syntax is gdivent"(x,y)" for "x" "\" "y".

\/

When "x" is a vector or matrix, the operator is applied componentwise.

The library syntax is gdivround"(x,y)" for "x" "\/" "y".

%

  ? (1/2) % 3
  %1 = 2
  ? 0.5 % 3
    ***   forbidden division t_REAL % t_INT.
  ? (1/2) % 3.0
  %2 = 1/2

Note that when "y" is an integer and "x" a polynomial, "y" is first promoted to a polynomial of degree 0. When "x" is a vector or matrix, the operator is applied componentwise.

The library syntax is gmod"(x,y)" for "x" "%" "y".

divrem"(x,y,{v})"

Beware that "divrem(x,y)[2]" is in general not the same as "x % y"; there is no operator to obtain it in GP:

  ? divrem(1/2, 3)[2]
  %1 = 1/2
  ? (1/2) % 3
  %2 = 2
  ? divrem(Mod(2,9), 3)[2]
    ***   forbidden division t_INTMOD \ t_INT.
  ? Mod(2,9) % 6
  %3 = Mod(2,3)

The library syntax is divrem"(x,y,v)",where "v" is a "long". Also available as " gdiventres(x,y)" when "v" is not needed.

^

PARI is able to rewrite the multiplication "x * x" of two \emph{identical} objects as "x^2", or 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 "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 "p/q" and "x" an integer modulo a prime or a "p"-adic number, return a solution "y" of "y^q = x^p" if it exists. Currently, "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 */

If the exponent is a negative integer, an inverse must be computed. For non-invertible "t_INTMOD", this will fail and implicitly exhibit a non trivial factor of the modulus:

      ? Mod(4,6)^(-1)
        ***   impossible inverse modulo: Mod(2, 6).

(Here, a factor 2 is obtained directly. In general, take the gcd of the representative and the modulus.) This is most useful when performing complicated operations modulo an integer "N" whose factorization is unknown. Either the computation succeeds and all is well, or a factor "d" is discovered and the computation may be restarted modulo "d" or "N/d".

For non-invertible "t_POLMOD", this will fail without exhibiting a factor.

      ? Mod(x^2, x^3-x)^(-1)
        ***   non-invertible polynomial in RgXQ_inv.

      ? a = Mod(3,4)*y^3 + Mod(1,4); b = y^6+y^5+y^4+y^3+y^2+y+1;
      ? Mod(a, b)^(-1);
        ***   non-invertible polynomial in RgXQ_inv.

In fact the latter polynomial is invertible, but the algorithm used (subresultant) assumes the base ring is a domain. If it is not the case, as here for "Z/4Z", a result will be correct but chances are an error will occur first. In this specific case, one should work with 2-adics. In general, one can try the following approach

      ? inversemod(a, b) =
      { local(m);
        m = polsylvestermatrix(polrecip(a), polrecip(b));
        m = matinverseimage(m, matid(#m)[,1]);
        Polrev( vecextract(m, Str("..", poldegree(b))), variable(b) )
      }
      ? inversemod(a,b)
      %2 = Mod(2,4)*y^5 + Mod(3,4)*y^3 + Mod(1,4)*y^2 + Mod(3,4)*y + Mod(2,4)

This is not guaranteed to work either since it must invert pivots. See "Label se:linear_algebra".

The library syntax is gpow"(x,n, prec)" for "x^n".

bittest"(x,n)"

See "Label se:bitand" for the behaviour at negative arguments.

The library syntax is bittest"(x,n)", where "n" and the result are "long"s.

shift"(x,n)" or "x" "<< " "n" ( = "x" ">> " "(-n)")

The library syntax is gshift"(x,n)" where "n" is a "long".

shiftmul"(x,n)"

The library syntax is gmul2n"(x,n)" where "n" is a "long".

Comparison and boolean operators

The standard boolean functions "||" (inclusive or), "&&" (and) and "!" (not) are also available, and the library syntax is " gor(x,y)", " gand(x,y)" and " gnot(x)" respectively.

In library mode, it is in fact usually preferable to use the two basic functions which are " gcmp(x,y)" which gives the sign (1, 0, or -1) of "x-y", where "x" and "y" must be in R, and " gequal (x,y)" which can be applied to any two PARI objects "x" and "y" and gives 1 (i.e. true) if they are equal (but not necessarily identical), 0 (i.e. false) otherwise. Comparisons to special constants are implemented and should be used instead of "gequal": " gcmp0(x)" ("x == 0" ?), " gcmp1(x)" ("x == 1" ?), and " gcmp_1(x)" ("x == -1" ?).

Note that gcmp0(x) tests whether "x" is equal to zero, even if "x" is not an exact object. To test whether "x" is an exact object which is equal to zero, one must use " isexactzero (x)".

Also note that the "gcmp" and "gequal" functions return a C-integer, and \emph{not} a "GEN" like "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 "and" or bitwise "or" (use "bitand" or "bitor"), hence "|" and "&" are accepted as synonyms of "||" and "&&" respectively. Also, "< > " is accepted as a synonym for "! = ". On the other hand, " = " is definitely \emph{not} a synonym for " == " since it is the assignment statement.

lex"(x,y)"

In case all components are equal up to the smallest length of the operands, the more complex is considered to be larger. More precisely, the longest is the largest; when lengths are equal, we have matrix " > " vector " > " scalar. For example:

  ? lex([1,3], [1,2,5])
  %1 = 1
  ? lex([1,3], [1,3,-1])
  %2 = -1
  ? lex([1], [[1]])
  %3 = -1
  ? lex([1], [1]~)
  %4 = 0

The library syntax is lexcmp"(x,y)".

sign"(x)"

The library syntax is gsigne"(x)". The result is a "long".

max"(x,y)" and " min(x,y)"

The library syntax is gmax"(x,y)" and " gmin(x,y)".

vecmax"(x)"

The library syntax is vecmax"(x)".

vecmin"(x)"

The library syntax is vecmin"(x)".

Col"({x = []})"

The library syntax is gtocol"(x)".

List"({x = []})"

This is useless in library mode.

Mat"({x = []})"

    ? Mat(x + 1)
    %1 =
    [x + 1]
    ? Vec( matid(3) )
    %2 = [[1, 0, 0]~, [0, 1, 0]~, [0, 0, 1]~]
    ? Mat(%)
    %3 =
    [1 0 0]

    [0 1 0]

    [0 0 1]
    ? Col( [1,2; 3,4] )
    %4 = [[1, 2], [3, 4]]~
    ? Mat(%)
    %5 =
    [1 2]

    [3 4]

The library syntax is gtomat"(x)".

Mod"(x,y,{flag = 0})"

This function is not the same as "x" "%" "y", the result of which is an integer or a polynomial.

"flag" is obsolete and should not be used.

The library syntax is gmodulo"(x,y)".

Pol"(x,{v = x})"

Warning: this is \emph{not} a substitution function. It will not transform an object containing variables of higher priority than "v".

  ? Pol(x + y, y)
    *** Pol: variable must have higher priority in gtopoly.

The library syntax is gtopoly"(x,v)", where "v" is a variable number.

Polrev"(x,{v = x})"

The library syntax is gtopolyrev"(x,v)", where "v" is a variable number.

Qfb"(a,b,c,{D = 0.})"

The library syntax is Qfb0"(a,b,c,D, prec)". Also available are " qfi(a,b,c)" (when "b^2-4ac < 0"), and " qfr(a,b,c,d)" (when "b^2-4ac > 0").

Ser"(x,{v = x})"

The warning given for "Pol" also applies here: this is not a substitution function.

The library syntax is gtoser"(x,v)", where "v" is a variable number (i.e. a C integer).

Set"({x = []})"

The library syntax is gtoset"(x)".

Str"({x}*)"

  ? x2 = 0; i = 2; Str(x, i)
  %1 = "x2"
  ? eval(%)
  %2 = 0

This function is mostly useless in library mode. Use the pair "strtoGEN"/"GENtostr" to convert between "GEN" and "char*". The latter returns a malloced string, which should be freed after usage.

Strchr"(x)"

  ? Strchr(97)
  %1 = "a"
  ? Vecsmall("hello world")
  %2 = Vecsmall([104, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100])
  ? Strchr(%)
  %3 = "hello world"

Strexpand"({x}*)"

  ? Strexpand("$HOME/doc")
  %1 = "/home/pari/doc"

The individual arguments are read in string context, see "Label se:strings".

Strtex"({x}*)"

The individual arguments are read in string context, see "Label se:strings".

Vec"({x = []})"

The library syntax is gtovec"(x)".

Vecsmall"({x = []})"

The library syntax is gtovecsmall"(x)".

binary"(x)"

The library syntax is binaire"(x)".

bitand"(x,y)"

  "sum_i (x_i and y_i) 2^i"

Negative numbers behave 2-adically, i.e. the result is the 2-adic limit of "bitand""(x_n,y_n)", where "x_n" and "y_n" are non-negative integers tending to "x" and "y" respectively. (The result is an ordinary integer, possibly negative.)

  ? bitand(5, 3)
  %1 = 1
  ? bitand(-5, 3)
  %2 = 3
  ? bitand(-5, -3)
  %3 = -7

The library syntax is gbitand"(x,y)".

bitneg"(x,{n = -1})"

  "sum_{i = 0}^{n-1} not(x_i) 2^i"

The special case "n = -1" means no truncation: an infinite sequence of leading 1 is then represented as a negative number.

See "Label se:bitand" for the behaviour for negative arguments.

The library syntax is gbitneg"(x)".

bitnegimply"(x,y)"

  "sum (x_i and not(y_i)) 2^i"

See "Label se:bitand" for the behaviour for negative arguments.

The library syntax is gbitnegimply"(x,y)".

bitor"(x,y)"

  "sum (x_i or y_i) 2^i"

See "Label se:bitand" for the behaviour for negative arguments.

The library syntax is gbitor"(x,y)".

bittest"(x,n)"

The library syntax is bittest"(x,n)", where "n" and the result are "long"s.

bitxor"(x,y)"

  "sum (x_i xor y_i) 2^i"

See "Label se:bitand" for the behaviour for negative arguments.

The library syntax is gbitxor"(x,y)".

ceil"(x)"

The library syntax is gceil"(x)".

centerlift"(x,{v})"

The library syntax is centerlift0"(x,v)", where "v" is a "long" and an omitted "v" is coded as "-1". Also available is " centerlift(x)" = "centerlift0(x,-1)".

changevar"(x,y)"

The library syntax is changevar"(x,y)".

components of a PARI object

The first and most general, is the function " component(x,n)" which extracts the "n^{th}"-component of "x". This is to be understood as follows: every PARI type has one or two initial code words. The components are counted, starting at 1, after these code words. In particular if "x" is a vector, this is indeed the "n^{th}"-component of "x", if "x" is a matrix, the "n^{th}" column, if "x" is a polynomial, the "n^{th}" coefficient (i.e. of degree "n-1"), and for power series, the "n^{th}" significant coefficient. The use of the function "component" implies the knowledge of the structure of the different PARI types, which can be recalled by typing "\t" under "gp".

The library syntax is compo"(x,n)", where "n" is a "long".

The two other methods are more natural but more restricted. The function " polcoeff(x,n)" gives the coefficient of degree "n" of the polynomial or power series "x", with respect to the main variable of "x" (to check variable ordering, or to change it, use the function "reorder", see "Label se:reorder"). In particular if "n" is less than the valuation of "x" or in the case of a polynomial, greater than the degree, the result is zero (contrary to "compo" which would send an error message). If "x" is a power series and "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 "x", and the meaning is then identical with that of "compo".

Finally note that a scalar type is considered by "polcoeff" as a polynomial of degree zero.

The library syntax is truecoeff"(x,n)".

The third method is specific to vectors or matrices in GP. If "x" is a (row or column) vector, then "x[n]" represents the "n^{th}" component of "x", i.e. "compo(x,n)". It is more natural and shorter to write. If "x" is a matrix, "x[m,n]" represents the coefficient of row "m" and column "n" of the matrix, "x[m,]" represents the "m^{th}" \emph{row} of "x", and "x[,n]" represents the "n^{th}" \emph{column} of "x".

Finally note that in library mode, the macros gcoeff and gmael are available as direct accessors to a "GEN component". See Chapter 4 for details.

conj"(x)"

The library syntax is gconj"(x)".

conjvec"(x)"

The library syntax is conjvec"(x, prec)".

denominator"(x)"

      denominator( content(x) )

instead. As for modular objects, "t_INTMOD" and "t_PADIC" have denominator 1, and the denominator of a "t_POLMOD" is the denominator of its (minimal degree) polynomial representative.

If "x" is a recursive structure, for instance a vector or matrix, the lcm of the denominators of its components (a common denominator) is computed. This also applies for "t_COMPLEX"s and "t_QUAD"s.

Warning: multivariate objects are created according to variable priorities, with possibly surprising side effects ("x/y" is a polynomial, but "y/x" is a rational function). See "Label se:priority".

The library syntax is denom"(x)".

floor"(x)"

The library syntax is gfloor"(x)".

frac"(x)"

The library syntax is gfrac"(x)".

imag"(x)"

The library syntax is gimag"(x)". This returns a copy of the imaginary part. The internal routine "imag_i" is faster, since it returns the pointer and skips the copy.

length"(x)"

The library syntax is glength"(x)" and the result is a C long.

lift"(x,{v})"

  ? lift(Mod(5,3))
  %1 = 2
  ? lift(3 + O(3^9))
  %2 = 3
  ? lift(Mod(x,x^2+1))
  %3 = x
  ? lift(x * Mod(1,3) + Mod(2,3))
  %4 = x + 2
  ? lift(x * Mod(y,y^2+1) + Mod(2,3))
  %5 = y*x + Mod(2, 3)   \\ do you understand this one ?
  ? lift(x * Mod(y,y^2+1) + Mod(2,3), x)
  %6 = Mod(y, y^2+1) * x + Mod(2, y^2+1)

The library syntax is lift0"(x,v)", where "v" is a "long" and an omitted "v" is coded as "-1". Also available is " lift(x)" = "lift0(x,-1)".

norm"(x)"

The library syntax is gnorm"(x)".

norml2"(x)"

  ? norml2( [ 1, 2, 3 ] )      \\ vector
  %1 = 14
  ? norml2( [ 1, 2; 3, 4] )   \\ matrix
  %1 = 30
  ? norml2( I + x )
  %3 = x^2 + 1
  ? norml2( [ [1,2], [3,4], 5, 6 ] )   \\ recursively defined
  %4 = 91

The library syntax is gnorml2"(x)".

numerator"(x)"

      numerator( content(x) )

instead.

In other cases, numerator(x) is defined to be "denominator(x)*x". This is the case when "x" is a vector or a matrix, but also for "t_COMPLEX" or "t_QUAD". In particular since a "t_PADIC" or "t_INTMOD" has denominator 1, its numerator is itself.

Warning: multivariate objects are created according to variable priorities, with possibly surprising side effects ("x/y" is a polynomial, but "y/x" is a rational function). See "Label se:priority".

The library syntax is numer"(x)".

numtoperm"(n,k)"

The library syntax is numtoperm"(n,k)", where "n" is a "long".

padicprec"(x,p)"

The library syntax is padicprec"(x,p)" and the result is a "long" integer.

permtonum"(x)"

The library syntax is permtonum"(x)".

precision"(x,{n})"

For exact types, no change. For "x" a vector or a matrix, the operation is done componentwise.

For real "x", "n" is the number of desired significant \emph{decimal} digits. If "n" is smaller than the precision of "x", "x" is truncated, otherwise "x" is extended with zeros.

For "x" a "p"-adic or a power series, "n" is the desired number of significant "p"-adic or "X"-adic digits, where "X" is the main variable of "x".

Note that the function "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 "truncate".

The library syntax is precision0"(x,n)", where "n" is a "long". Also available are " ggprecision(x)" (result is a "GEN") and " gprec(x,n)", where "n" is a "long".

random"({N = 2^{31}})"

The resulting integer is obtained by means of linear congruences and will not be well distributed in arithmetic progressions. The random seed may be obtained via "getrand", and reset using "setrand".

Note that "random(2^31)" is \emph{not} equivalent to "random()", although both return an integer between 0 and "2^{31}-1". In fact, calling "random" with an argument generates a number of random words (32bit or 64bit depending on the architecture), rescaled to the desired interval. The default uses directly a 31-bit generator.

Important technical note: the implementation of this function is incorrect unless "N" is a power of 2 (integers less than the bound are not equally likely, some may not even occur). It is kept for backward compatibility only, and has been rewritten from scratch in the 2.4.x unstable series. Use the following script for a correct version:

  RANDOM(N) = 
  { local(n, L);

    L = 1; while (L < N, L <<= 1;);
    /* L/2 < N <= L, L power of 2 */
    until(n < N, n = random(L)); n
  }

The library syntax is genrand"(N)". Also available are "pari_rand""()" which returns a random "unsigned long" (32bit or 64bit depending on the architecture), and "pari_rand31""()" which returns a 31bit "long" integer.

real"(x)"

The library syntax is greal"(x)". This returns a copy of the real part. The internal routine "real_i" is faster, since it returns the pointer and skips the copy.

round"(x,{&e})"

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

  "truncate((2.4*X^2-1.7)/(X)) = 2.4*X,"

whereas

  "round((2.4*X^2-1.7)/(X)) = (2*X^2-2)/(X)."

An important use of "round" is to get exact results after a long approximate computation, when theory tells you that the coefficients must be integers.

The library syntax is grndtoi"(x,&e)", where "e" is a "long" integer. Also available is " ground(x)".

simplify"(x)"

This function is especially useful before using arithmetic functions, which expect integer arguments:

  ? x = 1 + y - y
  %1 = 1
  ? divisors(x)
    *** divisors: not an integer argument in an arithmetic function
  ? type(x)
  %2 = "t_POL"
  ? type(simplify(x))
  %3 = "t_INT"

Note that GP results are simplified as above before they are stored in the history. (Unless you disable automatic simplification with "\y", that is.) In particular

  ? type(%1)
  %4 = "t_INT"

The library syntax is simplify"(x)".

sizebyte"(x)"

The library syntax is taille2"(x)" which returns a "long"; " taille(x)" returns the number of \emph{words} instead.

sizedigit"(x)"

The library syntax is sizedigit"(x)" which returns a "long".

truncate"(x,{&e})"

Note a very special use of "truncate": when applied to a power series, it transforms it into a polynomial or a rational function with denominator a power of "X", by chopping away the "O(X^k)". Similarly, when applied to a "p"-adic number, it transforms it into an integer or a rational number by chopping away the "O(p^k)".

The library syntax is gcvtoi"(x,&e)", where "e" is a "long" integer. Also available is " gtrunc(x)".

valuation"(x,p)"

If "p" is of type polynomial, "x" must be of type polynomial or rational function, and also a power series if "x" is a monomial. Finally, the valuation of a vector, complex or quadratic number is the minimum of the component valuations.

If "x = 0", the result is "VERYBIGINT" ("2^{31}-1" for 32-bit machines or "2^{63}-1" for 64-bit machines) if "x" is an exact object. If "x" is a "p"-adic numbers or power series, the result is the exponent of the zero. Any other type combinations gives an error.

The library syntax is ggval"(x,p)", and the result is a "long".

variable"(x)"

The library syntax is gpolvar"(x)". However, in library mode, this function should not be used. Instead, test whether "x" is a "p"-adic (type "t_PADIC"), in which case "p" is in "x[2]", or call the function " gvar(x)" which returns the variable \emph{number} of "x" if it exists, "BIGINT" otherwise.

^

The library syntax is gpow"(x,y, prec)".

Euler

The library syntax is mpeuler"( prec)" where " prec" \emph{must} be given. Note that this creates "gamma" on the PARI stack, but a copy is also created on the heap for quicker computations next time the function is called.

I

The library syntax is the global variable "gi" (of type "GEN").

Pi

The library syntax is mppi"(prec)" where "prec" \emph{must} be given. Note that this creates "Pi" on the PARI stack, but a copy is also created on the heap for quicker computations next time the function is called.

abs"(x)"

  ? abs(-1)
  %1 = 1
  ? abs(3/7 + 4/7*I)
  %2 = 5/7
  ? abs(1 + I)
  %3 = 1.414213562373095048801688724

If "x" is a polynomial, returns "-x" if the leading coefficient is real and negative else returns "x". For a power series, the constant coefficient is considered instead.

The library syntax is gabs"(x,prec)".

acos"(x)"

The library syntax is gacos"(x, prec)".

acosh"(x)"

The library syntax is gach"(x,prec)".

agm"(x,y)"

The library syntax is agm"(x,y, prec)".

arg"(x)"

The library syntax is garg"(x,prec)".

asin"(x)"

The library syntax is gasin"(x, prec)".

asinh"(x)"

The library syntax is gash"(x,prec)".

atan"(x)"

The library syntax is gatan"(x, prec)".

atanh"(x)"

The library syntax is gath"(x,prec)".

bernfrac"(x)"

The library syntax is bernfrac"(x)".

bernreal"(x)"

The library syntax is bernreal"(x, prec)".

bernvec"(x)"

Note: this routine is implemented using repeated independent calls to "bernfrac", which is faster than the standard recursion in exact arithmetic. It is only kept for backward compatibility: it is not faster than individual calls to "bernfrac", its output uses a lot of memory space, and coping with the index shift is awkward.

The library syntax is bernvec"(x)".

besselh1"(nu,x)"

The library syntax is hbessel1"( nu,x, prec)".

besselh2"(nu,x)"

The library syntax is hbessel2"( nu,x, prec)".

besseli"(nu,x)"

The library syntax is ibessel"( nu,x, prec)".

besselj"(nu,x)"

The library syntax is jbessel"( nu,x, prec)".

besseljh"(n,x)"

The library syntax is jbesselh"(n,x, prec)".

besselk"(nu,x,{flag = 0})"

The library syntax is kbessel"( nu,x, prec)" and " kbessel2(nu,x,prec)" respectively.

besseln"(nu,x)"

The library syntax is nbessel"( nu,x, prec)".

cos"(x)"

The library syntax is gcos"(x,prec)".

cosh"(x)"

The library syntax is gch"(x,prec)".

cotan"(x)"

The library syntax is gcotan"(x, prec)".

dilog"(x)"

The library syntax is dilog"(x, prec)".

eint1"(x,{n})"

If "n" is present, outputs the "n"-dimensional vector "[eint1(x),...,eint1(nx)]" ("x >= 0"). This is faster than repeatedly calling "eint1(i * x)".

The library syntax is veceint1"(x,n,prec)". Also available is " eint1(x,prec)".

erfc"(x)"

The library syntax is erfc"(x,prec)".

eta"(x,{flag = 0})"

If "flag = 1" and "x" can be converted to a complex number (i.e. is not a power series), computes the true "eta" function, including the leading "q^{1/24}".

The library syntax is eta"(x,prec)".

exp"(x)"

The library syntax is gexp"(x,prec)".

gammah"(x)"

The library syntax is ggamd"(x, prec)".

gamma"(x)"

The library syntax is ggamma"(x, prec)".

hyperu"(a,b,x)"

The library syntax is hyperu"(a,b,x, prec)".

incgam"(s,x,{y})"

The library syntax is incgam"(s,x, prec)" and " incgam0(s,x,y,prec)", respectively (an omitted "y" is coded as "NULL").

incgamc"(s,x)"

The library syntax is incgamc"(s,x, prec)".

log"(x)"

  " log (x) ~ (Pi)/(2agm(1, 4/s)) - m log 2, "

if "s = x 2^m" is large enough. (The result is exact to "B" bits provided "s > 2^{B/2}".) At low accuracies, the series expansion near 1 is used.

"p"-adic arguments are also accepted for "x", with the convention that " log (p) = 0". Hence in particular " exp ( log (x))/x" is not in general equal to 1 but to a "(p-1)"-th root of unity (or "+-1" if "p = 2") times a power of "p".

The library syntax is glog"(x,prec)".

lngamma"(x)"

The library syntax is glngamma"(x, prec)".

polylog"(m,x,{flag = 0})"

If "flag = 0" or is omitted: "m^th" polylogarithm of "x", i.e. analytic continuation of the power series "Li_m(x) = sum_{n >= 1}x^n/n^m" ("x < 1"). Uses the functional equation linking the values at "x" and "1/x" to restrict to the case "|x| <= 1", then the power series when "|x|^2 <= 1/2", and the power series expansion in " log (x)" otherwise.

Using "flag", computes a modified "m^th" polylogarithm of "x". We use Zagier's notations; let " Re _m" denotes " Re " or " Im " depending whether "m" is odd or even:

If "flag = 1": compute "~ D_m(x)", defined for "|x| <= 1" by

  " Re _m(sum_{k = 0}^{m-1} ((- log |x|)^k)/(k!)Li_{m-k}(x) +((- log |x|)^{m-1})/(m!) log |1-x|)."

If "flag = 2": compute D_m(x), defined for "|x| <= 1" by

  " Re _m(sum_{k = 0}^{m-1}((- log |x|)^k)/(k!)Li_{m-k}(x) -(1)/(2)((- log |x|)^m)/(m!))."

If "flag = 3": compute P_m(x), defined for "|x| <= 1" by

  " Re _m(sum_{k = 0}^{m-1}(2^kB_k)/(k!)( log |x|)^kLi_{m-k}(x) -(2^{m-1}B_m)/(m!)( log |x|)^m)."

These three functions satisfy the functional equation "f_m(1/x) = (-1)^{m-1}f_m(x)".

The library syntax is polylog0"(m,x, flag,prec)".

psi"(x)"

The library syntax is gpsi"(x,prec)".

sin"(x)"

The library syntax is gsin"(x,prec)".

sinh"(x)"

The library syntax is gsh"(x,prec)".

sqr"(x)"

  ? (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 \emph{identical}, e.g. 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 %2 and %3 above).

The library syntax is gsqr"(x)".

sqrt"(x)"

Intmod a prime and "p"-adics are allowed as arguments. In that case, the square root (if it exists) which is returned is the one whose first "p"-adic digit (or its unique "p"-adic digit in the case of intmods) is in the interval "[0,p/2]". When the argument is an intmod a non-prime (or a non-prime-adic), the result is undefined.

The library syntax is gsqrt"(x, prec)".

sqrtn"(x,n,{&z})"

If "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. In the case this argument is present and no square root exist, 0 is returned instead or raising an error.

  ? sqrtn(Mod(2,7), 2)
  %1 = Mod(4, 7)
  ? sqrtn(Mod(2,7), 2, &z); z
  %2 = Mod(6, 7)
  ? sqrtn(Mod(2,7), 3)
    *** sqrtn: nth-root does not exist in gsqrtn.
  ? sqrtn(Mod(2,7), 3,  &z)
  %2 = 0
  ? z
  %3 = 0

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");

The library syntax is gsqrtn"(x,n,&z,prec)".

tan"(x)"

The library syntax is gtan"(x,prec)".

tanh"(x)"

The library syntax is gth"(x,prec)".

teichmuller"(x)"

The library syntax is teich"(x)".

theta"(q,z)"

The library syntax is theta"(q,z, prec)".

thetanullk"(q,k)"

The library syntax is thetanullk"(q,k,prec)", where "k" is a "long".

weber"(x,{flag = 0})"

  "f(x) = exp (-iPi/24). eta((x+1)/2)/eta(x) such that j = (f^{24}-16)^3/f^{24},"

where "j" is the elliptic "j"-invariant (see the function "ellj"). If "flag = 1", returns

  "f_1(x) = eta(x/2)/eta(x) such that j = (f_1^{24}+16)^3/f_1^{24}."

Finally, if "flag = 2", returns

  "f_2(x) = sqrt {2}eta(2x)/eta(x) such that j = (f_2^{24}+16)^3/f_2^{24}."

Note the identities "f^8 = f_1^8+f_2^8" and "ff_1f_2 = sqrt 2".

The library syntax is weber0"(x, flag,prec)". Associated to the various values of flag, the following functions are also available: " werberf(x,prec)", " werberf1(x,prec)" or " werberf2(x,prec)".

zeta"(s)"

For "s" a "p"-adic number, Kubota-Leopoldt zeta function at "s", that is the unique continuous "p"-adic function on the "p"-adic integers that interpolates the values of "(1 - p^{-k}) zeta(k)" at negative integers "k" such that "k = 1 (mod p-1)" (resp. "k" is odd) if "p" is odd (resp. "p = 2").

The library syntax is gzeta"(s, prec)".

addprimes"({x = []})"

The entries in "x" are not checked for primality, and in fact they need only be positive integers. The algorithm makes sure that all elements in the table are pairwise coprime, so it may end up containing divisors of the input integers.

It is a useful trick to add known composite numbers, which the function "factor(x,0)" was not able to factor. In case the message ``impossible inverse modulo "<"some INTMOD">"'' shows up afterwards, you have just stumbled over a non-trivial factor. Note that the arithmetic functions in the narrow sense, like eulerphi, do \emph{not} use this extra table.

To remove primes from the list use "removeprimes".

The library syntax is addprimes"(x)".

bestappr"(x,A,{B})"

If "B" is present, "x" is assumed to be of type "t_INTMOD" modulo "M" (or a recursive combination of those), and the routine returns the unique fraction "a/b" in coprime integers "a <= A" and "b <= B" which is congruent to "x" modulo "M". If "M <= 2AB", uniqueness is not guaranteed and the function fails with an error message. If rational reconstruction is not possible (no such "a/b" exists for at least one component of "x"), returns "-1".

The library syntax is bestappr0"(x,A,B)". Also available is " bestappr(x,A)" corresponding to an omitted "B".

bezout"(x,y)"

The library syntax is vecbezout"(x,y)" to get the vector, or " 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 "u" and "v".

bezoutres"(x,y)"

The library syntax is vecbezoutres"(x,y)" to get the vector, or " 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 "u" and "v".

bigomega"(x)"

The library syntax is bigomega"(x)", the result is a "long".

binomial"(x,y)"

The library syntax is binomial"(x,y)", where "y" must be a "long".

chinese"(x,{y})"

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.

If "y" is omitted, and "x" is a vector, "chinese" is applied recursively to the components of "x", yielding a residue belonging to the same class as all components of "x".

Finally "chinese(x,x) = x" regardless of the type of "x"; this allows vector arguments to contain other data, so long as they are identical in both vectors.

The library syntax is chinese"(x,y)". Also available is "chinese1""(x)", corresponding to an ommitted "y".

content"(x)"

      ? content(2*x+y)
      %1 = 1            \\ = gcd(2,y) over Q[y]

If "x" is a scalar, this simply returns the absolute value of "x" if "x" is rational ("t_INT" or "t_FRAC"), and either 1 (inexact input) or "x" (exact input) otherwise; the result should be identical to "gcd(x, 0)".

The content of a rational function is the ratio of the contents of the numerator and the denominator. In recursive structures, if a matrix or vector \emph{coefficient} "x" appears, the gcd is taken not with "x", but with its content:

      ? content([ [2], 4*matid(3) ])
      %1 = 2

The library syntax is content"(x)".

contfrac"(x,{b},{nmax})"

The number of partial quotients "n" is limited to "nmax". If "x" is a real number, the expansion stops at the last significant partial quotient if "nmax" is omitted. "x" can also be a rational function or a power series.

If a vector "b" is supplied, the numerators will be equal to the coefficients of "b" (instead of all equal to 1 as above). The length of the result is then equal to the length of "b", unless a partial remainder is encountered which is equal to zero, in which case the expansion stops. In the case of real numbers, the stopping criterion is thus different from the one mentioned above since, if "b" is too long, some partial quotients may not be significant.

If "b" is an integer, the command is understood as "contfrac(x,nmax)".

The library syntax is contfrac0"(x,b,nmax)". Also available are " gboundcf(x,nmax)", " gcf(x)", or " gcf2(b,x)", where "nmax" is a C integer.

contfracpnqn"(x)"

The library syntax is pnqn"(x)".

core"(n,{flag = 0})"

The library syntax is core0"(n, flag)". Also available are " core(n)" ( = " core0(n,0)") and " core2(n)" ( = " core0(n,1)").

coredisc"(n,{flag})"

The library syntax is coredisc0"(n, flag)". Also available are " coredisc(n)" ( = " coredisc(n,0)") and " coredisc2(n)" ( = " coredisc(n,1)").

dirdiv"(x,y)"

The library syntax is dirdiv"(x,y)".

direuler"(p = a,b,expr,{c})"

The series is output as a vector of coefficients. If "c" is present, output only the first "c" coefficients in the series. The following command computes the sigma function, associated to "zeta(s)zeta(s-1)":

  ? direuler(p=2, 10, 1/((1-X)*(1-p*X)))
  %1 = [1, 3, 4, 7, 6, 12, 8, 15, 13, 18]

The library syntax is direuler"(void *E, GEN (*eval)(GEN,void*), GEN a, GEN b)"

dirmul"(x,y)"

The library syntax is dirmul"(x,y)".

divisors"(x)"

By definition, these divisors are the products of the irreducible factors of "n", as produced by factor(n), raised to appropriate powers (no negative exponent may occur in the factorization). If "n" is an integer, they are the positive divisors, in increasing order.

The library syntax is divisors"(x)".

eulerphi"(x)"

The library syntax is phi"(x)".

factor"(x,{lim = -1})"

If "x" is of type integer or rational, the factors are pseudoprimes (see "ispseudoprime"), and in general not rigorously proven primes. In fact, any factor which is " <= 10^{13}" is a genuine prime number. Use "isprime" to prove primality of other factors, as in

  fa = factor(2^2^7 +1)
  isprime( fa[,1] )

An argument lim can be added, meaning that we look only for prime factors "p < lim", or up to "primelimit", whichever is lowest (except when "lim = 0" where the effect is identical to setting "lim = primelimit"). In this case, the remaining part may actually be a proven composite! See "factorint" for more information about the algorithms used.

The polynomials or rational functions to be factored must have scalar coefficients. In particular PARI does \emph{not} know how to factor multivariate polynomials. See "factormod" and "factorff" for the algorithms used over finite fields, "factornf" for the algorithms over number fields. Over Q, van Hoeij's method is used, which is able to cope with hundreds of modular factors.

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 needed, 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 "factornf" and "nffactor".

The library syntax is factor0"(x, lim)", where lim is a C integer. Also available are " factor(x)" ( = " factor0(x,-1)"), " smallfact(x)" ( = " factor0(x,0)").

factorback"(f,{e},{nf})"

If "e" is present, "e" and "f" must be vectors of the same length ("e" being integral), and the corresponding factorization is the product of the "f[i]^{e[i]}".

If not, and "f" is vector, it is understood as in the preceding case with "e" a vector of 1 (the product of the "f[i]" is returned). Finally, "f" can be a regular factorization, as produced with any "factor" command. A few examples:

  ? factorback([2,2; 3,1])
  %1 = 12
  ? factorback([2,2], [3,1])
  %2 = 12
  ? factorback([5,2,3])
  %3 = 30
  ? factorback([2,2], [3,1], nfinit(x^3+2))
  %4 =
  [16 0 0]

  [0 16 0]

  [0 0 16]
  ? nf = nfinit(x^2+1); fa = idealfactor(nf, 10)
  %5 =
  [[2, [1, 1]~, 2, 1, [1, 1]~] 2]

  [[5, [-2, 1]~, 1, 1, [2, 1]~] 1]

  [[5, [2, 1]~, 1, 1, [-2, 1]~] 1]
  ? factorback(fa)
    ***   forbidden multiplication t_VEC * t_VEC.
  ? factorback(fa, nf)
  %6 =
  [10 0]

  [0 10]

In the fourth example, 2 and 3 are interpreted as principal ideals in a cubic field. In the fifth one, "factorback(fa)" is meaningless since we forgot to indicate the number field, and the entries in the first column of "fa" can't be multiplied.

The library syntax is factorback0"(f,e,nf)", where an omitted "nf" or "e" is entered as "NULL". Also available is "factorback""(f,nf)" (case "e = NULL") where an omitted "nf" is entered as "NULL".

factorcantor"(x,p)"

The library syntax is factcantor"(x,p)".

factorff"(x,p,a)"

The library syntax is factorff"(x,p,a)".

factorial"(x)" or "x!"

The library syntax is mpfact"(x)" for "x!" and " mpfactr(x,prec)" for factorial(x). "x" must be a "long" integer and not a PARI integer.

factorint"(n,{flag = 0})"

This gives direct access to the integer factoring engine called by most arithmetical functions. 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.

You are invited to play with the flag settings and watch the internals at work by using "gp"'s "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.

The library syntax is factorint"(n, flag)".

factormod"(x,p,{flag = 0})"

The library syntax is factormod"(x,p, flag)". Also available are " factmod(x,p)" (which is equivalent to " factormod(x,p,0)") and " simplefactmod(x,p)" ( = " factormod(x,p,1)").

fibonacci"(x)"

The library syntax is fibo"(x)". "x" must be a "long".

ffinit"(p,n,{v = x})"

The library syntax is ffinit"(p,n,v)", where "v" is a variable number.

gcd"(x,{y})"

When "x" and "y" are both given and one of them is a vector/matrix type, the GCD is again taken recursively on each component, but in a different way. If "y" is a vector, resp. matrix, then the result has the same type as "y", and components equal to "gcd(x, y[i])", resp. "gcd(x, y[,i])". Else if "x" is a vector/matrix the result has the same type as "x" and an analogous definition. Note that for these types, "gcd" is not commutative.

The algorithm used is a naive Euclid except for the following inputs:

\item integers: use modified right-shift binary (``plus-minus'' variant).

\item univariate polynomials with coeffients in the same number field (in particular rational): use modular gcd algorithm.

\item general polynomials: use the subresultant algorithm if coefficient explosion is likely (exact, non modular, coefficients).

The library syntax is ggcd"(x,y)". For general polynomial inputs, " srgcd(x,y)" is also available. For univariate \emph{rational} polynomials, one also has " modulargcd(x,y)".

hilbert"(x,y,{p})"

The library syntax is hil"(x,y,p)".

isfundamental"(x)"

The library syntax is gisfundamental"(x)", but the simpler function " isfundamental(x)" which returns a "long" should be used if "x" is known to be of type integer.

ispower"(x,{k}, {&n})"

If "k" is omitted, only integers and fractions are allowed and the function returns the maximal "k >= 2" such that "x = n^k" is a perfect power, or 0 if no such "k" exist; in particular "ispower(-1)", ispower(0), and ispower(1) all return 0.

If a third argument &n is given and a "k"-th root was computed in the process, then "n" is set to that root.

The library syntax is ispower"(x, k, &n)", the result is a "long". Omitted "k" or "n" are coded as "NULL".

isprime"(x,{flag = 0})"

If "flag = 0", use a combination of Baillie-PSW pseudo primality test (see "ispseudoprime"), Selfridge ``"p-1"'' test if "x-1" is smooth enough, and Adleman-Pomerance-Rumely-Cohen-Lenstra (APRCL) for general "x".

If "flag = 1", use Selfridge-Pocklington-Lehmer ``"p-1"'' test and output a primality certificate as follows: return 0 if "x" is composite, 1 if "x" is small enough that passing Baillie-PSW test guarantees its primality (currently "x < 10^{13}"), 2 if "x" is a large prime whose primality could only sensibly be proven (given the algorithms implemented in PARI) using the APRCL test. Otherwise ("x" is large and "x-1" is smooth) output a three column matrix as a primality certificate. The first column contains the prime factors "p" of "x-1", the second the corresponding elements "a_p" as in Proposition 8.3.1 in GTM 138, and the third the output of isprime(p,1). The algorithm fails if one of the pseudo-prime factors is not prime, which is exceedingly unlikely (and well worth a bug report).

If "flag = 2", use APRCL.

The library syntax is gisprime"(x, flag)", but the simpler function " isprime(x)" which returns a "long" should be used if "x" is known to be of type integer.

ispseudoprime"(x,{flag})"

If "flag = 0", checks whether "x" is a Baillie-Pomerance-Selfridge-Wagstaff pseudo prime (strong Rabin-Miller pseudo prime for base 2, followed by strong Lucas test for the sequence "(P,-1)", "P" smallest positive integer such that "P^2 - 4" is not a square mod "x").

There are no known composite numbers passing this test (in particular, all composites " <= 10^{13}" are correctly detected), although it is expected that infinitely many such numbers exist.

If "flag > 0", checks whether "x" is a strong Miller-Rabin pseudo prime for "flag " randomly chosen bases (with end-matching to catch square roots of "-1").

The library syntax is gispseudoprime"(x,flag)", but the simpler function " ispseudoprime(x)" which returns a "long" should be used if "x" is known to be of type integer.

issquare"(x,{&n})"

      ? issquare(3)          \\ as an integer
      %1 = 0
      ? issquare(3.)         \\ as a real number
      %2 = 1
      ? issquare(Mod(7, 8))  \\ in Z/8Z
      %3 = 0
      ? issquare( 5 + O(13^4) )  \\ in Q_13
      %4 = 0

If "n" is given and an exact square root had to be computed in the checking process, puts that square root in "n". This is the case when "x" is a "t_INT", "t_FRAC", "t_POL" or "t_RFRAC" (or a vector of such objects):

      ? issquare(4, &n)
      %1 = 1
      ? n
      %2 = 2
      ? issquare([4, x^2], &n)
      %3 = [1, 1]  \\ both are squares
      ? n
      %4 = [2, x]  \\ the square roots

This will \emph{not} work for "t_INTMOD" (use quadratic reciprocity) or "t_SER" (only check the leading coefficient).

The library syntax is gissquarerem"(x,&n)". Also available is " gissquare(x)".

issquarefree"(x)"

The library syntax is gissquarefree"(x)", but the simpler function " issquarefree(x)" which returns a "long" should be used if "x" is known to be of type integer. This issquarefree is just the square of the Moebius function, and is computed as a multiplicative arithmetic function much like the latter.

kronecker"(x,y)"

\item "(x|0) = 1" if "|x |= 1" and 0 otherwise.

\item "(x|-1) = 1" if "x >= 0" and "-1" otherwise.

\item "(x|2) = 0" if "x" is even and 1 if "x = 1,-1 mod 8" and "-1" if "x = 3,-3 mod 8".

The library syntax is kronecker"(x,y)", the result (0 or "+- 1") is a "long".

lcm"(x,{y})"

When "x" and "y" are both given and one of them is a vector/matrix type, the LCM is again taken recursively on each component, but in a different way. If "y" is a vector, resp. matrix, then the result has the same type as "y", and components equal to "lcm(x, y[i])", resp. "lcm(x, y[,i])". Else if "x" is a vector/matrix the result has the same type as "x" and an analogous definition. Note that for these types, "lcm" is not commutative.

Note that lcm(v) is quite different from

      l = v[1]; for (i = 1, #v, l = lcm(l, v[i]))

Indeed, lcm(v) is a scalar, but "l" may not be (if one of the "v[i]" is a vector/matrix). The computation uses a divide-conquer tree and should be much more efficient, especially when using the GMP multiprecision kernel (and more subquadratic algorithms become available):

      ? v = vector(10^4, i, random);
      ? lcm(v);
      time = 323 ms.
      ? l = v[1]; for (i = 1, #v, l = lcm(l, v[i]))
      time = 833 ms.

The library syntax is glcm"(x,y)".

moebius"(x)"

The library syntax is mu"(x)", the result (0 or "+- 1") is a "long".

nextprime"(x)"

The library syntax is nextprime"(x)".

numdiv"(x)"

The library syntax is numbdiv"(x)".

numbpart"(n)"

The library syntax is numbpart"(n)".

omega"(x)"

The library syntax is omega"(x)", the result is a "long".

precprime"(x)"

The library syntax is precprime"(x)".

prime"(x)"

The library syntax is prime"(x)". "x" must be a "long".

primepi"(x)"

The library syntax is primepi"(x)".

primes"(x)"

The library syntax is primes"(x)". "x" must be a "long".

qfbclassno"(D,{flag = 0})"

If "flag = 1", compute the class number using Euler products and the functional equation. However, it is in "O(|D|^{1/2})".

Important warning. For "D < 0", this function may give incorrect results when the class group has a low exponent (has many cyclic factors), because implementing Shanks's method in full generality slows it down immensely. It is therefore strongly recommended to double-check results using either the version with "flag = 1" or the function "quadclassunit".

Warning. contrary to what its name implies, this routine does not compute the number of classes of binary primitive forms of discriminant "D", which is equal to the \emph{narrow} class number. The two notions are the same when "D < 0" or the fundamental unit "varepsilon" has negative norm; when "D > 0" and "Nvarepsilon > 0", the number of classes of forms is twice the ordinary class number. This is a problem which we cannot fix for backward compatibility reasons. Use the following routine if you are only interested in the number of classes of forms:

  QFBclassno(D) =
    qfbclassno(D) * if (D < 0 || norm(quadunit(D)) < 0, 1, 2)

Here are a few examples:

  %2 = 1
  ? qfbclassno(-400000028)
  time = 0 ms.
  %3 = 7253 \{ much faster}
  %2 = 1
  ? qfbclassno(-400000028)
  time = 0 ms.
  %3 = 7253 \{ correct, and fast enough}
  ? quadclassunit(-400000028).no
  time = 0 ms.
  %4 = 7253

The library syntax is qfbclassno0"(D, flag)". Also available: " classno(D)" ( = " qfbclassno(D)"), " classno2(D)" ( = " qfbclassno(D,1)"), and finally we have the function " hclassno(D)" which computes the class number of an imaginary quadratic field by counting reduced forms, an "O(|D|)" algorithm. See also "qfbhclassno".

qfbcompraw"(x,y)"

The library syntax is compraw"(x,y)".

qfbhclassno"(x)"

The library syntax is hclassno"(x)".

qfbnucomp"(x,y,l)"

The current implementation is straightforward and in general \emph{slower} than the generic routine (since the latter take advantadge of asymptotically fast operations and careful optimizations).

The library syntax is nucomp"(x,y,l)". The auxiliary function " nudupl(x,l)" can be used when "x = y".

qfbnupow"(x,n)"

The library syntax is nupow"(x,n)".

qfbpowraw"(x,n)"

The library syntax is powraw"(x,n)" where "n" must be a "long" integer.

qfbprimeform"(x,p)"

The library syntax is primeform"(x,p, prec)", where the third variable "prec" is a "long", but is only taken into account when "x > 0".

qfbred"(x,{flag = 0},{D},{isqrtD},{sqrtD})"

  1: perform a single reduction step

  2: don't update Shanks's distance

"D", isqrtD, sqrtD, if present, supply the values of the discriminant, "\floor{ sqrt {D}}", and " sqrt {D}" respectively (no checking is done of these facts). If "D < 0" these values are useless, and all references to Shanks's distance are irrelevant.

The library syntax is qfbred0"(x, flag,D,isqrtD,sqrtD)". Use "NULL" to omit any of "D", isqrtD, sqrtD.

Also available are

" redimag(x)" ( = " qfbred(x)" where "x" is definite),

and for indefinite forms:

" redreal(x)" ( = " qfbred(x)"),

" rhoreal(x)" ( = " qfbred(x,1)"),

" redrealnod(x,sq)" ( = " qfbred(x,2,,isqrtD)"),

" rhorealnod(x,sq)" ( = " qfbred(x,3,,isqrtD)").

qfbsolve"(Q,p)"

Return "[x,y]" as a two-components vector, or zero if there is no solution. Note that this function returns only one solution and not all the solutions.

Let "D = \disc Q". The algorithm used runs in probabilistic polynomial time in "p" (through the computation of a square root of "D" modulo "p"); it is polynomial time in "D" if "Q" is imaginary, but exponential time if "Q" is real (through the computation of a full cycle of reduced forms). In the latter case, note that "bnfisprincipal" provides a solution in heuristic subexponential time in "D" assuming the GRH.

The library syntax is qfbsolve"(Q,n)".

quadclassunit"(D,{flag = 0},{tech = []})"

This function should be used instead of "qfbclassno" or "quadregula" when "D < -10^{25}", "D > 10^{10}", or when the \emph{structure} is wanted. It is a special case of "bnfinit", which is slower, but more robust.

If "flag" is non-zero \emph{and} "D > 0", computes the narrow class group and regulator, instead of the ordinary (or wide) ones. In the current version 2.2.0, this does not work at all: use the general function "bnfnarrow".

Optional parameter tech is a row vector of the form "[c_1, c_2]", where "c_1 <= c_2" are positive real numbers which control the execution time and the stack size. For a given "c_1", set "c_2 = c_1" to get maximum speed. To get a rigorous result under GRH, you must take "c_2 >= 6". Reasonable values for "c_1" are between 0.1 and 2. More precisely, the algorithm will \emph{assume} that prime ideals of norm less than "c_2 ( log |D|)^2" generate the class group, but the bulk of the work is done with prime ideals of norm less than "c_1 ( log |D|)^2". A larger "c_1" means that relations are easier to find, but more relations are needed and the linear algebra will be harder. The default is "c_1 = c_2 = 0.2", so the result is \emph{not} rigorously proven.

The result is a vector "v" with 3 components if "D < 0", and 4 otherwise. The correspond respectively to

\item "v[1]": the class number

\item "v[2]": a vector giving the structure of the class group as a product of cyclic groups;

\item "v[3]": a vector giving generators of those cyclic groups (as binary quadratic forms).

\item "v[4]": (omitted if "D < 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).

The library syntax is quadclassunit0"(D,flag,tech)". Also available are " buchimag(D,c_1,c_2)" and " buchreal(D,flag,c_1,c_2)".

quaddisc"(x)"

The library syntax is quaddisc"(x)".

quadhilbert"(D,{pq})"

If "D < 0", uses complex multiplication (Schertz's variant). The technical component "pq", if supplied, is a vector "[p,q]" where "p", "q" are the prime numbers needed for the Schertz's method. More precisely, prime ideals above "p" and "q" should be non-principal and coprime to all reduced representatives of the class group. In addition, if one of these ideals has order 2 in the class group, they should have the same class. Finally, for efficiency, "gcd(24,(p-1)(q-1))" should be as large as possible. The routine returns 0 if "[p,q]" is not suitable.

If "D > 0" Stark units are used and (in rare cases) a vector of extensions may be returned whose compositum is the requested class field. See "bnrstark" for details.

The library syntax is quadhilbert"(D,pq,prec)".

quadgen"(D)"

The library syntax is quadgen"(x)".

quadpoly"(D,{v = x})"

The library syntax is quadpoly0"(x,v)".

quadray"(D,f,{lambda})"

For "D < 0", uses the "sigma" function. If supplied, lambda is is the technical element "lambda" of "bnf" necessary for Schertz's method. In that case, returns 0 if "lambda" is not suitable.

For "D > 0", uses Stark's conjecture, and a vector of relative equations may be returned. See "bnrstark" for more details.

The library syntax is quadray"(D,f,lambda,prec)", where an omitted "lambda" is coded as "NULL".

quadregulator"(x)"

The library syntax is regula"(x, prec)".

quadunit"(D)"

The library syntax is fundunit"(x)".

removeprimes"({x = []})"

The library syntax is removeprimes"(x)".

sigma"(x,{k = 1})"

The library syntax is sumdiv"(x)" ( = " sigma(x)") or " gsumdivk(x,k)" ( = " sigma(x,k)"), where "k" is a C long integer.

sqrtint"(x)"

The library syntax is sqrti"(x)". Also available is "sqrtremi""(x,&r)" which returns "s" such that "s^2 = x+r", with "0 <= r <= 2s".

zncoppersmith"(P, N, X, {B = N})"

  "gcd(N, P(x_0)) >= B."

If "N" is prime or a prime power, "polrootsmod" or "polrootspadic" will be much faster. "X" must be smaller than " exp ( log ^2 B / ( deg (P) log N))".

The library syntax is zncoppersmith"(P, N, X, B)", where an omitted "B" is coded as "NULL".

znlog"(x,g)"

The library syntax is znlog"(x,g)".

znorder"(x,{o})"

The library syntax is znorder"(x,o)", where an omitted "o" is coded as "NULL". Also available is " order(x)".

znprimroot"(n)"

The library syntax is gener"(x)".

znstar"(n)"

The library syntax is znstar"(n)".

elladd"(E,z1,z2)"

The library syntax is addell"(E,z1,z2)".

ellak"(E,n)"

The library syntax is akell"(E,n)".

ellan"(E,n)"

The library syntax is anell"(E,n)", where "n" is a C integer.

ellap"(E,p,{flag = 0})"

If "flag" is 1, computes the "a_p" as a sum of Legendre symbols. This is slower than the previous method as soon as "p" is greater than 100, say.

No checking is done that "p" is indeed prime. "E" must be an sell as output by "ellinit", defined over Q, "F _p" or " Q_p". "E" must be given by a Weierstrass equation minimal at "p".

The library syntax is ellap0"(E,p, flag)". Also available are " apell(E,p)", corresponding to "flag = 0", and " apell2(E,p)" ("flag = 1").

ellbil"(E,z1,z2)"

  " ( h(E,z1+z2) - h(E,z1) - h(E,z2) ) / 2 "

where "+" denotes of course addition on "E". In addition, "z1" or "z2" (but not both) can be vectors or matrices.

The library syntax is bilhell"(E,z1,z2,prec)".

ellchangecurve"(E,v)"

The library syntax is coordch"(E,v)".

ellchangepoint"(x,v)"

The library syntax is pointch"(x,v)".

ellconvertname"(name)"

  ? ellconvertname("123b1")
  %1 = [123, 1, 1]
  ? ellconvertname(%)
  %2 = "123b1"

The library syntax is ellconvertname"(name)".

elleisnum"(E,k,{flag = 0})"

  " (2i Pi/omega_2)^k \Big(1 + 2/zeta(1-k) sum_{n >= 0} n^{k-1}q^n / (1-q^n)\Big), "

where "q = e(omega_1/omega_2)".

When flag is non-zero and "k = 4" or 6, returns the elliptic invariants "g_2" or "g_3", such that

  "y^2 = 4x^3 - g_2 x - g_3"

is a Weierstrass equation for "E".

The library syntax is elleisnum"(E,k, flag)".

elleta"(om)"

The library syntax is elleta"(om, prec)"

ellgenerators"(E)"

The library syntax is ellgenerators"(E)".

ellglobalred"(E)"

The library syntax is ellglobalred"(E)".

ellheight"(E,z,{flag = 2})"

The library syntax is ellheight0"(E,z,flag,prec)". Also available are " ghell(E,z,prec)" ("flag = 0") and " ghell2(E,z,prec)" ("flag = 1").

ellheightmatrix"(E,x)"

The library syntax is mathell"(E,x, prec)".

ellidentify"(E)"

The library syntax is ellidentify"(E)".

ellinit"(E,{flag = 0})"

  " Y^2 + a_1 XY + a_3 Y = X^3 + a_2 X^2 + a_4 X + a_6 "

or a string, in this case the coefficients of the curve with matching name are looked in the "elldata" database if available. For the time being, only curves over a prime field "F_p" and over the "p"-adic or real numbers (including rational numbers) are fully supported. Other domains are only supported for very basic operations such as point addition.

The result of "ellinit" is a an ell structure by default, and a shorted sell if "flag = 1". Both contain the following information in their components:

  " a_1,a_2,a_3,a_4,a_6,b_2,b_4,b_6,b_8,c_4,c_6,Delta,j."

All are accessible via member functions. In particular, the discriminant is "E.disc", and the "j"-invariant is "E.j".

The other six components are only present if "flag" is 0 or omitted. Their content depends on whether the curve is defined over R or not:

\item When "E" is defined over R, "E.roots" is a vector whose three components contain the roots of the right hand side of the associated Weierstrass equation.

  " (y + a_1x/2 + a_3/2)^2 = g(x) "

If the roots are all real, then they are ordered by decreasing value. If only one is real, it is the first component.

Then "omega_1 = ""E.omega[1]" is the real period of "E" (integral of "dx/(2y+a_1x+a_3)" over the connected component of the identity element of the real points of the curve), and "omega_2 = ""E.omega[2]" is a complex period. In other words, "E.omega" forms a basis of the complex lattice defining "E", with "tau = (omega_2)/(omega_1)" having positive imaginary part.

"E.eta" is a row vector containing the corresponding values "eta_1" and "eta_2" such that "eta_1omega_2-eta_2omega_1 = iPi".

Finally, "E.area" is the volume of the complex lattice defining "E".

\item When "E" is defined over "Q_p", the "p"-adic valuation of "j" must be negative. Then "E.roots" is the vector with a single component equal to the "p"-adic root of the associated Weierstrass equation corresponding to "-1" under the Tate parametrization.

"E.tate" yields the three-component vector "[u^2,u,q]", in the notations of Tate. If the "u"-component does not belong to "Q_p", it is set to zero.

"E.w" is Mestre's "w" (this is technical).

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.

The library syntax is ellinit0"(E, flag,prec)". Also available are " initell(E,prec)" ("flag = 0") and " smallinitell(E,prec)" ("flag = 1").

ellisoncurve"(E,z)"

The library syntax is ellisoncurve"(E,z)". Also available is " oncurve(E,z)" which returns a "long" but does not accept vector of points.

ellj"(x)"

The library syntax is jell"(x,prec)".

elllocalred"(E,p)"

1 means good reduction (type I"_0"), 2, 3 and 4 mean types II, III and IV respectively, "4+nu" with "nu > 0" means type I"_nu"; finally the opposite values "-1", "-2", etc. refer to the starred types I"_0^*", II"^*", etc. The third component "v" is itself a vector "[u,r,s,t]" giving the coordinate changes done during the local reduction. Normally, this has no use if "u" is 1, that is, if the given equation was already minimal. Finally, the last component "c" is the local Tamagawa number "c_p".

The library syntax is elllocalred"(E,p)".

elllseries"(E,s,{A = 1})"

Note that if the conductor of the curve is large, say greater than "10^{12}", this function will take an unreasonable amount of time since it uses an "O(N^{1/2})" algorithm.

The library syntax is elllseries"(E,s,A,prec)" where "prec" is a "long" and an omitted "A" is coded as "NULL".

ellminimalmodel"(E,{&v})"

The resulting model has integral coefficients, is everywhere minimal, "a_1" is 0 or 1, "a_2" is 0, 1 or "-1" and "a_3" is 0 or 1. Such a model is unique, and the vector "v" is unique if we specify that "u" is positive, which we do.

The library syntax is ellminimalmodel"(E,&v)", where an omitted "v" is coded as "NULL".

ellorder"(E,z)"

The library syntax is orderell"(E,z)".

ellordinate"(E,x)"

The library syntax is ordell"(E,x)".

ellpointtoz"(E,z)"

If "E" has coefficients in "Q_p", then either Tate's "u" is in "Q_p", in which case the output is a "p"-adic number "t" corresponding to the point "z" under the Tate parametrization, or only its square is, in which case the output is "t+1/t". "E" must be an ell as output by "ellinit".

The library syntax is zell"(E,z, prec)".

ellpow"(E,z,n)"

The library syntax is powell"(E,z,n)".

ellrootno"(E,{p = 1})"

The library syntax is ellrootno"(E,p)" and the result (equal to "+-1") is a "long".

ellsigma"(E,z,{flag = 0})"

If "flag = 1", computes an (arbitrary) determination of " log (sigma (z))".

If "flag = 2,3", same using the product expansion instead of theta series. The library syntax is ellsigma"(E,z,flag)"

ellsearch"(N)"

If "N" is a full curve name, the output format is "[N, [a_1,a_2,a_3,a_4,a_6], G]" where "[a_1,a_2,a_3,a_4,a_6]" are the coefficients of the Weierstrass equation of the curve and "G" is a Z-basis of the free part of the Mordell-Weil group associated to the curve.

If "N" is not a full-curve name, the output is the list (as a vector) of all matching curves in the above format.

The library syntax is ellsearch"(N)". Also available is " ellsearchcurve(N)" that only accept complete curve names.

ellsub"(E,z1,z2)"

The library syntax is subell"(E,z1,z2)".

elltaniyama"(E)"

The library syntax is elltaniyama"(E, prec)", and the precision of the result is determined by "prec".

elltors"(E,{flag = 0})"

  ?  E = ellinit([0,0,0,-1,0]);
  ?  elltors(E)
  %1 = [4, [2, 2], [[0, 0], [1, 0]]]

Here, the torsion subgroup is isomorphic to "Z/2Z x Z/2Z ", with generators "[0,0]" and "[1,0]".

If "flag = 0", use Doud's algorithm: bound torsion by computing "#E(F_p)" for small primes of good reduction, then look for torsion points using Weierstrass parametrization (and Mazur's classification).

If "flag = 1", use Lutz-Nagell (\emph{much} slower), "E" is allowed to be an sell.

The library syntax is elltors0"(E,flag)".

ellwp"(E,{z = x},{flag = 0})"

If "z" is omitted or is a simple variable, computes the \emph{power series} expansion in "z" (starting "z^{-2}+O(z^2)"). The number of terms to an \emph{even} power in the expansion is the default serieslength in "gp", and the second argument (C long integer) in library mode.

Optional flag is (for now) only taken into account when "z" is numeric, and means 0: compute only " wp (z)", 1: compute "[ wp (z), wp '(z)]".

The library syntax is ellwp0"(E,z, flag,prec,precdl)". Also available is " weipell(E,precdl)" for the power series.

ellzeta"(E,z)"

The library syntax is ellzeta"(E,z)".

ellztopoint"(E,z)"

The library syntax is pointell"(E,z, prec)".

Number field structures

\item "nf" denotes a number field, i.e. a data structure output by "nfinit". This contains the basic arithmetic data associated to the number field: signature, maximal order (given by a basis "nf.zk"), discriminant, defining polynomial "T", etc.

\item "bnf" denotes a ``Buchmann's number field'', i.e. a data structure output by "bnfinit". This contains "nf" and the deeper invariants of the field: units U(K), class group "\Cl(K)", as well as technical data required to solve the two associated discrete logarithm problems.

\item "bnr" denotes a ``ray number field'', i.e. a data structure output by "bnrinit", corresponding to the ray class group structure of the field, for some modulus "f". It contains a bnf, the modulus "f", the ray class group "\Cl_f(K)" and data associated to the discrete logarithm problem therein.

Algebraic numbers and ideals

\item a "t_INT", "t_FRAC" or "t_POL" (implicitly modulo "T"), or

\item a "t_POLMOD" (modulo "T"), or

\item a "t_COL" "v" of dimension "N = [K:Q]", representing the element in terms of the computed integral basis, as "sum(i = 1, N, v[i] * nf.zk[i])". Note that a "t_VEC" will not be recognized.

An ideal is given in any of the following ways:

\item an algebraic number in one of the above forms, defining a principal ideal.

\item a prime ideal, i.e. a 5-component vector in the format output by "idealprimedec".

\item a "t_MAT", square and in Hermite Normal Form (or at least upper triangular with non-negative coefficients), whose columns represent a basis of the ideal.

One may use "idealhnf" to convert an ideal to the last (preferred) format.

Note. Some routines accept non-square matrices, but using this format is strongly discouraged. Nevertheless, their behaviour is as follows: If strictly less than "N = [K:Q]" generators are given, it is assumed they form a "Z_K"-basis. If "N" or more are given, a Z -basis is assumed. If exactly "N" are given, it is further assumed the matrix is in HNF. If any of these assumptions is not correct the behaviour of the routine is undefined.

\item an idele is a 2-component vector, the first being an ideal as above, the second being a "R_1+R_2"-component row vector giving Archimedean information, as complex numbers.

Finite abelian groups

\item a character on the abelian group " oplus (Z/d_iZ) g_i" is given by a row vector "chi = [a_1,...,a_n]" such that "chi (prod g_i^{n_i}) = exp (2iPi sum a_i n_i / d_i)".

\item given such a structure, a subgroup "H" is input as a square matrix, whose column express generators of "H" on the given generators "g_i". Note that the absolute value of the determinant of that matrix is equal to the index "(G:H)".

Relative extensions

\item "rnf" denotes a relative number field, i.e. a data structure output by "rnfinit".

\item A \emph{relative matrix} is a matrix whose entries are elements of a (fixed) number field "nf", always expressed as column vectors on the integral basis "nf.zk". Hence it is a matrix of vectors.

\item An ideal list is a row vector of (fractional) ideals of the number field "nf".

\item A pseudo-matrix is a pair "(A,I)" where "A" is a relative matrix and "I" an ideal list whose length is the same as the number of columns of "A". This pair is represented by a 2-component row vector.

\item The projective module generated by a pseudo-matrix "(A,I)" is the sum " sum_i {a}_j A_j" where the "{a}_j" are the ideals of "I" and "A_j" is the "j"-th column of "A".

\item A pseudo-matrix "(A,I)" is a pseudo-basis of the module it generates if "A" is a square matrix with non-zero determinant and all the ideals of "I" are non-zero. We say that it is in Hermite Normal Form (HNF) if it is upper triangular and all the elements of the diagonal are equal to 1.

\item The \emph{determinant} of a pseudo-basis "(A,I)" is the ideal equal to the product of the determinant of "A" by all the ideals of "I". The determinant of a pseudo-matrix is the determinant of any pseudo-basis of the module it generates.

Class field theory

A bid or ``big ideal'' is a structure output by "idealstar" needed to compute in "(Z_K/I)^*", where "I" is a modulus in the above sense. If is a finite abelian group as described above, supplemented by technical data needed to solve discrete log problems.

Finally we explain how to input ray number fields (or bnr), using class field theory. These are defined by a triple "a1", "a2", "a3", where the defining set "[a1,a2,a3]" can have any of the following forms: "[bnr]", "[bnr,subgroup]", "[bnf,module]", "[bnf,module,subgroup]".

\item "bnf" is as output by "bnfinit", where units are mandatory unless the modulus is trivial; bnr is as output by "bnrinit". This is the ground field "K".

\item \emph{module} is a modulus "\goth{f}", as described above.

\item \emph{subgroup} a subgroup of the ray class group modulo "\goth{f}" of "K". As described above, this is input as a square matrix expressing generators of a subgroup of the ray class group "bnr.clgp" on the given generators.

The corresponding bnr is the subfield of the ray class field of "K" modulo "\goth{f}", fixed by the given subgroup.

General use

However, and even though it may not be specified in the descriptions of the functions below, it is permissible, if the function expects a "nf", to use a "bnf" instead, which contains much more information. On the other hand, if the function requires a "bnf", it will \emph{not} launch "bnfinit" for you, which is a costly operation. Instead, it will give you a specific error message. In short, the types

  " nf <= bnf <= bnr"

are ordered, each function requires a minimal type to work properly, but you may always substitute a larger type.

The data types corresponding to the structures described above are rather complicated. Thus, as we already have seen it with elliptic curves, GP provides ``member functions'' to retrieve data from these structures (once they have been initialized of course). The relevant types of number fields are indicated between parentheses:

 "bid" (bnr, ) : bid ideal structure.

 "bnf" (bnr, bnf ) : Buchmann's number field.

 "clgp" (bnr, bnf ) : classgroup. This one admits the following three subclasses:

  "cyc" : cyclic decomposition (SNF).

  "gen" : generators.

  "no" : number of elements.

 "diff" (bnr, bnf, nf ) : the different ideal.

 "codiff" (bnr, bnf, nf ) : the codifferent (inverse of the different in the ideal group).

 "disc" (bnr, bnf, nf ) : discriminant.

 "fu" (bnr, bnf, nf ) : fundamental units.

 "index" (bnr, bnf, nf ) : index of the power order in the ring of integers.

 "nf" (bnr, bnf, nf ) : number field.

 "r1" (bnr, bnf, nf ) : the number of real embeddings.

 "r2" (bnr, bnf, nf ) : the number of pairs of complex embeddings.

 "reg" (bnr, bnf, ) : regulator.

 "roots" (bnr, bnf, nf ) : roots of the polynomial generating the field.

 "t2" (bnr, bnf, nf ) : the T2 matrix (see "nfinit").

 "tu" (bnr, bnf, ) : a generator for the torsion units.

 "tufu" (bnr, bnf, ) : "[w,u_1,...,u_r]", "(u_i)" is a vector of fundamental units, "w" generates the torsion units.

 "zk" (bnr, bnf, nf ) : integral basis, i.e. a Z -basis of the maximal order.

For instance, assume that "bnf = bnfinit(pol)", for some polynomial. Then "bnf.clgp" retrieves the class group, and "bnf.clgp.no" the class number. If we had set "bnf = nfinit(pol)", both would have output an error message. All these functions are completely recursive, thus for instance "bnr.bnf.nf.zk" will yield the maximal order of bnr, which you could get directly with a simple "bnr.zk".

Class group, units, and the GRH

  "tech = [c, c2, nrpid ],"

where the parameters are to be understood as follows:

"P" is the defining polynomial for the number field, which must be in "Z[X]", irreducible and monic. In fact, if you supply a non-monic polynomial at this point, "gp" issues a warning, then \emph{transforms your polynomial} so that it becomes monic. The "nfinit" routine will return a different result in this case: instead of "res", you get a vector "[res,Mod(a,Q)]", where "Mod(a,Q) = Mod(X,P)" gives the change of variables. In all other routines, the variable change is simply lost.

The numbers "c <= c_2" are positive real numbers which control the execution time and the stack size. For a given "c", set "c_2 = c" to get maximum speed. To get a rigorous result under GRH you must take "c2 >= 12" (or "c2 >= 6" in "P" is quadratic). Reasonable values for "c" are between 0.1 and 2. The default is "c = c_2 = 0.3".

"nrpid" is the maximal number of small norm relations associated to each ideal in the factor base. Set it to 0 to disable the search for small norm relations. Otherwise, reasonable values are between 4 and 20. The default is 4.

Warning. Make sure you understand the above! By default, most of the "bnf" routines depend on the correctness of a heuristic assumption which is stronger than the GRH. In particular, any of the class number, class group structure, class group generators, regulator and fundamental units may be wrong, independently of each other. Any result computed from such a "bnf" may be wrong. The only guarantee is that the units given generate a subgroup of finite index in the full unit group. In practice, very few counter-examples are known, requiring unlucky random seeds. No counter-example has been reported for "c_2 = 0.5" (which should be almost as fast as "c_2 = 0.3", and shall very probably become the default). If you use "c_2 = 12", then everything is correct assuming the GRH holds. You can use "bnfcertify" to certify the computations unconditionally.

Remarks.

Apart from the polynomial "P", you do not need to supply the technical parameters (under the library you still need to send at least an empty vector, coded as "NULL"). However, should you choose to set some of them, they \emph{must} be given in the requested order. For example, if you want to specify a given value of nrpid, you must give some values as well for "c" and "c_2", and provide a vector "[c,c_2,nrpid]".

Note also that you can use an "nf " instead of "P", which avoids recomputing the integral basis and analogous quantities.

bnfcertify"(bnf)"

The library syntax is certifybuchall"(bnf)", and the result is a C long.

bnfclassunit"(P,{flag = 0},{tech = []})"

Buchmann's sub-exponential algorithm for computing the class group, the regulator and a system of fundamental units of the general algebraic number field "K" defined by the irreducible polynomial "P" with integer coefficients.

The result of this function is a vector "v" with many components, which for ease of presentation is in fact output as a one column matrix. It is \emph{not} a "bnf", you need "bnfinit" for that. First we describe the default behaviour ("flag = 0"):

"v[1]" is equal to the polynomial "P".

"v[2]" is the 2-component vector "[r1,r2]", where "r1" and "r2" are as usual the number of real and half the number of complex embeddings of the number field "K".

"v[3]" is the 2-component vector containing the field discriminant and the index.

"v[4]" is an integral basis in Hermite normal form.

"v[5]" ("v.clgp") is a 3-component vector containing the class number ("v.clgp.no"), the structure of the class group as a product of cyclic groups of order "n_i" ("v.clgp.cyc"), and the corresponding generators of the class group of respective orders "n_i" ("v.clgp.gen").

"v[6]" ("v.reg") is the regulator computed to an accuracy which is the maximum of an internally determined accuracy and of the default.

"v[7]" is deprecated, maintained for backward compatibility and always equal to 1.

"v[8]" ("v.tu") a vector with 2 components, the first being the number "w" of roots of unity in "K" and the second a primitive "w"-th root of unity expressed as a polynomial.

"v[9]" ("v.fu") is a system of fundamental units also expressed as polynomials.

If "flag = 1", and the precision happens to be insufficient for obtaining the fundamental units, the internal precision is doubled and the computation redone, until the exact results are obtained. 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 large real quadratic fields. For this case, there are alternate compact representations for algebraic numbers, implemented in PARI but currently not available in GP.

If "flag = 2", the fundamental units and roots of unity are not computed. Hence the result has only 7 components, the first seven ones.

The library syntax is bnfclassunit0"(P,flag,tech,prec)".

bnfclgp"(P,{tech = []})"

The library syntax is classgrouponly"(P,tech,prec)", where tech is as described under "bnfinit".

bnfdecodemodule"(nf,m)"

The library syntax is decodemodule"( nf,m)".

bnfinit"(P,{flag = 0},{tech = []})"

This implements Buchmann's sub-exponential algorithm for computing the class group, the regulator and a system of fundamental units of the general algebraic number field "K" defined by the irreducible polynomial "P" with integer coefficients.

If the precision becomes insufficient, "gp" outputs a warning ("fundamental units too large, not given") and does not strive to compute the units by default (" flag = 0").

When "flag = 1", we insist on finding the fundamental units exactly. Be warned that this can take a very long time when the coefficients of the fundamental units on the integral basis are very large. If the fundamental units are simply too large to be represented in this form, an error message is issued. They could be obtained using the so-called compact representation of algebraic numbers as a formal product of algebraic integers. The latter is implemented internally but not publicly accessible yet.

When "flag = 2", on the contrary, it is initially agreed that units are not computed. Note that the resulting bnf will not be suitable for "bnrinit", and that this flag provides negligible time savings compared to the default. In short, it is deprecated.

When "flag = 3", computes a very small version of "bnfinit", a ``small Buchmann's number field'' (or sbnf for short) which contains enough information to recover the full "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 "bnfmake".

"tech" is a technical vector (empty by default, see se:GRHbnf). Careful use of this parameter may speed up your computations considerably.

The components of a bnf or sbnf are technical and never used by the casual user. In fact: \emph{never access a component directly, always use a proper member function.} However, for the sake of completeness and internal documentation, their description is as follows. We use the notations explained in the book by H. Cohen, \emph{A Course in Computational Algebraic Number Theory}, Graduate Texts in Maths 138, Springer-Verlag, 1993, Section 6.5, and subsection 6.5.5 in particular.

"bnf[1]" contains the matrix "W", i.e. the matrix in Hermite normal form giving relations for the class group on prime ideal generators "( wp _i)_{1 <= i <= r}".

"bnf[2]" contains the matrix "B", i.e. the matrix containing the expressions of the prime ideal factorbase in terms of the " wp _i". It is an "r x c" matrix.

"bnf[3]" contains the complex logarithmic embeddings of the system of fundamental units which has been found. It is an "(r_1+r_2) x (r_1+r_2-1)" matrix.

"bnf[4]" contains the matrix "M''_C" of Archimedean components of the relations of the matrix "(W|B)".

"bnf[5]" contains the prime factor base, i.e. the list of prime ideals used in finding the relations.

"bnf[6]" used to contain a permutation of the prime factor base, but has been obsoleted. It contains a dummy 0.

"bnf[7]" or "bnf.nf" is equal to the number field data "nf" as would be given by "nfinit".

"bnf[8]" is a vector containing the classgroup "bnf .clgp" as a finite abelian group, the regulator "bnf.reg", a 1 (used to contain an obsolete ``check number''), the number of roots of unity and a generator "bnf.tu", the fundamental units "bnf.fu".

"bnf[9]" is a 3-element row vector used in "bnfisprincipal" only and obtained as follows. Let "D = U W V" obtained by applying the Smith normal form algorithm to the matrix "W" ( = "bnf[1]") and let "U_r" be the reduction of "U" modulo "D". The first elements of the factorbase are given (in terms of "bnf.gen") by the columns of "U_r", with Archimedean component "g_a"; let also "GD_a" be the Archimedean components of the generators of the (principal) ideals defined by the "bnf.gen[i]^bnf.cyc[i]". Then "bnf[9] = [U_r, g_a, GD_a]".

"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 "bnfinit" call. For instance, the generators of the principal ideals "bnf.gen[i]^bnf.cyc[i]" (during a call to "bnrisprincipal"), or those corresponding to the relations in "W" and "B" (when the "bnf" internal precision needs to be increased).

An sbnf is a 12 component vector "v", as follows. Let "bnf" be the result of a full "bnfinit", complete with units. Then "v[1]" is the polynomial "P", "v[2]" is the number of real embeddings "r_1", "v[3]" is the field discriminant, "v[4]" is the integral basis, "v[5]" is the list of roots as in the sixth component of "nfinit", "v[6]" is the matrix "MD" of "nfinit" giving a Z-basis of the different, "v[7]" is the matrix "W = bnf[1]", "v[8]" is the matrix "matalpha = bnf[2]", "v[9]" is the prime ideal factor base "bnf[5]" coded in a compact way, and ordered according to the permutation "bnf[6]", "v[10]" is the 2-component vector giving the number of roots of unity and a generator, expressed on the integral basis, "v[11]" is the list of fundamental units, expressed on the integral basis, "v[12]" is a vector containing the algebraic numbers alpha corresponding to the columns of the matrix "matalpha", expressed on the integral basis.

Note that all the components are exact (integral or rational), except for the roots in "v[5]". Note also that member functions will \emph{not} work on sbnf, you have to use "bnfmake" explicitly first.

The library syntax is bnfinit0"(P, flag,tech,prec)".

bnfisintnorm"(bnf,x)"

See also "bnfisnorm".

The library syntax is bnfisintnorm"( bnf,x)".

bnfisnorm"(bnf,x,{flag = 1})"

Assuming GRH, the answer is guaranteed (i.e. "x" is a norm iff "b = 1"), if "S" contains all primes less than "12 log (\disc(Bnf))^2", where "Bnf" is the Galois closure of "bnf".

See also "bnfisintnorm".

The library syntax is bnfisnorm"( bnf,x,flag,prec)", where "flag" and "prec" are "long"s.

bnfissunit"(bnf,sfu,x)"

The library syntax is bnfissunit"( bnf,sfu,x)".

bnfisprincipal"(bnf,x,{flag = 1})"

"v_1" is the vector of components "c_i" of the class of the ideal "x" in the class group, expressed on the generators "g_i" given by "bnfinit" (specifically "bnf.gen"). The "c_i" are chosen so that "0 <= c_i < n_i" where "n_i" is the order of "g_i" (the vector of "n_i" being "bnf.cyc").

"v_2" gives on the integral basis the components of "alpha" such that "x = alpha prod_ig_i^{c_i}". In particular, "x" is principal if and only if "v_1" is equal to the zero vector. In the latter case, "x = alpha Z_K" where "alpha" is given by "v_2". Note that if "alpha" is too large to be given, a warning message will be printed and "v_2" will be set equal to the empty vector.

If "flag = 0", outputs only "v_1", which is much easier to compute.

If "flag = 2", does as if "flag" were 0, but doubles the precision until a result is obtained.

If "flag = 3", as in the default behaviour ("flag = 1"), but doubles the precision until a result is obtained.

The user is warned that these two last setting may induce \emph{very} lengthy computations.

The library syntax is isprincipalall"(bnf,x,flag)".

bnfisunit"(bnf,x)"

The library syntax is isunit"(bnf,x)".

bnfmake"(sbnf)"

Note that the member functions are \emph{not} available for sbnf, you have to use "bnfmake" explicitly first.

The library syntax is makebigbnf"( sbnf,prec)", where "prec" is a C long integer.

bnfnarrow"(bnf)"

The library syntax is buchnarrow"( bnf)".

bnfsignunit"(bnf)"

  /* exponents of totally positive units generators on bnf.tufu */
  tpuexpo(bnf)=
  { local(S,d,K);

    S = bnfsignunit(bnf); d = matsize(S);
    S = matrix(d[1],d[2], i,j, if (S[i,j] < 0, 1,0));
    S = concat(vectorv(d[1],i,1), S);   \\ add sign(-1)
    K = lift(matker(S * Mod(1,2)));
    if (K, mathnfmodid(K, 2), 2*matid(d[1]))
  }

  /* totally positive units */
  tpu(bnf)=
  { local(vu = bnf.tufu, ex = tpuexpo(bnf));

    vector(#ex-1, i, factorback(vu, ex[,i+1]))  \\ ex[,1] is 1
  }

The library syntax is signunits"( bnf)".

bnfreg"(bnf)"

The library syntax is regulator"( bnf, tech,prec)", where tech is as in "bnfinit".

bnfsunit"(bnf,S)"

"v[1]" gives a minimal system of (integral) generators of the "S"-unit group modulo the unit group.

"v[2]" contains technical data needed by "bnfissunit".

"v[3]" is an empty vector (used to give the logarithmic embeddings of the generators in "v[1]" in version 2.0.16).

"v[4]" is the "S"-regulator (this is the product of the regulator, the determinant of "v[2]" and the natural logarithms of the norms of the ideals in "S").

"v[5]" gives the "S"-class group structure, in the usual format (a row vector whose three components give in order the "S"-class number, the cyclic components and the generators).

"v[6]" is a copy of "S".

The library syntax is bnfsunit"( bnf,S,prec)".

bnfunit"(bnf)"

This function is mostly useless, since it will only succeed if bnf contains the units, in which case "bnf.fu" is recommanded instead, or bnf was produced with "bnfinit(,,2)", which is itself deprecated.

The library syntax is buchfu"(bnf)".

bnrL1"(bnr,{subgroup},{flag = 0})"

  "L(s, chi) = c_chi.s^{r_chi} + O(s^{r_chi + 1})"

near 0. flag is optional, default value is 0; its binary digits mean 1: compute at "s = 1" if set to 1 or "s = 0" if set to 0, 2: compute the primitive "L"-functions associated to "chi" if set to 0 or the "L"-function with Euler factors at prime ideals dividing the modulus of bnr removed if set to 1 (this is the so-called "L_S(s, chi)" function where "S" is the set of infinite places of the number field together with the finite prime ideals dividing the modulus of bnr, see the example below), 3: returns also the character. Example:

  bnf = bnfinit(x^2 - 229);
  bnr = bnrinit(bnf,1,1);
  bnrL1(bnr)

returns the order and the first non-zero term of the abelian "L"-functions "L(s, chi)" at "s = 0" where " chi" runs through the characters of the class group of "Q( sqrt {229})". Then

  bnr2 = bnrinit(bnf,2,1);
  bnrL1(bnr2,,2)

returns the order and the first non-zero terms of the abelian "L"-functions "L_S(s, chi)" at "s = 0" where "chi" runs through the characters of the class group of "Q( sqrt {229})" and "S" is the set of infinite places of "Q( sqrt {229})" together with the finite prime 2. Note that the ray class group modulo 2 is in fact the class group, so "bnrL1(bnr2,0)" returns exactly the same answer as "bnrL1(bnr,0)".

The library syntax is bnrL1"(bnr,subgroup,flag,prec)", where an omitted subgroup is coded as "NULL".

bnrclass"(bnf,ideal,{flag = 0})"

"bnf" being as output by "bnfinit" (the units are mandatory unless the ideal is trivial), and ideal being a modulus, computes the ray class group of the number field for the modulus ideal, as a finite abelian group.

The library syntax is bnrclass0"( bnf, ideal,flag)".

bnrclassno"(bnf,I)"

The library syntax is bnrclassno"( bnf,I)".

bnrclassnolist"(bnf,list)"

  ? bnf = bnfinit(x^2 - 2);
  ? L = ideallist(bnf, 100, 2);
  ? H = bnrclassnolist(bnf, L);
  ? H[98]
  %4 = [1, 3, 1]
  ? l = L[1][98]; ids = vector(#l, i, l[i].mod[1])
  %5 = [[98, 88; 0, 1], [14, 0; 0, 7], [98, 10; 0, 1]]

The weird "l[i].mod[1]", is the first component of "l[i].mod", i.e. the finite part of the conductor. (This is cosmetic: since by construction the archimedean part is trivial, I do not want to see it). This tells us that the ray class groups modulo the ideals of norm 98 (printed as %5) have respectively order 1, 3 and 1. Indeed, we may check directly :

  ? bnrclassno(bnf, ids[2])
  %6 = 3

The library syntax is bnrclassnolist"(bnf,list)".

bnrconductor"(a_1,{a_2},{a_3}, {flag = 0})"

If "flag = 0", returns "f".

If "flag = 1", returns "[f, Cl_f, H]", where "Cl_f" is the ray class group modulo "f", as a finite abelian group; finally "H" is the subgroup of "Cl_f" defining the extension.

If "flag = 2", returns "[f, bnr(f), H]", as above except "Cl_f" is replaced by a "bnr" structure, as output by "bnrinit(,f,1)".

The library syntax is conductor"( bnr, subgroup, flag)", where an omitted subgroup (trivial subgroup, i.e. ray class field) is input as "NULL", and "flag" is a C long.

bnrconductorofchar"(bnr,chi)"

The library syntax is bnrconductorofchar"(bnr,chi)".

bnrdisc"(a1,{a2},{a3},{flag = 0})"

If "flag = 1", as above but outputs relative data. "N" is now the degree of "L/K", "R_1" is the number of real places of "K" unramified in "L" (so that the number of real places of "L" is equal to "R_1" times the relative degree "N"), and "D" is the relative discriminant ideal of "L/K".

If "flag = 2", as the default case, except that if the modulus is not the exact conductor corresponding to the "L", no data is computed and the result is 0.

If "flag = 3", as case 2, but output relative data.

The library syntax is bnrdisc0"(a1,a2,a3,flag)".

bnrdisclist"(bnf,bound,{arch})"

The alternative syntax "bnrdisclist(bnf,list)" is supported, where list is as output by "ideallist" or "ideallistarch" (with units), in which case arch is disregarded.

The output "v" is a vector of vectors, where "v[i][j]" is understood to be in fact "V[2^{15}(i-1)+j]" of a unique big vector "V". (This akward scheme allows for larger vectors than could be otherwise represented.)

"V[k]" is itself a vector "W", whose length is the number of ideals of norm "k". We consider first the case where arch was specified. Each component of "W" corresponds to an ideal "m" of norm "k", and gives invariants associated to the ray class field "L" of "bnf" of conductor "[m, arch]". Namely, each contains a vector "[m,d,r,D]" with the following meaning: "m" is the prime ideal factorization of the modulus, "d = [L:Q]" is the absolute degree of "L", "r" is the number of real places of "L", and "D" is the factorization of its absolute discriminant. We set "d = r = D = 0" if "m" is not the finite part of a conductor.

If arch was omitted, all "t = 2^{r_1}" possible values are taken and a component of "W" has the form "[m, [[d_1,r_1,D_1],..., [d_t,r_t,D_t]]]", where "m" is the finite part of the conductor as above, and "[d_i,r_i,D_i]" are the invariants of the ray class field of conductor "[m,v_i]", where "v_i" is the "i"-th archimedean component, ordered by inverse lexicographic order; so "v_1 = [0,...,0]", "v_2 = [1,0...,0]", etc. Again, we set "d_i = r_i = D_i = 0" if "[m,v_i]" is not a conductor.

Finally, each prime ideal "pr = [p,alpha,e,f,beta]" in the prime factorization "m" is coded as the integer "p.n^2+(f-1).n+(j-1)", where "n" is the degree of the base field and "j" is such that

"pr = idealprimedec(nf,p)[j]".

"m" can be decoded using "bnfdecodemodule".

Note that to compute such data for a single field, either "bnrclassno" or "bnrdisc" is more efficient.

The library syntax is bnrdisclist0"(bnf,bound,arch)".

bnrinit"(bnf,f,{flag = 0})"

The last group of functions are different from the members of the underlying bnf, which refer to the class group; use "bnr.bnf.xxx" to access these, e.g. "bnr.bnf.cyc" to get the cyclic decomposition of the class group.

They are also different from the members of the underlying bid, which refer to "(\O_K/f)^*"; use "bnr.bid.xxx" to access these, e.g. "bnr.bid.no" to get "phi(f)".

If "flag = 0" (default), the generators of the ray class group are not computed, which saves time. Hence "bnr.gen" would produce an error.

If "flag = 1", as the default, except that generators are computed.

The library syntax is bnrinit0"( bnf,f,flag)".

bnrisconductor"(a1,{a2},{a3})"

The library syntax is bnrisconductor"(a1,a2,a3)" and the result is a "long".

bnrisprincipal"(bnr,x,{flag = 1})"

If "flag = 0", outputs only "v_1". In that case, bnr need not contain the ray class group generators, i.e. it may be created with "bnrinit""(,,0)"

The library syntax is bnrisprincipal"(bnr,x,flag)".

bnrrootnumber"(bnr,chi,{flag = 0})"

  "Lambda(1-s,chi) = W(chi) Lambda(s,\overline{chi})"

where "Lambda(s,chi) = A(chi)^{s/2}gamma_chi(s) L(s,chi)" is the enlarged L-function associated to "L".

The generators of the ray class group are needed, and you can set "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 " chi" of "\Cl_7(Q( sqrt {145}))" such that "chi(g) = zeta^5", where "g" is the generator of the ray-class field and "zeta = e^{2i Pi/N}" where "N" is the order of "g" ("N = 12" as "bnr.cyc" readily tells us).

The library syntax is bnrrootnumber"( bnf,chi,flag)"

bnrstark"{(bnr,{subgroup})}"

The routine uses Stark units and needs to find a suitable auxilliary conductor, which may not exist when the class field is not cyclic over the base. In this case "bnrstark" is allowed to return a vector of polynomials defining \emph{independent} relative extensions, whose compositum is the requested class field. It was decided that it was more useful to keep the extra information thus made available, hence the user has to take the compositum herself.

The main variable of bnr must not be "x", and the ground field and the class field must be totally real. When the base field is Q, the vastly simpler "galoissubcyclo" is used instead. Here is an example:

  bnf = bnfinit(y^2 - 3);
  bnr = bnrinit(bnf, 5, 1);
  pol = bnrstark(bnr)

returns the ray class field of " Q( sqrt {3})" modulo 5. Usually, one wants to apply to the result one of

  rnfpolredabs(bnf, pol, 16 + 2) \\ compute a reduced relative polynomial
  rnfpolredabs(bnf, pol, 16 + 2) \\ compute a reduced absolute polynomial

The library syntax is bnrstark"( bnr, subgroup)", where an omitted subgroup is coded by "NULL".

dirzetak"(nf,b)"

The library syntax is dirzetak"( nf,b)".

factornf"(x,t)"

The main variable of "t" must be of \emph{lower} priority than that of "x" (see "Label se:priority"). However if non-rational number field elements occur (as polmods or polynomials) as coefficients of "x", the variable of these polmods \emph{must} be the same as the main variable of "t". For example

  ? factornf(x^2 + Mod(y, y^2+1), y^2+1);
  ? factornf(x^2 + y, y^2+1); \\ these two are OK
  ? factornf(x^2 + Mod(z,z^2+1), y^2+1)
    *** factornf: inconsistent data in rnf function.
  ? factornf(x^2 + z, y^2+1)
    *** factornf: incorrect variable in rnf function.

The library syntax is polfnf"(x,t)".

galoisexport"(gal,{flag = 0})"

  ? G = galoisinit(x^6+108);
  ? s = galoisexport(G)
  %2 = "Group((1, 2, 3)(4, 5, 6), (1, 4)(2, 6)(3, 5))"
  ? extern("echo \"IdGroup("s");\" | gap -q")
  %3 = [6, 1]
  ? galoisidentify(G)
  %4 = [6, 1]

This command also accepts subgroups returned by "galoissubgroups".

The library syntax is galoisexport"( gal,flag)".

galoisfixedfield"(gal,perm,{flag = 0},{v = y}))"

If no flags or "flag = 0", output format is the same as for "nfsubfield", returning "[P,x]" such that "P" is a polynomial defining the fixed field, and "x" is a root of "P" expressed as a polmod in "gal.pol".

If "flag = 1" return only the polynomial "P".

If "flag = 2" return "[P,x,F]" where "P" and "x" are as above and "F" is the factorization of "gal.pol" over the field defined by "P", where variable "v" ("y" by default) stands for a root of "P". The priority of "v" must be less than the priority of the variable of "gal.pol" (see "Label se:priority"). Example:

  ? G = galoisinit(x^4+1);
  ? galoisfixedfield(G,G.group[2],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 "x^4+1 = (x^2- sqrt {-2}x-1)(x^2+ sqrt {-2}x-1)"

The library syntax is galoisfixedfield"(gal,perm,flag,"v")", where "v" is a variable number, an omitted "v" being coded by "-1".

galoisidentify"(gal)"

This command also accepts subgroups returned by "galoissubgroups".

The current implementation is limited to degree less or equal to 127. Some larger ``easy'' orders are also supported.

The output is similar to the output of the function "IdGroup" in GAP4. Note that GAP4 "IdGroup" handles all groups of order less than 2000 except 1024, so you can use "galoisexport" and GAP4 to identify large Galois groups.

The library syntax is galoisidentify"(gal)".

galoisinit"(pol,{den})"

This is a prerequisite for most of the "galois""xxx" routines. For instance:

    P = x^6 + 108;
    G = galoisinit(P);
    L = galoissubgroups(G);
    vector(#L, i, galoisisabelian(L[i],1))
    vector(#L, i, galoisidentify(L[i]))

The output is an 8-component vector gal.

"gal[1]" contains the polynomial pol ("gal.pol").

"gal[2]" is a three-components vector "[p,e,q]" where "p" is a prime number ("gal.p") such that pol totally split modulo "p" , "e" is an integer and "q = p^e" ("gal.mod") is the modulus of the roots in "gal.roots".

"gal[3]" is a vector "L" containing the "p"-adic roots of pol as integers implicitly modulo "gal.mod". ("gal.roots").

"gal[4]" is the inverse of the Van der Monde matrix of the "p"-adic roots of pol, multiplied by "gal[5]".

"gal[5]" is a multiple of the least common denominator of the automorphisms expressed as polynomial in a root of pol.

"gal[6]" is the Galois group "G" expressed as a vector of permutations of "L" ("gal.group").

"gal[7]" is a generating subset "S = [s_1,...,s_g]" of "G" expressed as a vector of permutations of "L" ("gal.gen").

"gal[8]" contains the relative orders "[o_1,...,o_g]" of the generators of "S" ("gal .orders").

Let "H" be the maximal normal supersolvable subgroup of "G", we have the following properties:

  \item if "G/H ~ A_4" then "[o_1,...,o_g]" ends by "[2,2,3]".

  \item if "G/H ~ S_4" then "[o_1,...,o_g]" ends by "[2,2,3,2]".

  \item else "G" is super-solvable.

  \item for "1 <= i <= g" the subgroup of "G" generated by "[s_1,...,s_g]" is normal, with the exception of "i = g-2" in the second case and of "i = g-3" in the third.

  \item the relative order "o_i" of "s_i" is its order in the quotient group "G/<s_1,...,s_{i-1}>", with the same exceptions.

  \item for any "x belongs to G" there exists a unique family "[e_1,...,e_g]" such that (no exceptions):

-- for "1 <= i <= g" we have "0 <= e_i < o_i"

-- "x = g_1^{e_1}g_2^{e_2}...g_n^{e_n}"

If present "den" must be a suitable value for "gal[5]".

The library syntax is galoisinit"( gal,den)".

galoisisabelian"(gal,{fl = 0})"

This command also accepts subgroups returned by "galoissubgroups".

The library syntax is galoisisabelian"(gal,fl)" where fl is a C long integer.

galoispermtopol"(gal,perm)"

Note that

  G = galoisinit(pol);
  galoispermtopol(G, G[6])~

is equivalent to "nfgaloisconj(pol)", if degree of pol is greater or equal to 2.

The library syntax is galoispermtopol"(gal,perm)".

galoissubcyclo"(N,H,{fl = 0},{v})"

The pair "(n, H)" is deduced from the parameters "(N, H)" as follows

\item "N" an integer: then "n = N"; "H" is a generator, i.e. an integer or an integer modulo "n"; or a vector of generators.

\item "N" the output of znstar(n). "H" as in the first case above, or a matrix, taken to be a HNF left divisor of the SNF for "(Z/nZ)^*" (of type "N.cyc"), giving the generators of "H" in terms of "N.gen".

\item "N" the output of "bnrinit(bnfinit(y), m, 1)" where "m" is a module. "H" as in the first case, or a matrix taken to be a HNF left divisor of the SNF for the ray class group modulo "m" (of type "N.cyc"), giving the generators of "H" in terms of "N.gen".

In this last case, beware that "H" is understood relatively to "N"; in particular, if the infinite place does not divide the module, e.g if "m" is an integer, then it is not a subgroup of "( Z/n Z)^*", but of its quotient by "{+- 1}".

If "fl = 0", compute a polynomial (in the variable v) defining the the subfield of "Q(zeta_n)" fixed by the subgroup H of "(Z /n Z)^*".

If "fl = 1", compute only the conductor of the abelian extension, as a module.

If "fl = 2", output "[pol, N]", where "pol" is the polynomial as output when "fl = 0" and "N" the conductor as output when "fl = 1".

The following function can be used to compute all subfields of "Q(zeta_n)" (of exact degree "d", if "d" is set):

  subcyclo(n, d = -1)=
  {
    local(bnr,L,IndexBound);
    IndexBound = if (d < 0, n, [d]);
    bnr = bnrinit(bnfinit(y), [n,[1]], 1);
    L = subgrouplist(bnr, IndexBound, 1);
    vector(#L,i, galoissubcyclo(bnr,L[i]));
  }

Setting "L = subgrouplist(bnr, IndexBound)" would produce subfields of exact conductor "n oo ".

The library syntax is galoissubcyclo"(N,H,fl,v)" where fl is a C long integer, and v a variable number.

galoissubfields"(G,{fl = 0},{v})"

The library syntax is galoissubfields"(G,fl,v)", where fl is a long and v a variable number.

galoissubgroups"(gal)"

To get the subfield fixed by a subgroup sub of gal, use

  galoisfixedfield(gal,sub[1])

The library syntax is galoissubgroups"(gal)".

idealadd"(nf,x,y)"

The library syntax is idealadd"( nf,x,y)".

idealaddtoone"(nf,x,{y})"

The alternative syntax "idealaddtoone( nf,v)", is supported, where "v" is a "k"-component vector of ideals (given in any form) which sum to "Z_K". This outputs a "k"-component vector "e" such that "e[i] belongs to x[i]" for "1 <= i <= k" and "sum_{1 <= i <= k}e[i] = 1".

The library syntax is idealaddtoone0"(nf,x,y)", where an omitted "y" is coded as "NULL".

idealappr"(nf,x,{flag = 0})"