libPARI.dumb(3) User Contributed Perl Documentation libPARI.dumb(3)NAME
libPARI - Functions and Operations Available in PARI and GP
DESCRIPTION
The functions and operators available in PARI and in the GP/PARI calcu-
lator are numerous and everexpanding. Here is a description of the ones
available in version 2.2.0. It should be noted that many of these func-
tions accept quite different types as arguments, but others are more
restricted. The list of acceptable types will be given for each func-
tion or class of functions. Except when stated otherwise, it is under-
stood that a function or operation which should make natural sense is
legal. In this chapter, we will describe the functions according to a
rough classification. The general entry looks something like:
foo"(x,{"flag" = 0})": short description.
The library syntax is foo"(x,"flag")".
This means that the GP function "foo" has one mandatory argument "x",
and an optional one, flag, whose default value is 0 (the "{}" should
never be typed, it is just a convenient notation we will use throughout
to denote optional arguments). That is, you can type "foo(x,2)", or
foo(x), which is then understood to mean "foo(x,0)". As well, a comma
or closing parenthesis, where an optional argument should have been,
signals to GP it should use the default. Thus, the syntax "foo(x,)" is
also accepted as a synonym for our last expression. When a function has
more than one optional argument, the argument list is filled with user
supplied values, in order. And when none are left, the defaults are
used instead. Thus, assuming that "foo"'s prototype had been
foo"({x = 1},{y = 2},{z = 3}), "
typing in "foo(6,4)" would give you "foo(6,4,3)". In the rare case when
you want to set some far away flag, and leave the defaults in between
as they stand, you can use the ``empty arg'' trick alluded to above:
"foo(6,,1)" would yield "foo(6,2,1)". By the way, "foo()" by itself
yields "foo(1,2,3)" as was to be expected. In this rather special case
of a function having no mandatory argument, you can even omit the "()":
a standalone "foo" would be enough (though we don't really recommend it
for your scripts, for the sake of clarity). In defining GP syntax, we
strove to put optional arguments at the end of the argument list (of
course, since they would not make sense otherwise), and in order of
decreasing usefulness so that, most of the time, you will be able to
ignore them.
Binary Flags. For some of these optional flags, we adopted the custom-
ary binary notation as a compact way to represent many toggles with
just one number. Letting "(p_0,...,p_n)" be a list of switches (i.e. of
properties which can be assumed to take either the value 0 or 1), the
number "2^3 + 2^5 = 40" means that "p_3" and "p_5" have been set (that
is, set to 1), and none of the others were (that is, they were set to
0). This will usually be announced as ``The binary digits of flag mean
1: "p_0", 2: "p_1", 4: "p_2"'', and so on, using the available consecu-
tive powers of 2.
Pointers. If a parameter in the function prototype is prefixed with a &
sign, as in
foo"(x,&e)"
it means that, besides the normal return value, the variable named "e"
may be set as a side effect. When passing the argument, the & sign has
to be typed in explicitly. As of version 2.2.0, this "pointer" argument
is optional for all documented functions, hence the & will always
appear between brackets as in "issquare""(x,{&e})".
About library programming. To finish with our generic simple-minded
example, the library function "foo", as defined above, is seen to have
two mandatory arguments, "x" and flag (no PARI mathematical function
has been implemented so as to accept a variable number of arguments).
When not mentioned otherwise, the result and arguments of a function
are assumed implicitly to be of type "GEN". Most other functions
return an object of type "long" integer in C (see Chapter 4). The vari-
able or parameter names prec and flag always denote "long" integers.
The "entree" type is used by the library to implement iterators (loops,
sums, integrals, etc.) when a formal variable has to successively
assume a number of values in a given set. When programming with the
library, it is easier and much more efficient to code loops and the
like directly. Hence this type is not documented, although it does
appear in a few library function prototypes below. See "Label se:sums"
for more details.
Standard monadic or dyadic operators
+"/"-
The expressions "+""x" and "-""x" refer to monadic operators (the first
does nothing, the second negates "x").
The library syntax is gneg"(x)" for "-""x".
+, "-"
The expression "x" "+" "y" is the sum and "x" "-" "y" is the difference
of "x" and "y". Among the prominent impossibilities are addition/sub-
traction between a scalar type and a vector or a matrix, between vec-
tor/matrices of incompatible sizes and between an integermod and a real
number.
The library syntax is gadd"(x,y)" "x" "+" "y", gsub"(x,y)" for "x" "-"
"y".
*
The expression "x" "*" "y" is the product of "x" and "y". Among the
prominent impossibilities are multiplication between vector/matrices of
incompatible sizes, between an integermod and a real number. Note that
because of vector and matrix operations, "*" is not necessarily commu-
tative. Note also that since multiplication between two column or two
row vectors is not allowed, to obtain the scalar product of two vectors
of the same length, you must multiply a line vector by a column vector,
if necessary by transposing one of the vectors (using the operator "~"
or the function "mattranspose", see "Label se:linear_algebra").
If "x" and "y" are binary quadratic forms, compose them. See also "qfb-
nucomp" and "qfbnupow".
The library syntax is gmul"(x,y)" for "x" "*" "y". Also available is
gsqr"(x)" for "x" "*" "x" (faster of course!).
/
The expression "x" "/" "y" is the quotient of "x" and "y". In addition
to the impossibilities for multiplication, note that if the divisor is
a matrix, it must be an invertible square matrix, and in that case the
result is "x*y^{-1}". Furthermore note that the result is as exact as
possible: in particular, division of two integers always gives a ratio-
nal number (which may be an integer if the quotient is exact) and not
the Euclidean quotient (see "x" "\" "y" for that), and similarly the
quotient of two polynomials is a rational function in general. To
obtain the approximate real value of the quotient of two integers, add
0. to the result; to obtain the approximate "p"-adic value of the quo-
tient of two integers, add "O(p^k)" to the result; finally, to obtain
the Taylor series expansion of the quotient of two polynomials, add
"O(X^k)" to the result or use the "taylor" function (see "Label se:tay-
lor").
The library syntax is gdiv"(x,y)" for "x" "/" "y".
\
The expression "x" "\" "y" is the
Euclidean quotient of "x" and "y". The types must be either both inte-
ger or both polynomials. The result is the Euclidean quotient. In the
case of integer division, the quotient is such that the corresponding
remainder is non-negative.
The library syntax is gdivent"(x,y)" for "x" "\" "y".
\/
The expression "x" "\/" "y" is the Euclidean quotient of "x" and "y".
The types must be either both integer or both polynomials. The result
is the rounded Euclidean quotient. In the case of integer division, the
quotient is such that the corresponding remainder is smallest in abso-
lute value and in case of a tie the quotient closest to "+ oo " is cho-
sen.
The library syntax is gdivround"(x,y)" for "x" "\/" "y".
%
The expression "x" "%" "y" is the
Euclidean remainder of "x" and "y". The modulus "y" must be of type
integer or polynomial. The result is the remainder, always non-negative
in the case of integers. Allowed dividend types are scalar exact types
when the modulus is an integer, and polynomials, polmods and rational
functions when the modulus is a polynomial.
The library syntax is gmod"(x,y)" for "x" "%" "y".
divrem"(x,y)"
creates a column vector with two components, the first being the
Euclidean quotient, the second the Euclidean remainder, of the division
of "x" by "y". This avoids the need to do two divisions if one needs
both the quotient and the remainder. The arguments must be both inte-
gers or both polynomials; in the case of integers, the remainder is
non-negative.
The library syntax is gdiventres"(x,y)".
^
The expression "x^n" is powering. If the exponent is an integer, then
exact operations are performed using binary (left-shift) powering tech-
niques. In particular, in this case "x" cannot be a vector or matrix
unless it is a square matrix (and moreover invertible if the exponent
is negative). If "x" is a "p"-adic number, its precision will increase
if "v_p(n) > 0". PARI is able to rewrite the multiplication "x * x" of
two 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 transcen-
dental 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, 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*/
The library syntax is gpow"(x,n,"prec")" for "x^n".
shift"(x,n)" or "x" "<< " "n" ( = "x" ">> " "(-n)")
shifts "x" componentwise left by "n" bits if "n >= 0" and right by
"|n|" bits if "n < 0". A left shift by "n" corresponds to multiplica-
tion by "2^n". A right shift of an integer "x" by "|n|" corresponds to
a Euclidean division of "x" by "2^{|n|}" with a remainder of the same
sign as "x", hence is not the same (in general) as "x \ 2^n".
The library syntax is gshift"(x,n)" where "n" is a "long".
shiftmul"(x,n)"
multiplies "x" by "2^n". The difference with "shift" is that when "n <
0", ordinary division takes place, hence for example if "x" is an inte-
ger the result may be a fraction, while for "shift" Euclidean division
takes place when "n < 0" hence if "x" is an integer the result is still
an integer.
The library syntax is gmul2n"(x,n)" where "n" is a "long".
Comparison and boolean operators
The six standard comparison operators "<= ", "< ", ">= ", "> ", " == ",
"! = " are available in GP, and in library mode under the names gle,
glt, gge, ggt, geq, gne respectively. The library syntax is co"(x,y)",
where co is the comparison operator. The result is 1 (as a "GEN") if
the comparison is true, 0 (as a "GEN") if it is false.
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 gegal"(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) other-
wise. Particular cases of gegal which should be used are 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.
Also note that the "gcmp" and "gegal" functions return a C-integer, and
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 not a syn-
onym for " == " since it is the assignment statement.
lex"(x,y)"
gives the result of a lexicographic comparison between "x" and "y".
This is to be interpreted in quite a wide sense. For example, the vec-
tor "[1,3]" will be considered smaller than the longer vector
"[1,3,-1]" (but of course larger than "[1,2,5]"), i.e. "lex([1,3],
[1,3,-1])" will return "-1".
The library syntax is lexcmp"(x,y)".
sign"(x)"
sign (0, 1 or "-1") of "x", which must be of type integer, real or
fraction.
The library syntax is gsigne"(x)". The result is a "long".
max"(x,y)" and min"(x,y)"
creates the maximum and minimum of "x" and "y" when they can be com-
pared.
The library syntax is gmax"(x,y)" and gmin"(x,y)".
vecmax"(x)"
if "x" is a vector or a matrix, returns the maximum of the elements of
"x", otherwise returns a copy of "x". Returns "- oo " in the form of
"-(2^{31}-1)" (or "-(2^{63}-1)" for 64-bit machines) if "x" is empty.
The library syntax is vecmax"(x)".
vecmin"(x)"
if "x" is a vector or a matrix, returns the minimum of the elements of
"x", otherwise returns a copy of "x". Returns "+ oo " in the form of
"2^{31}-1" (or "2^{63}-1" for 64-bit machines) if "x" is empty.
The library syntax is vecmin"(x)".
Conversions and similar elementary functions or commands
Many of the conversion functions are rounding or truncating operations.
In this case, if the argument is a rational function, the result is the
Euclidean quotient of the numerator by the denominator, and if the
argument is a vector or a matrix, the operation is done componentwise.
This will not be restated for every function.
List"({x = []})"
transforms a (row or column) vector "x" into a list. The only other way
to create a "t_LIST" is to use the function "listcreate".
This is useless in library mode.
Mat"({x = []})"
transforms the object "x" into a matrix. If "x" is not a vector or a
matrix, this creates a "1 x 1" matrix. If "x" is a row (resp. column)
vector, this creates a 1-row (resp. 1-column) matrix. If "x" is
already a matrix, a copy of "x" is created.
This function can be useful in connection with the function "concat"
(see there).
The library syntax is gtomat"(x)".
Mod"(x,y,{"flag" = 0})"
creates the PARI object "(x mod y)", i.e. an integermod or a polmod.
"y" must be an integer or a polynomial. If "y" is an integer, "x" must
be an integer, a rational number, or a "p"-adic number compatible with
the modulus "y". If "y" is a polynomial, "x" must be a scalar (which is
not a polmod), a polynomial, a rational function, or a power series.
This function is not the same as "x" "%" "y", the result of which is an
integer or a polynomial.
If flag is equal to 1, the modulus of the created result is put on the
heap and not on the stack, and hence becomes a permanent copy which
cannot be erased later by garbage collecting (see "Label se:garbage").
Functions will operate faster on such objects and memory consumption
will be lower. On the other hand, care should be taken to avoid creat-
ing too many such objects.
Under GP, the same effect can be obtained by assigning the object to a
GP variable (the value of which is a permanent object for the duration
of the relevant library function call, and is treated as such). This
value is subject to garbage collection, since it will be deleted when
the value changes. This is preferable and the above flag is only
retained for compatibility reasons (it can still be useful in library
mode).
The library syntax is Mod0"(x,y,"flag")". Also available are
* for flag" = 1": gmodulo"(x,y)".
* for flag" = 0": gmodulcp"(x,y)".
Pol"(x,{v = x})"
transforms the object "x" into a polynomial with main variable "v". If
"x" is a scalar, this gives a constant polynomial. If "x" is a power
series, the effect is identical to "truncate" (see there), i.e. it
chops off the "O(X^k)". If "x" is a vector, this function creates the
polynomial whose coefficients are given in "x", with "x[1]" being the
leading coefficient (which can be zero).
Warning: this is not a substitution function. It is intended to be
quick and dirty. So if you try "Pol(a,y)" on the polynomial "a = x+y",
you will get "y+y", which is not a valid PARI object.
The library syntax is gtopoly"(x,v)", where "v" is a variable number.
Polrev"(x,{v = x})"
transform the object "x" into a polynomial with main variable "v". If
"x" is a scalar, this gives a constant polynomial. If "x" is a power
series, the effect is identical to "truncate" (see there), i.e. it
chops off the "O(X^k)". If "x" is a vector, this function creates the
polynomial whose coefficients are given in "x", with "x[1]" being the
constant term. Note that this is the reverse of "Pol" if "x" is a vec-
tor, otherwise it is identical to "Pol".
The library syntax is gtopolyrev"(x,v)", where "v" is a variable num-
ber.
Qfb"(a,b,c,{D = 0.})"
creates the binary quadratic form "ax^2+bxy+cy^2". If "b^2-4ac > 0",
initialize Shanks' distance function to "D".
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})"
transforms the object "x" into a power series with main variable "v"
("x" by default). If "x" is a scalar, this gives a constant power
series with precision given by the default "serieslength" (correspond-
ing to the C global variable "precdl"). If "x" is a polynomial, the
precision is the greatest of "precdl" and the degree of the polynomial.
If "x" is a vector, the precision is similarly given, and the coeffi-
cients of the vector are understood to be the coefficients of the power
series starting from the constant term (i.e. the reverse of the func-
tion "Pol").
The warning given for "Pol" 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 = []})"
converts "x" into a set, i.e. into a row vector with strictly increas-
ing entries. "x" can be of any type, but is most useful when "x" is
already a vector. The components of "x" are put in canonical form (type
"t_STR") so as to be easily sorted. To recover an ordinary "GEN" from
such an element, you can apply "eval" to it.
The library syntax is gtoset"(x)".
Str"({x = ""},{"flag" = 0})"
converts "x" into a character string (type "t_STR", the empty string if
"x" is omitted). To recover an ordinary "GEN" from a string, apply
"eval" to it. The arguments of "Str" are evaluated in string context
(see "Label se:strings"). If flag is set, treat "x" as a filename and
perform environment expansion on the string. This feature can be used
to read environment variable values.
? i = 1; Str("x" i)
%1 = "x1"
? eval(%)
%2 = x1;
? Str("$HOME", 1)
%3 = "/home/pari"
The library syntax is strtoGENstr"(x,"flag")". This function is mostly
useless in library mode. Use the pair "strtoGEN"/"GENtostr" to convert
between "char*" and "GEN".
Vec"({x = []})"
transforms the object "x" into a row vector. The vector will be with
one component only, except when "x" is a vector/matrix or a quadratic
form (in which case the resulting vector is simply the initial object
considered as a row vector), but more importantly when "x" is a polyno-
mial or a power series. In the case of a polynomial, the coefficients
of the vector start with the leading coefficient of the polynomial,
while for power series only the significant coefficients are taken into
account, but this time by increasing order of degree.
The library syntax is gtovec"(x)".
binary"(x)"
outputs the vector of the binary digits of "|x|". Here "x" can be an
integer, a real number (in which case the result has two components,
one for the integer part, one for the fractional part) or a vec-
tor/matrix.
The library syntax is binaire"(x)".
bitand"(x,y)"
bitwise "and" of two integers "x" and "y", that is the integer
sum" (x_i and y_i) 2^i"
Negative numbers behave as if modulo a huge power of 2.
The library syntax is gbitand"(x,y)".
bitneg"(x,{n = -1})"
bitwise negation of an integer "x", truncated to "n" bits, that is the
integer
sum"_{i = 0}^n 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.
Negative numbers behave as if modulo a huge power of 2.
The library syntax is gbitneg"(x)".
bitnegimply"(x,y)"
bitwise negated imply of two integers "x" and "y" (or "not" "(x ==>
y)"), that is the integer
sum" (x_i and not(y_i)) 2^i"
Negative numbers behave as if modulo a huge power of 2.
The library syntax is gbitnegimply"(x,y)".
bitor"(x,y)"
bitwise (inclusive) "or"
of two integers "x" and "y", that is the integer
sum" (x_i or y_i) 2^i"
Negative numbers behave as if modulo a huge power of 2.
The library syntax is gbitor"(x,y)".
bittest"(x,n)"
outputs the "n^{th}" bit of "|x|" starting from the right (i.e. the
coefficient of "2^n" in the binary expansion of "x"). The result is 0
or 1. To extract several bits at once as a vector, pass a vector for
"n".
The library syntax is bittest"(x,n)", where "n" and the result are
"long"s.
bitxor"(x,y)"
bitwise (exclusive) "or"
of two integers "x" and "y", that is the integer
sum" (x_i xor y_i) 2^i"
Negative numbers behave as if modulo a huge power of 2.
The library syntax is gbitxor"(x,y)".
ceil"(x)"
ceiling of "x". When "x" is in R, the result is the smallest integer
greater than or equal to "x". Applied to a rational function, ceil(x)
returns the euclidian quotient of the numerator by the denominator.
The library syntax is gceil"(x)".
centerlift"(x,{v})"
lifts an element "x = a mod n" of Z"/n"Z to "a" in Z, and similarly
lifts a polmod to a polynomial. This is the same as "lift" except that
in the particular case of elements of Z"/n"Z, the lift "y" is such that
"-n/2 < y <= n/2". If "x" is of type fraction, complex, quadratic,
polynomial, power series, rational function, vector or matrix, the lift
is done for each coefficient. Real and "p"-adics are forbidden.
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)" = "cen-
terlift0(x,-1)".
changevar"(x,y)"
creates a copy of the object "x" where its variables are modified
according to the permutation specified by the vector "y". For example,
assume that the variables have been introduced in the order "x", "a",
"b", "c". Then, if "y" is the vector "[x,c,a,b]", the variable "a" will
be replaced by "c", "b" by "a", and "c" by "b", "x" being unchanged.
Note that the permutation must be completely specified, e.g. "[c,a,b]"
would not work, since this would replace "x" by "c", and leave "a" and
"b" unchanged (as well as "c" which is the fourth variable of the ini-
tial list). In particular, the new variable names must be distinct.
The library syntax is changevar"(x,y)".
components of a PARI object
There are essentially three ways to extract the components from 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 compo-
nents 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 func-
tion
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 poly-
nomial of degree zero.
The library syntax is truecoeff"(x,n)".
The third method is specific to vectors or matrices under 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}" row of "x",
and "x[,n]" represents the "n^{th}" column of "x".
Finally note that in library mode, the macros coeff and mael are avail-
able to deal with the non-recursivity of the "GEN" type from the com-
piler's point of view. See the discussion on typecasts in Chapter 4.
conj"(x)"
conjugate of "x". The meaning of this is clear, except that for real
quadratic numbers, it means conjugation in the real quadratic field.
This function has no effect on integers, reals, integermods, fractions
or "p"-adics. The only forbidden type is polmod (see "conjvec" for
this).
The library syntax is gconj"(x)".
conjvec"(x)"
conjugate vector representation of "x". If "x" is a polmod, equal to
"Mod""(a,q)", this gives a vector of length degree(q) containing the
complex embeddings of the polmod if "q" has integral or rational coef-
ficients, and the conjugates of the polmod if "q" has some integermod
coefficients. The order is the same as that of the "polroots" func-
tions. If "x" is an integer or a rational number, the result is "x". If
"x" is a (row or column) vector, the result is a matrix whose columns
are the conjugate vectors of the individual elements of "x".
The library syntax is conjvec"(x,"prec")".
denominator"(x)"
lowest denominator of "x". The meaning of this is clear when "x" is a
rational number or function. When "x" is an integer or a polynomial,
the result is equal to 1. When "x" is a vector or a matrix, the lowest
common denominator of the components of "x" is computed. All other
types are forbidden.
The library syntax is denom"(x)".
floor"(x)"
floor of "x". When "x" is in R, the result is the largest integer
smaller than or equal to "x". Applied to a rational function, floor(x)
returns the euclidian quotient of the numerator by the denominator.
The library syntax is gfloor"(x)".
frac"(x)"
fractional part of "x". Identical to "x-floor(x)". If "x" is real, the
result is in "[0,1[".
The library syntax is gfrac"(x)".
imag"(x)"
imaginary part of "x". When "x" is a quadratic number, this is the
coefficient of omega in the ``canonical'' integral basis "(1,"omega")".
The library syntax is gimag"(x)".
length"(x)"
number of non-code words in "x" really used (i.e. the effective length
minus 2 for integers and polynomials). In particular, the degree of a
polynomial is equal to its length minus 1. If "x" has type "t_STR",
output number of letters.
The library syntax is glength"(x)" and the result is a C long.
lift"(x,{v})"
lifts an element "x = a mod n" of Z"/n"Z to "a" in Z, and similarly
lifts a polmod to a polynomial if "v" is omitted. Otherwise, lifts
only polmods with main variable "v" (if "v" does not occur in "x",
lifts only intmods). If "x" is of type fraction, complex, quadratic,
polynomial, power series, rational function, vector or matrix, the lift
is done for each coefficient. Forbidden types for "x" are reals and
"p"-adics.
The library syntax is lift0"(x,v)", where "v" is a "long" and an omit-
ted "v" is coded as "-1". Also available is lift"(x)" = "lift0(x,-1)".
norm"(x)"
algebraic norm of "x", i.e. the product of "x" with its conjugate (no
square roots are taken), or conjugates for polmods. For vectors and
matrices, the norm is taken componentwise and hence is not the
"L^2"-norm (see "norml2"). Note that the norm of an element of R is its
square, so as to be compatible with the complex norm.
The library syntax is gnorm"(x)".
norml2"(x)"
square of the "L^2"-norm of "x". "x" must be a (row or column) vector.
The library syntax is gnorml2"(x)".
numerator"(x)"
numerator of "x". When "x" is a rational number or function, the mean-
ing is clear. When "x" is an integer or a polynomial, the result is "x"
itself. When "x" is a vector or a matrix, then numerator(x) is defined
to be "denominator(x)*x". All other types are forbidden.
The library syntax is numer"(x)".
numtoperm"(n,k)"
generates the "k"-th permutation (as a row vector of length "n") of the
numbers 1 to "n". The number "k" is taken modulo "n!", i.e. inverse
function of "permtonum".
The library syntax is permute"(n,k)", where "n" is a "long".
padicprec"(x,p)"
absolute "p"-adic precision of the object "x". This is the minimum
precision of the components of "x". 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.
The library syntax is padicprec"(x,p)" and the result is a "long" inte-
ger.
permtonum"(x)"
given a permutation "x" on "n" elements, gives the number "k" such that
"x = numtoperm(n,k)", i.e. inverse function of "numtoperm".
The library syntax is permuteInv"(x)".
precision"(x,{n})"
gives the precision in decimal digits of the PARI object "x". If "x" is
an exact object, the largest single precision integer is returned. If
"n" is not omitted, creates a new object equal to "x" with a new preci-
sion "n". This is to be understood as follows:
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 decimal digits.
If "n" is smaller than the precision of "x", "x" is truncated, other-
wise "x" is extended with zeros.
For "x" a "p"-adic or a power series, "n" is the desired number of sig-
nificant "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 polyno-
mial 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}})"
gives a random integer between 0 and "N-1". "N" can be arbitrary large.
This is an internal PARI function and does not depend on the system's
random number generator. Note that the resulting integer is obtained by
means of linear congruences and will not be well distributed in arith-
metic progressions.
The library syntax is genrand"(N)".
real"(x)"
real part of "x". In the case where "x" is a quadratic number, this is
the coefficient of 1 in the ``canonical'' integral basis "(1,"omega")".
The library syntax is greal"(x)".
round"(x,{&e})"
If "x" is in R, rounds "x" to the nearest integer and sets "e" to the
number of error bits, that is the binary exponent of the difference
between the original and the rounded value (the ``fractional part'').
If the exponent of "x" is too large compared to its precision (i.e. "e
> 0"), the result is undefined and an error occurs if "e" was not
given.
Important remark: note that, contrary to the other truncation func-
tions, 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 tries to simplify the object "x" as much as it can. The
simplifications do not concern rational functions (which PARI automati-
cally tries to simplify), but type changes. Specifically, a complex or
quadratic number whose imaginary part is exactly equal to 0 (i.e. not a
real zero) is converted to its real part, and a polynomial of degree
zero is converted to its constant term. For all types, this of course
occurs recursively. This function is useful in any case, but in partic-
ular before the use of arithmetic functions which expect integer argu-
ments, and not for example a complex number of 0 imaginary part and
integer real part (which is however printed as an integer).
The library syntax is simplify"(x)".
sizebyte"(x)"
outputs the total number of bytes occupied by the tree representing the
PARI object "x".
The library syntax is taille2"(x)" which returns a "long". The function
taille returns the number of words instead.
sizedigit"(x)"
outputs a quick bound for the number of decimal digits of (the compo-
nents of) "x", off by at most 1. If you want the exact value, you can
use "length(Str(x))", which is much slower.
The library syntax is sizedigit"(x)" which returns a "long".
truncate"(x,{&e})"
truncates "x" and sets "e" to the number of error bits. When "x" is in
R, this means that the part after the decimal point is chopped away,
"e" is the binary exponent of the difference between the original and
the truncated value (the ``fractional part''). If the exponent of "x"
is too large compared to its precision (i.e. "e > 0"), the result is
undefined and an error occurs if "e" was not given. The function
applies componentwise on rational functions and vector / matrices; "e"
is then the maximal number of error bits.
Note a very special use of "truncate": when applied to a power series,
it transforms it into a polynomial or a rational function with denomi-
nator 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)"
computes the highest exponent of "p" dividing "x". If "p" is of type
integer, "x" must be an integer, an integermod whose modulus is divisi-
ble by "p", a fraction, a "q"-adic number with "q = p", or a polynomial
or power series in which case the valuation is the minimum of the valu-
ation of the coefficients.
If "p" is of type polynomial, "x" must be of type polynomial or ratio-
nal 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)"
gives the main variable of the object "x", and "p" if "x" is a "p"-adic
number. Gives an error if "x" has no variable associated to it. Note
that this function is useful only in GP, since in library mode the
function "gvar" is more appropriate.
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 number of "x" if it exists, "BIG-
INT" otherwise.
Transcendental functions
As a general rule, which of course in some cases may have exceptions,
transcendental functions operate in the following way:
* If the argument is either an integer, a real, a rational, a complex
or a quadratic number, it is, if necessary, first converted to a real
(or complex) number using the current precision held in the default
"realprecision". Note that only exact arguments are converted, while
inexact arguments such as reals are not.
Under GP this is transparent to the user, but when programming in
library mode, care must be taken to supply a meaningful parameter prec
as the last argument of the function if the first argument is an exact
object. This parameter is ignored if the argument is inexact.
Note that in library mode the precision argument prec is a word count
including codewords, i.e. represents the length in words of a real num-
ber, while under GP the precision (which is changed by the metacommand
"\p" or using "default(realprecision,...)") is the number of signifi-
cant decimal digits.
Note that some accuracies attainable on 32-bit machines cannot be
attained on 64-bit machines for parity reasons. For example the default
GP accuracy is 28 decimal digits on 32-bit machines, corresponding to
prec having the value 5, but this cannot be attained on 64-bit
machines.
After possible conversion, the function is computed. Note that even if
the argument is real, the result may be complex (e.g. "acos(2.0)" or
"acosh(0.0)"). Note also that the principal branch is always chosen.
* If the argument is an integermod or a "p"-adic, at present only a few
functions like "sqrt" (square root), "sqr" (square), "log", "exp", pow-
ering, "teichmuller" (Teichmueller character) and "agm" (arith-
metic-geometric mean) are implemented.
Note that in the case of a 2-adic number, sqr(x) may not be identical
to "x*x": for example if "x = 1+O(2^5)" and "y = 1+O(2^5)" then "x*y =
1+O(2^5)" while "sqr(x) = 1+O(2^6)". Here, "x * x" yields the same
result as sqr(x) since the two operands are known to be identical. The
same statement holds true for "p"-adics raised to the power "n", where
"v_p(n) > 0".
Remark: note that if we wanted to be strictly consistent with the PARI
philosophy, we should have "x*y = (4 mod 8)" and "sqr(x) = (4 mod 32)"
when both "x" and "y" are congruent to 2 modulo 4. However, since
integermod is an exact object, PARI assumes that the modulus must not
change, and the result is hence "(0 mod 4)" in both cases. On the other
hand, "p"-adics are not exact objects, hence are treated differently.
* If the argument is a polynomial, power series or rational function,
it is, if necessary, first converted to a power series using the cur-
rent precision held in the variable "precdl". Under GP this again is
transparent to the user. When programming in library mode, however, the
global variable "precdl" must be set before calling the function if the
argument has an exact type (i.e. not a power series). Here "precdl" is
not an argument of the function, but a global variable.
Then the Taylor series expansion of the function around "X = 0" (where
"X" is the main variable) is computed to a number of terms depending on
the number of terms of the argument and the function being computed.
* If the argument is a vector or a matrix, the result is the component-
wise evaluation of the function. In particular, transcendental func-
tions on square matrices, which are not implemented in the present ver-
sion 2.2.0 (see Appendix B however), will have a slightly different
name if they are implemented some day.
^
If "y" is not of type integer, "x^y" has the same effect as
"exp(y*ln(x))". It can be applied to "p"-adic numbers as well as to the
more usual types.
The library syntax is gpow"(x,y,"prec")".
Euler
Euler's constant 0.57721.... Note that "Euler" is one of the few spe-
cial reserved names which cannot be used for variables (the others are
"I" and "Pi", as well as all function names).
The library syntax is mpeuler"("prec")" where prec 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 complex number sqrt "{-1}".
The library syntax is the global variable "gi" (of type "GEN").
Pi
the constant Pi (3.14159...).
The library syntax is mppi"("prec")" where prec 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)"
absolute value of "x" (modulus if "x" is complex). Power series and
rational functions are not allowed. Contrary to most transcendental
functions, an exact argument is not converted to a real number before
applying "abs" and an exact result is returned if possible.
? abs(-1)
%1 = 1
? abs(3/7 + 4/7*I)
%2 = 5/7
? abs(1 + I)
%3 = 1.414213562373095048801688724
If "x" is a polynomial, returns "-x" if the leading coefficient is real
and negative else returns "x". For a power series, the constant coeffi-
cient is considered instead.
The library syntax is gabs"(x,"prec")".
acos"(x)"
principal branch of "cos^{-1}(x)", i.e. such that "Re(acos(x)) belongs
to [0,"Pi"]". If "x belongs to "R and "|x| > 1", then acos(x) is com-
plex.
The library syntax is gacos"(x,"prec")".
acosh"(x)"
principal branch of "cosh^{-1}(x)", i.e. such that "Im(acosh(x))
belongs to [0,"Pi"]". If "x belongs to "R and "x < 1", then acosh(x) is
complex.
The library syntax is gach"(x,"prec")".
agm"(x,y)"
arithmetic-geometric mean of "x" and "y". In the case of complex or
negative numbers, the principal square root is always chosen. "p"-adic
or power series arguments are also allowed. Note that a "p"-adic agm
exists only if "x/y" is congruent to 1 modulo "p" (modulo 16 for "p =
2"). "x" and "y" cannot both be vectors or matrices.
The library syntax is agm"(x,y,"prec")".
arg"(x)"
argument of the complex number "x", such that "-"Pi" < arg(x) <= "Pi.
The library syntax is garg"(x,"prec")".
asin"(x)"
principal branch of "sin^{-1}(x)", i.e. such that "Re(asin(x)) belongs
to [-"Pi"/2,"Pi"/2]". If "x belongs to "R and "|x| > 1" then asin(x) is
complex.
The library syntax is gasin"(x,"prec")".
asinh"(x)"
principal branch of "sinh^{-1}(x)", i.e. such that "Im(asinh(x))
belongs to [-"Pi"/2,"Pi"/2]".
The library syntax is gash"(x,"prec")".
atan"(x)"
principal branch of "tan^{-1}(x)", i.e. such that "Re(atan(x)) belongs
to ]-"Pi"/2,"Pi"/2[".
The library syntax is gatan"(x,"prec")".
atanh"(x)"
principal branch of "tanh^{-1}(x)", i.e. such that "Im(atanh(x))
belongs to ]-"Pi"/2,"Pi"/2]". If "x belongs to "R and "|x| > 1" then
atanh(x) is complex.
The library syntax is gath"(x,"prec")".
bernfrac"(x)"
Bernoulli number "B_x", where "B_0 = 1", "B_1 = -1/2", "B_2 = 1/6",...,
expressed as a rational number. The argument "x" should be of type
integer.
The library syntax is bernfrac"(x)".
bernreal"(x)"
Bernoulli number "B_x", as "bernfrac", but "B_x" is returned as a real
number (with the current precision).
The library syntax is bernreal"(x,"prec")".
bernvec"(x)"
creates a vector containing, as rational numbers, the Bernoulli numbers
"B_0", "B_2",..., "B_{2x}". These Bernoulli numbers can then be used as
follows. Assume that this vector has been put into a variable, say
"bernint". Then you can define under GP:
bern(x) =
{
if (x == 1, return(-1/2));
if (x < 0 || x % 2, return(0));
bernint[x/2+1]
}
and then bern(k) gives the Bernoulli number of index "k" as a rational
number, exactly as bernreal(k) gives it as a real number. If you need
only a few values, calling bernfrac(k) each time will be much more
efficient than computing the huge vector above.
The library syntax is bernvec"(x)".
besseljh"(n,x)"
"J"-Bessel function of half integral index. More precisely,
"besseljh(n,x)" computes "J_{n+1/2}(x)" where "n" must be of type inte-
ger, and "x" is any element of C. In the present version 2.2.0, this
function is not very accurate when "x" is small.
The library syntax is jbesselh"(n,x,"prec")".
besselk"("nu",x,{"flag" = 0})"
"K"-Bessel function of index nu (which can be complex) and argument
"x". Only real and positive arguments "x" are allowed in the present
version 2.2.0. If flag is equal to 1, uses another implementation of
this function which is often faster.
The library syntax is kbessel"("nu",x,"prec")" and
kbessel2"("nu",x,"prec")" respectively.
cos"(x)"
cosine of "x".
The library syntax is gcos"(x,"prec")".
cosh"(x)"
hyperbolic cosine of "x".
The library syntax is gch"(x,"prec")".
cotan"(x)"
cotangent of "x".
The library syntax is gcotan"(x,"prec")".
dilog"(x)"
principal branch of the dilogarithm of "x", i.e. analytic continuation
of the power series log "_2(x) = "sum"_{n >= 1}x^n/n^2".
The library syntax is dilog"(x,"prec")".
eint1"(x,{n})"
exponential integral int"_x^ oo (e^{-t})/(t)dt" ("x belongs to "R)
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)"
complementary error function "(2/" sqrt Pi")"int"_x^ oo e^{-t^2}dt".
The library syntax is erfc"(x,"prec")".
eta"(x,{"flag" = 0})"
Dedekind's eta function, without the "q^{1/24}". This means the follow-
ing: if "x" is a complex number with positive imaginary part, the
result is prod"_{n = 1}^ oo (1-q^n)", where "q = e^{2i"Pi" x}". If "x"
is a power series (or can be converted to a power series) with positive
valuation, the result is prod"_{n = 1}^ oo (1-x^n)".
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)"
exponential of "x". "p"-adic arguments with positive valuation are
accepted.
The library syntax is gexp"(x,"prec")".
gammah"(x)"
gamma function evaluated at the argument "x+1/2". When "x" is an inte-
ger, this is much faster than using "gamma(x+1/2)".
The library syntax is ggamd"(x,"prec")".
gamma"(x)"
gamma function of "x". In the present version 2.2.0 the "p"-adic gamma
function is not implemented.
The library syntax is ggamma"(x,"prec")".
hyperu"(a,b,x)"
"U"-confluent hypergeometric function with parameters "a" and "b". The
parameters "a" and "b" can be complex but the present implementation
requires "x" to be positive.
The library syntax is hyperu"(a,b,x,"prec")".
incgam"(s,x,{y})"
incomplete gamma function.
"x" must be positive and "s" real. The result returned is int"_x^ oo
e^{-t}t^{s-1}dt". When "y" is given, assume (of course without check-
ing!) that "y = "Gamma"(s)". For small "x", this will tremendously
speed up the computation.
The library syntax is incgam"(s,x,"prec")" and incgam4"(s,x,y,"prec")",
respectively. There exist also the functions incgam1 and incgam2 which
are used for internal purposes.
incgamc"(s,x)"
complementary incomplete gamma function.
The arguments "s" and "x" must be positive. The result returned is
int"_0^x e^{-t}t^{s-1}dt", when "x" is not too large.
The library syntax is incgam3"(s,x,"prec")".
log"(x,{"flag" = 0})"
principal branch of the natural logarithm of "x", i.e. such that
"Im(ln(x)) belongs to ]-"Pi","Pi"]". The result is complex (with imag-
inary part equal to Pi) if "x belongs to "R and "x < 0".
"p"-adic arguments are also accepted for "x", with the convention that
ln "(p) = 0". Hence in particular exp "(" ln "(x))/x" will not in
general be equal to 1 but to a "(p-1)"-th root of unity (or "+-1" if "p
= 2") times a power of "p".
If flag is equal to 1, use an agm formula suggested by Mestre, when "x"
is real, otherwise identical to "log".
The library syntax is glog"(x,"prec")" or glogagm"(x,"prec")".
lngamma"(x)"
principal branch of the logarithm of the gamma function of "x". Can
have much larger arguments than "gamma" itself. In the present version
2.2.0, the "p"-adic "lngamma" function is not implemented.
The library syntax is glngamma"(x,"prec")".
polylog"(m,x,{"flag" = 0})"
one of the different polylogarithms, depending on flag:
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". The
program uses the power series when "|x|^2 <= 1/2", and the power series
expansion in log "(x)" otherwise. It is valid in a large domain (at
least "|x| < 230"), but should not be used too far away from the unit
circle since it is then better to use the functional equation linking
the value at "x" to the value at "1/x", which takes a trivial form for
the variant below. Power series, polynomial, rational and vector/matrix
arguments are allowed.
For the variants to follow we need a notation: let Re "_m" denotes Re
or Im depending whether "m" is odd or even.
If flag" = 1": modified "m^th" polylogarithm of "x", called "~ D_m(x)"
in Zagier, 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": modified "m^th" polylogarithm of "x", called D_m(x) in
Zagier, 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": another modified "m^th" polylogarithm of "x", called
P_m(x) in Zagier, 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 psi-function of "x", i.e. the logarithmic derivative
Gamma"'(x)/"Gamma"(x)".
The library syntax is gpsi"(x,"prec")".
sin"(x)"
sine of "x".
The library syntax is gsin"(x,"prec")".
sinh"(x)"
hyperbolic sine of "x".
The library syntax is gsh"(x,"prec")".
sqr"(x)"
square of "x". This operation is not completely straightforward,
i.e. identical to "x * x", since it can usually be computed more effi-
ciently (roughly one-half of the elementary multiplications can be
saved). Also, squaring a 2-adic number increases its precision. For
example,
? (1 + O(2^4))^2
%1 = 1 + O(2^5)
? (1 + O(2^4)) * (1 + O(2^4))
%2 = 1 + O(2^4)
Note that this function is also called whenever one multiplies two
objects which are known to be 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)"
principal branch of the square root of "x", i.e. such that
"Arg(sqrt(x)) belongs to ]-"Pi"/2, "Pi"/2]", or in other words such
that Re "(sqrt(x)) > 0" or Re "(sqrt(x)) = 0" and
Im "(sqrt(x)) >= 0". If "x belongs to "R and "x < 0", then the result
is complex with positive imaginary part.
Integermod 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 inte-
germods) is in the interval "[0,p/2]". When the argument is an inte-
germod a non-prime (or a non-prime-adic), the result is undefined.
The library syntax is gsqrt"(x,"prec")".
sqrtn"(x,n,{&z})"
principal branch of the "n"th root of "x", i.e. such that "Arg(sqrt(x))
belongs to ]-"Pi"/n, "Pi"/n]".
Integermod a prime and "p"-adics are allowed as arguments.
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.
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)"
tangent of "x".
The library syntax is gtan"(x,"prec")".
tanh"(x)"
hyperbolic tangent of "x".
The library syntax is gth"(x,"prec")".
teichmuller"(x)"
Teichmueller character of the "p"-adic number "x".
The library syntax is teich"(x)".
theta"(q,z)"
Jacobi sine theta-function.
The library syntax is theta"(q,z,"prec")".
thetanullk"(q,k)"
"k"-th derivative at "z = 0" of "theta(q,z)".
The library syntax is thetanullk"(q,k,"prec")", where "k" is a "long".
weber"(x,{"flag" = 0})"
one of Weber's three "f" functions. If flag" = 0", returns
"f(x) = " exp "(-i"Pi"/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")", or wf"(x,"prec")",
wf1"(x,"prec")" or wf2"(x,"prec")".
zeta"(s)"
Riemann's zeta function zeta"(s) = "sum"_{n >= 1}n^{-s}", computed
using the Euler-Maclaurin summation formula, except when "s" is of type
integer, in which case it is computed using Bernoulli numbers for "s <=
0" or "s > 0" and even, and using modular forms for "s > 0" and odd.
The library syntax is gzeta"(s,"prec")".
Arithmetic functions
These functions are by definition functions whose natural domain of
definition is either Z (or Z"_{ > 0}"), or sometimes polynomials over a
base ring. Functions which concern polynomials exclusively will be
explained in the next section. The way these functions are used is com-
pletely different from transcendental functions: in general only the
types integer and polynomial are accepted as arguments. If a vector or
matrix type is given, the function will be applied on each coefficient
independently.
In the present version 2.2.0, all arithmetic functions in the narrow
sense of the word --- Euler's totient function, the Moebius function,
the sums over divisors or powers of divisors etc.--- call, after trial
division by small primes, the same versatile factoring machinery
described under "factorint". It includes Shanks SQUFOF, Pollard Rho,
ECM and MPQS stages, and has an early exit option for the functions
moebius and (the integer function underlying) issquarefree. Note that
it relies on a (fairly strong) probabilistic primality test: numbers
found to be strong pseudo-primes after 10 successful trials of the
Rabin-Miller test are declared primes.
addprimes"({x = []})"
adds the primes contained in the vector "x" (or the single integer "x")
to the table computed upon GP initialization (by "pari_init" in library
mode), and returns a row vector whose first entries contain all primes
added by the user and whose last entries have been filled up with 1's.
In total the returned row vector has 100 components. Whenever "factor"
or "smallfact" is subsequently called, first the primes in the table
computed by "pari_init" will be checked, and then the additional primes
in this table. If "x" is empty or omitted, just returns the current
list of extra primes.
The entries in "x" are not checked for primality. They need only be
positive integers not divisible by any of the pre-computed primes. It's
in fact a nice trick to add composite numbers, which for example the
function "factor(x,0)" was not able to factor. In case the message
``impossible inverse modulo "<"some integermod">"'' shows up after-
wards, you have just stumbled over a non-trivial factor. Note that the
arithmetic functions in the narrow sense, like eulerphi, do not use
this extra table.
The present PARI version 2.2.0 allows up to 100 user-specified primes
to be appended to the table. This limit may be changed by altering
"NUMPRTBELT" in file "init.c". To remove primes from the list use
"removeprimes".
The library syntax is addprimes"(x)".
bestappr"(x,k)"
if "x belongs to "R, finds the best rational approximation to "x" with
denominator at most equal to "k" using continued fractions.
The library syntax is bestappr"(x,k)".
bezout"(x,y)"
finds "u" and "v" minimal in a natural sense such that "x*u+y*v =
gcd(x,y)". The arguments must be both integers or both polynomials, and
the result is a row vector with three components "u", "v", and
"gcd(x,y)".
The library syntax is vecbezout"(x,y)" to get the vector, or gbe-
zout"(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)"
as "bezout", with the resultant of "x" and "y" replacing the gcd.
The library syntax is vecbezoutres"(x,y)" to get the vector, or subre-
sext"(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)"
number of prime divisors of "|x|" counted with multiplicity. "x" must
be an integer.
The library syntax is bigomega"(x)", the result is a "long".
binomial"(x,y)"
binomial coefficient "\binom x y". Here "y" must be an integer, but
"x" can be any PARI object.
The library syntax is binome"(x,y)", where "y" must be a "long".
chinese"(x,y)"
if "x" and "y" are both integermods or both polmods, creates (with the
same type) a "z" in the same residue class as "x" and in the same
residue class as "y", if it is possible.
This function also allows vector and matrix arguments, in which case
the operation is recursively applied to each component of the vector or
matrix. For polynomial arguments, it is applied to each coefficient.
Finally "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 chinois"(x,y)".
content"(x)"
computes the gcd of all the coefficients of "x", when this gcd makes
sense. If "x" is a scalar, this simply returns "x". If "x" is a polyno-
mial (and by extension a power series), it gives the usual content of
"x". If "x" is a rational function, it gives the ratio of the contents
of the numerator and the denominator. Finally, if "x" is a vector or a
matrix, it gives the gcd of all the entries.
The library syntax is content"(x)".
contfrac"(x,{b},{lmax})"
creates the row vector whose components are the partial quotients of
the continued fraction expansion of "x", the number of partial quo-
tients being limited to "lmax". If "x" is a real number, the expansion
stops at the last significant partial quotient if "lmax" is omitted.
"x" can also be a rational function or a power series.
If a vector "b" is supplied, the numerators will be equal to the coef-
ficients of "b". The length of the result is then equal to the length
of "b", unless a partial remainder is encountered which is equal to
zero. In which case the expansion stops. In the case of real numbers,
the stopping criterion is thus different from the one mentioned above
since, if "b" is too long, some partial quotients may not be signifi-
cant.
If "b" is an integer, the command is understood as "contfrac(x,lmax)".
The library syntax is contfrac0"(x,b,lmax)". Also available are
gboundcf"(x,lmax)", gcf"(x)", or gcf2"(b,x)", where "lmax" is a C inte-
ger.
contfracpnqn"(x)"
when "x" is a vector or a one-row matrix, "x" is considered as the list
of partial quotients "[a_0,a_1,...,a_n]" of a rational number, and the
result is the 2 by 2 matrix "[p_n,p_{n-1};q_n,q_{n-1}]" in the standard
notation of continued fractions, so "p_n/q_n =
a_0+1/(a_1+...+1/a_n)...)". If "x" is a matrix with two rows
"[b_0,b_1,...,b_n]" and "[a_0,a_1,...,a_n]", this is then considered as
a generalized continued fraction and we have similarly "p_n/q_n =
1/b_0(a_0+b_1/(a_1+...+b_n/a_n)...)". Note that in this case one usu-
ally has "b_0 = 1".
The library syntax is pnqn"(x)".
core"(n,{"flag" = 0})"
if "n" is a non-zero integer written as "n = df^2" with "d" squarefree,
returns "d". If flag is non-zero, returns the two-element row vector
"[d,f]".
The library syntax is core0"(n,"flag")". Also available are core"(n)"
( = core"(n,0)") and core2"(n)" ( = core"(n,1)").
coredisc"(n,{"flag"})"
if "n" is a non-zero integer written as "n = df^2" with "d" fundamental
discriminant (including 1), returns "d". If flag is non-zero, returns
the two-element row vector "[d,f]". Note that if "n" is not congruent
to 0 or 1 modulo 4, "f" will be a half integer and not an integer.
The library syntax is coredisc0"(n,"flag")". Also available are core-
disc"(n)" ( = coredisc"(n,0)") and coredisc2"(n)" ( = coredisc"(n,1)").
dirdiv"(x,y)"
"x" and "y" being vectors of perhaps different lengths but with "y[1] !
= 0" considered as Dirichlet series, computes the quotient of "x" by
"y", again as a vector.
The library syntax is dirdiv"(x,y)".
direuler"(p = a,b,"expr",{c})"
computes the Dirichlet series to "b" terms of the Euler product of
expression expr as "p" ranges through the primes from "a" to "b". expr
must be a polynomial or rational function in another variable than "p"
(say "X") and expr"(X)" is understood as the Dirichlet series (or more
precisely the local factor) expr"(p^{-s})". If "c" is present, output
only the first "c" coefficients in the series.
The library syntax is direuler"(entree *ep, GEN a, GEN b, char *expr)"
dirmul"(x,y)"
"x" and "y" being vectors of perhaps different lengths considered as
Dirichlet series, computes the product of "x" by "y", again as a vec-
tor.
The library syntax is dirmul"(x,y)".
divisors"(x)"
creates a row vector whose components are the positive divisors of the
integer "x" in increasing order. The factorization of "x" (as output by
"factor") can be used instead.
The library syntax is divisors"(x)".
eulerphi"(x)"
Euler's phi (totient) function of "|x|", in other words
"|("Z"/x"Z")^*|". "x" must be of type integer.
The library syntax is phi"(x)".
factor"(x,{"lim" = -1})"
general factorization function. If "x" is of type integer, rational,
polynomial or rational function, the result is a two-column matrix, the
first column being the irreducibles dividing "x" (prime numbers or
polynomials), and the second the exponents. If "x" is a vector or a
matrix, the factoring is done componentwise (hence the result is a vec-
tor or matrix of two-column matrices). By definition, 0 is factored as
"0^1".
If "x" is of type integer or rational, an argument lim can be added,
meaning that we look only for factors up to lim, or to "primelimit",
whichever is lowest (except when lim" = 0" where the effect is identi-
cal to setting lim" = primelimit"). Hence in this case, the remaining
part is not necessarily prime. 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 not know how to factor multivari-
ate polynomials.
Note that PARI tries to guess in a sensible way over which ring you
want to factor. Note also that factorization of polynomials is done up
to multiplication by a constant. In particular, the factors of rational
polynomials will have integer coefficients, and the content of a poly-
nomial or rational function is discarded and not included in the fac-
torization. If you need it, you can always ask for the content explic-
itly:
? 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.
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,{nf})"
"f" being any factorization, gives back the factored object. If a sec-
ond argument nf is supplied, "f" is assumed to be a prime ideal factor-
ization in the number field nf. The resulting ideal is given in HNF
form.
The library syntax is factorback"(f,"nf")", where an omitted nf is
entered as "NULL".
factorcantor"(x,p)"
factors the polynomial "x" modulo the prime "p", using distinct degree
plus Cantor-Zassenhaus. The coefficients of "x" must be operation-com-
patible with Z"/p"Z. The result is a two-column matrix, the first col-
umn being the irreducible polynomials dividing "x", and the second the
exponents. If you want only the degrees of the irreducible polynomials
(for example for computing an "L"-function), use "factormod(x,p,1)".
Note that the "factormod" algorithm is usually faster than "factorcan-
tor".
The library syntax is factcantor"(x,p)".
factorff"(x,p,a)"
factors the polynomial "x" in the field F"_q" defined by the irreduc-
ible polynomial "a" over F"_p". The coefficients of "x" must be opera-
tion-compatible with Z"/p"Z. The result is a two-column matrix, the
first column being the irreducible polynomials dividing "x", and the
second the exponents. It is recommended to use for the variable of "a"
(which will be used as variable of a polmod) a name distinct from the
other variables used, so that a "lift()" of the result will be legible.
If all the coefficients of "x" are in F"_p", a much faster algorithm is
applied, using the computation of isomorphisms between finite fields.
The library syntax is factmod9"(x,p,a)".
factorial"(x)" or "x!"
factorial of "x". The expression "x!" gives a result which is an inte-
ger, while factorial(x) gives a real number.
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})"
factors the integer n using a combination of the Shanks SQUFOF and Pol-
lard Rho method (with modifications due to Brent), Lenstra's ECM (with
modifications by Montgomery), and MPQS (the latter adapted from the
LiDIA code with the kind permission of the LiDIA maintainers), as well
as a search for pure powers with exponents" <= 10". The output is a
two-column matrix as for "factor".
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) prob-
abilistic primality test is used; thus composites might (very rarely)
not be detected.
The machinery underlying this function is still in a somewhat experi-
mental state, but should be much faster on average than pure ECM as
used by all PARI versions up to 2.0.8, at the expense of heavier memory
use. You are invited to play with the flag settings and watch the
internals at work by using GP's "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 hap-
pening, please let us know.
The library syntax is factorint"(n,"flag")".
factormod"(x,p,{"flag" = 0})"
factors the polynomial "x" modulo the prime integer "p", using
Berlekamp. The coefficients of "x" must be operation-compatible with
Z"/p"Z. The result is a two-column matrix, the first column being the
irreducible polynomials dividing "x", and the second the exponents. If
flag is non-zero, outputs only the degrees of the irreducible polynomi-
als (for example, for computing an "L"-function). A different algorithm
for computing the mod "p" factorization is "factorcantor" which is
sometimes faster.
The library syntax is factormod"(x,p,"flag")". Also available are fact-
mod"(x,p)" (which is equivalent to factormod"(x,p,0)") and simplefact-
mod"(x,p)" ( = factormod"(x,p,1)").
fibonacci"(x)"
"x^{th}" Fibonacci number.
The library syntax is fibo"(x)". "x" must be a "long".
ffinit"(p,n,{v = x})"
computes a monic polynomial of degree "n" which is irreducible over
F"_p". For instance if "P = ffinit(3,2,y)", you can represent elements
in F"_{3^2}" as polmods modulo "P".
The library syntax is ffinit"(p,n,v)", where "v" is a variable number.
gcd"(x,y,{"flag" = 0})"
creates the greatest common divisor of "x" and "y". "x" and "y" can be
of quite general types, for instance both rational numbers. Vec-
tor/matrix types are also accepted, in which case the GCD is taken
recursively on each component. Note that for these types, "gcd" is not
commutative.
If flag" = 0", use Euclid's algorithm.
If flag" = 1", use the modular gcd algorithm ("x" and "y" have to be
polynomials, with integer coefficients).
If flag" = 2", use the subresultant algorithm.
The library syntax is gcd0"(x,y,"flag")". Also available are
ggcd"(x,y)", modulargcd"(x,y)", and srgcd"(x,y)" corresponding to flag"
= 0", 1 and 2 respectively.
hilbert"(x,y,{p})"
Hilbert symbol of "x" and "y" modulo "p". If "x" and "y" are of type
integer or fraction, an explicit third parameter "p" must be supplied,
"p = 0" meaning the place at infinity. Otherwise, "p" needs not be
given, and "x" and "y" can be of compatible types integer, fraction,
real, integermod a prime (result is undefined if the modulus is not
prime), or "p"-adic.
The library syntax is hil"(x,y,p)".
isfundamental"(x)"
true (1) if "x" is equal to 1 or to the discriminant of a quadratic
field, false (0) otherwise.
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.
isprime"(x,{"flag" = 0})"
if flag" = 0" (default), true (1) if "x" is a strong pseudo-prime for
10 randomly chosen bases, false (0) otherwise.
If flag" = 1", use Pocklington-Lehmer ``P-1'' test. true (1) if "x" is
prime, false (0) otherwise.
If flag" = 2", use Pocklington-Lehmer ``P-1'' test and output a primal-
ity certificate as follows: return 0 if "x" is composite, 1 if "x" is a
small prime (currently strictly less than "341 550 071 728 321"), and a
matrix if "x" is a large prime. The matrix has three columns. The
first contains the prime factors "p", the second the corresponding ele-
ments "a_p" as in Proposition 8.3.1 in GTM 138, and the third the out-
put of isprime(p,2).
In the two last cases, the algorithm fails if one of the (strong
pseudo-)prime factors is not prime, but it should be exceedingly rare.
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. Also available is plisprime"(N,"flag")", corre-
sponding to gisprime"(x,"flag"+1)" if "x" is known to be of type inte-
ger.
ispseudoprime"(x)"
true (1) if "x" is a strong pseudo-prime for a randomly chosen base,
false (0) otherwise.
The library syntax is gispsp"(x)", but the simpler function ispsp"(x)"
which returns a "long" should be used if "x" is known to be of type
integer.
issquare"(x,{&n})"
true (1) if "x" is square, false (0) if not. "x" can be of any type. If
"n" is given and an exact square root had to be computed in the check-
ing process, puts that square root in "n". This is in particular the
case when "x" is an integer or a polynomial. This is not the case for
intmods (use quadratic reciprocity) or series (only check the leading
coefficient).
The library syntax is gcarrecomplet"(x,&n)". Also available is gcar-
reparfait"(x)".
issquarefree"(x)"
true (1) if "x" is squarefree, false (0) if not. Here "x" can be an
integer or a polynomial.
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 Moe-
bius function, and is computed as a multiplicative arithmetic function
much like the latter.
kronecker"(x,y)"
Kronecker (i.e. generalized Legendre) symbol "((x)/(y))". "x" and "y"
must be of type integer.
The library syntax is kronecker"(x,y)", the result (0 or "+- 1") is a
"long".
lcm"(x,y)"
least common multiple of "x" and "y", i.e. such that "lcm(x,y)*gcd(x,y)
= abs(x*y)".
The library syntax is glcm"(x,y)".
moebius"(x)"
Moebius mu-function of "|x|". "x" must be of type integer.
The library syntax is mu"(x)", the result (0 or "+- 1") is a "long".
nextprime"(x)"
finds the smallest prime greater than or equal to "x". "x" can be of
any real type. Note that if "x" is a prime, this function returns "x"
and not the smallest prime strictly larger than "x".
The library syntax is nextprime"(x)".
numdiv"(x)"
number of divisors of "|x|". "x" must be of type integer, and the
result is a "long".
The library syntax is numbdiv"(x)".
omega"(x)"
number of distinct prime divisors of "|x|". "x" must be of type inte-
ger.
The library syntax is omega"(x)", the result is a "long".
precprime"(x)"
finds the largest prime less than or equal to "x". "x" can be of any
real type. Returns 0 if "x <= 1". Note that if "x" is a prime, this
function returns "x" and not the largest prime strictly smaller than
"x".
The library syntax is precprime"(x)".
prime"(x)"
the "x^{th}" prime number, which must be among the precalculated
primes.
The library syntax is prime"(x)". "x" must be a "long".
primes"(x)"
creates a row vector whose components are the first "x" prime numbers,
which must be among the precalculated primes.
The library syntax is primes"(x)". "x" must be a "long".
qfbclassno"(x,{"flag" = 0})"
class number of the quadratic field of discriminant "x". In the present
version 2.2.0, a simple algorithm is used for "x > 0", so "x" should
not be too large (say "x < 10^7") for the time to be reasonable. On the
other hand, for "x < 0" one can reasonably compute classno("x") for
"|x| < 10^{25}", since the method used is Shanks' method which is in
"O(|x|^{1/4})". For larger values of "|D|", see "quadclassunit".
If flag" = 1", compute the class number using Euler products and the
functional equation. However, it is in "O(|x|^{1/2})".
Important warning. For "D < 0", this function often gives incorrect
results when the class group is non-cyclic, because the authors were
too lazy to implement Shanks' method completely. It is therefore
strongly recommended to use either the version with flag" = 1", the
function "qfbhclassno(-x)" if "x" is known to be a fundamental discrim-
inant, or the function "quadclassunit".
The library syntax is qfbclassno0"(x,"flag")". Also available are
classno"(x)" ( = qfbclassno"(x)"), classno2"(x)" ( = qfb-
classno"(x,1)"), and finally there exists the function hclassno"(x)"
which computes the class number of an imaginary quadratic field by
counting reduced forms, an "O(|x|)" algorithm. See also "qfbhclassno".
qfbcompraw"(x,y)"
composition of the binary quadratic forms "x" and "y", without reduc-
tion of the result. This is useful e.g. to compute a generating element
of an ideal.
The library syntax is compraw"(x,y)".
qfbhclassno"(x)"
Hurwitz class number of "x", where "x" is non-negative and congruent to
0 or 3 modulo 4. See also "qfbclassno".
The library syntax is hclassno"(x)".
qfbnucomp"(x,y,l)"
composition of the primitive positive definite binary quadratic forms
"x" and "y" using the NUCOMP and NUDUPL algorithms of Shanks (A la
Atkin). "l" is any positive constant, but for optimal speed, one should
take "l = |D|^{1/4}", where "D" is the common discriminant of "x" and
"y". When "x" and "y" do not have the same discriminant, the result is
undefined.
The library syntax is nucomp"(x,y,l)". The auxiliary function
nudupl"(x,l)" should be used instead for speed when "x = y".
qfbnupow"(x,n)"
"n"-th power of the primitive positive definite binary quadratic form
"x" using the NUCOMP and NUDUPL algorithms (see "qfbnucomp").
The library syntax is nupow"(x,n)".
qfbpowraw"(x,n)"
"n"-th power of the binary quadratic form "x", computed without doing
any reduction (i.e. using "qfbcompraw"). Here "n" must be non-negative
and "n < 2^{31}".
The library syntax is powraw"(x,n)" where "n" must be a "long" integer.
qfbprimeform"(x,p)"
prime binary quadratic form of discriminant "x" whose first coefficient
is the prime number "p". By abuse of notation, "p = 1" is a valid spe-
cial case which returns the unit form. Returns an error if "x" is not a
quadratic residue mod "p". In the case where "x > 0", the ``distance''
component of the form is set equal to zero according to the current
precision.
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"})"
reduces the binary quadratic form "x" (updating Shanks's distance func-
tion if "x" is indefinite). The binary digits of flag are toggles mean-
ing
1: perform a single reduction step
2: don't update Shanks's distance
"D", isqrtD, sqrtD, if present, supply the values of the discriminant,
"\lfloor " sqrt "{D}\rfloor", 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)").
quadclassunit"(D,{"flag" = 0},{"tech" = []})"
Buchmann-McCurley's sub-exponential algorithm for computing the class
group of a quadratic field of discriminant "D". If "D" is not fundamen-
tal, the function may or may not be defined, but usually is, and often
gives the right answer (a warning is issued). The more general function
"bnrinit" should be used to compute the class group of an order.
This function should be used instead of "qfbclassno" or "quadregula"
when "D < -10^{25}", "D > 10^{10}", or when the structure is wanted.
If flag is non-zero and "D > 0", computes the narrow class group and
regulator, instead of the ordinary (or wide) ones. In the current ver-
sion 2.2.0, this doesn't work at all : use the general function "bnf-
narrow".
Optional parameter tech is a row vector of the form "[c_1,c_2]", where
"c_1" and "c_2" are positive real numbers which control the execution
time and the stack size. To get maximum speed, set "c_2 = c". To get a
rigorous result (under GRH) you must take "c_2 = 6". Reasonable values
for "c" are between 0.1 and 2.
The result of this function is a vector "v" with 4 components if "D <
0", and 5 otherwise. The correspond respectively to
* "v[1]" : the class number
* "v[2]" : a vector giving the structure of the class group as a prod-
uct of cyclic groups;
* "v[3]" : a vector giving generators of those cyclic groups (as binary
quadratic forms).
* "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).
* "v[5]" : a measure of the correctness of the result. If it is close
to 1, the result is correct (under GRH). If it is close to a larger
integer, this shows that the class number is off by a factor equal to
this integer, and you must start again with a larger value for "c_1" or
a different random seed. In this case, a warning message is printed.
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)"
discriminant of the quadratic field Q"(" sqrt "{x})", where "x belongs
to "Q.
The library syntax is quaddisc"(x)".
quadhilbert"(D,{"flag" = 0})"
relative equation defining the Hilbert class field of the quadratic
field of discriminant "D". If flag is non-zero and "D < 0", outputs
"["form","root"("form")]" (to be used for constructing subfields). If
flag is non-zero and "D > 0", try hard to get the best modulus. Uses
complex multiplication in the imaginary case and Stark units in the
real case.
The library syntax is quadhilbert"(D,"flag","prec")".
quadgen"(x)"
creates the quadratic number omega" = (a+" sqrt "{x})/2" where "a = 0"
if "x = 0 mod 4", "a = 1" if "x = 1 mod 4", so that "(1,"omega")" is an
integral basis for the quadratic order of discriminant "x". "x" must be
an integer congruent to 0 or 1 modulo 4.
The library syntax is quadgen"(x)".
quadpoly"(D,{v = x})"
creates the ``canonical'' quadratic polynomial (in the variable "v")
corresponding to the discriminant "D", i.e. the minimal polynomial of
quadgen(x). "D" must be an integer congruent to 0 or 1 modulo 4.
The library syntax is quadpoly0"(x,v)".
quadray"(D,f,{"flag" = 0})"
relative equation for the ray class field of conductor "f" for the qua-
dratic field of discriminant "D" (which can also be a "bnf"), using
analytic methods.
For "D < 0", uses the sigma function. flag has the following meaning:
if it's an odd integer, outputs instead the vector of "["ideal", "cor-
responding root"]". It can also be a two-component vector
"["lambda","flag"]", where flag is as above and lambda is the technical
element of "bnf" necessary for Schertz's method. In that case, returns
0 if lambda is not suitable.
For "D > 0", uses Stark's conjecture. If flag is non-zero, try hard to
get the best modulus. The function may fail with the following message
"Cannot find a suitable modulus in FindModulus"
See "bnrstark" for more details about the real case.
The library syntax is quadray"(D,f,"flag")".
quadregulator"(x)"
regulator of the quadratic field of positive discriminant "x". Returns
an error if "x" is not a discriminant (fundamental or not) or if "x" is
a square. See also "quadclassunit" if "x" is large.
The library syntax is regula"(x,"prec")".
quadunit"(x)"
fundamental unit of the real quadratic field Q"(" sqrt " x)" where "x"
is the positive discriminant of the field. If "x" is not a fundamental
discriminant, this probably gives the fundamental unit of the corre-
sponding order. "x" must be of type integer, and the result is a qua-
dratic number.
The library syntax is fundunit"(x)".
removeprimes"({x = []})"
removes the primes listed in "x" from the prime number table. In par-
ticular "removeprimes(addprimes)" empties the extra prime table. "x"
can also be a single integer. List the current extra primes if "x" is
omitted.
The library syntax is removeprimes"(x)".
sigma"(x,{k = 1})"
sum of the "k^{th}" powers of the positive divisors of "|x|". "x" must
be of type integer.
The library syntax is sumdiv"(x)" ( = sigma"(x)") or gsumdivk"(x,k)" (
= sigma"(x,k)"), where "k" is a C long integer.
sqrtint"(x)"
integer square root of "x", which must be of PARI type integer. The
result is non-negative and rounded towards zero. A negative "x" is
allowed, and the result in that case is "I*sqrtint(-x)".
The library syntax is racine"(x)".
znlog"(x,g)"
"g" must be a primitive root mod a prime "p", and the result is the
discrete log of "x" in the multiplicative group "("Z"/p"Z")^*". This
function using a simple-minded baby-step/giant-step approach and
requires "O(" sqrt "{p})" storage, hence it cannot be used for "p"
greater than about "10^{13}".
The library syntax is znlog"(x,g)".
znorder"(x)"
"x" must be an integer mod "n", and the result is the order of "x" in
the multiplicative group "("Z"/n"Z")^*". Returns an error if "x" is not
invertible.
The library syntax is order"(x)".
znprimroot"(x)"
returns a primitive root of "x", where "x" is a prime power.
The library syntax is gener"(x)".
znstar"(n)"
gives the structure of the multiplicative group "("Z"/n"Z")^*" as a
3-component row vector "v", where "v[1] = "phi"(n)" is the order of
that group, "v[2]" is a "k"-component row-vector "d" of integers "d[i]"
such that "d[i] > 1" and "d[i] | d[i-1]" for "i >= 2" and "("Z"/n"Z")^*
~ "prod"_{i = 1}^k("Z"/d[i]"Z")", and "v[3]" is a "k"-component row
vector giving generators of the image of the cyclic groups Z"/d[i]"Z.
The library syntax is znstar"(n)".
Functions related to elliptic curves
We have implemented a number of functions which are useful for number
theorists working on elliptic curves. We always use Tate's notations.
The functions assume that the curve is given by a general Weierstrass
model
" y^2+a_1xy+a_3y = x^3+a_2x^2+a_4x+a_6, "
where a priori the "a_i" can be of any scalar type. This curve can be
considered as a five-component vector "E = [a1,a2,a3,a4,a6]". Points on
"E" are represented as two-component vectors "[x,y]", except for the
point at infinity, i.e. the identity element of the group law, repre-
sented by the one-component vector "[0]".
It is useful to have at one's disposal more information. This is given
by the function "ellinit" (see there), which usually gives a 19 compo-
nent vector (which we will call a long vector in this section). If a
specific flag is added, a vector with only 13 component will be output
(which we will call a medium vector). A medium vector just gives the
first 13 components of the long vector corresponding to the same curve,
but is of course faster to compute. The following member functions are
available to deal with the output of "ellinit":
"a1"--"a6", "b2"--"b8", "c4"--"c6" : coefficients of the elliptic
curve.
"area" : volume of the complex lattice defining "E".
"disc" : discriminant of the curve.
"j" : "j"-invariant of the curve.
"omega" : "["omega"_1,"omega"_2]", periods forming a basis of the
complex lattice defining "E" (omega"_1" is the
real period, and omega"_2/"omega"_1" belongs to
Poincare's half-plane).
"eta" : quasi-periods "["eta"_1, "eta"_2]", such that
eta"_1"omega"_2-"eta"_2"omega"_1 = i"Pi.
"roots" : roots of the associated Weierstrass equation.
"tate" : "[u^2,u,v]" in the notation of Tate.
"w" : Mestre's "w" (this is technical).
Their use is best described by an example: assume that "E" was output
by "ellinit", then typing "E.disc" will retrieve the curve's discrimi-
nant. The member functions "area", "eta" and "omega" are only available
for curves over Q. Conversely, "tate" and "w" are only available for
curves defined over Q"_p".
Some functions, in particular those relative to height computations
(see "ellheight") require also that the curve be in minimal Weierstrass
form. This is achieved by the function "ellglobalred".
All functions related to elliptic curves share the prefix "ell", and
the precise curve we are interested in is always the first argument, in
either one of the three formats discussed above, unless otherwise spec-
ified. For instance, in functions which do not use the extra informa-
tion given by long vectors, the curve can be given either as a five-
component vector, or by one of the longer vectors computed by
"ellinit".
elladd"(E,z1,z2)"
sum of the points "z1" and "z2" on the elliptic curve corresponding to
the vector "E".
The library syntax is addell"(E,z1,z2)".
ellak"(E,n)"
computes the coefficient "a_n" of the "L"-function of the elliptic
curve "E", i.e. in principle coefficients of a newform of weight 2
assuming Taniyama-Weil conjecture (which is now known to hold in full
generality thanks to the work of Breuil, Conrad, Diamond, Taylor and
Wiles). "E" must be a medium or long vector of the type given by
"ellinit". For this function to work for every "n" and not just those
prime to the conductor, "E" must be a minimal Weierstrass equation. If
this is not the case, use the function "ellglobalred" first before
using "ellak".
The library syntax is akell"(E,n)".
ellan"(E,n)"
computes the vector of the first "n" "a_k" corresponding to the ellip-
tic curve "E". All comments in "ellak" description remain valid.
The library syntax is anell"(E,n)", where "n" is a C integer.
ellap"(E,p,{"flag" = 0})"
computes the "a_p" corresponding to the elliptic curve "E" and the
prime number "p". These are defined by the equation "#E("F"_p) = p+1 -
a_p", where "#E("F"_p)" stands for the number of points of the curve
"E" over the finite field F"_p". When flag is 0, this uses the baby-
step giant-step method and a trick due to Mestre. This runs in time
"O(p^{1/4})" and requires "O(p^{1/4})" storage, hence becomes unreason-
able when "p" has about 30 digits.
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 a medium or
long vector of the type given 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)"
if "z1" and "z2" are points on the elliptic curve "E", this function
computes the value of the canonical bilinear form on "z1", "z2":
" ellheight(E,z1+z2) - ellheight(E,z1) - ellheight(E,z2) "
where "+" denotes of course addition on "E". In addition, "z1" or "z2"
(but not both) can be vectors or matrices. Note that this is equal to
twice some normalizations. "E" is assumed to be integral, given by a
minimal model.
The library syntax is bilhell"(E,z1,z2,"prec")".
ellchangecurve"(E,v)"
changes the data for the elliptic curve "E" by changing the coordinates
using the vector "v = [u,r,s,t]", i.e. if "x'" and "y'" are the new
coordinates, then "x = u^2x'+r", "y = u^3y'+su^2x'+t". The vector "E"
must be a medium or long vector of the type given by "ellinit".
The library syntax is coordch"(E,v)".
ellchangepoint"(x,v)"
changes the coordinates of the point or vector of points "x" using the
vector "v = [u,r,s,t]", i.e. if "x'" and "y'" are the new coordinates,
then "x = u^2x'+r", "y = u^3y'+su^2x'+t" (see also "ellchangecurve").
The library syntax is pointch"(x,v)".
elleisnum"(E,k,{"flag" = 0})"
"E" being an elliptic curve as output by "ellinit" (or, alternatively,
given by a 2-component vector "["omega"_1,"omega"_2]"), and "k" being
an even positive integer, computes the numerical value of the Eisen-
stein series of weight "k" at "E". When flag is non-zero and "k = 4" or
6, returns "g_2" or "g_3" with the correct normalization.
The library syntax is elleisnum"(E,k,"flag")".
elleta"(om)"
returns the two-component row vector "["eta"_1,"eta"_2]" of quasi-peri-
ods associated to "om = ["omega"_1, "omega"_2]"
The library syntax is elleta"(om, "prec")"
ellglobalred"(E)"
calculates the arithmetic conductor, the global minimal model of "E"
and the global Tamagawa number "c". Here "E" is an elliptic curve given
by a medium or long vector of the type given by "ellinit", and is sup-
posed to have all its coefficients "a_i" in Q. The result is a 3 compo-
nent vector "[N,v,c]". "N" is the arithmetic conductor of the curve,
"v" is itself a vector "[u,r,s,t]" with rational components. It gives a
coordinate change for "E" over Q such that the resulting model has
integral coefficients, is everywhere minimal, "a_1" is 0 or 1, "a_2" is
0, 1 or "-1" and "a_3" is 0 or 1. Such a model is unique, and the vec-
tor "v" is unique if we specify that "u" is positive. To get the new
model, simply type "ellchangecurve(E,v)". Finally "c" is the product of
the local Tamagawa numbers "c_p", a quantity which enters in the Birch
and Swinnerton-Dyer conjecture.
The library syntax is globalreduction"(E)".
ellheight"(E,z,{"flag" = 0})"
global Neron-Tate height of the point "z" on the elliptic curve "E".
The vector "E" must be a long vector of the type given by "ellinit",
with flag" = 1". If flag" = 0", this computation is done using sigma
and theta-functions and a trick due to J. Silverman. If flag" = 1",
use Tate's "4^n" algorithm, which is much slower. "E" is assumed to be
integral, given by a minimal model.
The library syntax is ellheight0"(E,z,"flag","prec")". The Archimedean
contribution alone is given by the library function hell"(E,z,"prec")".
Also available are ghell"(E,z,"prec")" (flag" = 0") and
ghell2"(E,z,"prec")" (flag" = 1").
ellheightmatrix"(E,x)"
"x" being a vector of points, this function outputs the Gram matrix of
"x" with respect to the Neron-Tate height, in other words, the "(i,j)"
component of the matrix is equal to "ellbil(E,x[i],x[j])". The rank of
this matrix, at least in some approximate sense, gives the rank of the
set of points, and if "x" is a basis of the Mordell-Weil group of "E",
its determinant is equal to the regulator of "E". Note that this matrix
should be divided by 2 to be in accordance with certain normalizations.
"E" is assumed to be integral, given by a minimal model.
The library syntax is mathell"(E,x,"prec")".
ellinit"(E,{"flag" = 0})"
computes some fixed data concerning the elliptic curve given by the
five-component vector "E", which will be essential for most further
computations on the curve. The result is a 19-component vector E
(called a long vector in this section), shortened to 13 components
(medium vector) if flag" = 1". Both contain the following information
in the first 13 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."
In particular, the discriminant is "E[12]" (or "E.disc"), and the
"j"-invariant is "E[13]" (or "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:
* When "E" is defined over R, "E[14]" ("E.roots") is a vector whose
three components contain the roots of the associated Weierstrass equa-
tion. If the roots are all real, then they are ordered by decreasing
value. If only one is real, it is the first component of "E[14]".
"E[15]" ("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 "E[16]" ("E.omega[2]") is a com-
plex period. In other words, omega"_1 = E[15]" and omega"_2 = E[16]"
form a basis of the complex lattice defining "E" ("E.omega"), with tau"
= ("omega"_2)/("omega"_1)" having positive imaginary part.
"E[17]" and "E[18]" are the corresponding values eta"_1" and eta"_2"
such that eta"_1"omega"_2-"eta"_2"omega"_1 = i"Pi, and both can be
retrieved by typing "E.eta" (as a row vector whose components are the
eta"_i").
Finally, "E[19]" ("E.area") is the volume of the complex lattice defin-
ing "E".
* When "E" is defined over Q"_p", the "p"-adic valuation of "j" must be
negative. Then "E[14]" ("E.roots") is the vector with a single compo-
nent equal to the "p"-adic root of the associated Weierstrass equation
corresponding to "-1" under the Tate parametrization.
"E[15]" is equal to the square of the "u"-value, in the notation of
Tate.
"E[16]" is the "u"-value itself, if it belongs to Q"_p", otherwise
zero.
"E[17]" is the value of Tate's "q" for the curve "E".
"E.tate" will yield the three-component vector "[u^2,u,q]".
"E[18]" ("E.w") is the value of Mestre's "w" (this is technical), and
"E[19]" is arbitrarily set equal to zero.
For all other base fields or rings, the last six components are arbi-
trarily 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)"
gives 1 (i.e. true) if the point "z" is on the elliptic curve "E", 0
otherwise. If "E" or "z" have imprecise coefficients, an attempt is
made to take this into account, i.e. an imprecise equality is checked,
not a precise one.
The library syntax is oncurve"(E,z)", and the result is a "long".
ellj"(x)"
elliptic "j"-invariant. "x" must be a complex number with positive
imaginary part, or convertible into a power series or a "p"-adic number
with positive valuation.
The library syntax is jell"(x,"prec")".
elllocalred"(E,p)"
calculates the Kodaira type of the local fiber of the elliptic curve
"E" at the prime "p". "E" must be given by a medium or long vector of
the type given by "ellinit", and is assumed to have all its coeffi-
cients "a_i" in Z. The result is a 4-component vector "[f,kod,v,c]".
Here "f" is the exponent of "p" in the arithmetic conductor of "E", and
"kod" is the Kodaira type which is coded as follows:
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. Nor-
mally, 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 localreduction"(E,p)".
elllseries"(E,s,{A = 1})"
"E" being a medium or long vector given by "ellinit", this computes the
value of the L-series of "E" at "s". It is assumed that "E" is a mini-
mal model over Z and that the curve is a modular elliptic curve. The
optional parameter "A" is a cutoff point for the integral, which must
be chosen close to 1 for best speed. The result must be independent of
"A", so this allows some internal checking of the function.
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 lseriesell"(E,s,A,"prec")" where prec is a "long"
and an omitted "A" is coded as "NULL".
ellorder"(E,z)"
gives the order of the point "z" on the elliptic curve "E" if it is a
torsion point, zero otherwise. In the present version 2.2.0, this is
implemented only for elliptic curves defined over Q.
The library syntax is orderell"(E,z)".
ellordinate"(E,x)"
gives a 0, 1 or 2-component vector containing the "y"-coordinates of
the points of the curve "E" having "x" as "x"-coordinate.
The library syntax is ordell"(E,x)".
ellpointtoz"(E,z)"
if "E" is an elliptic curve with coefficients in R, this computes a
complex number "t" (modulo the lattice defining "E") corresponding to
the point "z", i.e. such that, in the standard Weierstrass model, wp
"(t) = z[1]," wp "'(t) = z[2]". In other words, this is the inverse
function of "ellztopoint".
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 a long vector output by
"ellinit".
The library syntax is zell"(E,z,"prec")".
ellpow"(E,z,n)"
computes "n" times the point "z" for the group law on the elliptic
curve "E". Here, "n" can be in Z, or "n" can be a complex quadratic
integer if the curve "E" has complex multiplication by "n" (if not, an
error message is issued).
The library syntax is powell"(E,z,n)".
ellrootno"(E,{p = 1})"
"E" being a medium or long vector given by "ellinit", this computes the
local (if "p ! = 1") or global (if "p = 1") root number of the L-series
of the elliptic curve "E". Note that the global root number is the sign
of the functional equation and conjecturally is the parity of the rank
of the Mordell-Weil group. The equation for "E" must have coefficients
in Q but need not be minimal.
The library syntax is ellrootno"(E,p)" and the result (equal to "+-1")
is a "long".
ellsigma"(E,z,{"flag" = 0})"
value of the Weierstrass sigma function of the lattice associated to
"E" as given by "ellinit" (alternatively, "E" can be given as a lattice
"["omega"_1,"omega"_2]").
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")"
ellsub"(E,z1,z2)"
difference of the points "z1" and "z2" on the elliptic curve corre-
sponding to the vector "E".
The library syntax is subell"(E,z1,z2)".
elltaniyama"(E)"
computes the modular parametrization of the elliptic curve "E", where
"E" is given in the (long or medium) format output by "ellinit", in the
form of a two-component vector "[u,v]" of power series, given to the
current default series precision. This vector is characterized by the
following two properties. First the point "(x,y) = (u,v)" satisfies the
equation of the elliptic curve. Second, the differential
"du/(2v+a_1u+a_3)" is equal to "f(z)dz", a differential form on
"H/"Gamma_0(N) where "N" is the conductor of the curve. The variable
used in the power series for "u" and "v" is "x", which is implicitly
understood to be equal to exp "(2i"Pi" z)". It is assumed that the
curve is a strong Weil curve, and the Manin constant is equal to 1. The
equation of the curve "E" must be minimal (use "ellglobalred" to get a
minimal equation).
The library syntax is taniyama"(E)", and the precision of the result is
determined by the global variable "precdl".
elltors"(E,{"flag" = 0})"
if "E" is an elliptic curve defined over Q, outputs the torsion sub-
group of "E" as a 3-component vector "[t,v1,v2]", where "t" is the
order of the torsion group, "v1" gives the structure of the torsion
group as a product of cyclic groups (sorted by decreasing order), and
"v2" gives generators for these cyclic groups. "E" must be a long vec-
tor as output by "ellinit".
? E = ellinit([0,0,0,-1,0]);
? elltors(E)
%1 = [4, [2, 2], [[0, 0], [1, 0]]]
Here, the torsion subgroup is isomorphic to Z"/2"Z" x "Z"/2"Z, 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 (much slower), "E" is allowed to be a
medium vector.
The library syntax is elltors0"(E,flag)".
ellwp"(E,{z = x},{"flag" = 0})"
Computes the value at "z" of the Weierstrass wp function attached to
the elliptic curve "E" as given by "ellinit" (alternatively, "E" can be
given as a lattice "["omega"_1,"omega"_2]").
If "z" is omitted or is a simple variable, computes the power series
expansion in "z" (starting "z^{-2}+O(z^2)"). The number of terms to an
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 avail-
able is weipell"(E,"precdl")" for the power series (in "x = polx[0]").
ellzeta"(E,z)"
value of the Weierstrass zeta function of the lattice associated to "E"
as given by "ellinit" (alternatively, "E" can be given as a lattice
"["omega"_1,"omega"_2]").
The library syntax is ellzeta"(E,z)".
ellztopoint"(E,z)"
"E" being a long vector, computes the coordinates "[x,y]" on the curve
"E" corresponding to the complex number "z". Hence this is the inverse
function of "ellpointtoz". In other words, if the curve is put in
Weierstrass form, "[x,y]" represents the
wp Weierstrass wp -function and its derivative. If "z" is in the
lattice defining "E" over C, the result is the point at infinity "[0]".
The library syntax is pointell"(E,z,"prec")".
Functions related to general number fields
In this section can be found functions which are used almost exclu-
sively for working in general number fields. Other less specific func-
tions can be found in the next section on polynomials. Functions
related to quadratic number fields can be found in the section "Label
se:arithmetic" (Arithmetic functions).
We shall use the following conventions:
* nf denotes a number field, i.e. a 9-component vector in the format
output by "nfinit". This contains the basic arithmetic data associated
to the number field: signature, maximal order, discriminant, etc.
* bnf denotes a big number field, i.e. a 10-component vector in the
format output by "bnfinit". This contains nf and the deeper invariants
of the field: units, class groups, as well as a lot of technical data
necessary for some complex fonctions like "bnfisprincipal".
* bnr denotes a big ``ray number field'', i.e. some data structure out-
put by "bnrinit", even more complicated than bnf, corresponding to the
ray class group structure of the field, for some modulus.
* rnf denotes a relative number field (see below).
* ideal can mean any of the following:
-- a Z-basis, in Hermite normal form (HNF) or not. In this case "x"
is a square matrix.
-- an idele, i.e. a 2-component vector, the first being an ideal
given as a Z--basis, the second being a "r_1+r_2"-component row vector
giving the complex logarithmic Archimedean information.
-- a Z"_K"-generating system for an ideal.
-- a column vector "x" expressing an element of the number field on
the integral basis, in which case the ideal is treated as being the
principal idele (or ideal) generated by "x".
-- a prime ideal, i.e. a 5-component vector in the format output by
"idealprimedec".
-- a polmod "x", i.e. an algebraic integer, in which case the ideal
is treated as being the principal idele generated by "x".
-- an integer or a rational number, also treated as a principal
idele.
* a {character} on the Abelian group "\bigoplus ("Z"/N_i"Z") g_i" is
given by a row vector chi" = [a_1,...,a_n]" such that chi"("prod"
g_i^{n_i}) = exp(2i"Pisum" a_i n_i / N_i)".
Warnings:
1) An element in nf can be expressed either as a polmod or as a vector
of components on the integral basis nf".zk". It is absolutely essential
that all such vectors be column vectors.
2) When giving an ideal by a Z"_K" generating system to a function
expecting an ideal, it must be ensured that the function understands
that it is a Z"_K"-generating system and not a Z-generating system.
When the number of generators is strictly less than the degree of the
field, there is no ambiguity and the program assumes that one is giving
a Z"_K"-generating set. When the number of generators is greater than
or equal to the degree of the field, however, the program assumes on
the contrary that you are giving a Z-generating set. If this is not the
case, you must absolutely change it into a Z-generating set, the sim-
plest manner being to use "idealhnf("nf",x)".
Concerning relative extensions, some additional definitions are neces-
sary.
* A {relative matrix} will be a matrix whose entries are elements of a
(given) number field nf, always expressed as column vectors on the
integral basis nf".zk". Hence it is a matrix of vectors.
* An ideal list will be a row vector of (fractional) ideals of the num-
ber field nf.
* A pseudo-matrix will be 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 will be represented by a 2-component row vector.
* The module generated by a pseudo-matrix "(A,I)" is the sum
sum"_i{"a"}_jA_j" where the "{"a"}_j" are the ideals of "I" and "A_j"
is the "j"-th column of "A".
* 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.
* The 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 deter-
minant of a pseudo-matrix is the determinant of any pseudo-basis of the
module it generates.
Finally, when defining a relative extension, the base field should be
defined by a variable having a lower priority (i.e. a higher number)
than the variable defining the extension. For example, under GP you can
use the variable name "y" (or "t") to define the base field, and the
variable name "x" to define the relative extension.
Now a last set of definitions concerning the way big ray number fields
(or bnr) are input, 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"]", where:
* bnf is as output by "bnfclassunit" or "bnfinit", where units are
mandatory unless the ideal is trivial; bnr by "bnrclass" (with flag" >
0") or "bnrinit". This is the ground field.
* module is either an ideal in any form (see above) or a two-component
row vector containing an ideal and an "r_1"-component row vector of
flags indicating which real Archimedean embeddings to take in the mod-
ule.
* subgroup is the HNF matrix of a subgroup of the ray class group of
the ground field for the modulus module. 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 then the subfield of the ray class field of
the ground field for the given modulus, associated to the given sub-
group.
All the functions which are specific to relative extensions, number
fields, big number fields, big number rays, share the prefix "rnf",
"nf", "bnf", "bnr" respectively. They are meant to take as first argu-
ment a number field of that precise type, respectively output by
"rnfinit", "nfinit", "bnfinit", and "bnrinit".
However, and even though it may not be specified in the descriptions of
the functions below, it is permissible, if the function expects a nf,
to use a bnf instead (which contains much more information). The pro-
gram will make the effort of converting to what it needs. On the other
hand, if the program requires a big number field, the program will not
launch "bnfinit" for you, which can be a costly operation. Instead, it
will give you a specific error message.
The data types corresponding to the structures described above are
rather complicated. Thus, as we already have seen it with elliptic
curves, GP provides you with some ``member functions'' to retrieve the
data you need from these structures (once they have been initialized of
course). The relevant types of number fields are indicated between
parentheses:
"bnf" (bnr, bnf ) : big 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 differ-
ent in the ideal group).
"disc" (bnr, bnf, nf ) : discriminant.
"fu" (bnr, bnf, nf ) : fundamental units.
"futu" (bnr, bnf ) : "[u,w]", "u" is a vector of fundamental
units, "w" generates the torsion.
"nf" (bnr, bnf, nf ) : number field.
"reg" (bnr, bnf, ) : regulator.
"roots" (bnr, bnf, nf ) : roots of the polnomial generating the
field.
"sign" (bnr, bnf, nf ) : "[r_1,r_2]" the signature of the field.
This means that the field has "r_1" real embeddings, "2r_2" com-
plex ones.
"t2" (bnr, bnf, nf ) : the T2 matrix (see "nfinit").
"tu" (bnr, bnf, ) : a generator for the torsion units.
"tufu" (bnr, bnf, ) : as "futu", but outputs "[w,u]".
"zk" (bnr, bnf, nf ) : integral basis, i.e. a Z-basis of the
maximal order.
"zkst" (bnr ) : structure of "("Z"_K/m)^*" (can be
extracted also from an idealstar).
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" of course).
The following functions, starting with "buch" in library mode, and with
"bnf" under GP, are implementations of the sub-exponential algorithms
for finding class and unit groups under GRH, due to Hafner-McCurley,
Buchmann and Cohen-Diaz-Olivier.
The general call to the functions concerning class groups of general
number fields (i.e. excluding "quadclassunit") involves a polynomial
"P" and a technical vector
tech" = [c,c2,"nrel","borne","nrpid","minsfb"],"
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, preferably, monic. In fact, if you supply a
non-monic polynomial at this point, GP will issue a warning, then
transform your polynomial so that it becomes monic. Instead of the nor-
mal result, say "res", you then get a vector "[res,Mod(a,Q)]", where
"Mod(a,Q) = Mod(X,P)" gives the change of variables.
The numbers "c" and "c2" are positive real numbers which control the
execution time and the stack size. To get maximum speed, set "c2 = c".
To get a rigorous result (under GRH) you must take "c2 = 12" (or "c2 =
6" in the quadratic case, but then you should use the much faster func-
tion "quadclassunit"). Reasonable values for "c" are between 0.1 and 2.
(The defaults are "c = c2 = 0.3").
nrel is the number of initial extra relations requested in computing
the relation matrix. Reasonable values are between 5 and 20. (The
default is 5).
borne is a multiplicative coefficient of the Minkowski bound which con-
trols the search for small norm relations. If this parameter is set
equal to 0, the program does not search for small norm relations. Oth-
erwise reasonable values are between 0.5 and 2.0. (The default is 1.0).
nrpid is the maximal number of small norm relations associated to each
ideal in the factor base. Irrelevant when borne" = 0". Otherwise, rea-
sonable values are between 4 and 20. (The default is 4).
minsfb is the minimal number of elements in the ``sub-factorbase''. If
the program does not seem to succeed in finding a full rank matrix
(which you can see in GP by typing "\g 2"), increase this number. Rea-
sonable values are between 2 and 5. (The default is 3).
Remarks.
Apart from the polynomial "P", you don't need to supply any of the
technical parameters (under the library you still need to send at least
an empty vector, "cgetg(1,t_VEC)"). However, should you choose to set
some of them, they must be given in the requested order. For example,
if you want to specify a given value of "nrel", you must give some val-
ues as well for "c" and "c2", and provide a vector "[c,c2,nrel]".
Note also that you can use an nf instead of "P", which avoids recomput-
ing the integral basis and analogous quantities.
bnfcertify"("bnf")"
bnf being a big number field as output by "bnfinit" or "bnfclassunit",
checks whether the result is correct, i.e. whether it is possible to
remove the assumption of the Generalized Riemann Hypothesis. If it is
correct, the answer is 1. If not, the program may output some error
message, but more probably will loop indefinitely. In no occasion can
the program give a wrong answer (barring bugs of course): if the pro-
gram answers 1, the answer is certified.
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 10 components (it is
not a bnf, you need "bnfinit" for that), which for ease of presentation
is in fact output as a one column matrix. First we describe the default
behaviour (flag" = 0"):
"v[1]" is equal to the polynomial "P". Note that for optimum perfor-
mance, "P" should have gone through "polred" or "nfinit(x,2)".
"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 a measure of the correctness of the result. If it is close to
1, the results are correct (under GRH). If it is close to a larger
integer, this shows that the product of the class number by the regula-
tor is off by a factor equal to this integer, and you must start again
with a larger value for "c" or a different random seed, i.e. use the
function "setrand". (Since the computation involves a random process,
starting again with exactly the same parameters may give the correct
result.) In this case a warning message is printed.
"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.
"v[10]" gives a measure of the correctness of the computations of the
fundamental units (not of the regulator), expressed as a number of
bits. If this number is greater than 20, say, everything is OK. If
"v[10] <= 0", then we have lost all accuracy in computing the units
(usually an error message will be printed and the units not given). In
the intermediate cases, one must proceed with caution (for example by
increasing the current precision).
If flag" = 1", and the precision happens to be insufficient for obtain-
ing the fundamental units exactly, the internal precision is doubled
and the computation redone, until the exact results are obtained. The
user should be warned that this can take a very long time when the
coefficients of the fundamental units on the integral basis are very
large, for example in the case of large real quadratic fields. In that
case, there are alternate methods for representing algebraic numbers
which are not implemented in PARI.
If flag" = 2", the fundamental units and roots of unity are not com-
puted. Hence the result has only 7 components, the first seven ones.
tech is a technical vector (empty by default) containing "c", "c2",
nrel, borne, nbpid, minsfb, in this order (see the beginning of the
section or the keyword "bnf"). You can supply any number of these pro-
vided you give an actual value to each of them (the ``empty arg'' trick
won't work here). Careful use of these parameters may speed up your
computations considerably.
The library syntax is bnfclassunit0"(P,"flag","tech","prec")".
bnfclgp"(P,{"tech" = []})"
as "bnfclassunit", but only outputs "v[5]", i.e. the class group.
The library syntax is bnfclassgrouponly"(P,"tech","prec")", where tech
is as described under "bnfclassunit".
bnfdecodemodule"("nf",m)"
if "m" is a module as output in the first component of an extension
given by "bnrdisclist", outputs the true module.
The library syntax is decodemodule"("nf",m)".
bnfinit"(P,{"flag" = 0},{"tech" = []})"
essentially identical to "bnfclassunit" except that the output contains
a lot of technical data, and should not be printed out explicitly in
general. The result of "bnfinit" is used in programs such as "bnfis-
principal", "bnfisunit" or "bnfnarrow". The result is a 10-component
vector bnf.
* The first 6 and last 2 components are technical and in principle are
not used by the casual user. However, for the sake of completeness,
their description is as follows. We use the notations explained in the
book by H. Cohen, 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
"("p"_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 p"_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]" contains the permutation of the prime factor base which was
necessary to reduce the relation matrix to the form explained in sub-
section 6.5.5 of GTM 138 (i.e. with a big "c x c" identity matrix on
the lower right). Note that in the above mentioned book, the need to
permute the rows of the relation matrices which occur was not empha-
sized.
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 archi-
median component "g_a"; let also "GD_a" be the archimedian 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]".
Finally, 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 com-
pute 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).
* The less technical components are as follows:
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 last 6 components of "bnfclas-
sunit[,1]", i.e. the classgroup bnf".clgp", the regulator bnf".reg",
the general ``check'' number which should be close to 1, the number of
roots of unity and a generator bnf".tu", the fundamental units
bnf".fu", and finally the check on their computation. 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", GP insists on finding the fundamental units exactly,
the internal precision being doubled and the computation redone, until
the exact results are obtained. The user should be warned that this can
take a very long time when the coefficients of the fundamental units on
the integral basis are very large.
When flag" = 2", on the contrary, it is initially agreed that GP will
not compute units.
When flag" = 3", computes a very small version of "bnfinit", a ``small
big number field'' (or sbnf for short) which contains enough informa-
tion 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". The output 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 inte-
gral 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]". In practice, this is the only component which
a user is allowed to modify, by recomputing the roots to a higher accu-
racy if desired. Note also that the member functions will not work on
sbnf, you have to use "bnfmake" explicitly first.
The library syntax is bnfinit0"(P,"flag","tech","prec")".
bnfisintnorm"("bnf",x)"
computes a complete system of solutions (modulo units of positive norm)
of the absolute norm equation "Norm(a) = x", where "a" is an integer in
bnf. If bnf has not been certified, the correctness of the result
depends on the validity of GRH.
The library syntax is bnfisintnorm"("bnf",x)".
bnfisnorm"("bnf",x,{"flag" = 1})"
tries to tell whether the rational number "x" is the norm of some ele-
ment y in bnf. Returns a vector "[a,b]" where "x = Norm(a)*b". Looks
for a solution which is an "S"-unit, with "S" a certain set of prime
ideals containing (among others) all primes dividing "x". If bnf is
known to be Galois, set flag" = 0" (in this case, "x" is a norm iff "b
= 1"). If flag is non zero the program adds to "S" the following prime
ideals, depending on the sign of flag. If flag" > 0", the ideals of
norm less than flag. And if flag" < 0" the ideals dividing flag.
If you are willing to assume 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.
The library syntax is bnfisnorm"("bnf",x,"flag","prec")", where flag
and prec are "long"s.
bnfissunit"("bnf","sfu",x)"
bnf being output by "bnfinit", sfu by "bnfsunit", gives the column vec-
tor of exponents of "x" on the fundamental "S"-units and the roots of
unity. If "x" is not a unit, outputs an empty vector.
The library syntax is bnfissunit"("bnf","sfu",x)".
bnfisprincipal"("bnf",x,{"flag" = 1})"
bnf being the number field data output by "bnfinit", and "x" being
either a Z-basis of an ideal in the number field (not necessarily in
HNF) or a prime ideal in the format output by the function "ideal-
primedec", this function tests whether the ideal is principal or not.
The result is more complete than a simple true/false answer: it gives a
row vector "[v_1,v_2,check]", where
"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".clgp.gen" which is the same as
bnf"[8][1][3]"). 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".clgp.cyc",
that is bnf"[8][1][2]").
"v_2" gives on the integral basis the components of alpha such that "x
= "alphaprod"_ig_i^{c_i}". In particular, "x" is principal if and only
if "v_1" is equal to the zero vector, and if this the case "x = "alp-
haZ"_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.
Finally the third component check is analogous to the last component of
"bnfclassunit": it gives a check on the accuracy of the result, in
bits. check should be at least 10, and preferably much more. In any
case, the result is checked for correctness.
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 very lengthy
computations.
The library syntax is isprincipalall"("bnf",x,"flag")".
bnfisunit"("bnf",x)"
bnf being the number field data output by "bnfinit" and "x" being an
algebraic number (type integer, rational or polmod), this outputs the
decomposition of "x" on the fundamental units and the roots of unity if
"x" is a unit, the empty vector otherwise. More precisely, if
"u_1",...,"u_r" are the fundamental units, and zeta is the generator of
the group of roots of unity (found by "bnfclassunit" or "bnfinit"), the
output is a vector "[x_1,...,x_r,x_{r+1}]" such that "x =
u_1^{x_1}...u_r^{x_r}."zeta"^{x_{r+1}}". The "x_i" are integers for "i
<= r" and is an integer modulo the order of zeta for "i = r+1".
The library syntax is isunit"("bnf",x)".
bnfmake"("sbnf")"
sbnf being a ``small bnf'' as output by "bnfinit""(x,3)", computes the
complete "bnfinit" information. The result is not identical to what
"bnfinit" would yield, but is functionally identical. The execution
time is very small compared to a complete "bnfinit". Note that if the
default precision in GP (or prec in library mode) is greater than the
precision of the roots sbnf"[5]", these are recomputed so as to get a
result with greater accuracy.
Note that the member functions are 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")"
bnf being a big number field as output by "bnfinit", computes the nar-
row class group of bnf. The output is a 3-component row vector "v"
analogous to the corresponding class group component bnf".clgp"
(bnf"[8][1]"): the first component is the narrow class number "v.no",
the second component is a vector containing the SNF cyclic components
"v.cyc" of the narrow class group, and the third is a vector giving the
generators of the corresponding "v.gen" cyclic groups. Note that this
function is a special case of "bnrclass".
The library syntax is buchnarrow"("bnf")".
bnfsignunit"("bnf")"
bnf being a big number field output by "bnfinit", this computes an "r_1
x (r_1+r_2-1)" matrix having "+-1" components, giving the signs of the
real embeddings of the fundamental units.
The library syntax is signunits"("bnf")".
bnfreg"("bnf")"
bnf being a big number field output by "bnfinit", computes its regula-
tor.
The library syntax is regulator"("bnf","tech","prec")", where tech is
as in "bnfclassunit".
bnfsunit"("bnf",S)"
computes the fundamental "S"-units of the number field bnf (output by
"bnfinit"), where "S" is a list of prime ideals (output by "ideal-
primedec"). The output is a vector "v" with 6 components.
"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")"
bnf being a big number field as output by "bnfinit", outputs a two-com-
ponent row vector giving in the first component the vector of fundamen-
tal units of the number field, and in the second component the number
of bit of accuracy which remained in the computation (which is always
correct, otherwise an error message is printed). This function is
mainly for people who used the wrong flag in "bnfinit" and would like
to skip part of a lengthy "bnfinit" computation.
The library syntax is buchfu"("bnf")".
bnrL1"("bnr","subgroup",{"flag" = 0})"
bnr being the number field data which is output by "bnrinit(,,1)" and
subgroup being a square matrix defining a congruence subgroup of the
ray class group corresponding to bnr (or 0 for the trivial congruence
subgroup), returns for each character chi of the ray class group which
is trivial on this subgroup, the value at "s = 1" (or "s = 0") of the
abelian "L"-function associated to chi. For the value at "s = 0", the
function returns in fact for each character chi a vector "[r_"chi" ,
c_"chi"]" where "r_"chi is the order of "L(s, "chi")" at "s = 0" and
"c_"chi the first non-zero term in the expansion of "L(s, "chi")" at "s
= 0"; in other words
"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"-func-
tion 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 exam-
ple below), 3: returns also the character.
Example:
bnf = bnfinit(x^2 - 229);
bnr = bnrinit(bnf,1,1);
bnrL1(bnr, 0)
returns the order and the first non-zero term of the abelian "L"-func-
tions "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,0,2)
returns the order and the first non-zero terms of the abelian "L"-func-
tions "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")"
bnrclass"("bnf","ideal",{"flag" = 0})"
bnf being a big number field as output by "bnfinit" (the units are
mandatory unless the ideal is trivial), and ideal being either an ideal
in any form or a two-component row vector containing an ideal and an
"r_1"-component row vector of flags indicating which real Archimedean
embeddings to take in the module, computes the ray class group of the
number field for the module ideal, as a 3-component vector as all other
finite Abelian groups (cardinality, vector of cyclic components, corre-
sponding generators).
If flag" = 2", the output is different. It is a 6-component vector "w".
"w[1]" is bnf. "w[2]" is the result of applying "idealstar("bnf",I,2)".
"w[3]", "w[4]" and "w[6]" are technical components used only by the
function "bnrisprincipal". "w[5]" is the structure of the ray class
group as would have been output with flag" = 0".
If flag" = 1", as above, except that the generators of the ray class
group are not computed, which saves time.
The library syntax is bnrclass0"("bnf","ideal","flag","prec")".
bnrclassno"("bnf",I)"
bnf being a big number field as output by "bnfinit" (units are manda-
tory unless the ideal is trivial), and "I" being either an ideal in any
form or a two-component row vector containing an ideal and an
"r_1"-component row vector of flags indicating which real Archimedean
embeddings to take in the modulus, computes the ray class number of the
number field for the modulus "I". This is faster than "bnrclass" and
should be used if only the ray class number is desired.
The library syntax is rayclassno"("bnf",I)".
bnrclassnolist"("bnf","list")"
bnf being a big number field as output by "bnfinit" (units are manda-
tory unless the ideal is trivial), and list being a list of modules as
output by "ideallist" of "ideallistarch", outputs the list of the class
numbers of the corresponding ray class groups.
The library syntax is rayclassnolist"("bnf","list")".
bnrconductor"(a_1,{a_2},{a_3}, {"flag" = 0})"
conductor of the subfield of a ray class field as defined by
"[a_1,a_2,a_3]" (see "bnr" at the beginning of this section).
The library syntax is bnrconductor"(a_1,a_2,a_3,"flag","prec")", where
an omitted argument among the "a_i" is input as "gzero", and flag is a
C long.
bnrconductorofchar"("bnr","chi")"
bnr being a big ray number field as output by "bnrclass", and chi being
a row vector representing a character as expressed on the generators of
the ray class group, gives the conductor of this character as a modu-
lus.
The library syntax is bnrconductorofchar"("bnr","chi","prec")" where
prec is a "long".
bnrdisc"(a1,{a2},{a3},{"flag" = 0})"
"a1", "a2", "a3" defining a big ray number field "L" over a groud field
"K" (see "bnr" at the beginning of this section for the meaning of
"a1", "a2", "a3"), outputs a 3-component row vector "[N,R_1,D]", where
"N" is the (absolute) degree of "L", "R_1" the number of real places of
"L", and "D" the discriminant of "L/"Q, including sign (if 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", does as in case 0, except that if the modulus is not the
exact conductor corresponding to the "L", no data is computed and the
result is 0 ("gzero").
If flag" = 3", as case 2, outputting relative data.
The library syntax is bnrdisc0"(a1,a2,a3,"flag","prec")".
bnrdisclist"("bnf","bound",{"arch"},{"flag" = 0})"
bnf being a big number field as output by "bnfinit" (the units are
mandatory), computes a list of discriminants of Abelian extensions of
the number field by increasing modulus norm up to bound bound, where
the ramified Archimedean places are given by arch (unramified at infin-
ity if arch is void or omitted). If flag is non-zero, give arch all the
possible values. (See "bnr" at the beginning of this section for the
meaning of "a1", "a2", "a3".)
The alternative syntax "bnrdisclist("bnf","list")" is supported, where
list is as output by "ideallist" or "ideallistarch" (with units).
The output format is as follows. The output "v" is a row vector of row
vectors, allowing the bound to be greater than "2^{16}" for 32-bit
machines, and "v[i][j]" is understood to be in fact "V[2^{15}(i-1)+j]"
of a unique big vector "V" (note that "2^{15}" is hardwired and can be
increased in the source code only on 64-bit machines and higher).
Such a component "V[k]" is itself a vector "W" (maybe of length 0)
whose components correspond to each possible ideal of norm "k". Each
component "W[i]" corresponds to an Abelian extension "L" of bnf whose
modulus is an ideal of norm "k" and no Archimedean components (hence
the extension is unramified at infinity). The extension "W[i]" is rep-
resented by a 4-component row 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 the absolute discrimi-
nant. Each prime ideal "pr = [p,"alpha",e,f,"beta"]" in the prime fac-
torization "m" is coded as "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".
The library syntax is bnrdisclist0"(a1,a2,a3,"bound","arch","flag")".
bnrinit"("bnf","ideal",{"flag" = 0})"
bnf is as output by "bnfinit", ideal is a valid ideal (or a module),
initializes data linked to the ray class group structure corresponding
to this module. This is the same as "bnrclass("bnf","ideal","flag"+1)".
The library syntax is bnrinit0"("bnf","ideal","flag","prec")".
bnrisconductor"(a1,{a2},{a3})"
"a1", "a2", "a3" represent an extension of the base field, given by
class field theory for some modulus encoded in the parameters. Outputs
1 if this modulus is the conductor, and 0 otherwise. This is slightly
faster than "bnrconductor".
The library syntax is bnrisconductor"(a1,a2,a3)" and the result is a
"long".
bnrisprincipal"("bnr",x,{"flag" = 1})"
bnr being the number field data which is output by "bnrinit""(,,1)" and
"x" being an ideal in any form, outputs the components of "x" on the
ray class group generators in a way similar to "bnfisprincipal". That
is a 3-component vector "v" where "v[1]" is the vector of components of
"x" on the ray class group generators, "v[2]" gives on the integral
basis an element alpha such that "x = "alphaprod"_ig_i^{x_i}". Finally
"v[3]" indicates the number of bits of accuracy left in the result. In
any case the result is checked for correctness, but "v[3]" is included
to see if it is necessary to increase the accuracy in other computa-
tions.
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 isprincipalrayall"("bnr",x,"flag")".
bnrrootnumber"("bnr","chi",{"flag" = 0})"
if chi" = "chi is a (not necessarily primitive) character over bnr, let
"L(s,"chi") = "sum"_{id} "chi"(id) N(id)^{-s}" be the associated Artin
L-function. Returns the so-called Artin root number, i.e. the complex
number "W("chi")" of modulus 1 such that
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",{"flag" = 0})}"
bnr being as output by "bnrinit(,,1)", finds a relative equation for
the class field corresponding to the modulus in bnr and the given con-
gruence subgroup using Stark units (set subgroup" = 0" if you want the
whole ray class group). The main variable of bnr must not be "x", and
the ground field and the class field must be totally real and not iso-
morphic to Q (over the rationnals, use "polsubcyclo" or "galoissubcy-
clo"). flag is optional and may be set to 0 to obtain a reduced rela-
tive polynomial, 1 to be satisfied with any relative polynomial, 2 to
obtain an absolute polynomial and 3 to obtain the irreducible relative
polynomial of the Stark unit, 0 being default. Example:
bnf = bnfinit(y^2 - 3);
bnr = bnrinit(bnf, 5, 1);
bnrstark(bnr, 0)
returns the ray class field of Q"(" sqrt "{3})" modulo 5.
Remark. The result of the computation depends on the choice of a modu-
lus verifying special conditions. By default the function will try few
moduli, choosing the one giving the smallest result. In some cases
where the result is however very large, you can tell the function to
try more moduli by adding 4 to the value of flag. Whether this flag is
set or not, the function may fail in some extreme cases, returning the
error message
"Cannot find a suitable modulus in FindModule".
In this case, the corresponding congruence group is a product of cyclic
groups and, for the time being, the class field has to be obtained by
splitting this group into its cyclic components.
The library syntax is bnrstark"("bnr","subgroup","flag")".
dirzetak"("nf",b)"
gives as a vector the first "b" coefficients of the Dedekind zeta func-
tion of the number field nf considered as a Dirichlet series.
The library syntax is dirzetak"("nf",b)".
factornf"(x,t)"
factorization of the univariate polynomial "x" over the number field
defined by the (univariate) polynomial "t". "x" may have coefficients
in Q or in the number field. The main variable of "t" must be of lower
priority than that of "x" (in other words the variable number of "t"
must be greater than that of "x"). However if the coefficients of the
number field occur explicitly (as polmods) as coefficients of "x", the
variable of these polmods 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 + 1, y^2+1); \\ these two are OK
? factornf(x^2 + Mod(z,z^2+1), y^2+1)
*** incorrect type in gmulsg
The library syntax is polfnf"(x,t)".
galoisfixedfield"("gal","perm",{fl = 0},{v = y}))"
gal being be a Galois field as output by "galoisinit" and perm an ele-
ment of gal".group" or a vector of such elements, computes the fixed
field of gal by the automorphism defined by the permutations perm of
the roots gal".roots". "P" is guaranteed to be squarefree modulo
gal".p".
If no flags or flag" = 0", output format is the same as for "nfsub-
field", 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".
Example:
G = galoisinit(x^4+1);
galoisfixedfield(G,G.group[2],2)
[x^2 + 2, Mod(x^3 + x, x^4 + 1), [x^2 - y*x - 1, x^2 + y*x - 1]]
computes the factorization "x^4+1 = (x^2-" sqrt "{-2}x-1)(x^2+" sqrt
"{-2}x-1)"
The library syntax is galoisfixedfield"("gal","perm",p)".
galoisinit"("pol",{den})"
computes the Galois group and all neccessary information for computing
the fixed fields of the Galois extension "K/"Q where "K" is the number
field defined by pol (monic irreducible polynomial in Z"[X]" or a num-
ber field as output by "nfinit"). The extension "K/"Q must be Galois
with Galois group ``weakly'' super-solvable (see "nfgaloisconj")
Warning: The interface of this function is experimental, so the
described output can be subject to important changes in the near
future. However the function itself should work as described. For any
remarks about this interface, please mail "allomber@math.u-bor-
deaux.fr".
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 inte-
gers 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 automor-
phisms 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:
* if "G/H ~ A_4" then "[o_1,...,o_g]" ends by "[2,2,3]".
* if "G/H ~ S_4" then "[o_1,...,o_g]" ends by "[2,2,3,2]".
* else "G" is super-solvable.
* 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.
* 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.
* 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")".
galoispermtopol"("gal","perm")"
gal being a galois field as output by "galoisinit" and perm a element
of gal".group", return the polynomial defining the Galois automorphism,
as output by "nfgaloisconj", associated with the permutation perm of
the roots gal".roots". perm can also be a vector or matrix, in this
case, "galoispermtopol" is applied to all components recursively.
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,{Z},{v})"
compute a polynomial defining the subfield of Q"("zeta"_n)" fixed by
the subgroup H of Z"/n"Z. The subgroup H can be given by a generator, a
set of generators given by a vector or a HNF matrix. If present "Z"
must be znstar(n), and is currently only used when H is a HNF matrix.
If v is given, the polynomial is given in the variable v.
The following function can be used to compute all subfields of
Q"("zeta"_n)" (of order less than "d", if "d" is set):
subcyclo(n, d = -1)=
{
local(Z,G,S);
if (d < 0, d = n);
Z = znstar(n);
G = matdiagonal(Z[2]);
S = [];
forsubgroup(H = G, d,
S = concat(S, galoissubcyclo(n, mathnf(concat(G,H)),Z));
);
S
}
The library syntax is galoissubcyclo"(n,H,Z,v)" where n is a C long
integer.
idealadd"("nf",x,y)"
sum of the two ideals "x" and "y" in the number field nf. When "x" and
"y" are given by Z-bases, this does not depend on nf and can be used to
compute the sum of any two Z-modules. The result is given in HNF.
The library syntax is idealadd"("nf",x,y)".
idealaddtoone"("nf",x,{y})"
"x" and "y" being two co-prime integral ideals (given in any form),
this gives a two-component row vector "[a,b]" such that "a belongs to
x", "b belongs to y" and "a+b = 1".
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})"
if "x" is a fractional ideal (given in any form), gives an element
alpha in nf such that for all prime ideals p such that the valuation of
"x" at p is non-zero, we have "v_{"p"}("alpha") = v_{"p"}(x)", and.
"v_{"p"}("alpha") >= 0" for all other "{"p"}".
If flag is non-zero, "x" must be given as a prime ideal factorization,
as output by "idealfactor", but possibly with zero or negative expo-
nents. This yields an element alpha such that for all prime ideals p
occurring in "x", "v_{"p"}("alpha")" is equal to the exponent of p in
"x", and for all other prime ideals, "v_{"p"}("alpha") >= 0". This gen-
eralizes "idealappr("nf",x,0)" since zero exponents are allowed. Note
that the algorithm used is slightly different, so that "ide-
alapp("nf",idealfactor("nf",x))" may not be the same as "ide-
alappr("nf",x,1)".
The library syntax is idealappr0"("nf",x,"flag")".
idealchinese"("nf",x,y)"
"x" being a prime ideal factorization (i.e. a 2 by 2 matrix whose first
column contain prime ideals, and the second column integral exponents),
"y" a vector of elements in nf indexed by the ideals in "x", computes
an element "b" such that
"v_"p"(b - y_"p") >= v_"p"(x)" for all prime ideals in "x" and
"v_"p"(b) >= 0" for all other p.
The library syntax is idealchinese"("nf",x,y)".
idealcoprime"("nf",x,y)"
given two integral ideals "x" and "y" in the number field nf, finds a
beta in the field, expressed on the integral basis nf"[7]", such that
beta".y" is an integral ideal coprime to "x".
The library syntax is idealcoprime"("nf",x)".
idealdiv"("nf",x,y,{"flag" = 0})"
quotient "x.y^{-1}" of the two ideals "x" and "y" in the number field
nf. The result is given in HNF.
If flag is non-zero, the quotient "x.y^{-1}" is assumed to be an inte-
gral ideal. This can be much faster when the norm of the quotient is
small even though the norms of "x" and "y" are large.
The library syntax is idealdiv0"("nf",x,y,"flag")". Also available are
idealdiv"("nf",x,y)" (flag" = 0") and idealdivexact"("nf",x,y)" (flag"
= 1").
idealfactor"("nf",x)"
factors into prime ideal powers the ideal "x" in the number field nf.
The output format is similar to the "factor" function, and the prime
ideals are represented in the form output by the "idealprimedec" func-
tion, i.e. as 5-element vectors.
The library syntax is idealfactor"("nf",x)".
idealhnf"("nf",a,{b})"
gives the Hermite normal form matrix of the ideal "a". The ideal can be
given in any form whatsoever (typically by an algebraic number if it is
principal, by a Z"_K"-system of generators, as a prime ideal as given
by "idealprimedec", or by a Z-basis).
If "b" is not omitted, assume the ideal given was "a"Z"_K+b"Z"_K",
where "a" and "b" are elements of "K" given either as vectors on the
integral basis nf"[7]" or as algebraic numbers.
The library syntax is idealhnf0"("nf",a,b)" where an omitted "b" is
coded as "NULL". Also available is idealhermite"("nf",a)" ("b" omit-
ted).
idealintersect"("nf",x,y)"
intersection of the two ideals "x" and "y" in the number field nf. When
"x" and "y" are given by Z-bases, this does not depend on nf and can be
used to compute the intersection of any two Z-modules. The result is
given in HNF.
The library syntax is idealintersect"("nf",x,y)".
idealinv"("nf",x)"
inverse of the ideal "x" in the number field nf. The result is the Her-
mite normal form of the inverse of the ideal, together with the oppo-
site of the Archimedean information if it is given.
The library syntax is idealinv"("nf",x)".
ideallist"("nf","bound",{"flag" = 4})"
computes the list of all ideals of norm less or equal to bound in the
number field nf. The result is a row vector with exactly bound compo-
nents. Each component is itself a row vector containing the informa-
tion about ideals of a given norm, in no specific order. This informa-
tion can be either the HNF of the ideal or the "idealstar" with possi-
bly some additional information.
If flag is present, its binary digits are toggles meaning
1: give also the generators in the "idealstar".
2: output "[L,U]", where "L" is as before and "U" is a vector of
"zinternallog"s of the units.
4: give only the ideals and not the "idealstar" or the "ideallog" of
the units.
The library syntax is ideallist0"("nf","bound","flag")", where bound
must be a C long integer. Also available is ideallist"("nf","bound")",
corresponding to the case flag" = 0".
ideallistarch"("nf","list",{"arch" = []},{"flag" = 0})"
vector of vectors of all "idealstarinit" (see "idealstar") of all mod-
ules in list, with Archimedean part arch added (void if omitted). list
is a vector of big ideals, as output by "ideallist""(..., "flag")" for
instance. flag is optional; its binary digits are toggles meaning: 1:
give generators as well, 2: list format is "[L,U]" (see "ideallist").
The library syntax is ideallistarch0"("nf","list","arch","flag")",
where an omitted arch is coded as "NULL".
ideallog"("nf",x,"bid")"
nf being a number field, bid being a ``big ideal'' as output by "ideal-
star" and "x" being a non-necessarily integral element of nf which must
have valuation equal to 0 at all prime ideals dividing "I = "bid"[1]",
computes the ``discrete logarithm'' of "x" on the generators given in
bid"[2]". In other words, if "g_i" are these generators, of orders
"d_i" respectively, the result is a column vector of integers "(x_i)"
such that "0 <= x_i < d_i" and
"x = "prod"_ig_i^{x_i} (mod ^*I) ."
Note that when "I" is a module, this implies also sign conditions on
the embeddings.
The library syntax is zideallog"("nf",x,"bid")".
idealmin"("nf",x,{"vdir"})"
computes a minimum of the ideal "x" in the direction vdir in the number
field nf.
The library syntax is minideal"("nf",x,"vdir","prec")", where an omit-
ted vdir is coded as "NULL".
idealmul"("nf",x,y,{"flag" = 0})"
ideal multiplication of the ideals "x" and "y" in the number field nf.
The result is a generating set for the ideal product with at most "n"
elements, and is in Hermite normal form if either "x" or "y" is in HNF
or is a prime ideal as output by "idealprimedec", and this is given
together with the sum of the Archimedean information in "x" and "y" if
both are given.
If flag is non-zero, reduce the result using "idealred".
The library syntax is idealmul"("nf",x,y)" (flag" = 0") or ideal-
mulred"("nf",x,y,"prec")" (flag" ! = 0"), where as usual, prec is a C
long integer representing the precision.
idealnorm"("nf",x)"
computes the norm of the ideal "x" in the number field nf.
The library syntax is idealnorm"("nf", x)".
idealpow"("nf",x,k,{"flag" = 0})"
computes the "k"-th power of the ideal "x" in the number field nf. "k"
can be positive, negative or zero. The result is NOT reduced, it is
really the "k"-th ideal power, and is given in HNF.
If flag is non-zero, reduce the result using "idealred". Note however
that this is NOT the same as as "idealpow("nf",x,k)" followed by reduc-
tion, since the reduction is performed throughout the powering process.
The library syntax corresponding to flag" = 0" is idealpow"("nf",x,k)".
If "k" is a "long", you can use idealpows"("nf",x,k)". Corresponding to
flag" = 1" is idealpowred"("nf",vp,k,"prec")", where prec is a "long".
idealprimedec"("nf",p)"
computes the prime ideal decomposition of the prime number "p" in the
number field nf. "p" must be a (positive) prime number. Note that the
fact that "p" is prime is not checked, so if a non-prime number "p" is
given it may lead to unpredictable results.
The result is a vector of 5-component vectors, each representing one of
the prime ideals above "p" in the number field nf. The representation
"vp = [p,a,e,f,b]" of a prime ideal means the following. The prime
ideal is equal to "p"Z"_K+"alphaZ"_K" where Z"_K" is the ring of inte-
gers of the field and alpha" = "sum"_i a_i"omega"_i" where the
omega"_i" form the integral basis nf".zk", "e" is the ramification
index, "f" is the residual index, and "b" is an "n"-component column
vector representing a beta" belongs to "Z"_K" such that "vp^{-1} =
"Z"_K+"beta"/p"Z"_K" which will be useful for computing valuations, but
which the user can ignore. The number alpha is guaranteed to have a
valuation equal to 1 at the prime ideal (this is automatic if "e > 1").
The library syntax is idealprimedec"("nf",p)".
idealprincipal"("nf",x)"
creates the principal ideal generated by the algebraic number "x"
(which must be of type integer, rational or polmod) in the number field
nf. The result is a one-column matrix.
The library syntax is principalideal"("nf",x)".
idealred"("nf",I,{"vdir" = 0})"
LLL reduction of the ideal "I" in the number field nf, along the direc-
tion vdir. If vdir is present, it must be an "r1+r2"-component vector
("r1" and "r2" number of real and complex places of nf as usual).
This function finds a ``small'' "a" in "I" (it is an LLL pseudo-minimum
along direction vdir). The result is the Hermite normal form of the
LLL-reduced ideal "r I/a", where "r" is a rational number such that the
resulting ideal is integral and primitive. This is often, but not
always, a reduced ideal in the sense of Buchmann. If "I" is an idele,
the logarithmic embeddings of "a" are subtracted to the Archimedean
part.
More often than not, a principal ideal will yield the identity matrix.
This is a quick and dirty way to check if ideals are principal without
computing a full "bnf" structure, but it's not a necessary condition;
hence, a non-trivial result doesn't prove the ideal is non-trivial in
the class group.
Note that this is not the same as the LLL reduction of the lattice "I"
since ideal operations are involved.
The library syntax is ideallllred"("nf",x,"vdir","prec")", where an
omitted vdir is coded as "NULL".
idealstar"("nf",I,{"flag" = 1})"
nf being a number field, and "I" either and ideal in any form, or a row
vector whose first component is an ideal and whose second component is
a row vector of "r_1" 0 or 1, outputs necessary data for computing in
the group "("Z"_K/I)^*".
If flag" = 2", the result is a 5-component vector "w". "w[1]" is the
ideal or module "I" itself. "w[2]" is the structure of the group. The
other components are difficult to describe and are used only in con-
junction with the function "ideallog".
If flag" = 1" (default), as flag" = 2", but do not compute explicit
generators for the cyclic components, which saves time.
If flag" = 0", computes the structure of "("Z"_K/I)^*" as a 3-component
vector "v". "v[1]" is the order, "v[2]" is the vector of SNF cyclic
components and "v[3]" the corresponding generators. When the row vector
is explicitly included, the non-zero elements of this vector are con-
sidered as real embeddings of nf in the order given by "polroots",
i.e. in nf[6] (nf".roots"), and then "I" is a module with components at
infinity.
To solve discrete logarithms (using "ideallog"), you have to choose
flag" = 2".
The library syntax is idealstar0"("nf",I,"flag")".
idealtwoelt"("nf",x,{a})"
computes a two-element representation of the ideal "x" in the number
field nf, using a straightforward (exponential time) search. "x" can be
an ideal in any form, (including perhaps an Archimedean part, which is
ignored) and the result is a row vector "[a,"alpha"]" with two compo-
nents such that "x = a"Z"_K+"alphaZ"_K" and "a belongs to "Z, where "a"
is the one passed as argument if any. If "x" is given by at least two
generators, "a" is chosen to be the positive generator of "x" cap Z.
Note that when an explicit "a" is given, we use an asymptotically
faster method, however in practice it is usually slower.
The library syntax is ideal_two_elt0"("nf",x,a)", where an omitted "a"
is entered as "NULL".
idealval"("nf",x,"vp")"
gives the valuation of the ideal "x" at the prime ideal vp in the num-
ber field nf, where vp must be a 5-component vector as given by "ideal-
primedec".
The library syntax is idealval"("nf",x,"vp")", and the result is a
"long" integer.
ideleprincipal"("nf",x)"
creates the principal idele generated by the algebraic number "x"
(which must be of type integer, rational or polmod) in the number field
nf. The result is a two-component vector, the first being a one-column
matrix representing the corresponding principal ideal, and the second
being the vector with "r_1+r_2" components giving the complex logarith-
mic embedding of "x".
The library syntax is principalidele"("nf",x)".
matalgtobasis"("nf",x)"
nf being a number field in "nfinit" format, and "x" a matrix whose
coefficients are expressed as polmods in nf, transforms this matrix
into a matrix whose coefficients are expressed on the integral basis of
nf. This is the same as applying "nfalgtobasis" to each entry, but it
would be dangerous to use the same name.
The library syntax is matalgtobasis"("nf",x)".
matbasistoalg"("nf",x)"
nf being a number field in "nfinit" format, and "x" a matrix whose
coefficients are expressed as column vectors on the integral basis of
nf, transforms this matrix into a matrix whose coefficients are alge-
braic numbers expressed as polmods. This is the same as applying "nfba-
sistoalg" to each entry, but it would be dangerous to use the same
name.
The library syntax is matbasistoalg"("nf",x)".
modreverse"(a)"
"a" being a polmod A(X) modulo T(X), finds the ``reverse polmod'' B(X)
modulo Q(X), where "Q" is the minimal polynomial of "a", which must be
equal to the degree of "T", and such that if theta is a root of "T"
then theta" = B("alpha")" for a certain root alpha of "Q".
This is very useful when one changes the generating element in alge-
braic extensions.
The library syntax is polmodrecip"(x)".
newtonpoly"(x,p)"
gives the vector of the slopes of the Newton polygon of the polynomial
"x" with respect to the prime number "p". The "n" components of the
vector are in decreasing order, where "n" is equal to the degree of
"x". Vertical slopes occur iff the constant coefficient of "x" is zero
and are denoted by "VERYBIGINT", the biggest single precision integer
representable on the machine ("2^{31}-1" (resp. "2^{63}-1") on 32-bit
(resp. 64-bit) machines), see "Label se:valuation".
The library syntax is newtonpoly"(x,p)".
nfalgtobasis"("nf",x)"
this is the inverse function of "nfbasistoalg". Given an object "x"
whose entries are expressed as algebraic numbers in the number field
nf, transforms it so that the entries are expressed as a column vector
on the integral basis nf".zk".
The library syntax is algtobasis"("nf",x)".
nfbasis"(x,{"flag" = 0},{p})"
integral basis of the number field defined by the irreducible, prefer-
ably monic, polynomial "x", using a modified version of the round 4
algorithm by default. The binary digits of flag have the following
meaning:
1: assume that no square of a prime greater than the default "prime-
limit" divides the discriminant of "x", i.e. that the index of "x" has
only small prime divisors.
2: use round 2 algorithm. For small degrees and coefficient size, this
is sometimes a little faster. (This program is the translation into C
of a program written by David Ford in Algeb.)
Thus for instance, if flag" = 3", this uses the round 2 algorithm and
outputs an order which will be maximal at all the small primes.
If "p" is present, we assume (without checking!) that it is the two-
column matrix of the factorization of the discriminant of the polyno-
mial "x". Note that it does not have to be a complete factorization.
This is especially useful if only a local integral basis for some small
set of places is desired: only factors with exponents greater or equal
to 2 will be considered.
The library syntax is nfbasis0"(x,"flag",p)". An extended version is
nfbasis"(x,&d,"flag",p)", where "d" will receive the discriminant of
the number field (not of the polynomial "x"), and an omitted "p" should
be input as "gzero". Also available are base"(x,&d)" (flag" = 0"),
base2"(x,&d)" (flag" = 2") and factoredbase"(x,p,&d)".
nfbasistoalg"("nf",x)"
this is the inverse function of "nfalgtobasis". Given an object "x"
whose entries are expressed on the integral basis nf".zk", transforms
it into an object whose entries are algebraic numbers (i.e. polmods).
The library syntax is basistoalg"("nf",x)".
nfdetint"("nf",x)"
given a pseudo-matrix "x", computes a non-zero ideal contained in
(i.e. multiple of) the determinant of "x". This is particularly useful
in conjunction with "nfhnfmod".
The library syntax is nfdetint"("nf",x)".
nfdisc"(x,{"flag" = 0},{p})"
field discriminant of the number field defined by the integral, prefer-
ably monic, irreducible polynomial "x". flag and "p" are exactly as in
"nfbasis". That is, "p" provides the matrix of a partial factorization
of the discriminant of "x", and binary digits of flag are as follows:
1: assume that no square of a prime greater than "primelimit" divides
the discriminant.
2: use the round 2 algorithm, instead of the default round 4. This
should be slower except maybe for polynomials of small degree and coef-
ficients.
The library syntax is nfdiscf0"(x,"flag",p)" where, to omit "p", you
should input "gzero". You can also use discf"(x)" (flag" = 0").
nfeltdiv"("nf",x,y)"
given two elements "x" and "y" in nf, computes their quotient "x/y" in
the number field nf.
The library syntax is element_div"("nf",x,y)".
nfeltdiveuc"("nf",x,y)"
given two elements "x" and "y" in nf, computes an algebraic integer "q"
in the number field nf such that the components of "x-qy" are reason-
ably small. In fact, this is functionally identical to "round(nfelt-
div("nf",x,y))".
The library syntax is nfdiveuc"("nf",x,y)".
nfeltdivmodpr"("nf",x,y,"pr")"
given two elements "x" and "y" in nf and pr a prime ideal in "modpr"
format (see "nfmodprinit"), computes their quotient "x / y" modulo the
prime ideal pr.
The library syntax is element_divmodpr"("nf",x,y,"pr")".
nfeltdivrem"("nf",x,y)"
given two elements "x" and "y" in nf, gives a two-element row vector
"[q,r]" such that "x = qy+r", "q" is an algebraic integer in nf, and
the components of "r" are reasonably small.
The library syntax is nfdivres"("nf",x,y)".
nfeltmod"("nf",x,y)"
given two elements "x" and "y" in nf, computes an element "r" of nf of
the form "r = x-qy" with "q" and algebraic integer, and such that "r"
is small. This is functionally identical to
"x - nfeltmul("nf",round(nfeltdiv("nf",x,y)),y)."
The library syntax is nfmod"("nf",x,y)".
nfeltmul"("nf",x,y)"
given two elements "x" and "y" in nf, computes their product "x*y" in
the number field nf.
The library syntax is element_mul"("nf",x,y)".
nfeltmulmodpr"("nf",x,y,"pr")"
given two elements "x" and "y" in nf and pr a prime ideal in "modpr"
format (see "nfmodprinit"), computes their product "x*y" modulo the
prime ideal pr.
The library syntax is element_mulmodpr"("nf",x,y,"pr")".
nfeltpow"("nf",x,k)"
given an element "x" in nf, and a positive or negative integer "k",
computes "x^k" in the number field nf.
The library syntax is element_pow"("nf",x,k)".
nfeltpowmodpr"("nf",x,k,"pr")"
given an element "x" in nf, an integer "k" and a prime ideal pr in
"modpr" format (see "nfmodprinit"), computes "x^k" modulo the prime
ideal pr.
The library syntax is element_powmodpr"("nf",x,k,"pr")".
nfeltreduce"("nf",x,"ideal")"
given an ideal in Hermite normal form and an element "x" of the number
field nf, finds an element "r" in nf such that "x-r" belongs to the
ideal and "r" is small.
The library syntax is element_reduce"("nf",x,"ideal")".
nfeltreducemodpr"("nf",x,"pr")"
given an element "x" of the number field nf and a prime ideal pr in
"modpr" format compute a canonical representative for the class of "x"
modulo pr.
The library syntax is nfreducemodpr2"("nf",x,"pr")".
nfeltval"("nf",x,"pr")"
given an element "x" in nf and a prime ideal pr in the format output by
"idealprimedec", computes their the valuation at pr of the element "x".
The same result could be obtained using "idealval("nf",x,"pr")" (since
"x" would then be converted to a principal ideal), but it would be less
efficient.
The library syntax is element_val"("nf",x,"pr")", and the result is a
"long".
nffactor"("nf",x)"
factorization of the univariate polynomial "x" over the number field nf
given by "nfinit". "x" has coefficients in nf (i.e. either scalar,
polmod, polynomial or column vector). The main variable of nf must be
of lower priority than that of "x" (in other words, the variable number
of nf must be greater than that of "x"). However if the polynomial
defining the number field occurs explicitly in the coefficients of "x"
(as modulus of a "t_POLMOD"), its main variable must be the same as the
main variable of "x". For example,
? nf = nfinit(y^2 + 1);
? nffactor(nf, x^2 + y); \\ OK
? nffactor(nf, x^2 + Mod(y, y^2+1)); \\ OK
? nffactor(nf, x^2 + Mod(z, z^2+1)); \\ WRONG
The library syntax is nffactor"("nf",x)".
nffactormod"("nf",x,"pr")"
factorization of the univariate polynomial "x" modulo the prime ideal
pr in the number field nf. "x" can have coefficients in the number
field (scalar, polmod, polynomial, column vector) or modulo the prime
ideal (integermod modulo the rational prime under pr, polmod or polyno-
mial with integermod coefficients, column vector of integermod). The
prime ideal pr must be in the format output by "idealprimedec". The
main variable of nf must be of lower priority than that of "x" (in
other words the variable number of nf must be greater than that of
"x"). However if the coefficients of the number field occur explicitly
(as polmods) as coefficients of "x", the variable of these polmods must
be the same as the main variable of "t" (see "nffactor").
The library syntax is nffactormod"("nf",x,"pr")".
nfgaloisapply"("nf","aut",x)"
nf being a number field as output by "nfinit", and aut being a Galois
automorphism of nf expressed either as a polynomial or a polmod (such
automorphisms being found using for example one of the variants of
"nfgaloisconj"), computes the action of the automorphism aut on the
object "x" in the number field. "x" can be an element (scalar, polmod,
polynomial or column vector) of the number field, an ideal (either
given by Z"_K"-generators or by a Z-basis), a prime ideal (given as a
5-element row vector) or an idele (given as a 2-element row vector).
Because of possible confusion with elements and ideals, other vector or
matrix arguments are forbidden.
The library syntax is galoisapply"("nf","aut",x)".
nfgaloisconj"("nf",{"flag" = 0},{d})"
nf being a number field as output by "nfinit", computes the conjugates
of a root "r" of the non-constant polynomial "x = "nf"[1]" expressed as
polynomials in "r". This can be used even if the number field nf is not
Galois since some conjugates may lie in the field. As a note to old-
timers of PARI, starting with version 2.0.17 this function works much
better than in earlier versions.
nf can simply be a polynomial if flag" ! = 1".
If no flags or flag" = 0", if nf is a number field use a combination of
flag 4 and 1 and the result is always complete, else use a combination
of flag 4 and 2 and the result is subject to the restriction of flag" =
2", but a warning is issued when it is not proven complete.
If flag" = 1", use "nfroots" (require a number field).
If flag" = 2", use complex approximations to the roots and an integral
LLL. The result is not guaranteed to be complete: some conjugates may
be missing (no warning issued), especially so if the corresponding
polynomial has a huge index. In that case, increasing the default pre-
cision may help.
If flag" = 4", use Allombert's algorithm and permutation testing. If
the field is Galois with ``weakly'' super solvable Galois group, return
the complete list of automorphisms, else only the identity element. If
present, "d" is assumed to be a multiple of the least common denomina-
tor of the conjugates expressed as polynomial in a root of pol.
A group G is ``weakly'' super solvable if it contains a super solvable
normal subgroup "H" such that "G = H" , or "G/H ~ A_4" , or "G/H ~
S_4". Abelian and nilpotent groups are ``weakly'' super solvable. In
practice, almost all groups of small order are ``weakly'' super solv-
able, the exceptions having order 36(1 exception), 48(2), 56(1), 60(1),
72(5), 75(1), 80(1), 96(10) and " >= 108".
Hence flag" = 4" permits to quickly check whether a polynomial of order
strictly less than 36 is Galois or not. This method is much faster than
"nfroots" and can be applied to polynomials of degree larger than 50.
The library syntax is galoisconj0"("nf","flag",d,"prec")". Also avail-
able are galoisconj"("nf")" for flag" = 0", galois-
conj2"("nf",n,"prec")" for flag" = 2" where "n" is a bound on the num-
ber of conjugates, and galoisconj4"("nf",d)" corresponding to flag" =
4".
nfhilbert"("nf",a,b,{"pr"})"
if pr is omitted, compute the global Hilbert symbol "(a,b)" in nf, that
is 1 if "x^2 - a y^2 - b z^2" has a non trivial solution "(x,y,z)" in
nf, and "-1" otherwise. Otherwise compute the local symbol modulo the
prime ideal pr (as output by "idealprimedec").
The library syntax is nfhilbert"("nf",a,b,"pr")", where an omitted pr
is coded as "NULL".
nfhnf"("nf",x)"
given a pseudo-matrix "(A,I)", finds a pseudo-basis in Hermite normal
form of the module it generates.
The library syntax is nfhermite"("nf",x)".
nfhnfmod"("nf",x,"detx")"
given a pseudo-matrix "(A,I)" and an ideal detx which is contained in
(read integral multiple of) the determinant of "(A,I)", finds a pseudo-
basis in Hermite normal form of the module generated by "(A,I)". This
avoids coefficient explosion. detx can be computed using the function
"nfdetint".
The library syntax is nfhermitemod"("nf",x,"detx")".
nfinit"("pol",{"flag" = 0})"
pol being a non-constant, preferably monic, irreducible polynomial in
Z"[X]", initializes a number field structure ("nf") associated to the
field "K" defined by pol. As such, it's a technical object passed as
the first argument to most "nf"xxx functions, but it contains some
information which may be directly useful. Access to this information
via member functions is prefered since the specific data organization
specified below may change in the future. Currently, "nf" is a row vec-
tor with 9 components:
nf"[1]" contains the polynomial pol (nf".pol").
nf"[2]" contains "[r1,r2]" (nf".sign"), the number of real and complex
places of "K".
nf"[3]" contains the discriminant d(K) (nf".disc") of "K".
nf"[4]" contains the index of nf"[1]", i.e. "["Z"_K : "Z"["theta"]]",
where theta is any root of nf"[1]".
nf"[5]" is a vector containing 7 matrices "M", "MC", "T2", "T", "MD",
"TI", "MDI" useful for certain computations in the number field "K".
* "M" is the "(r1+r2) x n" matrix whose columns represent the numeri-
cal values of the conjugates of the elements of the integral basis.
* "MC" is essentially the conjugate of the transpose of "M", except
that the last "r2" columns are also multiplied by 2.
* "T2" is an "n x n" matrix equal to the real part of the product
"MC.M" (which is a real positive definite symmetric matrix), the so-
called "T_2"-matrix (nf".t2").
* "T" is the "n x n" matrix whose coefficients are
"Tr("omega"_i"omega"_j)" where the omega"_i" are the elements of the
integral basis. Note that "T = \overline{MC}.M" and in particular that
"T = T_2" if the field is totally real (in practice "T_2" will have
real approximate entries and "T" will have integer entries). Note also
that
det "(T)" is equal to the discriminant of the field "K".
* The columns of "MD" (nf".diff") express a Z-basis of the different
of "K" on the integral basis.
* "TI" is equal to "d(K)T^{-1}", which has integral coefficients.
Note that, understood as as ideal, the matrix "T^{-1}" generates the
codifferent ideal.
* Finally, "MDI" is a two-element representation (for faster ideal
product) of d(K) times the codifferent ideal (nf".disc*"nf".codiff",
which is an integral ideal). "MDI" is only used in "idealinv".
nf"[6]" is the vector containing the "r1+r2" roots (nf".roots") of
nf"[1]" corresponding to the "r1+r2" embeddings of the number field
into C (the first "r1" components are real, the next "r2" have positive
imaginary part).
nf"[7]" is an integral basis in Hermite normal form for Z"_K" (nf".zk")
expressed on the powers of theta.
nf"[8]" is the "n x n" integral matrix expressing the power basis in
terms of the integral basis, and finally
nf"[9]" is the "n x n^2" matrix giving the multiplication table of the
integral basis.
If a non monic polynomial is input, "nfinit" will transform it into a
monic one, then reduce it (see flag" = 3"). It is allowed, though not
very useful given the existence of nfnewprec, to input a "nf" or a
"bnf" instead of a polynomial.
The special input format "[x,B]" is also accepted where "x" is a poly-
nomial as above and "B" is the integer basis, as computed by "nfbasis".
This can be useful since "nfinit" uses the round 4 algorithm by
default, which can be very slow in pathological cases where round 2
("nfbasis(x,2)") would succeed very quickly.
If flag" = 2": pol is changed into another polynomial "P" defining the
same number field, which is as simple as can easily be found using the
"polred" algorithm, and all the subsequent computations are done using
this new polynomial. In particular, the first component of the result
is the modified polynomial.
If flag" = 3", does a "polred" as in case 2, but outputs
"["nf",Mod(a,P)]", where nf is as before and "Mod(a,P) = Mod(x,"pol")"
gives the change of variables. This is implicit when pol is not monic:
first a linear change of variables is performed, to get a monic polyno-
mial, then a "polred" reduction.
If flag" = 4", as 2 but uses a partial "polred".
If flag" = 5", as 3 using a partial "polred".
The library syntax is nfinit0"(x,"flag","prec")".
nfisideal"("nf",x)"
returns 1 if "x" is an ideal in the number field nf, 0 otherwise.
The library syntax is isideal"(x)".
nfisincl"(x,y)"
tests whether the number field "K" defined by the polynomial "x" is
conjugate to a subfield of the field "L" defined by "y" (where "x" and
"y" must be in Q"[X]"). If they are not, the output is the number 0. If
they are, the output is a vector of polynomials, each polynomial "a"
representing an embedding of "K" into "L", i.e. being such that "y | x
o a".
If "y" is a number field (nf), a much faster algorithm is used (factor-
ing "x" over "y" using "nffactor"). Before version 2.0.14, this wasn't
guaranteed to return all the embeddings, hence was triggered by a spe-
cial flag. This is no more the case.
The library syntax is nfisincl"(x,y,"flag")".
nfisisom"(x,y)"
as "nfisincl", but tests for isomorphism. If either "x" or "y" is a
number field, a much faster algorithm will be used.
The library syntax is nfisisom"(x,y,"flag")".
nfnewprec"("nf")"
transforms the number field nf into the corresponding data using cur-
rent (usually larger) precision. This function works as expected if nf
is in fact a bnf (update bnf to current precision) but may be quite
slow (many generators of principal ideals have to be computed).
The library syntax is nfnewprec"("nf","prec")".
nfkermodpr"("nf",a,"pr")"
kernel of the matrix "a" in Z"_K/"pr, where pr is in modpr format (see
"nfmodprinit").
The library syntax is nfkermodpr"("nf",a,"pr")".
nfmodprinit"("nf","pr")"
transforms the prime ideal pr into "modpr" format necessary for all
operations modulo pr in the number field nf. Returns a two-component
vector "[P,a]", where "P" is the Hermite normal form of pr, and "a" is
an integral element congruent to 1 modulo pr, and congruent to 0 modulo
"p / pr^e". Here "p = "Z cap pr and "e" is the absolute ramification
index.
The library syntax is nfmodprinit"("nf","pr")".
nfsubfields"("nf",{d = 0})"
finds all subfields of degree "d" of the number field nf (all subfields
if "d" is null or omitted). The result is a vector of subfields, each
being given by "[g,h]", where "g" is an absolute equation and "h"
expresses one of the roots of "g" in terms of the root "x" of the poly-
nomial defining nf. This is a crude implementation by M. Olivier of an
algorithm due to J. Klueners.
The library syntax is subfields"("nf",d)".
nfroots"("nf",x)"
roots of the polynomial "x" in the number field nf given by "nfinit"
without multiplicity. "x" has coefficients in the number field (scalar,
polmod, polynomial, column vector). The main variable of nf must be of
lower priority than that of "x" (in other words the variable number of
nf must be greater than that of "x"). However if the coefficients of
the number field occur explicitly (as polmods) as coefficients of "x",
the variable of these polmods must be the same as the main variable of
"t" (see "nffactor").
The library syntax is nfroots"("nf",x)".
nfrootsof1"("nf")"
computes the number of roots of unity "w" and a primitive "w"-th root
of unity (expressed on the integral basis) belonging to the number
field nf. The result is a two-component vector "[w,z]" where "z" is a
column vector expressing a primitive "w"-th root of unity on the inte-
gral basis nf".zk".
The library syntax is rootsof1"("nf")".
nfsnf"("nf",x)"
given a torsion module "x" as a 3-component row vector "[A,I,J]" where
"A" is a square invertible "n x n" matrix, "I" and "J" are two ideal
lists, outputs an ideal list "d_1,...,d_n" which is the Smith normal
form of "x". In other words, "x" is isomorphic to Z"_K/d_1" oplus "..."
oplus Z"_K/d_n" and "d_i" divides "d_{i-1}" for "i >= 2". The link
between "x" and "[A,I,J]" is as follows: if "e_i" is the canonical
basis of "K^n", "I = [b_1,...,b_n]" and "J = [a_1,...,a_n]", then "x"
is isomorphic to
" (b_1e_1" oplus "..." oplus " b_ne_n) / (a_1A_1" oplus "..." oplus "
a_nA_n)
, "
where the "A_j" are the columns of the matrix "A". Note that every fi-
nitely generated torsion module can be given in this way, and even with
"b_i = Z_K" for all "i".
The library syntax is nfsmith"("nf",x)".
nfsolvemodpr"("nf",a,b,"pr")"
solution of "a.x = b" in Z"_K/"pr, where "a" is a matrix and "b" a col-
umn vector, and where pr is in modpr format (see "nfmodprinit").
The library syntax is nfsolvemodpr"("nf",a,b,"pr")".
polcompositum"(x,y,{"flag" = 0})"
"x" and "y" being polynomials in Z"[X]" in the same variable, outputs a
vector giving the list of all possible composita of the number fields
defined by "x" and "y", if "x" and "y" are irreducible, or of the cor-
responding etale algebras, if they are only squarefree. Returns an
error if one of the polynomials is not squarefree. When one of the
polynomials is irreducible (say "x"), it is often much faster to use
"nffactor(nfinit(x), y)" then "rnfequation".
If flag" = 1", outputs a vector of 4-component vectors "[z,a,b,k]",
where "z" ranges through the list of all possible compositums as above,
and "a" (resp. "b") expresses the root of "x" (resp. "y") as a polmod
in a root of "z", and "k" is a small integer k such that "a+kb" is the
chosen root of "z".
The compositum will quite often be defined by a complicated polynomial,
which it is advisable to reduce before further work. Here is a simple
example involving the field Q"("zeta"_5, 5^{1/5})":
? z = polcompositum(x^5 - 5, polcyclo(5), 1)[1];
? pol = z[1] \\ pol defines the compositum
%2 = x^20 + 5*x^19 + 15*x^18 + 35*x^17 + 70*x^16 + 141*x^15 + 260*x^14 \
+ 355*x^13 + 95*x^12 - 1460*x^11 - 3279*x^10 - 3660*x^9 - 2005*x^8 \
+ 705*x^7 + 9210*x^6 + 13506*x^5 + 7145*x^4 - 2740*x^3 + 1040*x^2 \
- 320*x + 256
? a = z[2]; a^5 - 5 \\ a is a fifth root of 5
%3 = 0
? z = polredabs(pol, 1); \\ look for a simpler polynomial
? pol = z[1]
%5 = x^20 + 25*x^10 + 5
? a = subst(a.pol, x, z[2]) \\ a in the new coordinates
%6 = Mod(-5/22*x^19 + 1/22*x^14 - 123/22*x^9 + 9/11*x^4, x^20 + 25*x^10 + 5)
The library syntax is polcompositum0"(x,y,"flag")".
polgalois"(x)"
Galois group of the non-constant polynomial "x belongs to "Q"[X]". In
the present version 2.2.0, "x" must be irreducible and the degree of
"x" must be less than or equal to 7. On certain versions for which the
data file of Galois resolvents has been installed (available in the
Unix distribution as a separate package), degrees 8, 9, 10 and 11 are
also implemented.
The output is a 3-component vector "[n,s,k]" with the following mean-
ing: "n" is the cardinality of the group, "s" is its signature ("s = 1"
if the group is a subgroup of the alternating group "A_n", "s = -1"
otherwise), and "k" is the number of the group corresponding to a given
pair "(n,s)" ("k = 1" except in 2 cases). Specifically, the groups are
coded as follows, using standard notations (see GTM 138, quoted at the
beginning of this section; see also ``The transitive groups of degree
up to eleven'', by G. Butler and J. McKay in Communications in Algebra,
vol. 11, 1983, pp. 863--911):
In degree 1: "S_1 = [1,-1,1]".
In degree 2: "S_2 = [2,-1,1]".
In degree 3: "A_3 = C_3 = [3,1,1]", "S_3 = [6,-1,1]".
In degree 4: "C_4 = [4,-1,1]", "V_4 = [4,1,1]", "D_4 = [8,-1,1]", "A_4
= [12,1,1]", "S_4 = [24,-1,1]".
In degree 5: "C_5 = [5,1,1]", "D_5 = [10,1,1]", "M_{20} = [20,-1,1]",
"A_5 = [60,1,1]", "S_5 = [120,-1,1]".
In degree 6: "C_6 = [6,-1,1]", "S_3 = [6,-1,2]", "D_6 = [12,-1,1]",
"A_4 = [12,1,1]", "G_{18} = [18,-1,1]", "S_4^ -= [24,-1,1]", "A_4 x C_2
= [24,-1,2]", "S_4^ += [24,1,1]", "G_{36}^ -= [36,-1,1]", "G_{36}^ +=
[36,1,1]", "S_4 x C_2 = [48,-1,1]", "A_5 = PSL_2(5) = [60,1,1]",
"G_{72} = [72,-1,1]", "S_5 = PGL_2(5) = [120,-1,1]", "A_6 = [360,1,1]",
"S_6 = [720,-1,1]".
In degree 7: "C_7 = [7,1,1]", "D_7 = [14,-1,1]", "M_{21} = [21,1,1]",
"M_{42} = [42,-1,1]", "PSL_2(7) = PSL_3(2) = [168,1,1]", "A_7 =
[2520,1,1]", "S_7 = [5040,-1,1]".
The method used is that of resolvent polynomials and is sensitive to
the current precision. The precision is updated internally but, in very
rare cases, a wrong result may be returned if the initial precision was
not sufficient.
The library syntax is galois"(x,"prec")".
polred"(x,{"flag" = 0},{p})"
finds polynomials with reasonably small coefficients defining subfields
of the number field defined by "x". One of the polynomials always
defines Q (hence is equal to "x-1"), and another always defines the
same number field as "x" if "x" is irreducible. All "x" accepted by
"nfinit" are also allowed here (e.g. non-monic polynomials, "nf",
"bnf", "[x,Z_K_basis]").
The following binary digits of flag are significant:
1: does a partial reduction only. This means that only a suborder of
the maximal order may be used.
2: gives also elements. The result is a two-column matrix, the first
column giving the elements defining these subfields, the second giving
the corresponding minimal polynomials.
If "p" is given, it is assumed that it is the two-column matrix of the
factorization of the discriminant of the polynomial "x".
The library syntax is polred0"(x,"flag",p,"prec")", where an omitted
"p" is coded by "gzero". Also available are polred"(x,"prec")" and fac-
toredpolred"(x,p,"prec")", both corresponding to flag" = 0".
polredabs"(x,{"flag" = 0})"
finds one of the polynomial defining the same number field as the one
defined by "x", and such that the sum of the squares of the modulus of
the roots (i.e. the "T_2"-norm) is minimal. All "x" accepted by
"nfinit" are also allowed here (e.g. non-monic polynomials, "nf",
"bnf", "[x,Z_K_basis]").
The binary digits of flag mean
1: outputs a two-component row vector "[P,a]", where "P" is the default
output and "a" is an element expressed on a root of the polynomial "P",
whose minimal polynomial is equal to "x".
4: gives all polynomials of minimal "T_2" norm (of the two polynomials
P(x) and "P(-x)", only one is given).
The library syntax is polredabs0"(x,"flag","prec")".
polredord"(x)"
finds polynomials with reasonably small coefficients and of the same
degree as that of "x" defining suborders of the order defined by "x".
One of the polynomials always defines Q (hence is equal to "(x-1)^n",
where "n" is the degree), and another always defines the same order as
"x" if "x" is irreducible.
The library syntax is ordred"(x)".
poltschirnhaus"(x)"
applies a random Tschirnhausen transformation to the polynomial "x",
which is assumed to be non-constant and separable, so as to obtain a
new equation for the etale algebra defined by "x". This is for instance
useful when computing resolvents, hence is used by the "polgalois"
function.
The library syntax is tschirnhaus"(x)".
rnfalgtobasis"("rnf",x)"
rnf being a relative number field extension "L/K" as output by
"rnfinit" and "x" being an element of "L" expressed as a polynomial or
polmod with polmod coefficients, expresses "x" on the relative integral
basis.
The library syntax is rnfalgtobasis"("rnf",x)".
rnfbasis"("bnf",x)"
given a big number field bnf as output by "bnfinit", and either a poly-
nomial "x" with coefficients in bnf defining a relative extension "L"
of bnf, or a pseudo-basis "x" of such an extension, gives either a true
bnf-basis of "L" if it exists, or an "n+1"-element generating set of
"L" if not, where "n" is the rank of "L" over bnf.
The library syntax is rnfbasis"("bnf",x)".
rnfbasistoalg"("rnf",x)"
rnf being a relative number field extension "L/K" as output by
"rnfinit" and "x" being an element of "L" expressed on the relative
integral basis, computes the representation of "x" as a polmod with
polmods coefficients.
The library syntax is rnfbasistoalg"("rnf",x)".
rnfcharpoly"("nf",T,a,{v = x})"
characteristic polynomial of "a" over nf, where "a" belongs to the
algebra defined by "T" over nf, i.e. nf"[X]/(T)". Returns a polynomial
in variable "v" ("x" by default).
The library syntax is rnfcharpoly"("nf",T,a,v)", where "v" is a vari-
able number.
rnfconductor"("bnf","pol")"
bnf being a big number field as output by "bnfinit", and pol a relative
polynomial defining an Abelian extension, computes the class field the-
ory conductor of this Abelian extension. The result is a 3-component
vector "["conductor","rayclgp","subgroup"]", where conductor is the
conductor of the extension given as a 2-component row vector "[f_0,f_
oo ]", rayclgp is the full ray class group corresponding to the conduc-
tor given as a 3-component vector [h,cyc,gen] as usual for a group, and
subgroup is a matrix in HNF defining the subgroup of the ray class
group on the given generators gen.
The library syntax is rnfconductor"("rnf","pol","prec")".
rnfdedekind"("nf","pol","pr")"
given a number field nf as output by "nfinit" and a polynomial pol with
coefficients in nf defining a relative extension "L" of nf, evaluates
the relative Dedekind criterion over the order defined by a root of pol
for the prime ideal pr and outputs a 3-component vector as the result.
The first component is a flag equal to 1 if the enlarged order could be
proven to be pr-maximal and to 0 otherwise (it may be maximal in the
latter case if pr is ramified in "L"), the second component is a
pseudo-basis of the enlarged order and the third component is the valu-
ation at pr of the order discriminant.
The library syntax is rnfdedekind"("nf","pol","pr")".
rnfdet"("nf",M)"
given a pseudomatrix "M" over the maximal order of nf, computes its
pseudodeterminant.
The library syntax is rnfdet"("nf",M)".
rnfdisc"("nf","pol")"
given a number field nf as output by "nfinit" and a polynomial pol with
coefficients in nf defining a relative extension "L" of nf, computes
the relative discriminant of "L". This is a two-element row vector
"[D,d]", where "D" is the relative ideal discriminant and "d" is the
relative discriminant considered as an element of nf"^*/{"nf"^*}^2".
The main variable of nf must be of lower priority than that of pol.
Note: As usual, nf can be a bnf as output by "nfinit".
The library syntax is rnfdiscf"("bnf","pol")".
rnfeltabstorel"("rnf",x)"
rnf being a relative number field extension "L/K" as output by
"rnfinit" and "x" being an element of "L" expressed as a polynomial
modulo the absolute equation rnf"[11][1]", computes "x" as an element
of the relative extension "L/K" as a polmod with polmod coefficients.
The library syntax is rnfelementabstorel"("rnf",x)".
rnfeltdown"("rnf",x)"
rnf being a relative number field extension "L/K" as output by
"rnfinit" and "x" being an element of "L" expressed as a polynomial or
polmod with polmod coefficients, computes "x" as an element of "K" as a
polmod, assuming "x" is in "K" (otherwise an error will occur). If "x"
is given on the relative integral basis, apply "rnfbasistoalg" first,
otherwise PARI will believe you are dealing with a vector.
The library syntax is rnfelementdown"("rnf",x)".
rnfeltreltoabs"("rnf",x)"
rnf being a relative number field extension "L/K" as output by
"rnfinit" and "x" being an element of "L" expressed as a polynomial or
polmod with polmod coefficients, computes "x" as an element of the
absolute extension "L/"Q as a polynomial modulo the absolute equation
rnf"[11][1]". If "x" is given on the relative integral basis, apply
"rnfbasistoalg" first, otherwise PARI will believe you are dealing with
a vector.
The library syntax is rnfelementreltoabs"("rnf",x)".
rnfeltup"("rnf",x)"
rnf being a relative number field extension "L/K" as output by
"rnfinit" and "x" being an element of "K" expressed as a polynomial or
polmod, computes "x" as an element of the absolute extension "L/"Q as a
polynomial modulo the absolute equation rnf"[11][1]". Note that it is
unnecessary to compute "x" as an element of the relative extension
"L/K" (its expression would be identical to itself). If "x" is given on
the integral basis of "K", apply "nfbasistoalg" first, otherwise PARI
will believe you are dealing with a vector.
The library syntax is rnfelementup"("rnf",x)".
rnfequation"("nf","pol",{"flag" = 0})"
given a number field nf as output by "nfinit" (or simply a polynomial)
and a polynomial pol with coefficients in nf defining a relative exten-
sion "L" of nf, computes the absolute equation of "L" over Q.
If flag is non-zero, outputs a 3-component row vector "[z,a,k]", where
"z" is the absolute equation of "L" over Q, as in the default behav-
iour, "a" expresses as an element of "L" a root alpha of the polynomial
defining the base field nf, and "k" is a small integer such that theta"
= "beta"+k"alpha where theta is a root of "z" and beta a root of pol.
The main variable of nf must be of lower priority than that of pol.
Note that for efficiency, this does not check whether the relative
equation is irreducible over nf, but only if it is squarefree. If it is
reducible but squarefree, the result will be the absolute equation of
the etale algebra defined by pol. If pol is not squarefree, an error
message will be issued.
The library syntax is rnfequation0"("nf","pol","flag")".
rnfhnfbasis"("bnf",x)"
given a big number field bnf as output by "bnfinit", and either a poly-
nomial "x" with coefficients in bnf defining a relative extension "L"
of bnf, or a pseudo-basis "x" of such an extension, gives either a true
bnf-basis of "L" in upper triangular Hermite normal form, if it exists,
zero otherwise.
The library syntax is rnfhermitebasis"("nf",x)".
rnfidealabstorel"("rnf",x)"
rnf being a relative number field extension "L/K" as output by
"rnfinit" and "x" being an ideal of the absolute extension "L/"Q given
in HNF (if it is not, apply "idealhnf" first), computes the relative
pseudomatrix in HNF giving the ideal "x" considered as an ideal of the
relative extension "L/K".
The library syntax is rnfidealabstorel"("rnf",x)".
rnfidealdown"("rnf",x)"
rnf being a relative number field extension "L/K" as output by
"rnfinit" and "x" being an ideal of the absolute extension "L/"Q given
in HNF (if it is not, apply "idealhnf" first), gives the ideal of "K"
below "x", i.e. the intersection of "x" with "K". Note that, if "x" is
given as a relative ideal (i.e. a pseudomatrix in HNF), then it is not
necessary to use this function since the result is simply the first
ideal of the ideal list of the pseudomatrix.
The library syntax is rnfidealdown"("rnf",x)".
rnfidealhnf"("rnf",x)"
rnf being a relative number field extension "L/K" as output by
"rnfinit" and "x" being a relative ideal (which can be, as in the abso-
lute case, of many different types, including of course elements), com-
putes as a 2-component row vector the relative Hermite normal form of
"x", the first component being the HNF matrix (with entries on the
integral basis), and the second component the ideals.
The library syntax is rnfidealhermite"("rnf",x)".
rnfidealmul"("rnf",x,y)"
rnf being a relative number field extension "L/K" as output by
"rnfinit" and "x" and "y" being ideals of the relative extension "L/K"
given by pseudo-matrices, outputs the ideal product, again as a rela-
tive ideal.
The library syntax is rnfidealmul"("rnf",x,y)".
rnfidealnormabs"("rnf",x)"
rnf being a relative number field extension "L/K" as output by
"rnfinit" and "x" being a relative ideal (which can be, as in the abso-
lute case, of many different types, including of course elements), com-
putes the norm of the ideal "x" considered as an ideal of the absolute
extension "L/"Q. This is identical to "idealnorm(rnfidealnorm-
rel("rnf",x))", only faster.
The library syntax is rnfidealnormabs"("rnf",x)".
rnfidealnormrel"("rnf",x)"
rnf being a relative number field extension "L/K" as output by
"rnfinit" and "x" being a relative ideal (which can be, as in the abso-
lute case, of many different types, including of course elements), com-
putes the relative norm of "x" as a ideal of "K" in HNF.
The library syntax is rnfidealnormrel"("rnf",x)".
rnfidealreltoabs"("rnf",x)"
rnf being a relative number field extension "L/K" as output by
"rnfinit" and "x" being a relative ideal (which can be, as in the abso-
lute case, of many different types, including of course elements), com-
putes the HNF matrix of the ideal "x" considered as an ideal of the
absolute extension "L/"Q.
The library syntax is rnfidealreltoabs"("rnf",x)".
rnfidealtwoelt"("rnf",x)"
rnf being a relative number field extension "L/K" as output by
"rnfinit" and "x" being an ideal of the relative extension "L/K" given
by a pseudo-matrix, gives a vector of two generators of "x" over Z"_L"
expressed as polmods with polmod coefficients.
The library syntax is rnfidealtwoelement"("rnf",x)".
rnfidealup"("rnf",x)"
rnf being a relative number field extension "L/K" as output by
"rnfinit" and "x" being an ideal of "K", gives the ideal "x"Z"_L" as an
absolute ideal of "L/"Q (the relative ideal representation is trivial:
the matrix is the identity matrix, and the ideal list starts with "x",
all the other ideals being Z"_K").
The library syntax is rnfidealup"("rnf",x)".
rnfinit"("nf","pol")"
nf being a number field in "nfinit" format considered as base field,
and pol a polynomial defining a relative extension over nf, this com-
putes all the necessary data to work in the relative extension. The
main variable of pol must be of higher priority (i.e. lower number)
than that of nf, and the coefficients of pol must be in nf.
The result is an 11-component row vector as follows (most of the compo-
nents are technical), the numbering being very close to that of
"nfinit". In the following description, we let "K" be the base field
defined by nf, "m" the degree of the base field, "n" the relative
degree, "L" the large field (of relative degree "n" or absolute degree
"nm"), "r_1" and "r_2" the number of real and complex places of "K".
rnf"[1]" contains the relative polynomial pol.
rnf"[2]" is a row vector with "r_1+r_2" entries, entry "j" being a
2-component row vector "[r_{j,1},r_{j,2}]" where "r_{j,1}" and
"r_{j,2}" are the number of real and complex places of "L" above the
"j"-th place of "K" so that "r_{j,1} = 0" and "r_{j,2} = n" if "j" is a
complex place, while if "j" is a real place we have "r_{j,1}+2r_{j,2} =
n".
rnf"[3]" is a two-component row vector "["d"(L/K),s]" where d"(L/K)" is
the relative ideal discriminant of "L/K" and "s" is the discriminant of
"L/K" viewed as an element of "K^*/(K^*)^2", in other words it is the
output of "rnfdisc".
rnf"[4]" is the ideal index f, i.e. such that "d(pol)"Z"_K =
"f"^2"d"(L/K)".
rnf"[5]" is a vector vm with 7 entries useful for certain computations
in the relative extension "L/K". vm"[1]" is a vector of "r_1+r_2"
matrices, the "j"-th matrix being an "(r_{1,j}+r_{2,j}) x n" matrix
"M_j" representing the numerical values of the conjugates of the "j"-th
embedding of the elements of the integral basis, where "r_{i,j}" is as
in rnf"[2]". vm"[2]" is a vector of "r_1+r_2" matrices, the "j"-th
matrix "MC_j" being essentially the conjugate of the matrix "M_j"
except that the last "r_{2,j}" columns are also multiplied by 2.
vm"[3]" is a vector of "r_1+r_2" matrices "T2_j", where "T2_j" is an "n
x n" matrix equal to the real part of the product "MC_j.M_j" (which is
a real positive definite matrix). vm"[4]" is the "n x n" matrix "T"
whose entries are the relative traces of omega"_i"omega"_j" expressed
as polmods in nf, where the omega"_i" are the elements of the relative
integral basis. Note that the "j"-th embedding of "T" is equal to
"\overline{MC_j}.M_j", and in particular will be equal to "T2_j" if
"r_{2,j} = 0". Note also that the relative ideal discriminant of "L/K"
is equal to det "(T)" times the square of the product of the ideals in
the relative pseudo-basis (in rnf"[7][2]"). The last 3 entries vm"[5]",
vm"[6]" and vm"[7]" are linked to the different as in "nfinit", but
have not yet been implemented.
rnf"[6]" is a row vector with "r_1+r_2" entries, the "j"-th entry being
the row vector with "r_{1,j}+r_{2,j}" entries of the roots of the
"j"-th embedding of the relative polynomial pol.
rnf"[7]" is a two-component row vector, where the first component is
the relative integral pseudo basis expressed as polynomials (in the
variable of "pol") with polmod coefficients in nf, and the second com-
ponent is the ideal list of the pseudobasis in HNF.
rnf"[8]" is the inverse matrix of the integral basis matrix, with coef-
ficients polmods in nf.
rnf"[9]" may be the multiplication table of the integral basis, but is
not implemented at present.
rnf"[10]" is nf.
rnf"[11]" is a vector vabs with 5 entries describing the absolute
extension "L/"Q. vabs"[1]" is an absolute equation. vabs"[2]"
expresses the generator alpha of the number field nf as a polynomial
modulo the absolute equation vabs"[1]". vabs"[3]" is a small integer
"k" such that, if beta is an abstract root of pol and alpha the genera-
tor of nf, the generator whose root is vabs will be beta" + k "alpha.
Note that one must be very careful if "k ! = 0" when dealing simultane-
ously with absolute and relative quantities since the generator chosen
for the absolute extension is not the same as for the relative one. If
this happens, one can of course go on working, but we strongly advise
to change the relative polynomial so that its root will be beta" + k
"alpha. Typically, the GP instruction would be
"pol = subst(pol, x, x - k*Mod(y,"nf".pol))"
Finally, vabs"[4]" is the absolute integral basis of "L" expressed in
HNF (hence as would be output by "nfinit(vabs[1])"), and vabs"[5]" the
inverse matrix of the integral basis, allowing to go from polmod to
integral basis representation.
The library syntax is rnfinitalg"("nf","pol","prec")".
rnfisfree"("bnf",x)"
given a big number field bnf as output by "bnfinit", and either a poly-
nomial "x" with coefficients in bnf defining a relative extension "L"
of bnf, or a pseudo-basis "x" of such an extension, returns true (1) if
"L/"bnf is free, false (0) if not.
The library syntax is rnfisfree"("bnf",x)", and the result is a "long".
rnfisnorm"("bnf","ext","el",{"flag" = 1})"
similar to "bnfisnorm" but in the relative case. This tries to decide
whether the element el in bnf is the norm of some "y" in ext. bnf is
as output by "bnfinit".
ext is a relative extension which has to be a row vector whose compo-
nents are:
ext"[1]": a relative equation of the number field ext over bnf. As
usual, the priority of the variable of the polynomial defining the
ground field bnf (say "y") must be lower than the main variable of
ext"[1]", say "x".
ext"[2]": the generator "y" of the base field as a polynomial in "x"
(as given by "rnfequation" with flag" = 1").
ext"[3]": is the "bnfinit" of the absolute extension ext"/"Q.
This returns a vector "[a,b]", where el" = "Norm"(a)*b". It looks for a
solution which is an "S"-integer, with "S" a list of places (of bnf)
containing the ramified primes, the generators of the class group of
ext, as well as those primes dividing el. If ext"/"bnf is known to be
Galois, set flag" = 0" (here el is a norm iff "b = 1"). If flag is non
zero add to "S" all the places above the primes which: divide flag if
flag" < 0", or are less than flag if flag" > 0". The answer is guaran-
teed (i.e. el is a norm iff "b = 1") under GRH, if "S" contains all
primes less than 12 log "^2|disc("Ext")|", where Ext is the normal clo-
sure of ext" / "bnf. Example:
bnf = bnfinit(y^3 + y^2 - 2*y - 1);
p = x^2 + Mod(y^2 + 2*y + 1, bnf.pol);
rnf = rnfequation(bnf,p,1);
ext = [p, rnf[2], bnfinit(rnf[1])];
rnfisnorm(bnf,ext,17, 1)
checks whether 17 is a norm in the Galois extension Q"("beta") /
"Q"("alpha")", where alpha"^3 + "alpha"^2 - 2"alpha" - 1 = 0" and
beta"^2 + "alpha"^2 + 2*"alpha" + 1 = 0" (it is).
The library syntax is rnfisnorm"("bnf",ext,x,"flag","prec")".
rnfkummer"("bnr","subgroup",{deg = 0})"
bnr being as output by "bnrinit", finds a relative equation for the
class field corresponding to the module in bnr and the given congruence
subgroup. If deg is positive, outputs the list of all relative equa-
tions of degree deg contained in the ray class field defined by bnr.
(THIS PROGRAM IS STILL IN DEVELOPMENT STAGE)
The library syntax is rnfkummer"("bnr","subgroup","deg","prec")", where
deg is a "long".
rnflllgram"("nf","pol","order")"
given a polynomial pol with coefficients in nf and an order order as
output by "rnfpseudobasis" or similar, gives "[["neworder"],U]", where
neworder is a reduced order and "U" is the unimodular transformation
matrix.
The library syntax is rnflllgram"("nf","pol","order","prec")".
rnfnormgroup"("bnr","pol")"
bnr being a big ray class field as output by "bnrinit" and pol a rela-
tive polynomial defining an Abelian extension, computes the norm group
(alias Artin or Takagi group) corresponding to the Abelian extension of
bnf" = bnr[1]" defined by pol, where the module corresponding to bnr is
assumed to be a multiple of the conductor (i.e. polrel defines a subex-
tension of bnr). The result is the HNF defining the norm group on the
given generators of bnr"[5][3]". Note that neither the fact that pol
defines an Abelian extension nor the fact that the module is a multiple
of the conductor is checked. The result is undefined if the assumption
is not correct.
The library syntax is rnfnormgroup"("bnr","pol")".
rnfpolred"("nf","pol")"
relative version of "polred". Given a monic polynomial pol with coef-
ficients in nf, finds a list of relative polynomials defining some sub-
fields, hopefully simpler and containing the original field. In the
present version 2.2.0, this is slower than "rnfpolredabs".
The library syntax is rnfpolred"("nf","pol","prec")".
rnfpolredabs"("nf","pol",{"flag" = 0})"
relative version of "polredabs". Given a monic polynomial pol with
coefficients in nf, finds a simpler relative polynomial defining the
same field. If flag" = 1", returns "[P,a]" where "P" is the default
output and "a" is an element expressed on a root of "P" whose charac-
teristic polynomial is pol, if flag" = 2", returns an absolute polyno-
mial (same as
"rnfequation("nf",rnfpolredabs("nf","pol"))"
but faster).
Remark. In the present implementation, this is both faster and much
more efficient than "rnfpolred", the difference being more dramatic
than in the absolute case. This is because the implementation of "rnf-
polred" is based on (a partial implementation of) an incomplete reduc-
tion theory of lattices over number fields (i.e. the function "rnflll-
gram") which deserves to be improved.
The library syntax is rnfpolredabs"("nf","pol","flag","prec")".
rnfpseudobasis"("nf","pol")"
given a number field nf as output by "nfinit" and a polynomial pol with
coefficients in nf defining a relative extension "L" of nf, computes a
pseudo-basis "(A,I)" and the relative discriminant of "L". This is
output as a four-element row vector "[A,I,D,d]", where "D" is the rela-
tive ideal discriminant and "d" is the relative discriminant considered
as an element of nf"^*/{"nf"^*}^2".
Note: As usual, nf can be a bnf as output by "bnfinit".
The library syntax is rnfpseudobasis"("nf","pol")".
rnfsteinitz"("nf",x)"
given a number field nf as output by "nfinit" and either a polynomial
"x" with coefficients in nf defining a relative extension "L" of nf, or
a pseudo-basis "x" of such an extension as output for example by "rnf-
pseudobasis", computes another pseudo-basis "(A,I)" (not in HNF in gen-
eral) such that all the ideals of "I" except perhaps the last one are
equal to the ring of integers of nf, and outputs the four-component row
vector "[A,I,D,d]" as in "rnfpseudobasis". The name of this function
comes from the fact that the ideal class of the last ideal of "I"
(which is well defined) is called the Steinitz class of the module
Z"_L".
Note: nf can be a bnf as output by "bnfinit".
The library syntax is rnfsteinitz"("nf",x)".
subgrouplist"("bnr",{"bound"},{"flag" = 0})"
bnr being as output by "bnrinit" or a list of cyclic components of a
finite Abelian group "G", outputs the list of subgroups of "G" (of
index bounded by bound, if not omitted). Subgroups are given as HNF
left divisors of the SNF matrix corresponding to "G". If flag" = 0"
(default) and bnr is as output by "bnrinit", gives only the subgroups
whose modulus is the conductor.
The library syntax is subgrouplist0"("bnr","bound","flag","prec")",
where bound, flag and prec are long integers.
zetak"("znf",x,{"flag" = 0})"
znf being a number field initialized by "zetakinit" (not by "nfinit"),
computes the value of the Dedekind zeta function of the number field at
the complex number "x". If flag" = 1" computes Dedekind Lambda function
instead (i.e. the product of the Dedekind zeta function by its gamma
and exponential factors).
The accuracy of the result depends in an essential way on the accuracy
of both the "zetakinit" program and the current accuracy, but even so
the result may be off by up to 5 or 10 decimal digits.
The library syntax is glambdak"("znf",x,"prec")" or gze-
tak"("znf",x,"prec")".
zetakinit"(x)"
computes a number of initialization data concerning the number field
defined by the polynomial "x" so as to be able to compute the Dedekind
zeta and lambda functions (respectively zetak(x) and "zetak(x,1)").
This function calls in particular the "bnfinit" program. The result is
a 9-component vector "v" whose components are very technical and cannot
really be used by the user except through the "zetak" function. The
only component which can be used if it has not been computed already is
"v[1][4]" which is the result of the "bnfinit" call.
This function is very inefficient and should be rewritten. It needs to
computes millions of coefficients of the corresponding Dirichlet series
if the precision is big. Unless the discriminant is small it will not
be able to handle more than 9 digits of relative precision
(e.g "zetakinit(x^8 - 2)" needs 440MB of memory at default precision).
The library syntax is initzeta"(x)".
Polynomials and power series
We group here all functions which are specific to polynomials or power
series. Many other functions which can be applied on these objects are
described in the other sections. Also, some of the functions described
here can be applied to other types.
O"(a""^""b)"
"p"-adic (if "a" is an integer greater or equal to 2) or power series
zero (in all other cases), with precision given by "b".
The library syntax is ggrandocp"(a,b)", where "b" is a "long".
deriv"(x,{v})"
derivative of "x" with respect to the main variable if "v" is omitted,
and with respect to "v" otherwise. "x" can be any type except polmod.
The derivative of a scalar type is zero, and the derivative of a vector
or matrix is done componentwise. One can use "x'" as a shortcut if the
derivative is with respect to the main variable of "x".
The library syntax is deriv"(x,v)", where "v" is a "long", and an omit-
ted "v" is coded as "-1".
eval"(x)"
replaces in "x" the formal variables by the values that have been
assigned to them after the creation of "x". This is mainly useful in
GP, and not in library mode. Do not confuse this with substitution (see
"subst"). Applying this function to a character string yields the out-
put from the corresponding GP command, as if directly input from the
keyboard (see "Label se:strings").
The library syntax is geval"(x)". The more basic functions pole-
val"(q,x)", qfeval"(q,x)", and hqfeval"(q,x)" evaluate "q" at "x",
where "q" is respectively assumed to be a polynomial, a quadratic form
(a symmetric matrix), or an Hermitian form (an Hermitian complex
matrix).
factorpadic"("pol",p,r,{"flag" = 0})"
"p"-adic factorization of the polynomial pol to precision "r", the
result being a two-column matrix as in "factor". The factors are nor-
malized so that their leading coefficient is a power of "p". "r" must
be strictly larger than the "p"-adic valuation of the discriminant of
pol for the result to make any sense. The method used is a modified
version of the round 4 algorithm of Zassenhaus.
If flag" = 1", use an algorithm due to Buchmann and Lenstra, which is
usually less efficient.
The library syntax is factorpadic4"("pol",p,r)", where "r" is a "long"
integer.
intformal"(x,{v})"
formal integration of "x" with respect to the main variable if "v" is
omitted, with respect to the variable "v" otherwise. Since PARI does
not know about ``abstract'' logarithms (they are immediately evaluated,
if only to a power series), logarithmic terms in the result will yield
an error. "x" can be of any type. When "x" is a rational function, it
is assumed that the base ring is an integral domain of characteristic
zero.
The library syntax is integ"(x,v)", where "v" is a "long" and an omit-
ted "v" is coded as "-1".
padicappr"("pol",a)"
vector of "p"-adic roots of the polynomial "pol" congruent to the
"p"-adic number "a" modulo "p" (or modulo 4 if "p = 2"), and with the
same "p"-adic precision as "a". The number "a" can be an ordinary
"p"-adic number (type "t_PADIC", i.e. an element of Q"_p") or can be an
element of a finite extension of Q"_p", in which case it is of type
"t_POLMOD", where at least one of the coefficients of the polmod is a
"p"-adic number. In this case, the result is the vector of roots
belonging to the same extension of Q"_p" as "a".
The library syntax is apprgen9"("pol",a)", but if "a" is known to be
simply a "p"-adic number (type "t_PADIC"), the syntax
apprgen"("pol",a)" can be used.
polcoeff"(x,s,{v})"
coefficient of degree "s" of the polynomial "x", with respect to the
main variable if "v" is omitted, with respect to "v" otherwise.
The library syntax is polcoeff0"(x,s,v)", where "v" is a "long" and an
omitted "v" is coded as "-1". Also available is truecoeff"(x,v)".
poldegree"(x,{v})"
degree of the polynomial "x" in the main variable if "v" is omitted, in
the variable "v" otherwise. This is to be understood as follows. When
"x" is a polynomial or a rational function, it gives the degree of "x",
the degree of 0 being "-1" by convention. When "x" is a non-zero
scalar, it gives 0, and when "x" is a zero scalar, it gives "-1".
Return an error otherwise.
The library syntax is poldegree"(x,v)", where "v" and the result are
"long"s (and an omitted "v" is coded as "-1"). Also available is
degree"(x)", which is equivalent to "poldegree(x,-1)".
polcyclo"(n,{v = x})"
"n"-th cyclotomic polynomial, in variable "v" ("x" by default). The
integer "n" must be positive.
The library syntax is cyclo"(n,v)", where "n" and "v" are "long" inte-
gers ("v" is a variable number, usually obtained through "varn").
poldisc"("pol",{v})"
discriminant of the polynomial pol in the main variable is "v" is omit-
ted, in "v" otherwise. The algorithm used is the subresultant algo-
rithm.
The library syntax is poldisc0"(x,v)". Also available is discsr"(x)",
equivalent to "poldisc0(x,-1)".
poldiscreduced"(f)"
reduced discriminant vector of the (integral, monic) polynomial "f".
This is the vector of elementary divisors of
Z"["alpha"]/f'("alpha")"Z"["alpha"]", where alpha is a root of the
polynomial "f". The components of the result are all positive, and
their product is equal to the absolute value of the discriminant
of "f".
The library syntax is reduceddiscsmith"(x)".
polhensellift"(x, y, p, e)"
given a vector "y" of polynomials that are pairwise relatively prime
modulo the prime "p", and whose product is congruent to "x" modulo "p",
lift the elements of "y" to polynomials whose product is congruent to
"x" modulo "p^e".
The library syntax is polhensellift"(x,y,p,e)" where "e" must be a
"long".
polinterpolate"(xa,{ya},{v = x},{&e})"
given the data vectors "xa" and "ya" of the same length "n" ("xa" con-
taining the "x"-coordinates, and "ya" the corresponding "y"-coordi-
nates), this function finds the interpolating polynomial passing
through these points and evaluates it at "v". If "ya" is omitted,
return the polynomial interpolating the "(i,xa[i])". If present, "e"
will contain an error estimate on the returned value.
The library syntax is polint"(xa,ya,v,&e)", where "e" will contain an
error estimate on the returned value.
polisirreducible"("pol")"
pol being a polynomial (univariate in the present version 2.2.0),
returns 1 if pol is non-constant and irreducible, 0 otherwise. Irre-
ducibility is checked over the smallest base field over which pol seems
to be defined.
The library syntax is gisirreducible"("pol")".
pollead"(x,{v})"
leading coefficient of the polynomial or power series "x". This is com-
puted with respect to the main variable of "x" if "v" is omitted, with
respect to the variable "v" otherwise.
The library syntax is pollead"(x,v)", where "v" is a "long" and an
omitted "v" is coded as "-1". Also available is leadingcoeff"(x)".
pollegendre"(n,{v = x})"
creates the "n^{th}" Legendre polynomial, in variable "v".
The library syntax is legendre"(n)", where "x" is a "long".
polrecip"("pol")"
reciprocal polynomial of pol, i.e. the coefficients are in reverse
order. pol must be a polynomial.
The library syntax is polrecip"(x)".
polresultant"(x,y,{v},{"flag" = 0})"
resultant of the two polynomials "x" and "y" with exact entries, with
respect to the main variables of "x" and "y" if "v" is omitted, with
respect to the variable "v" otherwise. The algorithm used is the subre-
sultant algorithm by default.
If flag" = 1", uses the determinant of Sylvester's matrix instead (here
"x" and "y" may have non-exact coefficients).
If flag" = 2", uses Ducos's modified subresultant algorithm. It should
be much faster than the default if the coefficient ring is complicated
(e.g multivariate polynomials or huge coefficients), and slightly
slower otherwise.
The library syntax is polresultant0"(x,y,v,"flag")", where "v" is a
"long" and an omitted "v" is coded as "-1". Also available are sub-
res"(x,y)" (flag" = 0") and resultant2"(x,y)" (flag" = 1").
polroots"("pol",{"flag" = 0})"
complex roots of the polynomial pol, given as a column vector where
each root is repeated according to its multiplicity. The precision is
given as for transcendental functions: under GP it is kept in the vari-
able "realprecision" and is transparent to the user, but it must be
explicitly given as a second argument in library mode.
The algorithm used is a modification of A. Schoenhage's remarkable
root-finding algorithm, due to and implemented by X. Gourdon. Barring
bugs, it is guaranteed to converge and to give the roots to the
required accuracy.
If flag" = 1", use a variant of the Newton-Raphson method, which is not
guaranteed to converge, but is rather fast. If you get the messages
``too many iterations in roots'' or ``INTERNAL ERROR: incorrect result
in roots'', use the default function (i.e. no flag or flag" = 0"). This
used to be the default root-finding function in PARI until version
1.39.06.
The library syntax is roots"("pol","prec")" or root-
sold"("pol","prec")".
polrootsmod"("pol",p,{"flag" = 0})"
row vector of roots modulo "p" of the polynomial pol. The particular
non-prime value "p = 4" is accepted, mainly for 2-adic computations.
Multiple roots are not repeated.
If "p < 100", you may try setting flag" = 1", which uses a naive
search. In this case, multiple roots are repeated with their order of
multiplicity.
The library syntax is rootmod"("pol",p)" (flag" = 0") or root-
mod2"("pol",p)" (flag" = 1").
polrootspadic"("pol",p,r)"
row vector of "p"-adic roots of the polynomial pol with "p"-adic preci-
sion equal to "r". Multiple roots are not repeated. "p" is assumed to
be a prime.
The library syntax is rootpadic"("pol",p,r)", where "r" is a "long".
polsturm"("pol",{a},{b})"
number of real roots of the real polynomial pol in the interval
"]a,b]", using Sturm's algorithm. "a" (resp. "b") is taken to be "- oo
" (resp. "+ oo ") if omitted.
The library syntax is sturmpart"("pol",a,b)". Use "NULL" to omit an
argument. sturm"("pol")" is equivalent to sturm-
part"("pol",NULL,NULL)". The result is a "long".
polsubcyclo"(n,d,{v = x})"
gives a polynomial (in variable "v") defining the sub-Abelian extension
of degree "d" of the cyclotomic field Q"("zeta"_n)", where "d |
"phi"(n)". "("Z"/n"Z")^*" has to be cyclic (i.e. "n = 2", 4, "p^k" or
"2p^k" for an odd prime "p"). The function "galoissubcyclo" covers the
general case.
The library syntax is subcyclo"(n,d,v)", where "v" is a variable num-
ber.
polsylvestermatrix"(x,y)"
forms the Sylvester matrix corresponding to the two polynomials "x" and
"y", where the coefficients of the polynomials are put in the columns
of the matrix (which is the natural direction for solving equations
afterwards). The use of this matrix can be essential when dealing with
polynomials with inexact entries, since polynomial Euclidean division
doesn't make much sense in this case.
The library syntax is sylvestermatrix"(x,y)".
polsym"(x,n)"
creates the vector of the symmetric powers of the roots of the polyno-
mial "x" up to power "n", using Newton's formula.
The library syntax is polsym"(x)".
poltchebi"(n,{v = x})"
creates the "n^{th}" Chebyshev polynomial, in variable "v".
The library syntax is tchebi"(n,v)", where "n" and "v" are "long" inte-
gers ("v" is a variable number).
polzagier"(n,m)"
creates Zagier's polynomial "P_{n,m}" used in the functions "sumalt"
and "sumpos" (with flag" = 1"). The exact definition can be found in a
forthcoming paper. One must have "m <= n".
The library syntax is polzagreel"(n,m,"prec")" if the result is only
wanted as a polynomial with real coefficients to the precision prec, or
polzag"(n,m)" if the result is wanted exactly, where "n" and "m" are
"long"s.
serconvol"(x,y)"
convolution (or Hadamard product) of the two power series "x" and "y";
in other words if "x = "sum" a_k*X^k" and "y = "sum" b_k*X^k" then
"serconvol(x,y) = "sum" a_k*b_k*X^k".
The library syntax is convol"(x,y)".
serlaplace"(x)"
"x" must be a power series with only non-negative exponents. If "x =
"sum" (a_k/k!)*X^k" then the result is sum" a_k*X^k".
The library syntax is laplace"(x)".
serreverse"(x)"
reverse power series (i.e. "x^{-1}", not "1/x") of "x". "x" must be a
power series whose valuation is exactly equal to one.
The library syntax is recip"(x)".
subst"(x,y,z)"
replace the simple variable "y" by the argument "z" in the ``polyno-
mial'' expression "x". Every type is allowed for "x", but if it is not
a genuine polynomial (or power series, or rational function), the sub-
stitution will be done as if the scalar components were polynomials of
degree one. In particular, beware that:
? subst(1, x, [1,2; 3,4])
%1 =
[1 0]
[0 1]
? subst(1, x, Mat([0,1]))
*** forbidden substitution by a non square matrix
If "x" is a power series, "z" must be either a polynomial, a power
series, or a rational function. "y" must be a simple variable name.
The library syntax is gsubst"(x,v,z)", where "v" is the number of the
variable "y".
taylor"(x,y)"
Taylor expansion around 0 of "x" with respect to the simple variable
"y". "x" can be of any reasonable type, for example a rational func-
tion. The number of terms of the expansion is transparent to the user
under GP, but must be given as a second argument in library mode.
The library syntax is tayl"(x,y,n)", where the "long" integer "n" is
the desired number of terms in the expansion.
thue"("tnf",a,{"sol"})"
solves the equation "P(x,y) = a" in integers "x" and "y", where tnf was
created with thueinit(P). sol, if present, contains the solutions of
"Norm(x) = a" modulo units of positive norm in the number field defined
by "P" (as computed by "bnfisintnorm"). If tnf was computed without
assuming GRH (flag" = 1" in "thueinit"), the result is unconditional.
For instance, here's how to solve the Thue equation "x^{13} - 5y^{13} =
- 4":
? tnf = thueinit(x^13 - 5);
? thue(tnf, -4)
%1 = [[1, 1]]
Hence, assuming GRH, the only solution is "x = 1", "y = 1".
The library syntax is thue"("tnf",a,"sol")", where an omitted sol is
coded as "NULL".
thueinit"(P,{"flag" = 0})"
initializes the tnf corresponding to "P". It is meant to be used in
conjunction with "thue" to solve Thue equations "P(x,y) = a", where "a"
is an integer. If flag is non-zero, certify the result unconditionnaly,
Otherwise, assume GRH, this being much faster of course.
The library syntax is thueinit"(P,"flag","prec")".
Vectors, matrices, linear algebra and sets
Note that most linear algebra functions operating on subspaces defined
by generating sets (such as "mathnf", "qflll", etc.) take matrices as
arguments. As usual, the generating vectors are taken to be the columns
of the given matrix.
algdep"(x,k,{"flag" = 0})"
"x" being real, complex, or "p"-adic, finds a polynomial of degree at
most "k" with integer coefficients having "x" as approximate root. Note
that the polynomial which is obtained is not necessarily the ``cor-
rect'' one (it's not even guaranteed to be irreducible!). One can check
the closeness either by a polynomial evaluation or substitution, or by
computing the roots of the polynomial given by algdep.
If "x" is padic, flag is meaningless and the algorithm LLL-reduces the
``dual lattice'' corresponding to the powers of "x".
Otherwise, if flag is zero, the algorithm used is a variant of the LLL
algorithm due to Hastad, Lagarias and Schnorr (STACS 1986). If the pre-
cision is too low, the routine may enter an infinite loop.
If flag is non-zero, use a standard LLL. flag then indicates a preci-
sion, which should be between 0.5 and 1.0 times the number of decimal
digits to which "x" was computed.
The library syntax is algdep0"(x,k,"flag","prec")", where "k" and flag
are "long"s. Also available is algdep"(x,k,"prec")" (flag" = 0").
charpoly"(A,{v = x},{"flag" = 0})"
characteristic polynomial of "A" with respect to the variable "v",
i.e. determinant of "v*I-A" if "A" is a square matrix, determinant of
the map ``multiplication by "A"'' if "A" is a scalar, in particular a
polmod (e.g. "charpoly(I,x) = x^2+1"). Note that in the latter case,
the minimal polynomial can be obtained as
minpoly(A)=
{
local(y);
y = charpoly(A);
y / gcd(y,y')
}
The value of flag is only significant for matrices.
If flag" = 0", the method used is essentially the same as for computing
the adjoint matrix, i.e. computing the traces of the powers of "A".
If flag" = 1", uses Lagrange interpolation which is almost always
slower.
If flag" = 2", uses the Hessenberg form. This is faster than the
default when the coefficients are integermod a prime or real numbers,
but is usually slower in other base rings.
The library syntax is charpoly0"(A,v,"flag")", where "v" is the vari-
able number. Also available are the functions caract"(A,v)" (flag" =
1"), carhess"(A,v)" (flag" = 2"), and caradj"(A,v,"pt")" where, in this
last case, pt is a "GEN*" which, if not equal to "NULL", will receive
the address of the adjoint matrix of "A" (see "matadjoint"), so both
can be obtained at once.
concat"(x,{y})"
concatenation of "x" and "y". If "x" or "y" is not a vector or matrix,
it is considered as a one-dimensional vector. All types are allowed for
"x" and "y", but the sizes must be compatible. Note that matrices are
concatenated horizontally, i.e. the number of rows stays the same.
Using transpositions, it is easy to concatenate them vertically.
To concatenate vectors sideways (i.e. to obtain a two-row or two-column
matrix), first transform the vector into a one-row or one-column matrix
using the function "Mat". Concatenating a row vector to a matrix having
the same number of columns will add the row to the matrix (top row if
the vector is "x", i.e. comes first, and bottom row otherwise).
The empty matrix "[;]" is considered to have a number of rows compati-
ble with any operation, in particular concatenation. (Note that this is
definitely not the case for empty vectors "[ ]" or "[ ]~".)
If "y" is omitted, "x" has to be a row vector or a list, in which case
its elements are concatenated, from left to right, using the above
rules.
? concat([1,2], [3,4])
%1 = [1, 2, 3, 4]
? a = [[1,2]~, [3,4]~]; concat(a)
%2 = [1, 2, 3, 4]~
? a[1] = Mat(a[1]); concat(a)
%3 =
[1 3]
[2 4]
? concat([1,2; 3,4], [5,6]~)
%4 =
[1 2 5]
[3 4 6]
? concat([%, [7,8]~, [1,2,3,4]])
%5 =
[1 2 5 7]
[3 4 6 8]
[1 2 3 4]
The library syntax is concat"(x,y)".
lindep"(x,{"flag" = 0})"
"x" being a vector with real or complex coefficients, finds a small
integral linear combination among these coefficients.
If flag" = 0", uses a variant of the LLL algorithm due to Hastad,
Lagarias and Schnorr (STACS 1986).
If flag" > 0", uses the LLL algorithm. flag is a parameter which should
be between one half the number of decimal digits of precision and that
number (see "algdep").
If flag" < 0", returns as soon as one relation has been found.
The library syntax is lindep0"(x,"flag","prec")". Also available is
lindep"(x,"prec")" (flag" = 0").
listcreate"(n)"
creates an empty list of maximal length "n".
This function is useless in library mode.
listinsert"("list",x,n)"
inserts the object "x" at position "n" in list (which must be of type
"t_LIST"). All the remaining elements of list (from position "n+1"
onwards) are shifted to the right. This and "listput" are the only com-
mands which enable you to increase a list's effective length (as long
as it remains under the maximal length specified at the time of the
"listcreate").
This function is useless in library mode.
listkill"("list")"
kill list. This deletes all elements from list and sets its effective
length to 0. The maximal length is not affected.
This function is useless in library mode.
listput"("list",x,{n})"
sets the "n"-th element of the list list (which must be of type
"t_LIST") equal to "x". If "n" is omitted, or greater than the list
current effective length, just appends "x". This and "listinsert" are
the only commands which enable you to increase a list's effective
length (as long as it remains under the maximal length specified at the
time of the "listcreate").
If you want to put an element into an occupied cell, i.e. if you don't
want to change the effective length, you can consider the list as a
vector and use the usual "list[n] = x" construct.
This function is useless in library mode.
listsort"("list",{"flag" = 0})"
sorts list (which must be of type "t_LIST") in place. If flag is
non-zero, suppresses all repeated coefficients. This is much faster
than the "vecsort" command since no copy has to be made.
This function is useless in library mode.
matadjoint"(x)"
adjoint matrix of "x", i.e. the matrix "y" of cofactors of "x", satis-
fying "x*y = " det "(x)*Id". "x" must be a (non-necessarily invertible)
square matrix.
The library syntax is adj"(x)".
matcompanion"(x)"
the left companion matrix to the polynomial "x".
The library syntax is assmat"(x)".
matdet"(x,{"flag" = 0})"
determinant of "x". "x" must be a square matrix.
If flag" = 0", uses Gauss-Bareiss.
If flag" = 1", uses classical Gaussian elimination, which is better
when the entries of the matrix are reals or integers for example, but
usually much worse for more complicated entries like multivariate poly-
nomials.
The library syntax is det"(x)" (flag" = 0") and det2"(x)" (flag" = 1").
matdetint"(x)"
"x" being an "m x n" matrix with integer coefficients, this function
computes a multiple of the determinant of the lattice generated by the
columns of "x" if it is of rank "m", and returns zero otherwise. This
function can be useful in conjunction with the function "mathnfmod"
which needs to know such a multiple. Other ways to obtain this determi-
nant (assuming the rank is maximal) is "matdet(qflll(x,4)[2]*x)" or
more simply "matdet(mathnf(x))". Experiment to see which is faster for
your applications.
The library syntax is detint"(x)".
matdiagonal"(x)"
"x" being a vector, creates the diagonal matrix whose diagonal entries
are those of "x".
The library syntax is diagonal"(x)".
mateigen"(x)"
gives the eigenvectors of "x" as columns of a matrix.
The library syntax is eigen"(x)".
mathess"(x)"
Hessenberg form of the square matrix "x".
The library syntax is hess"(x)".
mathilbert"(x)"
"x" being a "long", creates the Hilbert matrix of order "x", i.e. the
matrix whose coefficient ("i","j") is "1/ (i+j-1)".
The library syntax is mathilbert"(x)".
mathnf"(x,{"flag" = 0})"
if "x" is a (not necessarily square) matrix of maximal rank, finds the
upper triangular Hermite normal form of "x". If the rank of "x" is
equal to its number of rows, the result is a square matrix. In general,
the columns of the result form a basis of the lattice spanned by the
columns of "x".
If flag" = 0", uses the naive algorithm. If the Z-module generated by
the columns is a lattice, it is recommanded to use "mathnfmod(x, mat-
detint(x))" instead (much faster).
If flag" = 1", uses Batut's algorithm. Outputs a two-component row vec-
tor "[H,U]", where "H" is the upper triangular Hermite normal form of
"x" (i.e. the default result) and "U" is the unimodular transformation
matrix such that "xU = [0|H]". If the rank of "x" is equal to its num-
ber of rows, "H" is a square matrix. In general, the columns of "H"
form a basis of the lattice spanned by the columns of "x".
If flag" = 2", uses Havas's algorithm. Outputs "[H,U,P]", such that "H"
and "U" are as before and "P" is a permutation of the rows such that
"P" applied to "xU" gives "H". This does not work very well in present
version 2.2.0.
If flag" = 3", uses Batut's algorithm, and outputs "[H,U,P]" as in the
previous case.
If flag" = 4", as in case 1 above, but uses LLL reduction along the
way.
The library syntax is mathnf0"(x,"flag")". Also available are hnf"(x)"
(flag" = 0") and hnfall"(x)" (flag" = 1"). To reduce huge (say "400 x
400" and more) relation matrices (sparse with small entries), you can
use the pair "hnfspec" / "hnfadd". Since this is rather technical and
the calling interface may change, they are not documented yet. Look at
the code in "basemath/alglin1.c".
mathnfmod"(x,d)"
if "x" is a (not necessarily square) matrix of maximal rank with inte-
ger entries, and "d" is a multiple of the (non-zero) determinant of the
lattice spanned by the columns of "x", finds the upper triangular Her-
mite normal form of "x".
If the rank of "x" is equal to its number of rows, the result is a
square matrix. In general, the columns of the result form a basis of
the lattice spanned by the columns of "x". This is much faster than
"mathnf" when "d" is known.
The library syntax is hnfmod"(x,d)".
mathnfmodid"(x,d)"
outputs the (upper triangular) Hermite normal form of "x" concatenated
with "d" times the identity matrix.
The library syntax is hnfmodid"(x,d)".
matid"(n)"
creates the "n x n" identity matrix.
The library syntax is idmat"(n)" where "n" is a "long".
Related functions are gscalmat"(x,n)", which creates "x" times the
identity matrix ("x" being a "GEN" and "n" a "long"), and gscals-
mat"(x,n)" which is the same when "x" is a "long".
matimage"(x,{"flag" = 0})"
gives a basis for the image of the matrix "x" as columns of a matrix. A
priori the matrix can have entries of any type. If flag" = 0", use
standard Gauss pivot. If flag" = 1", use "matsupplement".
The library syntax is matimage0"(x,"flag")". Also available is
image"(x)" (flag" = 0").
matimagecompl"(x)"
gives the vector of the column indices which are not extracted by the
function "matimage". Hence the number of components of matimagecompl(x)
plus the number of columns of matimage(x) is equal to the number of
columns of the matrix "x".
The library syntax is imagecompl"(x)".
matindexrank"(x)"
"x" being a matrix of rank "r", gives two vectors "y" and "z" of length
"r" giving a list of rows and columns respectively (starting from 1)
such that the extracted matrix obtained from these two vectors using
"vecextract(x,y,z)" is invertible.
The library syntax is indexrank"(x)".
matintersect"(x,y)"
"x" and "y" being two matrices with the same number of rows each of
whose columns are independent, finds a basis of the Q-vector space
equal to the intersection of the spaces spanned by the columns of "x"
and "y" respectively. See also the function "idealintersect", which
does the same for free Z-modules.
The library syntax is intersect"(x,y)".
matinverseimage"(x,y)"
gives a column vector belonging to the inverse image of the column vec-
tor "y" by the matrix "x" if one exists, the empty vector otherwise. To
get the complete inverse image, it suffices to add to the result any
element of the kernel of "x" obtained for example by "matker".
The library syntax is inverseimage"(x,y)".
matisdiagonal"(x)"
returns true (1) if "x" is a diagonal matrix, false (0) if not.
The library syntax is isdiagonal"(x)", and this returns a "long" inte-
ger.
matker"(x,{"flag" = 0})"
gives a basis for the kernel of the matrix "x" as columns of a matrix.
A priori the matrix can have entries of any type.
If "x" is known to have integral entries, set flag" = 1".
Note: The library function "ker_mod_p(x, p)", where "x" has integer
entries and "p" is prime, which is equivalent to but many orders of
magnitude faster than "matker(x*Mod(1,p))" and needs much less stack
space. To use it under GP, type "install(ker_mod_p, GG)" first.
The library syntax is matker0"(x,"flag")". Also available are ker"(x)"
(flag" = 0"), keri"(x)" (flag" = 1") and "ker_mod_p(x,p)".
matkerint"(x,{"flag" = 0})"
gives an LLL-reduced Z-basis for the lattice equal to the kernel of the
matrix "x" as columns of the matrix "x" with integer entries (rational
entries are not permitted).
If flag" = 0", uses a modified integer LLL algorithm.
If flag" = 1", uses "matrixqz(x,-2)". If LLL reduction of the final
result is not desired, you can save time using "matrixqz(matker(x),-2)"
instead.
If flag" = 2", uses another modified LLL. In the present version 2.2.0,
only independent rows are allowed in this case.
The library syntax is matkerint0"(x,"flag")". Also available is
kerint"(x)" (flag" = 0").
matmuldiagonal"(x,d)"
product of the matrix "x" by the diagonal matrix whose diagonal entries
are those of the vector "d". Equivalent to, but much faster than
"x*matdiagonal(d)".
The library syntax is matmuldiagonal"(x,d)".
matmultodiagonal"(x,y)"
product of the matrices "x" and "y" knowing that the result is a diago-
nal matrix. Much faster than "x*y" in that case.
The library syntax is matmultodiagonal"(x,y)".
matpascal"(x,{q})"
creates as a matrix the lower triangular Pascal triangle of order "x+1"
(i.e. with binomial coefficients up to "x"). If "q" is given, compute
the "q"-Pascal triangle (i.e. using "q"-binomial coefficients).
The library syntax is matqpascal"(x,q)", where "x" is a "long" and "q =
NULL" is used to omit "q". Also available is matpascal{x}.
matrank"(x)"
rank of the matrix "x".
The library syntax is rank"(x)", and the result is a "long".
matrix"(m,n,{X},{Y},{"expr" = 0})"
creation of the "m x n" matrix whose coefficients are given by the
expression expr. There are two formal parameters in expr, the first one
("X") corresponding to the rows, the second ("Y") to the columns, and
"X" goes from 1 to "m", "Y" goes from 1 to "n". If one of the last 3
parameters is omitted, fill the matrix with zeroes.
The library syntax is matrice"(GEN nlig,GEN ncol,entree *e1,entree
*e2,char *expr)".
matrixqz"(x,p)"
"x" being an "m x n" matrix with "m >= n" with rational or integer
entries, this function has varying behaviour depending on the sign of
"p":
If "p >= 0", "x" is assumed to be of maximal rank. This function
returns a matrix having only integral entries, having the same image as
"x", such that the GCD of all its "n x n" subdeterminants is equal to 1
when "p" is equal to 0, or not divisible by "p" otherwise. Here "p"
must be a prime number (when it is non-zero). However, if the function
is used when "p" has no small prime factors, it will either work or
give the message ``impossible inverse modulo'' and a non-trivial divi-
sor of "p".
If "p = -1", this function returns a matrix whose columns form a basis
of the lattice equal to Z"^n" intersected with the lattice generated by
the columns of "x".
If "p = -2", returns a matrix whose columns form a basis of the lattice
equal to Z"^n" intersected with the Q-vector space generated by the
columns of "x".
The library syntax is matrixqz0"(x,p)".
matsize"(x)"
"x" being a vector or matrix, returns a row vector with two components,
the first being the number of rows (1 for a row vector), the second the
number of columns (1 for a column vector).
The library syntax is matsize"(x)".
matsnf"(X,{"flag" = 0})"
if "X" is a (singular or non-singular) square matrix outputs the vector
of elementary divisors of "X" (i.e. the diagonal of the Smith normal
form of "X").
The binary digits of flag mean:
1 (complete output): if set, outputs "[U,V,D]", where "U" and "V" are
two unimodular matrices such that "UXV" is the diagonal matrix "D".
Otherwise output only the diagonal of "D".
2 (generic input): if set, allows polynomial entries. Otherwise, assume
that "X" has integer coefficients.
4 (cleanup): if set, cleans up the output. This means that elementary
divisors equal to 1 will be deleted, i.e. outputs a shortened vector
"D'" instead of "D". If complete output was required, returns
"[U',V',D']" so that "U'XV' = D'" holds. If this flag is set, "X" is
allowed to be of the form "D" or "[U,V,D]" as would normally be output
with the cleanup flag unset.
The library syntax is matsnf0"(X,"flag")". Also available is smith"(X)"
(flag" = 0").
matsolve"(x,y)"
"x" being an invertible matrix and "y" a column vector, finds the solu-
tion "u" of "x*u = y", using Gaussian elimination. This has the same
effect as, but is a bit faster, than "x^{-1}*y".
The library syntax is gauss"(x,y)".
matsolvemod"(m,d,y,{"flag" = 0})"
"m" being any integral matrix, "d" a vector of positive integer moduli,
and "y" an integral column vector, gives a small integer solution to
the system of congruences sum"_i m_{i,j}x_j = y_i (mod d_i)" if one
exists, otherwise returns zero. Shorthand notation: "y" (resp. "d") can
be given as a single integer, in which case all the "y_i" (resp. "d_i")
above are taken to be equal to "y" (resp. "d").
If flag" = 1", all solutions are returned in the form of a two-compo-
nent row vector "[x,u]", where "x" is a small integer solution to the
system of congruences and "u" is a matrix whose columns give a basis of
the homogeneous system (so that all solutions can be obtained by adding
"x" to any linear combination of columns of "u"). If no solution
exists, returns zero.
The library syntax is matsolvemod0"(m,d,y,"flag")". Also available are
gaussmodulo"(m,d,y)" (flag" = 0") and gaussmodulo2"(m,d,y)" (flag" =
1").
matsupplement"(x)"
assuming that the columns of the matrix "x" are linearly independent
(if they are not, an error message is issued), finds a square invert-
ible matrix whose first columns are the columns of "x", i.e. supplement
the columns of "x" to a basis of the whole space.
The library syntax is suppl"(x)".
mattranspose"(x)" or "x~"
transpose of "x". This has an effect only on vectors and matrices.
The library syntax is gtrans"(x)".
qfgaussred"(q)"
decomposition into squares of the quadratic form represented by the
symmetric matrix "q". The result is a matrix whose diagonal entries are
the coefficients of the squares, and the non-diagonal entries represent
the bilinear forms. More precisely, if "(a_{ij})" denotes the output,
one has
" q(x) = "sum"_i a_{ii} (x_i + "sum"_{j > i} a_{ij} x_j)^2 "
The library syntax is sqred"(x)".
qfjacobi"(x)"
"x" being a real symmetric matrix, this gives a vector having two com-
ponents: the first one is the vector of eigenvalues of "x", the second
is the corresponding orthogonal matrix of eigenvectors of "x". The
method used is Jacobi's method for symmetric matrices.
The library syntax is jacobi"(x)".
qflll"(x,{"flag" = 0})"
LLL algorithm applied to the columns of the (not necessarily square)
matrix "x". The columns of "x" must however be linearly independent,
unless specified otherwise below. The result is a transformation matrix
"T" such that "x.T" is an LLL-reduced basis of the lattice generated by
the column vectors of "x".
If flag" = 0" (default), the computations are done with real numbers
(i.e. not with rational numbers) hence are fast but as presently pro-
grammed (version 2.2.0) are numerically unstable.
If flag" = 1", it is assumed that the corresponding Gram matrix is
integral. The computation is done entirely with integers and the algo-
rithm is both accurate and quite fast. In this case, "x" needs not be
of maximal rank, but if it is not, "T" will not be square.
If flag" = 2", similar to case 1, except "x" should be an integer
matrix whose columns are linearly independent. The lattice generated by
the columns of "x" is first partially reduced before applying the LLL
algorithm. [A basis is said to be partially reduced if "|v_i +- v_j| >=
|v_i|" for any two distinct basis vectors "v_i, v_j".]
This can be significantly faster than flag" = 1" when one row is huge
compared to the other rows.
If flag" = 3", all computations are done in rational numbers. This does
not incur numerical instability, but is extremely slow. This function
is essentially superseded by case 1, so will soon disappear.
If flag" = 4", "x" is assumed to have integral entries, but needs not
be of maximal rank. The result is a two-component vector of matrices :
the columns of the first matrix represent a basis of the integer kernel
of "x" (not necessarily LLL-reduced) and the second matrix is the
transformation matrix "T" such that "x.T" is an LLL-reduced Z-basis of
the image of the matrix "x".
If flag" = 5", case as case 4, but "x" may have polynomial coeffi-
cients.
If flag" = 7", uses an older version of case 0 above.
If flag" = 8", same as case 0, where "x" may have polynomial coeffi-
cients.
If flag" = 9", variation on case 1, using content.
The library syntax is qflll0"(x,"flag","prec")". Also available are
lll"(x,"prec")" (flag" = 0"), lllint"(x)" (flag" = 1"), and lllk-
erim"(x)" (flag" = 4").
qflllgram"(x,{"flag" = 0})"
same as "qflll" except that the matrix "x" which must now be a square
symmetric real matrix is the Gram matrix of the lattice vectors, and
not the coordinates of the vectors themselves. The result is again the
transformation matrix "T" which gives (as columns) the coefficients
with respect to the initial basis vectors. The flags have more or less
the same meaning, but some are missing. In brief:
flag" = 0": numerically unstable in the present version 2.2.0.
flag" = 1": "x" has integer entries, the computations are all done in
integers.
flag" = 4": "x" has integer entries, gives the kernel and reduced
image.
flag" = 5": same as 4 for generic "x".
flag" = 7": an older version of case 0.
The library syntax is qflllgram0"(x,"flag","prec")". Also available are
lllgram"(x,"prec")" (flag" = 0"), lllgramint"(x)" (flag" = 1"), and
lllgramkerim"(x)" (flag" = 4").
qfminim"(x,b,m,{"flag" = 0})"
"x" being a square and symmetric matrix representing a positive defi-
nite quadratic form, this function deals with the minimal vectors of
"x", depending on flag.
If flag" = 0" (default), seeks vectors of square norm less than or
equal to "b" (for the norm defined by "x"), and at most "2m" of these
vectors. The result is a three-component vector, the first component
being the number of vectors, the second being the maximum norm found,
and the last vector is a matrix whose columns are the vectors found,
only one being given for each pair "+- v" (at most "m" such pairs).
If flag" = 1", ignores "m" and returns the first vector whose norm is
less than "b".
In both these cases, "x" is assumed to have integral entries, and the
function searches for the minimal non-zero vectors whenever "b = 0".
If flag" = 2", "x" can have non integral real entries, but "b = 0" is
now meaningless (uses Fincke-Pohst algorithm).
The library syntax is qfminim0"(x,b,m,"flag","prec")", also available
are minim"(x,b,m)" (flag" = 0"), minim2"(x,b,m)" (flag" = 1"), and
finally
fincke_pohst"(x,b,m,"prec")" (flag" = 2").
qfperfection"(x)"
"x" being a square and symmetric matrix with integer entries represent-
ing a positive definite quadratic form, outputs the perfection rank of
the form. That is, gives the rank of the family of the "s" symmetric
matrices "v_iv_i^t", where "s" is half the number of minimal vectors
and the "v_i" ("1 <= i <= s") are the minimal vectors.
As a side note to old-timers, this used to fail bluntly when "x" had
more than 5000 minimal vectors. Beware that the computations can now be
very lengthy when "x" has many minimal vectors.
The library syntax is perf"(x)".
qfsign"(x)"
signature of the quadratic form represented by the symmetric matrix
"x". The result is a two-component vector.
The library syntax is signat"(x)".
setintersect"(x,y)"
intersection of the two sets "x" and "y".
The library syntax is setintersect"(x,y)".
setisset"(x)"
returns true (1) if "x" is a set, false (0) if not. In PARI, a set is
simply a row vector whose entries are strictly increasing. To convert
any vector (and other objects) into a set, use the function "Set".
The library syntax is setisset"(x)", and this returns a "long".
setminus"(x,y)"
difference of the two sets "x" and "y", i.e. set of elements of "x"
which do not belong to "y".
The library syntax is setminus"(x,y)".
setsearch"(x,y,{"flag" = 0})"
searches if "y" belongs to the set "x". If it does and flag is zero or
omitted, returns the index "j" such that "x[j] = y", otherwise returns
0. If flag is non-zero returns the index "j" where "y" should be
inserted, and 0 if it already belongs to "x" (this is meant to be used
in conjunction with "listinsert").
This function works also if "x" is a sorted list (see "listsort").
The library syntax is setsearch"(x,y,"flag")" which returns a "long"
integer.
setunion"(x,y)"
union of the two sets "x" and "y".
The library syntax is setunion"(x,y)".
trace"(x)"
this applies to quite general "x". If "x" is not a matrix, it is equal
to the sum of "x" and its conjugate, except for polmods where it is the
trace as an algebraic number.
For "x" a square matrix, it is the ordinary trace. If "x" is a non-
square matrix (but not a vector), an error occurs.
The library syntax is gtrace"(x)".
vecextract"(x,y,{z})"
extraction of components of the vector or matrix "x" according to "y".
In case "x" is a matrix, its components are as usual the columns of
"x". The parameter "y" is a component specifier, which is either an
integer, a string describing a range, or a vector.
If "y" is an integer, it is considered as a mask: the binary bits of
"y" are read from right to left, but correspond to taking the compo-
nents from left to right. For example, if "y = 13 = (1101)_2" then the
components 1,3 and 4 are extracted.
If "y" is a vector, which must have integer entries, these entries cor-
respond to the component numbers to be extracted, in the order speci-
fied.
If "y" is a string, it can be
* a single (non-zero) index giving a component number (a negative index
means we start counting from the end).
* a range of the form "a..b", where "a" and "b" are indexes as above.
Any of "a" and "b" can be omitted; in this case, we take as default
values "a = 1" and "b = -1", i.e. the first and last components respec-
tively. We then extract all components in the interval "[a,b]", in
reverse order if "b < a".
In addition, if the first character in the string is "^", the comple-
ment of the given set of indices is taken.
If "z" is not omitted, "x" must be a matrix. "y" is then the line spec-
ifier, and "z" the column specifier, where the component specifier is
as explained above.
? v = [a, b, c, d, e];
? vecextract(v, 5) \\ mask
%1 = [a, c]
? vecextract(v, [4, 2, 1]) \\ component list
%2 = [d, b, a]
? vecextract(v, "2..4") \\ interval
%3 = [b, c, d]
? vecextract(v, "-1..-3") \\ interval + reverse order
%4 = [e, d, c]
? vecextract([1,2,3], "^2") \\ complement
%5 = [1, 3]
? vecextract(matid(3), "2..", "..")
%6 =
[0 1 0]
[0 0 1]
The library syntax is extract"(x,y)" or matextract"(x,y,z)".
vecsort"(x,{k},{"flag" = 0})"
sorts the vector "x" in ascending order, using the heapsort method. "x"
must be a vector, and its components integers, reals, or fractions.
If "k" is present and is an integer, sorts according to the value of
the "k"-th subcomponents of the components of "x". "k" can also be a
vector, in which case the sorting is done lexicographically according
to the components listed in the vector "k". For example, if "k =
[2,1,3]", sorting will be done with respect to the second component,
and when these are equal, with respect to the first, and when these are
equal, with respect to the third.
The binary digits of flag mean:
* 1: indirect sorting of the vector "x", i.e. if "x" is an "n"-compo-
nent vector, returns a permutation of "[1,2,...,n]" which applied to
the components of "x" sorts "x" in increasing order. For example,
"vecextract(x, vecsort(x,,1))" is equivalent to vecsort(x).
* 2: sorts "x" by ascending lexicographic order (as per the "lex" com-
parison function).
* 4: use decreasing instead of ascending order.
The library syntax is vecsort0"(x,k,flag)". To omit "k", use "NULL"
instead. You can also use the simpler functions
sort"(x)" ( = "vecsort0(x,NULL,0)").
indexsort"(x)" ( = "vecsort0(x,NULL,1)").
lexsort"(x)" ( = "vecsort0(x,NULL,2)").
Also available are sindexsort and sindexlexsort which return a vector
of C-long integers (private type "t_VECSMALL") "v", where "v[1]...v[n]"
contain the indices. Note that the resulting "v" is not a generic PARI
object, but is in general easier to use in C programs!
vector"(n,{X},{"expr" = 0})"
creates a row vector (type "t_VEC") with "n" components whose compo-
nents are the expression expr evaluated at the integer points between 1
and "n". If one of the last two arguments is omitted, fill the vector
with zeroes.
The library syntax is vecteur"(GEN nmax, entree *ep, char *expr)".
vectorv"(n,X,"expr")"
as vector, but returns a column vector (type "t_COL").
The library syntax is vvecteur"(GEN nmax, entree *ep, char *expr)".
Sums, products, integrals and similar functions
Although the GP calculator is programmable, it is useful to have pre-
programmed a number of loops, including sums, products, and a certain
number of recursions. Also, a number of functions from numerical analy-
sis like numerical integration and summation of series will be
described here.
One of the parameters in these loops must be the control variable,
hence a simple variable name. The last parameter can be any legal PARI
expression, including of course expressions using loops. Since it is
much easier to program directly the loops in library mode, these func-
tions are mainly useful for GP programming. The use of these functions
in library mode is a little tricky and its explanation will be mostly
omitted, although the reader can try and figure it out by himself by
checking the example given for the "sum" function. In this section we
only give the library syntax, with no semantic explanation.
The letter "X" will always denote any simple variable name, and repre-
sents the formal parameter used in the function.
(numerical) integration: A number of Romberg-like integration methods
are implemented (see "intnum" as opposed to "intformal" which we
already described). The user should not require too much accuracy: 18
or 28 decimal digits is OK, but not much more. In addition, analytical
cleanup of the integral must have been done: there must be no singular-
ities in the interval or at the boundaries. In practice this can be
accomplished with a simple change of variable. Furthermore, for
improper integrals, where one or both of the limits of integration are
plus or minus infinity, the function must decrease sufficiently rapidly
at infinity. This can often be accomplished through integration by
parts. Finally, the function to be integrated should not be very small
(compared to the current precision) on the entire interval. This can of
course be accomplished by just multiplying by an appropriate constant.
Note that infinity can be represented with essentially no loss of accu-
racy by 1e4000. However beware of real underflow when dealing with
rapidly decreasing functions. For example, if one wants to compute the
int"_0^ oo e^{-x^2}dx" to 28 decimal digits, then one should set infin-
ity equal to 10 for example, and certainly not to 1e4000.
The integrand may have values belonging to a vector space over the real
numbers; in particular, it can be complex-valued or vector-valued.
See also the discrete summation methods below (sharing the prefix
"sum").
intnum"(X = a,b,"expr",{"flag" = 0})"
numerical integration of expr (smooth in "]a,b["), with respect to "X".
Set flag" = 0" (or omit it altogether) when "a" and "b" are not too
large, the function is smooth, and can be evaluated exactly everywhere
on the interval "[a,b]".
If flag" = 1", uses a general driver routine for doing numerical inte-
gration, making no particular assumption (slow).
flag" = 2" is tailored for being used when "a" or "b" are infinite. One
must have "ab > 0", and in fact if for example "b = + oo ", then it is
preferable to have "a" as large as possible, at least "a >= 1".
If flag" = 3", the function is allowed to be undefined (but continuous)
at "a" or "b", for example the function sin "(x)/x" at "x = 0".
The library syntax is intnum0"(entree*e,GEN a,GEN b,char*expr,long
"flag",long prec)".
prod"(X = a,b,"expr",{x = 1})"
product of expression expr, initialized at "x", the formal parameter
"X" going from "a" to "b". As for "sum", the main purpose of the ini-
tialization parameter "x" is to force the type of the operations being
performed. For example if it is set equal to the integer 1, operations
will start being done exactly. If it is set equal to the real 1., they
will be done using real numbers having the default precision. If it is
set equal to the power series "1+O(X^k)" for a certain "k", they will
be done using power series of precision at most "k". These are the
three most common initializations.
As an extreme example, compare
? prod(i=1, 100, 1 - X^i); \\ this has degree 5050 !!
time = 3,335 ms.
? prod(i=1, 100, 1 - X^i, 1 + O(X^101))
time = 43 ms.
%2 = 1 - X - X^2 + X^5 + X^7 - X^12 - X^15 + X^22 + X^26 - X^35 - X^40 + \
X^51 + X^57 - X^70 - X^77 + X^92 + X^100 + O(X^101)
The library syntax is produit"(entree *ep, GEN a, GEN b, char *expr,
GEN x)".
prodeuler"(X = a,b,"expr")"
product of expression expr, initialized at 1. (i.e. to a real number
equal to 1 to the current "realprecision"), the formal parameter "X"
ranging over the prime numbers between "a" and "b".
The library syntax is prodeuler"(entree *ep, GEN a, GEN b, char *expr,
long prec)".
prodinf"(X = a,"expr",{"flag" = 0})"
infinite product of expression expr, the formal parameter "X" starting
at "a". The evaluation stops when the relative error of the expression
minus 1 is less than the default precision. The expressions must always
evaluate to an element of C.
If flag" = 1", do the product of the ("1+"expr) instead.
The library syntax is prodinf"(entree *ep, GEN a, char *expr, long
prec)" (flag" = 0"), or prodinf1 with the same arguments (flag" = 1").
solve"(X = a,b,"expr")"
find a real root of expression expr between "a" and "b", under the con-
dition expr"(X = a) * "expr"(X = b) <= 0". This routine uses Brent's
method and can fail miserably if expr is not defined in the whole of
"[a,b]" (try "solve(x = 1, 2, tan(x)").
The library syntax is zbrent"(entree *ep, GEN a, GEN b, char *expr,
long prec)".
sum"(X = a,b,"expr",{x = 0})"
sum of expression expr, initialized at "x", the formal parameter going
from "a" to "b". As for "prod", the initialization parameter "x" may be
given to force the type of the operations being performed.
As an extreme example, compare
? sum(i=1, 5000, 1/i); \\ rational number: denominator has 2166 digits.
time = 1,241 ms.
? sum(i=1, 5000, 1/i, 0.)
time = 158 ms.
%2 = 9.094508852984436967261245533
The library syntax is somme"(entree *ep, GEN a, GEN b, char *expr, GEN
x)". This is to be used as follows: "ep" represents the dummy variable
used in the expression "expr"
/* compute a^2 + ... + b^2 */
{
/* define the dummy variable "i" */
entree *ep = is_entry("i");
/* sum for a <= i <= b */
return somme(ep, a, b, "i^2", gzero);
}
sumalt"(X = a,"expr",{"flag" = 0})"
numerical summation of the series expr, which should be an alternating
series, the formal variable "X" starting at "a".
If flag" = 0", use an algorithm of F. Villegas as modified by
D. Zagier. This is much better than Euler-Van Wijngaarden's method
which was used formerly. Beware that the stopping criterion is that
the term gets small enough, hence terms which are equal to 0 will cre-
ate problems and should be removed.
If flag" = 1", use a variant with slightly different polynomials. Some-
times faster.
Divergent alternating series can sometimes be summed by this method, as
well as series which are not exactly alternating (see for example
"Label se:user_defined").
Important hint: a significant speed gain can be obtained by writing the
"(-1)^X" which may occur in the expression as "(1. - X%2*2)".
The library syntax is sumalt"(entree *ep, GEN a, char *expr, long
"flag", long prec)".
sumdiv"(n,X,"expr")"
sum of expression expr over the positive divisors of "n".
Arithmetic functions like sigma use the multiplicativity of the under-
lying expression to speed up the computation. In the present version
2.2.0, there is no way to indicate that expr is multiplicative in "n",
hence specialized functions should be prefered whenever possible.
The library syntax is divsum"(entree *ep, GEN num, char *expr)".
suminf"(X = a,"expr")"
infinite sum of expression expr, the formal parameter "X" starting at
"a". The evaluation stops when the relative error of the expression is
less than the default precision. The expressions must always evaluate
to a complex number.
The library syntax is suminf"(entree *ep, GEN a, char *expr, long
prec)".
sumpos"(X = a,"expr",{"flag" = 0})"
numerical summation of the series expr, which must be a series of terms
having the same sign, the formal variable "X" starting at "a". The
algorithm used is Van Wijngaarden's trick for converting such a series
into an alternating one, and is quite slow. Beware that the stopping
criterion is that the term gets small enough, hence terms which are
equal to 0 will create problems and should be removed.
If flag" = 1", use slightly different polynomials. Sometimes faster.
The library syntax is sumpos"(entree *ep, GEN a, char *expr, long
"flag", long prec)".
Plotting functions
Although plotting is not even a side purpose of PARI, a number of plot-
ting functions are provided. Moreover, a lot of people felt like sug-
gesting ideas or submitting huge patches for this section of the code.
Among these, special thanks go to Klaus-Peter Nischke who suggested the
recursive plotting and the forking/resizing stuff under X11, and Ilya
Zakharevich who undertook a complete rewrite of the graphic code, so
that most of it is now platform-independent and should be relatively
easy to port or expand.
These graphic functions are either
* high-level plotting functions (all the functions starting with
"ploth") in which the user has little to do but explain what type of
plot he wants, and whose syntax is similar to the one used in the pre-
ceding section (with somewhat more complicated flags).
* low-level plotting functions, where every drawing primitive (point,
line, box, etc.) must be specified by the user. These low-level func-
tions (called rectplot functions, sharing the prefix "plot") work as
follows. You have at your disposal 16 virtual windows which are filled
independently, and can then be physically ORed on a single window at
user-defined positions. These windows are numbered from 0 to 15, and
must be initialized before being used by the function "plotinit", which
specifies the height and width of the virtual window (called a rectwin-
dow in the sequel). At all times, a virtual cursor (initialized at
"[0,0]") is associated to the window, and its current value can be
obtained using the function "plotcursor".
A number of primitive graphic objects (called rect objects) can then be
drawn in these windows, using a default color associated to that window
(which can be changed under X11, using the "plotcolor" function, black
otherwise) and only the part of the object which is inside the window
will be drawn, with the exception of polygons and strings which are
drawn entirely (but the virtual cursor can move outside of the window).
The ones sharing the prefix "plotr" draw relatively to the current
position of the virtual cursor, the others use absolute coordinates.
Those having the prefix "plotrecth" put in the rectwindow a large batch
of rect objects corresponding to the output of the related "ploth"
function.
Finally, the actual physical drawing is done using the function "plot-
draw". Note that the windows are preserved so that further drawings
using the same windows at different positions or different windows can
be done without extra work. If you want to erase a window (and free the
corresponding memory), use the function "plotkill". It is not possible
to partially erase a window. Erase it completely, initialize it again
and then fill it with the graphic objects that you want to keep.
In addition to initializing the window, you may want to have a scaled
window to avoid unnecessary conversions. For this, use the function
"plotscale" below. As long as this function is not called, the scaling
is simply the number of pixels, the origin being at the upper left and
the "y"-coordinates going downwards.
Note that in the present version 2.2.0 all these plotting functions
(both low and high level) have been written for the X11-window system
(hence also for GUI's based on X11 such as Openwindows and Motif) only,
though very little code remains which is actually platform-dependent. A
Suntools/Sunview, Macintosh, and an Atari/Gem port were provided for
previous versions. These may be adapted in future releases.
Under X11/Suntools, the physical window (opened by "plotdraw" or any of
the "ploth*" functions) is completely separated from GP (technically, a
"fork" is done, and the non-graphical memory is immediately freed in
the child process), which means you can go on working in the current GP
session, without having to kill the window first. Under X11, this win-
dow can be closed, enlarged or reduced using the standard window man-
ager functions. No zooming procedure is implemented though (yet).
* Finally, note that in the same way that "printtex" allows you to have
a TeX output corresponding to printed results, the functions starting
with "ps" allow you to have "PostScript" output of the plots. This will
not be absolutely identical with the screen output, but will be suffi-
ciently close. Note that you can use PostScript output even if you do
not have the plotting routines enabled. The PostScript output is writ-
ten in a file whose name is derived from the "psfile" default
("./pari.ps" if you did not tamper with it). Each time a new PostScript
output is asked for, the PostScript output is appended to that file.
Hence the user must remove this file, or change the value of "psfile",
first if he does not want unnecessary drawings from preceding sessions
to appear. On the other hand, in this manner as many plots as desired
can be kept in a single file.
None of the graphic functions are available within the PARI library,
you must be under GP to use them. The reason for that is that you
really should not use PARI for heavy-duty graphical work, there are
much better specialized alternatives around. This whole set of routines
was only meant as a convenient, but simple-minded, visual aid. If you
really insist on using these in your program (we warned you), the
source ("plot*.c") should be readable enough for you to achieve some-
thing.
plot"(X = a,b,"expr",{"Ymin"},{"Ymax"})"
crude (ASCII) plot of the function represented by expression expr from
"a" to "b", with Y ranging from Ymin to Ymax. If Ymin (resp. Ymax) is
not given, the minima (resp. the maxima) of the computed values of the
expression is used instead.
plotbox"(w,x2,y2)"
let "(x1,y1)" be the current position of the virtual cursor. Draw in
the rectwindow "w" the outline of the rectangle which is such that the
points "(x1,y1)" and "(x2,y2)" are opposite corners. Only the part of
the rectangle which is in "w" is drawn. The virtual cursor does not
move.
plotclip"(w)"
`clips' the content of rectwindow "w", i.e remove all parts of the
drawing that would not be visible on the screen. Together with "plot-
copy" this function enables you to draw on a scratchpad before commit-
ing the part you're interested in to the final picture.
plotcolor"(w,c)"
set default color to "c" in rectwindow "w". In present version 2.2.0,
this is only implemented for X11 window system, and you only have the
following palette to choose from:
1 = black, 2 = blue, 3 = sienna, 4 = red, 5 = cornsilk, 6 = grey, 7 =
gainsborough.
Note that it should be fairly easy for you to hardwire some more colors
by tweaking the files "rect.h" and "plotX.c". User-defined colormaps
would be nice, and may be available in future versions.
plotcopy"(w1,w2,dx,dy)"
copy the contents of rectwindow "w1" to rectwindow "w2", with offset
"(dx,dy)".
plotcursor"(w)"
give as a 2-component vector the current (scaled) position of the vir-
tual cursor corresponding to the rectwindow "w".
plotdraw"(list)"
physically draw the rectwindows given in "list" which must be a vector
whose number of components is divisible by 3. If "list =
[w1,x1,y1,w2,x2,y2,...]", the windows "w1", "w2", etc. are physically
placed with their upper left corner at physical position "(x1,y1)",
"(x2,y2)",...respectively, and are then drawn together. Overlapping
regions will thus be drawn twice, and the windows are considered trans-
parent. Then display the whole drawing in a special window on your
screen.
plotfile"(s)"
set the output file for plotting output. Special filename "-" redirects
to the same place as PARI output.
ploth"(X = a,b,"expr",{"flag" = 0},{n = 0})"
high precision plot of the function "y = f(x)" represented by the
expression expr, "x" going from "a" to "b". This opens a specific win-
dow (which is killed whenever you click on it), and returns a four-com-
ponent vector giving the coordinates of the bounding box in the form
"["xmin","xmax","ymin","ymax"]".
Important note: Since this may involve a lot of function calls, it is
advised to keep the current precision to a minimum (e.g. 9) before
calling this function.
"n" specifies the number of reference point on the graph (0 means use
the hardwired default values, that is: 1000 for general plot, 1500 for
parametric plot, and 15 for recursive plot).
If no flag is given, expr is either a scalar expression f(X), in which
case the plane curve "y = f(X)" will be drawn, or a vector
"[f_1(X),...,f_k(X)]", and then all the curves "y = f_i(X)" will be
drawn in the same window.
The binary digits of flag mean:
* 1: parametric plot. Here expr must be a vector with an even number of
components. Successive pairs are then understood as the parametric
coordinates of a plane curve. Each of these are then drawn.
For instance:
"ploth(X = 0,2*Pi,[sin(X),cos(X)],1)" will draw a circle.
"ploth(X = 0,2*Pi,[sin(X),cos(X)])" will draw two entwined sinusoidal
curves.
"ploth(X = 0,2*Pi,[X,X,sin(X),cos(X)],1)" will draw a circle and the
line "y = x".
* 2: recursive plot. If this flag is set, only one curve can be drawn
at time, i.e. expr must be either a two-component vector (for a single
parametric curve, and the parametric flag has to be set), or a scalar
function. The idea is to choose pairs of successive reference points,
and if their middle point is not too far away from the segment joining
them, draw this as a local approximation to the curve. Otherwise, add
the middle point to the reference points. This is very fast, and usu-
ally more precise than usual plot. Compare the results of
"ploth(X = -1,1,sin(1/X),2) and ploth(X = -1,1,sin(1/X))"
for instance. But beware that if you are extremely unlucky, or choose
too few reference points, you may draw some nice polygon bearing little
resemblance to the original curve. For instance you should never plot
recursively an odd function in a symmetric interval around 0. Try
ploth(x = -20, 20, sin(x), 2)
to see why. Hence, it's usually a good idea to try and plot the same
curve with slightly different parameters.
The other values toggle various display options:
* 4: do not rescale plot according to the computed extrema. This is
meant to be used when graphing multiple functions on a rectwindow (as a
"plotrecth" call), in conjuction with "plotscale".
* 8: do not print the "x"-axis.
* 16: do not print the "y"-axis.
* 32: do not print frame.
* 64: only plot reference points, do not join them.
* 256: use splines to interpolate the points.
* 512: plot no "x"-ticks.
* 1024: plot no "y"-ticks.
* 2048: plot all ticks with the same length.
plothraw"("listx","listy",{"flag" = 0})"
given listx and listy two vectors of equal length, plots (in high pre-
cision) the points whose "(x,y)"-coordinates are given in listx and
listy. Automatic positioning and scaling is done, but with the same
scaling factor on "x" and "y". If flag is 1, join points, other non-0
flags toggle display options and should be combinations of bits "2^k",
"k
>= 3" as in "ploth".
plothsizes"()"
return data corresponding to the output window in the form of a 6-com-
ponent vector: window width and height, sizes for ticks in horizontal
and vertical directions (this is intended for the "gnuplot" interface
and is currently not significant), width and height of characters.
plotinit"(w,x,y)"
initialize the rectwindow "w" to width "x" and height "y", and position
the virtual cursor at "(0,0)". This destroys any rect objects you may
have already drawn in "w".
The plotting device imposes an upper bound for "x" and "y", for
instance the number of pixels for screen output. These bounds are
available through the "plothsizes" function. The following sequence
initializes in a portable way (i.e independant of the output device) a
window of maximal size, accessed through coordinates in the "[0,1000]
x [0,1000]" range :
s = plothsizes();
plotinit(0, s[1]-1, s[2]-1);
plotscale(0, 0,1000, 0,1000);
plotkill"(w)"
erase rectwindow "w" and free the corresponding memory. Note that if
you want to use the rectwindow "w" again, you have to use "initrect"
first to specify the new size. So it's better in this case to use "ini-
trect" directly as this throws away any previous work in the given
rectwindow.
plotlines"(w,X,Y,{"flag" = 0})"
draw on the rectwindow "w" the polygon such that the (x,y)-coordinates
of the vertices are in the vectors of equal length "X" and "Y". For
simplicity, the whole polygon is drawn, not only the part of the poly-
gon which is inside the rectwindow. If flag is non-zero, close the
polygon. In any case, the virtual cursor does not move.
"X" and "Y" are allowed to be scalars (in this case, both have to).
There, a single segment will be drawn, between the virtual cursor cur-
rent position and the point "(X,Y)". And only the part thereof which
actually lies within the boundary of "w". Then move the virtual cursor
to "(X,Y)", even if it is outside the window. If you want to draw a
line from "(x1,y1)" to "(x2,y2)" where "(x1,y1)" is not necessarily the
position of the virtual cursor, use "plotmove(w,x1,y1)" before using
this function.
plotlinetype"(w,"type")"
change the type of lines subsequently plotted in rectwindow "w". type
"-2" corresponds to frames, "-1" to axes, larger values may correspond
to something else. "w = -1" changes highlevel plotting. This is only
taken into account by the "gnuplot" interface.
plotmove"(w,x,y)"
move the virtual cursor of the rectwindow "w" to position "(x,y)".
plotpoints"(w,X,Y)"
draw on the rectwindow "w" the points whose "(x,y)"-coordinates are in
the vectors of equal length "X" and "Y" and which are inside "w". The
virtual cursor does not move. This is basically the same function as
"plothraw", but either with no scaling factor or with a scale chosen
using the function "plotscale".
As was the case with the "plotlines" function, "X" and "Y" are allowed
to be (simultaneously) scalar. In this case, draw the single point
"(X,Y)" on the rectwindow "w" (if it is actually inside "w"), and in
any case move the virtual cursor to position "(x,y)".
plotpointsize"(w,size)"
changes the ``size'' of following points in rectwindow "w". If "w =
-1", change it in all rectwindows. This only works in the "gnuplot"
interface.
plotpointtype"(w,"type")"
change the type of points subsequently plotted in rectwindow "w". type"
= -1" corresponds to a dot, larger values may correspond to something
else. "w = -1" changes highlevel plotting. This is only taken into
account by the "gnuplot" interface.
plotrbox"(w,dx,dy)"
draw in the rectwindow "w" the outline of the rectangle which is such
that the points "(x1,y1)" and "(x1+dx,y1+dy)" are opposite corners,
where "(x1,y1)" is the current position of the cursor. Only the part
of the rectangle which is in "w" is drawn. The virtual cursor does not
move.
plotrecth"(w,X = a,b,"expr",{"flag" = 0},{n = 0})"
writes to rectwindow "w" the curve output of "ploth""(w,X =
a,b,"expr","flag",n)".
plotrecthraw"(w,"data",{"flag" = 0})"
plot graph(s) for data in rectwindow "w". flag has the same signifi-
cance here as in "ploth", though recursive plot is no more significant.
data is a vector of vectors, each corresponding to a list a coordi-
nates. If parametric plot is set, there must be an even number of vec-
tors, each successive pair corresponding to a curve. Otherwise, the
first one containe the "x" coordinates, and the other ones contain the
"y"-coordinates of curves to plot.
plotrline"(w,dx,dy)"
draw in the rectwindow "w" the part of the segment
"(x1,y1)-(x1+dx,y1+dy)" which is inside "w", where "(x1,y1)" is the
current position of the virtual cursor, and move the virtual cursor to
"(x1+dx,y1+dy)" (even if it is outside the window).
plotrmove"(w,dx,dy)"
move the virtual cursor of the rectwindow "w" to position
"(x1+dx,y1+dy)", where "(x1,y1)" is the initial position of the cursor
(i.e. to position "(dx,dy)" relative to the initial cursor).
plotrpoint"(w,dx,dy)"
draw the point "(x1+dx,y1+dy)" on the rectwindow "w" (if it is inside
"w"), where "(x1,y1)" is the current position of the cursor, and in any
case move the virtual cursor to position "(x1+dx,y1+dy)".
plotscale"(w,x1,x2,y1,y2)"
scale the local coordinates of the rectwindow "w" so that "x" goes from
"x1" to "x2" and "y" goes from "y1" to "y2" ("x2 < x1" and "y2 < y1"
being allowed). Initially, after the initialization of the rectwindow
"w" using the function "plotinit", the default scaling is the graphic
pixel count, and in particular the "y" axis is oriented downwards since
the origin is at the upper left. The function "plotscale" allows to
change all these defaults and should be used whenever functions are
graphed.
plotstring"(w,x,{"flag" = 0})"
draw on the rectwindow "w" the String "x" (see "Label se:strings"), at
the current position of the cursor.
flag is used for justification: bits 1 and 2 regulate horizontal align-
ment: left if 0, right if 2, center if 1. Bits 4 and 8 regulate verti-
cal alignment: bottom if 0, top if 8, v-center if 4. Can insert addi-
tional small gap between point and string: horizontal if bit 16 is set,
vertical if bit 32 is set (see the tutorial for an example).
plotterm"("term")"
sets terminal where high resolution plots go (this is currently only
taken into account by the "gnuplot" graphical driver). Using the "gnu-
plot" driver, possible terminals are the same as in gnuplot. If term is
"?", lists possible values.
Terminal options can be appended to the terminal name and space; termi-
nal size can be put immediately after the name, as in "gif = 300,200".
Positive return value means success.
psdraw"("list")"
same as "plotdraw", except that the output is a PostScript program
appended to the "psfile".
psploth"(X = a,b,"expr")"
same as "ploth", except that the output is a PostScript program
appended to the "psfile".
psplothraw"("listx","listy")"
same as "plothraw", except that the output is a PostScript program
appended to the "psfile".
Programming under GP
=head2 Control statements.
A number of control statements are available under GP. They are simpler
and have a syntax slightly different from their C counterparts, but are
quite powerful enough to write any kind of program. Some of them are
specific to GP, since they are made for number theorists. As usual, "X"
will denote any simple variable name, and seq will always denote a
sequence of expressions, including the empty sequence.
break"({n = 1})"
interrupts execution of current seq, and immediately exits from the "n" inner-
most enclosing loops, within the current function call (or the top level
loop). "n" must be bigger than 1. If "n" is greater than the number ofenclosing loops, all enclosing loops are exited.
for"(X = a,b,"seq")"
the formal variable "X" going from "a" to "b", the seq is evaluated. Nothing
is done if "a > b". "a" and "b" must be in R.
fordiv"(n,X,"seq")"
the formal variable "X" ranging through the positive divisors of "n", the
sequence seq is evaluated. "n" must be of type integer.forprime"(X = a,b,"seq")"
the formal variable "X" ranging over the prime numbers between "a" to "b"
(including "a" and "b" if they are prime), the seq is evaluated. More pre-
cisely, the value of "X" is incremented to the smallest prime strictly larger
than "X" at the end of each iteration. Nothing is done if "a > b". Note that
"a" and "b" must be in R.
? { forprime(p = 2, 12,
print(p);
if (p == 3, p = 6);
)
}
2
3
7
11
forstep"(X = a,b,s,"seq")"
the formal variable "X" going from "a" to "b", in increments of "s", the seq
is evaluated. Nothing is done if "s > 0" and "a > b" or if "s < 0" and "a <
b". "s" must be in R"^*" or a vector of steps "[s_1,...,s_n]". In the latter
case, the successive steps are used in the order they appear in "s".
? forstep(x=5, 20, [2,4], print(x))
5
7
11
13
17
19
forsubgroup"(H = G,{B},"seq")"
executes seq for each subgroup "H" of the abelian group "G" (given in SNF formor as a vector of elementary divisors), whose index is bounded by bound. The
subgroups are not ordered in any obvious way, unless "G" is a "p"-group in
which case Birkhoff's algorithm produces them by decreasing index. A subgroupis given as a matrix whose columns give its generators on the implicit genera-
tors of "G". For example, the following prints all subgroups of index less
than 2 in "G = "Z"/2"Z" g_1 x "Z"/2"Z" g_2" :
? G = [2,2]; forsubgroup(H=G, 2, print(H))
[1; 1]
[1; 2]
[2; 1]
[1, 0; 1, 1]
The last one, for instance is generated by "(g_1, g_1 + g_2)". This routine is
intended to treat huge groups, when subgrouplist is not an option due to the
sheer size of the output.For maximal speed the subgroups have been left as produced by the algorithm.To print them in canonical form (as left divisors of "G" in HNF form), one can
for instance use
? G = matdiagonal([2,2]); forsubgroup(H=G, 2, print(mathnf(concat(G,H))))
[2, 1; 0, 1]
[1, 0; 0, 2]
[2, 0; 0, 1]
[1, 0; 0, 1]
Note that in this last representation, the index "[G:H]" is given by the
determinant.forvec"(X = v,"seq",{"flag" = 0})"
"v" being an "n"-component vector (where "n" is arbitrary) of two-component
vectors "[a_i,b_i]" for "1 <= i <= n", the seq is evaluated with the formal
variable "X[1]" going from "a_1" to "b_1",...,"X[n]" going from "a_n" to
"b_n". The formal variable with the highest index moves the fastest. If flag"
= 1", generate only nondecreasing vectors "X", and if flag" = 2", generate
only strictly increasing vectors "X".if"(a,{"seq1"},{"seq2"})"
if "a" is non-zero, the expression sequence seq1 is evaluated, otherwise the
expression seq2 is evaluated. Of course, seq1 or seq2 may be empty, so "if
(a,"seq")" evaluates seq if "a" is not equal to zero (you don't have to write
the second comma), and does nothing otherwise, whereas "if (a,,"seq")" evalu-
ates seq if "a" is equal to zero, and does nothing otherwise. You could get
the same result using the "!" ("not") operator: "if (!a,"seq")".
Note that the boolean operators "&&" and "||" are evaluated according to oper-
ator precedence as explained in "Label se:operators", but that, contrary to
other operators, the evaluation of the arguments is stopped as soon as the
final truth value has been determined. For instance
if (reallydoit && longcomplicatedfunction(), ...)%
is a perfectly safe statement.Recall that functions such as "break" and "next" operate on loops (such as
"forxxx", "while", "until"). The "if" statement is not a loop (obviously!).
next"({n = 1})"
interrupts execution of current "seq", resume the next iteration of the inner-
most enclosing loop, within the current fonction call (or top level loop). If
"n" is specified, resume at the "n"-th enclosing loop. If "n" is bigger than
the number of enclosing loops, all enclosing loops are exited.
return"({x = 0})"
returns from current subroutine, with result "x".
until"(a,"seq")"
evaluates expression sequence seq until "a" is not equal to 0 (i.e. until "a"is true). If "a" is initially not equal to 0, seq is evaluated once (more gen-
erally, the condition on "a" is tested after execution of the seq, not before
as in "while").while"(a,"seq")"
while "a" is non-zero evaluate the expression sequence seq. The test is made
before evaluating the "seq", hence in particular if "a" is initially equal to
zero the seq will not be evaluated at all.Specific functions used in GP programmingIn addition to the general PARI functions, it is necessary to have some func-
tions which will be of use specifically for GP, though a few of these can be
accessed under library mode. Before we start describing these, we recall the
difference between strings and keywords (see "Label se:strings"): the latterdon't get expanded at all, and you can type them without any enclosing quotes.
The former are dynamic objects, where everything outside quotes gets immedi-
ately expanded.We need an additional notation for this chapter. An argument between braces,
followed by a star, like "{"str"}*", means that any number of such arguments
(possibly none) can be given.
addhelp"(S,"str")"
changes the help message for the symbol "S". The string str is expanded on
the spot and stored as the online help for "S". If "S" is a function you havedefined, its definition will still be printed before the message str. It is
recommended that you document global variables and user functions in this way.Of course GP won't protest if you don't do it.There's nothing to prevent you from modifying the help of built-in PARI func-
tions (but if you do, we'd like to hear why you needed to do it!).
alias"("newkey","key")"
defines the keyword newkey as an alias for keyword key. key must correspond toan existing function name. This is different from the general user macros inthat alias expansion takes place immediately upon execution, without having to
look up any function code, and is thus much faster. A sample alias file
"misc/gpalias" is provided with the standard distribution. Alias commands are
meant to be read upon startup from the ".gprc" file, to cope with function
names you are dissatisfied with, and should be useless in interactive usage.
allocatemem"({x = 0})"
this is a very special operation which allows the user to change the stacksize after initialization. "x" must be a non-negative integer. If "x! = 0", a
new stack of size "16*\lceil x/16\rceil" bytes will be allocated, all the PARI
data on the old stack will be moved to the new one, and the old stack will be
discarded. If "x = 0", the size of the new stack will be twice the size of the
old one.Although it is a function, this must be the last instruction in any GP
sequence. The technical reason is that this routine usually moves the stack,
so objects from the current sequence might not be correct anymore. Hence, to
prevent such problems, this routine terminates by a "longjmp" (just as an
error would) and not by a return.The library syntax is allocatemoremem"(x)", where "x" is an unsigned long, and
the return type is void. GP uses a variant which ends by a "longjmp".default"({"key"},{"val"},{"flag"})"
sets the default corresponding to keyword key to value val. val is a string
(which of course accepts numeric arguments without adverse effects, due to the
expansion mechanism). See "Label se:defaults" for a list of availabledefaults, and "Label se:meta" for some shortcut alternatives. Typing
"default()" (or "\d") yields the complete default list as well as their cur-
rent values.If val is omitted, prints the current value of default key. If flag is set,
returns the result instead of printing it.error"({"str"}*)"
outputs its argument list (each of them interpreted as a string), then inter-
rupts the running GP program, returning to the input prompt.
Example: "error("n = ", n, " is not squarefree !")".
Note that, due to the automatic concatenation of strings, you could in fact
use only one argument, just by suppressing the commas.
extern"("str")"the string str is the name of an external command (i.e. one you would typefrom your UNIX shell prompt). This command is immediately run and its inputfed into GP, just as if read from a file.
getheap"()"returns a two-component row vector giving the number of objects on the heap
and the amount of memory they occupy in long words. Useful mainly for debug-
ging purposes.The library syntax is getheap"()".getrand"()"returns the current value of the random number seed. Useful mainly for debug-
ging purposes.The library syntax is getrand"()", returns a C long.
getstack"()"returns the current value of "top-avma", i.e. the number of bytes used up to
now on the stack. Should be equal to 0 in between commands. Useful mainly fordebugging purposes.The library syntax is getstack"()", returns a C long.
gettime"()"returns the time (in milliseconds) elapsed since either the last call to "get-
time", or to the beginning of the containing GP instruction (if inside GP),
whichever came last.The library syntax is gettime"()", returns a C long.
global"({"list of variables"})"
declares the corresponding variables to be global. From now on, you will be
forbidden to use them as formal parameters for function definitions or as loopindexes. This is especially useful when patching together various scripts,
possibly written with different naming conventions. For instance the followingsituation is dangerous:
p = 3 \\ fix characteristic
...
forprime(p = 2, N, ...)
f(p) = ...
since within the loop or within the function's body (even worse: in the sub-
routines called in that scope), the true global value of "p" will be hidden.
If the statement "global(p = 3)" appears at the beginning of the script, then
both expressions will trigger syntax errors.Calling "global" without arguments prints the list of global variables in use.In particular, "eval(global)" will output the values of all local variables.
input"()"reads a string, interpreted as a GP expression, from the input file, usually
standard input (i.e. the keyboard). If a sequence of expressions is given, the
result is the result of the last expression of the sequence. When using thisinstruction, it is useful to prompt for the string by using the "print1" func-
tion. Note that in the present version 2.19 of "pari.el", when using GP under
GNU Emacs (see "Label se:emacs") one must prompt for the string, with a string
which ends with the same prompt as any of the previous ones (a "? " will do
for instance).install"("name","code",{"gpname"},{"lib"})"
loads from dynamic library lib the function name. Assigns to it the namegpname in this GP session, with argument code code (see "Label se:gp.inter-
face" for an explanation of those). If lib is omitted, uses "libpari.so". If
gpname is omitted, uses name.
This function is useful for adding custom functions to the GP interpreter, or
picking useful functions from unrelated libraries. For instance, it makes the
function "system" obsolete:
? install(system, vs, sys, "libc.so")
? sys("ls gp*")
gp.c gp.h gp_rl.c
But it also gives you access to all (non static) functions defined in the PARIlibrary. For instance, the function "GEN addii(GEN x, GEN y)" adds two PARI
integers, and is not directly accessible under GP (it's eventually called by
the "+" operator of course):
? install("addii", "GG")
? addii(1, 2)
%1 = 3
Caution: This function may not work on all systems, especially when GP has
been compiled statically. In that case, the first use of an installed function
will provoke a Segmentation Fault, i.e. a major internal blunder (this should
never happen with a dynamically linked executable). Hence, if you intend to
use this function, please check first on some harmless example such as the
ones above that it works properly on your machine.kill"(s)"
kills the present value of the variable, alias or user-defined function "s".
The corresponding identifier can now be used to name any GP object (variableor function). This is the only way to replace a variable by a function havingthe same name (or the other way round), as in the following example:
? f = 1
%1 = 1
? f(x) = 0
*** unused characters: f(x)=0
^----
? kill(f)
? f(x) = 0
? f()
%2 = 0
When you kill a variable, all objects that used it become invalid. You can
still display them, even though the killed variable will be printed in a funny
way (following the same convention as used by the library function
"fetch_var", see "Label se:vars"). For example:
? a^2 + 1
%1 = a^2 + 1
? kill(a)
? %1
%2 = #<1>^2 + 1
If you simply want to restore a variable to its ``undefined'' value (monomial
of degree one), use the quote operator: "a = 'a". Predefined symbols ("x" and
GP function names) cannot be killed.print"({"str"}*)"
outputs its (string) arguments in raw format, ending with a newline.
print1"({"str"}*)"
outputs its (string) arguments in raw format, without ending with a newline
(note that you can still embed newlines within your strings, using the "\n"
notation !).printp"({"str"}*)"
outputs its (string) arguments in prettyprint (beautified) format, ending with
a newline.printp1"({"str"}*)"
outputs its (string) arguments in prettyprint (beautified) format, without
ending with a newline.printtex"({"str"}*)"
outputs its (string) arguments in TeX format. This output can then be used ina TeX manuscript. The printing is done on the standard output. If you want toprint it to a file you should use "writetex" (see there).Another possibility is to enable the "log" default (see "Label se:defaults").You could for instance do:
default(logfile, "new.tex");
default(log, 1);
printtex(result);
(You can use the automatic string expansion/concatenation process to have
dynamic file names if you wish).quit"()"exits GP.read"({"str"})"
reads in the file whose name results from the expansion of the string str. Ifstr is omitted, re-reads the last file that was fed into GP. The return value
is the result of the last expression evaluated.reorder"({x = []})"
"x" must be a vector. If "x" is the empty vector, this gives the vector whose
components are the existing variables in increasing order (i.e. in decreasingimportance). Killed variables (see "kill") will be shown as 0. If "x" isnon-empty, it must be a permutation of variable names, and this permutation
gives a new order of importance of the variables, for output only. For exam-
ple, if the existing order is "[x,y,z]", then after "reorder([z,x])" the order
of importance of the variables, with respect to output, will be "[z,y,x]". The
internal representation is unaffected.setrand"(n)"reseeds the random number generator to the value "n". The initial seed is "n =
1".The library syntax is setrand"(n)", where "n" is a "long". Returns "n".
system"("str")"str is a string representing a system command. This command is executed, its
output written to the standard output (this won't get into your logfile), and
control returns to the PARI system. This simply calls the C "system" command.trap"({e}, {"rec"}, {"seq"})"
tries to execute seq, trapping error "e", that is effectively preventing it
from aborting computations in the usual way; the recovery sequence rec is exe-
cuted if the error occurs and the evaluation of rec becomes the result of thecommand. If "e" is omitted, all exceptions are trapped. Note in particular
that hitting "^C" (Control-C) raises an exception.
? \\ trap division by 0
? inv(x) = trap (gdiver2, INFINITY, 1/x)
? inv(2)
%1 = 1/2
? inv(0)
%2 = INFINITY
If seq is omitted, defines rec as a default action when encountering exception
"e". The error message is printed, as well as the result of the evaluation of
rec, and the control is given back to the GP prompt. In particular, current
computation is then lost.The following error handler prints the list of all user variables, then stores
in a file their name and their values:
? { trap( ,
print(reorder);
write("crash", reorder);
write("crash", eval(reorder))) }
If no recovery code is given (rec is omitted) a so-called break loop will be
started. During a break loop, all commands are read and evaluated as during
the main GP loop (except that no history of results is kept).To get out of the break loop, you can use "next", "break" or "return"; reading
in a file by "\r" will also terminate the loop once the file has been read
("read" will remain in the break loop). If the error is not fatal ("^C" is the
only non-fatal error), "next" will continue the computation as if nothing had
happened (except of course, you may have changed GP state during the break
loop); otherwise control will come back to the GP prompt. After a user inter-
rupt ("^C"), entering an empty input line (i.e hitting the return key) has the
same effect as "next".Break loops are useful as a debugging tool to inspect the values of GP vari-
ables to understand why a problem occurred, or to change GP behaviour
(increase debugging level, start storing results in a logfile, modify parame-
ters...) in the middle of a long computation (hit "^C", type in your modifica-
tions, then type "next").
If rec is the empty string "" the last default handler is popped out, and
replaced by the previous one for that error.Note: The interface is currently not adequate for trapping individual excep-
tions. In the current version 2.2.0, the following keywords are recognized,
but the name list will be expanded and changed in the future (all library modeerrors can be trapped: it's a matter of defining the keywords to GP, and there
are currently far too many useless ones):
"accurer": accuracy problem
"gdiver2": division by 0
"archer": not available on this architecture or operating system
"typeer": wrong type
"errpile": the PARI stack overflows
type"(x,{t})"
this is useful only under GP. If "t" is not present, returns the internal type
number of the PARI object "x". Otherwise, makes a copy of "x" and sets its
type equal to type "t", which can be either a number or, preferably since
internal codes may eventually change, a symbolic name such as "t_FRACN" (you
can skip the "t_" part here, so that "FRACN" by itself would also be all
right). Check out existing type names with the metacommand "\t".
GP won't let you create meaningless objects in this way where the internalstructure doesn't match the type. This function can be useful to create reduc-
ible rationals (type "t_FRACN") or rational functions (type "t_RFRACN"). Infact it's the only way to do so in GP. In this case, the created object, as
well as the objects created from it, will not be reduced automatically, making
some operations a bit faster.There is no equivalent library syntax, since the internal functions "typ" and
"settyp" are available. Note that "settyp" does not create a copy of "x", con-
trary to most PARI functions. It also doesn't check for consistency. "settyp"just changes the type in place and returns nothing. "typ" returns a C longinteger. Note also the different spellings of the internal functions
("set")"typ" and of the GP function "type", which is due to the fact that
"type" is a reserved identifier for some C compilers.
whatnow"("key")"if keyword key is the name of a function that was present in GP version1.39.15 or lower, outputs the new function name and syntax, if it changed at
all (387 out of 560 did).write"("filename",{"str"*})"
writes (appends) to filename the remaining arguments, and appends a newline
(same output as "print").
write1"("filename",{"str"*})"
writes (appends) to filename the remaining arguments without a trailing new-
line (same output as "print1").writetex"("filename",{"str"*})"
as "write", in TeX format.
perl v5.8.8 2007-10-29 libPARI.dumb(3)
