NAME

libPARI - Specific Use of the gp Calculator


DESCRIPTION


Introduction

Originally, gp was designed as a debugging device for the PARI system library, and not much thought had been given to making it user-friendly. The situation has changed, and gp is very useful as a stand-alone tool. The operations and functions available in PARI and gp are described in the next chapter. In the present one, we describe the specific use of the gp programmable calculator.

 If you have GNU Emacs, you can work in a special Emacs shell,
described in L<Label se:emacs>. Specific features of this Emacs shell are
indicated by an EMACS sign in the left margin.

Startup

To start the calculator, the general command line syntax is:

gp [-s stacksize] [-p primelimit] [files]

where items within brackets are optional. The [files] argument is a list of files written in the GP scripting language, which will be loaded on startup. The ones starting with a minus sign are flags, setting some internal parameters of gp, or defaults. See Label se:defaults below for a list and explanation of all defaults, there are many more than just those two. These defaults can be changed by adding parameters to the input line as above, or interactively during a gp session or in a preferences file (also known as gprc).

If a preferences file (or gprc, to be discussed in Label se:gprc) can be found, gp then read its and execute the commands it contains. This provides an easy way to customize gp. The files argument is processed right after the gprc.

A copyright message then appears which includes the version number, and a lot of useful technical information. After the copyright, the computer writes the top-level help information, some initial defaults, and then waits after printing its prompt, which is '? ' by default . Whether extended on-line help and line editing are available or not is indicated in this gp banner, between the version number and the copyright message. Consider investigating the matter with the person who installed gp if they are not. Do this as well if there is no mention of the GMP kernel.

Getting help

To get help, type a ? and hit return. A menu appears, describing the eleven main categories of available functions and how to get more detailed help. If you now type ?n with 1 <= n <= 11, you get the list of commands corresponding to category n and simultaneously to Section 3.n of this manual. If you type ?functionname where functionname is the name of a PARI function, you will get a short explanation of this function.

If extended help (see Label se:exthelp) is available on your system, you can double or triple the ? sign to get much more: respectively the complete description of the function (e.g. ??sqrt), or a list of gp functions relevant to your query (e.g.  ???"elliptic curve" or ???"quadratic field").

If gp was properly installed (see Appendix A), a line editor is available to correct the command line, get automatic completions, and so on. See Label se:readline or ??readline for a short summary of the line editor's commands.

If you type ?\ you will get a short description of the metacommands (keyboard shortcuts).

Finally, typing ?. will return the list of available (pre-defined) member functions. These are functions attached to specific kind of objects, used to retrieve easily some information from complicated structures (you can define your own but they won't be shown here). We will soon describe these commands in more detail.

As a general rule, under gp, commands starting with \b or with some other symbols like ? or #, are not computing commands, but are metacommands which allow you to exchange information with gp. The available metacommands can be divided into default setting commands (explained below) and simple commands (or keyboard shortcuts, to be dealt with in Label se:meta).

Input

Just type in an instruction, e.g. 1 + 1, or Pi. No action is undertaken until you hit the < Return > key. Then computation starts, and a result is eventually printed. To suppress printing of the result, end the expression with a ; sign. Note that many systems use ; to indicate end of input. Not so in gp: this will hide the result from you! (Which is certainly useful if it occupies several screens.)

Interrupt, Quit

Typing quit at the prompt ends the session and exits gp. At any point you can type Ctrl-C (that is press simultaneously the Control and C keys): the current computation is interrupted and control given back to you at the gp prompt, together with a message like

    *** gcd: user interrupt after 840 ms.

telling you how much time ellapsed since the last command was typed in and in which GP function the computation was aborted. It does not mean that that much time was spent in the function, only that the evaluator was busy processing that specific function when you stopped it.


The general gp input line

The gp calculator uses a purely interpreted language GP. The structure of this language is reminiscent of LISP with a functional notation, f(x,y) rather than (f x y): all programming constructs, such as if, while, etc...are functionsFOOTNOTE<<< Not exactly, since not all their arguments need be evaluated. For instance it would be stupid to evaluate both branches of an if statement: since only one will apply, only this one is evaluated. >>>, and the main loop does not really execute, but rather evaluates (sequences of) expressions. Of course, it is by no means a true LISP.

Introduction.

User interaction with a gp session proceeds as follows. First, one types a sequence of characters at the gp prompt; see Label se:readline for a description of the line editor. When you hit the < Return > key, gp gets your input, evaluates it, then prints the result and assigns it to an ``history'' array if it is not void (see next section).

More precisely, you input either a metacommand or a sequence of expressions. Metacommands, described in Label se:meta, are not part of the GP language and are simple shortcuts designed to alter gp's internal state (such as the working precision or general verbosity level), or speed up input/output.

An expression is formed by combining constants, variables, operator symbols, functions (including user-defined functions) and control statements. It always has a value, which can be any PARI object. There is a distinction between lowercase and uppercase. Also, outside of character strings, blanks are completely ignored in the input to gp. An expression is evaluated using the conventions about operator priorities and left to right associativity.

Several expressions are combined on a single line by separating them with semicolons (';'). Such an expression sequence will be called simply a seq. A seq also has a value, which is the value of the last expression in the sequence. Under gp, the value of the seq, and only this last value, becomes an history entry. The values of the other expressions in the seq are discarded after the execution of the seq is complete, except of course if they were assigned into variables. In addition, the value of the seq is printed if the line does not end with a semicolon ;.

The gp history.

This is not to be confused with the history of your commands, maintained by readline. It only contains their non-void results, in sequence. Several inputs only act through side effects and produce a void result, for instance a print statement, a for loop, or a function definition.

The successive elements of the history array are called %1, %2, ...As a shortcut, the latest computed expression can also be called %, the previous one %`, the one before that %`` and so on. The total number of history entries is %#.

When you suppress the printing of the result with a semicolon, its history number will not appear either, so it is often a better idea to assign it to a variable for later use than to mentally recompute what its number is. Of course, on the next line, just use % as usual.

This history ``array'' is in fact better thought of as a queue: its size is limited to 5000 entries by default, after which gp starts forgetting the initial entries. So %1 becomes unavailable as gp prints %5001. You can modify the history size using histsize.

Special editing characters

A GP program can of course have more than one line. Since gp executes your commands as soon as you have finished typing them, there must be a way to tell it to wait for the next line or lines of input before doing anything. There are three ways of doing this.

The first one is simply to use the backslash character \ at the end of the line that you are typing, just before hitting < Return > . This tells gp that what you will write on the next line is the physical continuation of what you have just written. In other words, it makes gp forget your newline character. You can type a \ anywhere. It is interpreted as above only if (apart from ignored whitespace characters) it is immediately followed by a newline. For example, you can type

  ? 3 + \
  4

instead of typing 3 + 4.

The second one is a slight variation on the first, and is mostly useful when defining a user function (see Label se:user_defined): since an equal sign can never end a valid expression, gp disregards a newline immediately following an = .

  ? a =
  123
  %1 = 123

The third one cannot be used everywhere, but is in general much more useful. It is the use of braces { and }. An opening brace ({) at the beginning of a line (modulo spaces as usual) signals that you are typing a multi-line command, and newlines are ignored until you type a closing brace }. There is an important, but easily obeyed, restriction: inside an open brace-close brace pair, all your input lines are concatenated, suppressing any newlines. Thus, all newlines should occur after a semicolon (;), a comma (,) or an operator (for clarity's sake, we don't recommend splitting an identifier over two lines in this way). For instance, the following program

  {
    a = b
    b = c
  }

would silently produce garbage, since this is interpreted as a = bb = c which assigns the value of c to both bb and a.


The PARI types

We see here how to input values of the different data types known to PARI. Recall that blanks are ignored in any expression which is not a string (see below).

A note on efficiency. The following types are provided for convenience, not for speed: t_INTMOD, t_FRAC, t_PADIC, t_QUAD, t_POLMOD, t_RFRAC. Indeed, they always perform a reduction of some kind after each basic operation, even though it is usually more efficient to perform a single reduction at the end of some complex computation. For instance, in a convolution product sum_{i+j = n} x_i y_j in Z/NZ (common when multiplying polynomials!), it is wasteful to perform n reductions modulo N. In short, basic individual operations on these types are fast, but recursive objects with such components could be handled more efficiently: programming with libpari will save large constant factors here, compared to GP.

Integers

(type t_INT): type the integer (with an initial + or -, if desired) with no decimal point.

Real numbers

(type t_REAL): type the number with a decimal point. The internal precision of the real number is the supremum of the input precision and the default precision. For example, if the default precision is 28 digits, typing 2. gives a number with internal precision 28, but typing a 45 significant digit real number gives a number with internal precision at least 45, although less may be printed.

You can also use scientific notation with the letter E or e, in which case the (non leading) decimal point may be omitted (like 6.02 E 23 or 1e-5, but not e10). By definition, 0.E N (or 0 E N) returns a real 0 of (decimal) exponent N, whereas 0. returns a real 0 ``of default precision'' (of exponent -realprecision), see Label se:whatzero.

Intmods

(type t_INTMOD): to enter n mod m, type Mod(n,m), not n%m. Internally, all operations are done on integer representatives belonging to [0,m-1].

Note that this type is available for convenience, not for speed: each elementary operation involves a reduction modulo m.

Rational numbers

(types t_FRAC): all fractions are automatically reduced to lowest terms, so it is impossible to work with reducible fractions. To enter n/m just type it as written. As explained in Label se:gdiv, division is not performed, only reduction to lowest terms.

Note that this type is available for convenience, not for speed: each elementary operation involves computing a gcd.

Complex numbers

(type t_COMPLEX): to enter x+iy, type x + I*y (not x+i*y). The letter I stands for sqrt {-1}. Recall from Chapter 1 that x and y can be of type t_INT, t_REAL, t_INTMOD, t_FRAC, or t_PADIC.

p-adic numbers

(type t_PADIC): to enter a p-adic number, simply write a rational or integer expression and add to it O(p^k), where p and k are integers. This last expression indicates three things to gp: first that it is dealing with a t_PADIC type (the fact that p is an integer, and not a polynomial, which would be used to enter a series, see Label se:series), secondly the prime p, and finally the number of significant p-adic digits k.

Note that it is not checked whether p is indeed prime but results are undefined if this is not the case: you can work on 10-adics if you want, but disasters will happen as soon as you do something non-trivial like taking a square root. Note that O(25) is not the same as O(5^2); you want the latter!

For example, you can type in the 7-adic number

2*7^(-1) + 3 + 4*7 + 2*7^2 + O(7^3)

exactly as shown, or equivalently as 905/7 + O(7^3).

Note that this type is available for convenience, not for speed: internally, t_PADICs are stored as p-adic units modulo some p^k. Each elementary operation involves updating p^k (multiplying or dividing by powers of p) and a reduction mod p^k. In particular additions are slow.

      ? n = 1+O(2^20);   for (i=1,10^5, n++)
      time = 86 ms.
      ? n = Mod(1,2^20); for (i=1,10^5, n++)
      time = 48 ms.
      ? n = 1;           for (i=1,10^5, n++)
      time = 38 ms.

Quadratic numbers

(type t_QUAD): first, you must define the default quadratic order or field in which you want to work. This is done using the quadgen function, in the following way. Write something like

      w = quadgen(d)

where d is the discriminant of the quadratic order in which you want to work (hence d is congruent to 0 or 1 modulo 4). The name w is of course just a suggestion, but corresponds to traditional usage. You can use any variable name that you like. However, quadratic numbers are always printed with a w, regardless of the discriminant. So beware, two numbers can be printed in the same way and not be equal. However gp will refuse to add or multiply them for example.

Now (1,w) is the ``canonical'' integral basis of the quadratic order (i.e. w = sqrt {d}/2 if d = 0 mod 4, and w = (1+ sqrt {d})/2 if d = 1 mod 4, where d is the discriminant), and to enter x+yw you just type x + y*w.

Polmods

(type t_POLMOD): exactly as for intmods, to enter x mod y (where x and y are polynomials), type Mod(x,y), not x%y. Note that when y is an irreducible polynomial in one variable, polmods whose modulus is y are simply algebraic numbers in the finite extension defined by the polynomial y. This allows us to work easily in number fields, finite extensions of the p-adic field Q_p, or finite fields.

Note that this type is available for convenience, not for speed: each elementary operation involves a reduction modulo y.

Important remark. Mathematically, the variables occurring in a polmod are not free variables. But internally, a congruence class in R[t]/(y) is represented by its representative of lowest degree, which is a t_POL in R[t], and computations occur with polynomials in the variable t. PARI will not recognize that Mod(y, y^2 + 1) is ``the same'' as Mod(x, x^2 + 1), since x and y are different variables.

To avoid inconsistencies, polmods must use the same variable in internal operations (i.e. between polmods) and variables of lower priority for external operations, typically between a polynomial and a polmod. See Label se:priority for a definition of ``priority'' and a discussion of (PARI's idea of) multivariate polynomial arithmetic. For instance:

      ? Mod(x, x^2+ 1) + Mod(x, x^2 + 1)
      %1 = Mod(2*x, x^2 + 1)    \\ 2i (or -2i), with i^2 = -1
      ? x + Mod(y, y^2 + 1)
      %2 = x + Mod(y, y^2 + 1)  \\ in B<Q>(i)[x]
      ? y + Mod(x, x^2 + 1)
      %3 = Mod(x + y, x^2 + 1)  \\ in B<Q>(y)[i]

The first two are straightforward, but the last one may not be what you want: y is treated here as a numerical parameter, not as a polynomial variable.

If the main variables are the same, it is allowed to mix t_POL and t_POLMODs. The result is the expected t_POLMOD. For instance

      ? x + Mod(x, x^2 + 1)
      %1 = Mod(2*x, x^2 + 1)

Polynomials

(type t_POL): type the polynomial in a natural way, not forgetting to put a ``*'' between a coefficient and a formal variable (this * does not appear in beautified output). Any variable name can be used except for the reserved names I (used exclusively for the square root of -1), Pi (3.14...), Euler (Euler's constant), and all the function names: predefined functions, as described in Chapter 3 (use \c to get the complete list of them) and user-defined functions, which you ought to know about (use \u if you are subject to memory lapses). The total number of different variable names is limited to 16384 and 65536 on 32-bit and 64-bit machines respectively, which should be enough. If you ever need hundreds of variables, you should probably be using vectors instead. See Label se:priority for a discussion of multivariate polynomial rings.

Power series

(type t_SER): type a rational function or polynomial expression and add to it {O(expr^k)}, where expr is an expression which has non-zero valuation (it can be a polynomial, power series, or a rational function; the most common case being simply a variable name). This indicates to gp that it is dealing with a power series, and the desired precision is k times the valuation of expr with respect to the main variable of expr. (To check the ordering of the variables, or to modify it, use the function reorder; see Label se:reorder.)

Caveat. Power series with inexact coefficients sometimes have a non-intuitive behaviour: if k significant terms are requested, an inexact zero is counted as significant, even if it is the coefficient of lowest degree. This means that useful higher order terms may be disregarded. If the series precision is insufficient, errors may occur (mostly division by 0), which could have been avoided by a better global understanding of the computation:

      ? A = 1/(y + 0.); B = 1. + O(y);
      ? B * denominator(A)
      %2 = 0.E-28 + O(y)
      ? A/B
      ***   division by zero
      ? A*B
      ***   Warning: normalizing a series with 0 leading term.
      ***   division by zero
      ? A*(1/B)
      ***   Warning: normalizing a series with 0 leading term.
      %3 = 1.000000000000000000000000000*y^-1 + O(1)

If a series with a zero leading coefficient must be inverted, then as a desperation measure that coefficient is discarded, and a warning is issued:

      ? C = 0. + y + O(y^2);
      ? 1/C
      ***   Warning: normalizing a series with 0 leading term.
      %2 = y^-1 + O(1)

The last result could be construed as a bug since it is a priori impossible to deduce such a result from the input (0. may represent any sufficiently small real number). But it was thought more useful to try and go on with an approximate computation than to raise an early exception.

In the first example above, to compute A*(1/B), the denominator of A was converted to a power series, then inverted.

Rational functions

(types t_RFRAC): as for fractions, all rational functions are automatically reduced to lowest terms. All that was said about fractions in Label se:FRAC remains valid here.

Binary quadratic forms of positive or negative discriminant

(type t_QFR and t_QFI): these are input using the function Qfb (see Chapter 3). For example Qfb(1,2,3) creates the binary form x^2+2xy+3y^2. It is imaginary (of internal type t_QFI) since 2^2 - 4*3 = -8 is negative.

Although imaginary forms could be positive or negative definite, only positive definite forms are implemented.

In the case of forms with positive discriminant (type t_QFR), you may add an optional fourth component (related to the regulator, more precisely to Shanks and Lenstra's ``distance''), which must be a real number. See also the function qfbprimeform which directly creates a prime form of given discriminant (see Chapter 3).

Row and column vectors

(types t_VEC and t_COL): to enter a row vector, type the components separated by commas ``,'', and enclosed between brackets ``[

  '' and ``

]'', e.g. [1,2,3]. To enter a column vector, type the vector horizontally, and add a tilde ``~'' to transpose. [ ] yields the empty (row) vector. The function Vec can be used to transform any object into a vector (see Chapter 3).

Matrices (type t_MAT)

to enter a matrix, type the components line by line, the components being separated by commas ``,'', the lines by semicolons ``;'', and everything enclosed in brackets ``[

  '' and ``

]'', e.g. [x,y; z,t; u,v]. [ ; ] yields the empty (0x0) matrix. The function Mat can be used to transform any object into a matrix (see Chapter 3).

Note that although the internal representation is essentially the same (only the type number is different), a row vector of column vectors is not a matrix; for example, multiplication will not work in the same way.

Note also that it is possible to create matrices (by conversion of empty column vectors and concatenation, or using the matrix function) with a given positive number of columns, each of which has zero rows. It is not possible to create or represent matrices with zero columns and a nonzero number of rows.

Lists (type t_LIST)

lists cannot be input directly; you have to use the function listcreate first, then listput each time you want to append a new element (but you can access the elements directly as with the vector types described above). The function List can be used to transform (row or column) vectors into lists (see Chapter 3).

Strings (type t_STR)

to enter a string, just enclose it between double quotes ", like this: "this is a string". The function Str can be used to transform any object into a string (see Chapter 3).

Small vectors (type t_VECSMALL)

this is an internal type, used to code in an efficient way vectors containing only small integers, such as permutations. Most gp functions will refuse to operate on these objects.

Note on output formats.

A zero real number is printed in e format as 0.Exx where xx is the (usually negative) decimal exponent of the number (cf. Label se:whatzero). This allows the user to check the accuracy of that particular zero.

When the integer part of a real number x is not known exactly because the exponent of x is greater than the internal precision, the real number is printed in e format.

Note also that in beautified format, a number of type integer or real is written without enclosing parentheses, while most other types have them. Hence, if you see the expression (3.14), it is not of type real, but probably of type complex with zero imaginary part, or polynomial of degree 0 (to be sure, use \x or the function type).


GP operators

Loosely speaking, an operator is a function (usually associated to basic arithmetic operations) whose name contains only non-alphanumeric characters. In practice, most of these are simple functions, which take arguments, and return a value; assignment operators also have side effects. Each of these has some fixed and unchangeable priority, which means that, in a given expression, the operations with the highest priority is performed first. Operations at the same priority level are performed in the order they were written, i.e. from left to right. Anything enclosed between parenthesis is considered a complete subexpression, and is resolved independently of the surrounding context. For instance, assuming that op_1, op_2, op_3 are standard binary operators with increasing priorities (think of +, *, ^ for instance),

   x op_1 y op_2 z op_2 x op_3 y

is equivalent to

   x op_1 ((y op_2 z) op_2 (xS< >op_3 y)).

GP contains quite a lot of different operators, some of them unary (having only one argument), some binary, plus special selection operators. Unary operators are defined for either prefix (preceding their single argument: op x) or postfix (following the argument: x op) position, never both (some are syntactically correct in both positions, but with different meanings). Binary operators all use the syntax x op y. Most of them are well known, some are borrowed from C syntax, and a few are specific to GP. Beware that some GP operators may differ slightly from their C counterparts. For instance, GP's postfix ++ returns the new value, like the prefix ++ of C, and the binary shifts << , >> have a priority which is different from (higher than) that of their C counterparts. When in doubt, just surround everything by parentheses. (Besides, your code will be more legible.)

Here is the complete list in order of decreasing priority, binary unless mentioned otherwise:

10}

++ and -- (unary, postfix): x++ assigns the value x+1 to x, then returns the new value of x. This corresponds to the C statement ++x (there is no prefix ++ operator in GP). x-- does the same with x-1.

* Priority 9

op = , where op is any simple binary operator (i.e. a binary operator with no side effects, i.e. one of those defined below) which is not a boolean operator (comparison or logical). x op = y assigns (x op y) to x, and returns the new value of x. This is not a reference to the variable x, i.e. an lvalue; thus

    (x += 2) = 3

is invalid.

* Priority 8

= is the assignment operator. The result of x = y is the value of the expression y, which is also assigned to the variable x. This is not the equality test operator; a statement like x = 1 is always true (i.e. non-zero), and sets x to 1. The right hand side of the assignment operator is evaluated before the left hand side. If the left hand side cannot be modified, raise an error.

* Priority 7 [ ] is the selection operator. x[i] returns the i-th component of vector x; x[i,j], x[,j] and x[i,] respectively return the entry of coordinates (i,j), the j-th column, and the i-th row of matrix x. If the assignment operator ( = ) immediately follows a sequence of selections, it assigns its right hand side to the selected component. E.g x[1][1] = 0 is valid; but beware that (x[1])[1] = 0 is not (because the parentheses force the complete evaluation of x[1], and the result is not modifiable).

* Priority 6

' (unary, prefix): quote its argument (a variable name) without evaluating it.

  ? a = x + 1; x = 1;
  ? subst(a,x,1)
    ***   variable name expected: subst(a,x,1)
                                          ^---
  ? subst(a,'x,1)
  %1 = 2

^: powering.

' (unary, postfix): derivative with respect to the main variable. If f is a (GP or user) function, f'(x) is allowed. If x is a scalar, the operator performs numerical derivation, defined as (f(x+varepsilon) - f(x-varepsilon)) / 2varepsilon for a suitably small epsilon depending on current precision. It behaves as (f(x))' otherwise.

~ (unary, postfix): vector/matrix transpose.

! (unary, postfix): factorial. x! = x(x-1)...1.

.member (unary, postfix): x.member extracts member from structure x (see Label se:member).

* Priority 5

! (unary, prefix): logical not. !x return 1 if x is equal to 0 (specifically, if gcmp0(x) == 1), and 0 otherwise.

# (unary, prefix): cardinality; #x returns length(x).

* Priority 4

+, - (unary, prefix): - toggles the sign of its argument, + has no effect whatsoever.

* Priority 3

*: multiplication.

/: exact division (3/2 = 3/2, not 1.5).

\, %: Euclidean quotient and remainder, i.e. if x = qy + r, with 0 <= r < y (if x and y are polynomials, assume instead that deg r < deg y and that the leading terms of r and x have the same sign), then x \ y = q, x%y = r.

\/: rounded Euclidean quotient for integers (rounded towards + oo when the exact quotient would be a half-integer).

<< , >> : left and right binary shift: x << n = x * 2^n if n > 0, and x \/ 2^{-n} otherwise. Right shift is defined by x >> n = x << (-n).

* Priority 2

+, -: addition/subtraction.

* Priority 1

< , > , <= , >= : the usual comparison operators, returning 1 for true and 0 for false. For instance, x <= 1 returns 1 if x <= 1 and 0 otherwise.

< > , != : test for (exact) inequality.

== : test for (exact) equality.

* Priority 0

&, &&: logical and.

|, ||: logical (inclusive) or. Any sequence of logical or and and operations is evaluated from left to right, and aborted as soon as the final truth value is known. Thus, for instance,

    x && test(1/x)
    type(p) == "t_INT" && isprime(p)

will never produce an error since the second argument need not (and will not) be processed when the first is already zero (false).

Remark: For optimal efficiency, you should use the ++, -- and op = operators whenever possible:

  ? a = 200000;
  ? i = 0; while(i<a, i=i+1)
  time = 4,919 ms.
  ? i = 0; while(i<a, i+=1)
  time = 4,478 ms.
  ? i = 0; while(i<a, i++)
  time = 3,639 ms.

For the same reason, the shift operators should be preferred to multiplication:

  ? a = 1<<20000;
  ? i = 1; while(i<a, i=i*2);
  time = 5,255 ms.
  ? i = 1; while(i<a, i<<=1);
  time = 988 ms.


Variables and symbolic expressions

=head2 Variable names.

In GP you can use up to 16383 variable names (up to 65535 on 64-bit machines). A valid identifier name starts with a letter and contain only valid keyword characters: _ or alphanumeric characters ([_A-Za-z0-9]). You may not use built-in function names; see the list with \c, including the constants Pi, Euler and I = sqrt {-1}.

Note that GP names are case sensitive. This means for instance that the symbol i is perfectly safe to use, and will not be mistaken for sqrt {-1}, and that o is not synonymous to O.

We will see in Label se:user_defined that it is possible to restrict the use of a given variable by declaring it to be global or local. This can be useful to enforce clean programming style, but is in no way mandatory.

Vectors and matrices.

If the variable x contains a vector or list, x[m] refers to its m-th entry. You can assign a result to x[m] (i.e. write something like x[k] = expr). If x is a matrix, x[m,n] referes to its (m,n) entry; you can assign a result to x[m,n], but not to x[m]. If you want to assign an expression to the m-th column of a matrix x, use x[,m] = expr instead. Similarly, use x[m,] = expr to assign an expression to the m-th row of x. This process is recursive, so if x is a matrix of matrices of..., an expression such as x[1,1][,3][4] = 1 is perfectly valid (and actually identical to x[1,1][4,3] = 1), assuming that all matrices along the way have compatible dimensions.

Variables and polynomials

The main thing to understand is that PARI/GP is not a symbolic manipulation package. One of the main consequences of this fact is that all expressions are evaluated as soon as they are written, they never stay in an abstract form FOOTNOTE<<< An obvious but important exception are character strings which are evaluated essentially to themselves (type t_STR). Not exactly so though, since we do some work to treat the quoted characters correctly (those preceded by a \). >>>.

As an important example, consider what happens when you use a variable name before assigning a value into it, x say. This is perfectly acceptable, it is considered as a monomial of degree 1 in the variable x.

    ? p = x^2 + 1
    %1 = x^2 + 1
    ? x = 2;
    ? x^2 + 1
    %3 = 5
    ? p
    %4 = x^2 + 1
    ? eval(p)
    %5 = 5

As is shown above, assigning a value to a variable, does not affect polynomials that used it; to take into account the new variable's value, one must use the function eval (see Label se:eval). It is in general preferable to use subst, rather than assigning values to polynomial variables.

Variable priorities, multivariate objects

PARI has no ``sparse'' representation of polynomials. So a multivariate polynomial in PARI is just a polynomial (in one variable), whose coefficients are themselves polynomials, arbitrary but for the fact that they do not involve the main variable. All computations are then just done formally on the coefficients as if the polynomial was univariate.

This is not symmetrical. So if I enter x + y in a clean session, what happens ? This is understood as

   x^1 + y*x^0 belongs to (Z[y])[x]

but how do we know that x is ``more important'' than y ? Why not y^1 + x*y^0, which is the same mathematical entity after all ?

The answer is that variables are ordered implicitly by the gp interpreter: when a new identifier (e.g x, or y as above) is input, the corresponding variable is registered as having a strictly lower priority than any variable in use at this pointFOOTNOTE<<< This is not strictly true: if an identifier is interpreted as a user function, no variable is registered. Also, the variable x is predefined and always has the highest possible priority. >>>

. To see the ordering used by gp at any given time, type reorder().

Given such an ordering, multivariate polynomials are stored so that the variable with the highest priority is the main variable. And so on, recursively, until all variables are exhausted. A different storage pattern (which could only be obtained via library mode) would produce an invalid object, and eventually a disaster.

In any case, if you are working with expressions involving several variables and want to have them ordered in a specific manner in the internal representation just described, the simplest is just to write down the variables one after the other under gp before starting any real computations. You could also define variables from your GPRC to have a consistent ordering of common variable names in all your gp sessions, e.g read in a file variables.gp containing

  x;y;z;t;a;b;c;d;

If you already have started working and want to change the names of the variables in an object, use the function changevar. If you only want to have them ordered when the result is printed, you can also use the function reorder, but this won't change anything to the internal representation, and is not recommended.

Important note: PARI allows Euclidean division of multivariate polynomials, but assumes that the computation takes place in the fraction field of the coefficient ring (if it is not an integral domain, the result will a priori not make sense). This can be very tricky; for instance assume x has highest priority (which is always the case), then y:

  ? x % y
  %1 = 0
  ? y % x
  %2 = y             \\ these two take place in B<Q>(y)[x]
  ? x * Mod(1,y)
  %3 = Mod(1, y)*x   \\ in (B<Q>(y)/yB<Q>(y))[x]  ~  B<Q>[x]
  ? Mod(x,y)
  %4 = 0

In the last example, the division by y takes place in Q(y)[x], hence the Mod object is a coset in (Q(y)[x]) / (yQ(y)[x]), which is the null ring since y is invertible! So be very wary of variable ordering when your computations involve implicit divisions and many variables. This also affects functions like numerator/denominator or content:

  ? denominator(x / y)
  %1 = 1
  ? denominator(y / x)
  %2 = x
  ? content(x / y)
  %3 = 1/y
  ? content(y / x)
  %4 = y
  ? content(2 / x)
  %5 = 2

Can you see why ? Hint: x/y = (1/y) * x is in Q(y)[x] and denominator is taken with respect to Q(y)(x); y/x = (y*x^0) / x is in Q(y)(x) so y is invertible in the coefficient ring. On the other hand, 2/x involves a single variable and the coefficient ring is simply Z.

These problems arise because the variable ordering defines an implicit variable with respect to which division takes place. This is the price to pay to allow % and / operators on polynomials instead of requiring a more cumbersome divrem(x, y, var) (which also exists). Unfortunately, in some functions like content and denominator, there is no way to set explicitly a main variable like in divrem and remove the dependence on implicit orderings. This will hopefully be corrected in future versions.

Multivariate power series

Just like multivariate polynomials, power series are fundamentally single-variable objects. It is awkward to handle many variables at once, since PARI's implementation cannot handle multivariate error terms like O(x^i y^j). (It can handle the polynomial O(y^j) x x^i which is a very different thing, see below.)

The basic assumption in our model is that if variable x has higher priority than y, then y does not depend on x: setting y to a function of x after some computations with bivariate power series does not make sense a priori. This is because implicit constants in expressions like O(x^i) depend on y (whereas in O(y^j) they can not depend on x). For instance

    ? O(x) * y
    %1 = O(x)
    ? O(y) * x
    %2 = O(y)*x

Here is a more involved example:

    ? A = 1/x^2 + 1 + O(x); B = 1/x + 1 + O(x^3);
    ? subst(z*A, z, B)
    %2 = x^-3 + x^-2 + x^-1 + 1 + O(x)
    ? B * A
    %3 = x^-3 + x^-2 + x^-1 + O(1)
    ? z * A
    %4 = z*x^-2 + z + O(x)

The discrepancy between %2 and %3 is surprising. Why does %2 contain a spurious constant term, which cannot be deduced from the input ? Well, we ignored the rule that forbids to substitute an expression involving high-priority variables to a low-priority variable. The result %4 is correct according to our rules since the implicit constant in O(x) may depend on z. It is obviously wrong if z is allowed to have negative valuation in x. Of course, the correct error term should be O(xz), but this is not possible in PARI.


User defined functions

Definition.

It is easy to define a new function in GP, which can then be used like any other function. The syntax is as follows:

name(list of formal variables) = local(list of local variables); seq

which looks better written on consecutive lines:part name(x_0, x_1,...) = { local(t_0, t_1,...); local(...);

... } @eprog (the first newline is disregarded due to the preceding = sign, and the others because of the enclosing braces). Both lists of variables are comma-separated and allowed to be empty. The local statements can be omitted; as usual seq is any expression sequence.

name is the name given to the function and is subject to the same restrictions as variable names. In addition, variable names are not valid function names, you have to kill the variable first (the converse is true: function names can't be used as variables, see Label se:kill). Previously used function names can be recycled: you are just redefining the function. The previous definition is lost of course.

list of formal variables is the list of variables corresponding to those which you will actually use when calling your function. The number of actual parameters supplied when calling the function has to be less than the number of formal variables. Arguments are passed by value, not as variables: modifying a function's argument in the function body is allowed, but does not modify its value in the calling frame. In fact, a copy of the actual parameter is assigned to the formal parameter when the function is called.

Uninitialized formal variables are given a default value. An equal ( = ) sign following a variable name in the function definition, followed by any expression, gives the variable a default value. The said expression gets evaluated the moment the function is called, hence may involve the preceding function parameters (a default value for x_i may involve x_j for j < i). A variable for which you supply no default value is initialized to (the integer) zero. For instance

    foo(x, y=2, z=3) = print(x ":" y ":" z)

defines a function which prints its arguments (at most three of them), separated by colons. This then follows the rules of default arguments generation as explained at the beginning of Label se:functions.

  ? foo(6,7)
  6:7:3
  ? foo(,5)
  0:5:3
  ? foo()
  0:2:3

list of local variables is the list of additional temporary variables used in the function body. Note that if you omit some or all of these local variable declarations, the non-declared variables will become global, hence known outside of the function, and this may have undesirable side-effects. On the other hand, in some cases it may also be what you want. See Label se:varscope for details. Local variables can be given a default value as the formal variables.

Restrictions on variable use: it is not allowed to use the same variable name for different parameters of your function. Or to use a given variable both as a formal parameter and a local variable in a given function. Hence

  ? f(x,x) = 1
    ***   user function f: variable x declared twice.

Note: The above syntax (using the local keyword) was introduced in version 2.0.13. The old syntax

name(list of true formal variables, list of local variables ) = {seq}

is still recognized but is deprecated since genuine arguments and local variables become undistinguishable.

Use.

Once the function is defined using the above syntax, you can use it like any other function, see the example with fun above. In addition, you can also recall its definition exactly as you do for predefined functions, that is by writing ?name. This will print the list of arguments, as well as their default values, the text of seq, and a short help text if one was provided using the addhelp function (see Label se:addhelp). One small difference to predefined functions is that you can never redefine the built-in functions, while you can redefine a user-defined function as many times as you want.

Typing \u will output the list of user-defined functions.

An amusing example of a user-defined function is the following. It is intended to illustrate both the use of user-defined functions and the power of the sumalt function. Although the Riemann zeta-function is included in the standard functions, let us assume that this is not the case (or that we want another implementation). One way to define it, which is probably the simplest, but certainly not the most efficient, is as follows:

  zet(s) =
  { local(n); /* not needed, and possibly confusing (see below) */
    sumalt(n=1, (-1)^(n-1)*n^(-s)) / (1 - 2^(1-s))
  }

This gives reasonably good accuracy and speed as long as you are not too far from the domain of convergence. Try it for s integral between -5 and 5, say, or for s = 0.5+i*t where t = 14.134...

Recursive functions.

Recursive functions can easily be written as long as one pays proper attention to variable scope. Here is an example, used to retrieve the coefficient array of a multivariate polynomial (a non-trivial task due to PARI's unsophisticated representation for those objects):

  coeffs(P, nbvar) =
  {
    if (type(P) != "t_POL",
      for (i=1, nbvar, P = [P]);
      return (P)
    );
    vector(poldegree(P)+1, i, coeffs(polcoeff(P, i-1), nbvar-1))
  }

If P is a polynomial in k variables, show that after the assignment v = coeffs(P,k), the coefficient of x_1^{n_1}... x_k^{n_k} in P is given by v[n_1+1][...][n_k+1].

The operating system automatically limits the recursion depth:

  ? dive(n) = if (n, dive(n-1))
  ? dive(5000);
    ***   deep recursion: if(n,dive(n-1))
                          ^---------------

There is no way to increase the recursion limit (which may be different on your machine) from within gp. To increase it before launching gp, you can use ulimit or limit, depending on your shell, and raise the process available stack space (increase stacksize).

Function which take functions as parameters ?

Use the following trick (neat example due to Bill Daly):

  calc(f, x) = eval( Str(f, "(x)") )

If you call this with calc("sin", 1), it will return sin (1) (evaluated!).

Defining functions within a function ?

The first idea

    init(x) = add(y) = x+y; mul(y) = x*y;

does not work since in the construction f() = seq, the function body contains everything until the end of the expression. Hence executing init defines the wrong function add. The way out is to use parentheses for grouping, to that enclosed subexpressions be evaluated independently:

    init(x) = ( add(y) = x+y ); ( mul(y) = x*y );

Variable scope

Local variables should more appropriately be called temporary values since they are in fact local to the function declaring them and any subroutine called from within. In the following example

    f() = local(y); ... ; g()
    g() = y + 1

g() ``sees'' the y introduced in f(). True lexical scoping does not exist in GP. (See e.g. the difference between local and my in Perl.)

In an iterative constructs which use a variable name (forxxx, prodxxx, sumxxx, vector, matrix, plot, etc.) the given variable is also local to the construct. A value is pushed on entry and poped on exit. So, it is not necessary for a function using such an iterator to declare the variable as local. On the other hand, if you exit the loop prematurely, e.g. using the break statement, you must save the loop index in another variable since its value prior the loop will be restored upon exit: for instance

    for(i = 1, n,
      if (ok(i), break);
    );
    if (i > n, return(failure));

is incorrect, since the value of i tested by the (i > n) is quite unrelated to the loop index.

Finally, the statement global(x, y, z, t) (see Label se:global) declares the corresponding variables to be global. It is then forbidden to use them as formal parameters or loop indexes as above, since the parameter would ``shadow'' the variable. If speed is of the essence and an object is large (e.g. a bnf, a huge matrix), it should be declared global, not passed as a parameter, since this saves an expensive copy. It is possible to declare it local and use it as a global variables from relevant subroutines, but global is safer.

It is strongly recommended to explicitly declare all global variables at the beginning of your program and all local variable used inside a given function, with the possible exception of loop indexes which are local to their loop. If a function accesses a variable which is not one of its formal parameters, the value used will be the one which happens to be on top of the stack at the time of the call. This could be a ``global'' value, or a local value belonging to any function higher in the call chain, and is in general not what you want to do. So, be warned.

Coming back to our previous example zet, since loop variables are not visible outside their loops, the variable n need not be declared in the function protoype.

  zet(s) = sumalt(n=1, (-1)^(n-1)*n^(-s)) / (1 - 2^(1-s))

would be a better definition. One last example: what is wrong with the following definition?

  FirstPrimeDiv(x) =
  { local(p);
    forprime(p=2, x, if (x%p == 0, break));
    p
  }
  ? FirstPrimeDiv(10)
  %1 = 0

Well, the index p in the forprime loop is local to the loop and is not visible to the outside world. Hence, it does not survive the break statement. More precisely, at this point the loop index is restored to its preceding value, which is 0 (local variables are initialized to 0 by default). To sum up, the routine returns the p declared local to it, not the one which was local to forprime and ran through consecutive prime numbers. Here is a corrected version:

  ? FirstPrimeDiv(x) = forprime(p=2, x, if (x%p == 0, return(p)))

Implementation note: For the curious reader, here is how values of variables are handled: a hashing function is computed from the variable name, and used as an index in hashtable, a table of linked list of structures (type entree). The linked list is searched linearly for the identifier (each list typically has less than 10 components). When the correct entree is found, it points to the top of the stack of values for that identifier if it is a variable, to the function itself if it is a predefined function, and to a copy of the text of the function if it is a user-defined function. When an error occurs, all of this maze (rather a tree, in fact) is searched and restored to the state preceding the last call of the main evaluator.


Member functions

Member functions use the `dot' notation to retrieve information from complicated structures, by default: bid, ell, galois, nf, bnf, bnr and prime ideals. The syntax structure.member is taken to mean: retrieve member from structure, e.g. ell.j returns the j-invariant of the elliptic curve ell, or outputs an error message if ell doesn't have the correct type.

To define your own member functions, use the syntax structure.member = function text, where function text is written as the seq in a standard user function (without local variables), whose only argument would be structure. For instance, the current implementation of the ell type is simply an horizontal vector, the j-invariant being the thirteenth component. It could be implemented as

  x.j =
  {
    if (type(x) != "t_VEC" || length(x) < 14,
      error("this is not a proper elliptic curve: " x)
    );
    x[13]
  }

Typing \um will output the list of user-defined member functions.

You can redefine one of your own member functions simply by typing a new definition for it. On the other hand, as a safety measure, you can't redefine the built-in member functions, so typing the above text would in fact produce an error (you'd have to call it e.g. x.myj in order for gp to accept it).

Warning: contrary to user functions arguments, the structure accessed by a member function is not copied before being used. Any modification to the structure's components will be permanent.

Warning: it is advised not to apply a member whose name starts with e or E to an integer constant, where it would be confused with the usual floating point exponent. E.g compare

    ? x.e2 = x+1
    ? 1.e2
    %1 = 100.000000000 \\ taken to mean 1.0E2.
    ? (1).e2
    %2 = 2
    ? 1.0.e2
    %3 = 2.00000000000

Note: Member functions were not meant to be too complicated or to depend on any data that wouldn't be global. Hence they do no have parameters (besides the implicit structure) or local variables. Of course, if you need some preprocessing work in there, there's nothing to prevent you from calling your own functions (using freely their local variables) from a member function. For instance, one could implement (a dreadful idea as far as efficiency goes):

  correct_ell_if_needed(x) =
  { local(tmp);
    if (type(x) != "t_VEC", tmp = ellinit(x))
      \\  some further checks
    tmp
  }
  x.j = correct_ell_if_needed(x)[13];


Strings and Keywords

Strings.

GP variables can hold values of type character string (internal type t_STR). This section describes how they are actually used, as well as some convenient tricks (automatic concatenation and expansion, keywords) valid in string context.

As explained above, the general way to input a string is to enclose characters between quotes ". This is the only input construct where whitespace characters are significant: the string will contain the exact number of spaces you typed in. Besides, you can ``escape'' characters by putting a \ just before them; the translation is as follows

     \e: <Escape>
     \n: <Newline>
     \t: <Tab>

For any other character x, \x is expanded to x. In particular, the only way to put a " into a string is to escape it. Thus, for instance, "\"a\"" would produce the string whose content is ``a''. This is definitely not the same thing as typing "a", whose content is merely the one-letter string a.

You can concatenate two strings using the concat function. If either argument is a string, the other is automatically converted to a string if necessary (it will be evaluated first).

  ? concat("ex", 1+1)
  %1 = "ex2"
  ? a = 2; b = "ex"; concat(b, a)
  %2 = "ex2"
  ? concat(a, b)
  %3 = "2ex"

Some functions expect strings for some of their arguments: print would be an obvious example, Str is a less obvious but useful one (see the end of this section for a complete list). While typing in such an argument, you will be said to be in string context. The rest of this section is devoted to special syntactical tricks which can be used with such arguments (and only here; you will get an error message if you try these outside of string context):

* Writing two strings alongside one another will just concatenate them, producing a longer string. Thus it is equivalent to type in "a " "b" or "a b". A little tricky point in the first expression: the first whitespace is enclosed between quotes, and so is part of a string; while the second (before the "b") is completely optional and gp actually suppresses it, as it would with any number of whitespace characters at this point (i.e. outside of any string).

* If you insert any expression when a string is expected, it gets ``expanded'': it is evaluated as a standard GP expression, and the final result (as would have been printed if you had typed it by itself) is then converted to a string, as if you had typed it directly. For instance "a" 1+1 "b" is equivalent to "a2b": three strings get created, the middle one being the expansion of 1+1, and these are then concatenated according to the rule described above. Another tricky point here: assume you did not assign a value to aaa in a GP expression before. Then typing aaa by itself in a string context will actually produce the correct output (i.e. the string whose content is aaa), but in a fortuitous way. This aaa gets expanded to the monomial of degree one in the variable aaa, which is of course printed as aaa, and thus will expand to the three letters you were expecting.

Warning: expression involving strings are not handled in a special way; even in string context, the largest possible expression is evaluated, hence print("a"[1]) is incorrect since "a" is not an object whose first component can be extracted. On the other hand print("a", [1]) is correct (two distinct argument, each converted to a string), and so is print("a" 1) (since "a"1 is not a valid expression, only "a" gets expanded, then 1, and the result is concatenated as explained above). In case of doubt, you can surround part of your text by parenthesis to force immediate interpretation of a subexpression: print("a"([1])) is another solution.

Keywords.

Since there are cases where expansion is not desirable, we now distinguish between ``Keywords'' and ``Strings''. String is what has been described so far. Keywords are special relatives of Strings which are automatically assumed to be quoted, whether you actually type in the quotes or not. Thus expansion is never performed on them. They get concatenated, though. The analyzer supplies automatically the quotes you have ``forgotten'' and treats Keywords just as normal strings otherwise. For instance, if you type "a"b+b in Keyword context, you will get the string whose contents are ab+b. In String context, on the other hand, you would get a2*b.

All GP functions have prototypes (described in Chapter 3 below) which specify the types of arguments they expect: either generic PARI objects (GEN), or strings, or keywords, or unevaluated expression sequences. In the keyword case, only a very small set of words will actually be meaningful (the default function is a prominent example).

Reference: The arguments of the following functions are processed in string context:

  Str   addhelp (second argument)   default (second argument)   error   extern   plotstring (second argument)   plotterm (first argument)   read and readvec   system   all the printxxx functions   all the writexxx functions

The arguments of the following functions are processed as keywords:

  alias   default (first argument)   install (all arguments but the last)   trap (first argument)   type (second argument)   whatnow

Useful examples

The function Str converts its arguments into strings and concatenate them. Coupled with eval, it is very powerful. The following example creates generic matrices:

  ? genmat(u,v,s="x") = matrix(u,v,i,j, eval( Str(s,i,j) ))
  ? genmat(2,3) + genmat(2,3,"m")
  %1 =
  [x11 + m11 x12 + m12 x13 + m13]
  [x21 + m21 x22 + m22 x23 + m23]

Two last examples: hist(10,20) returns all history entries from %10 to %20 neatly packed into a single vector; histlast(10) returns the last 10 history entries:

    hist(a,b) = vector(b-a+1, i, eval(Str("%", a-1+i)))
    histlast(n) = vector(n, i, eval(Str("%", %#-i+1)))


Errors and error recovery

Errors. There are two kind of errors

syntax errors, and errors produced by functions in the PARI library. Both kinds are fatal to your computation: gp will report the error, perform some cleanup (restore variables modified while evaluating the erroneous command, close open files, reclaim unused memory, etc.), and will output its usual prompt.

When reporting a syntax error, gp tries to give meaningful context by copying the sentence it was trying to read (whitespace and comments stripped out), indicating an error with a little caret like in

  ? factor(x^2 - 1
    ***   expected character: {\tt ','} instead of: factor(x^2-1
                                                          ^

possibly enlarged to a full arrow given enough trailing context

  ? if (siN(x) < eps, do_something())
    ***   expected character: {\tt '='} instead of: if(siN(x)<eps,do_something())
                                                       ^--------------------

Error messages will often be mysterious, because gp cannot guess what you were trying to do and the error usually occurs once gp has been sidetracked. Let's have a look at the two messages above.

The first error is a missing parenthesis, but from gp's point of view, you might as well have intended to give further arguments to factor (this is possible, and often useful, see the description of the function). Since gp did not see the closing parenthesis, it tried to read a second argument, first looking for the comma that would separate it form the first. The error occurred at this point. So gp tells you that it was expecting a comma and saw a blank.

The second error is even weirder. It is a simple typo, siN instead of sin and gp tells us that is was expecting an equal sign a few characters later? What happens is this: siN is not a recognized identifier, but from the context, it looks like a function (it is followed by an open parenthesis), then we have an argument, then a closing parenthesis. Then if siN were a known function we would evaluate it; but it is not, so gp assumes that you were trying to define it, as in

  ? if (siN(x)=sin(x), ...)

This is actually allowed (!) and defines the function siN as an alias for sin. As any expression a function definition has a value, which is 0, hence the test is meaningful, and false, so nothing happens. (Admittedly this doesn't look like a useful syntax but it can be interesting in other contexts to let functions define other functions. Anyway, it is allowed by the language definition.) So gp tells you in good faith that to correctly define a function, you need an equal sign between its name and its body.

Error messages from the library will usually be clearer since, by definition, they answer a correctly worded query (otherwise gp would have protested first). Also they have more mathematical content, which should be easier to grasp than a parser's logic. For instance:

  ? 1/0
    ***   division by zero

Error recovery

It is quite annoying to wait for some program to finish and find out the hard way that there was a mistake in it (like the division by 0 above), sending you back to the prompt. First you may lose some valuable intermediate data. Also, correcting the error may not be ovious; you might have to change your program, adding a number of extra statements and tests to try and narrow down the problem.

A slightly different situation, still related to error recovery, is when you you actually foresee that some error may occur, are unable to prevent it, but quite capable of recovering from it, given the chance. Examples include lazy factorization (cf. addprimes), where you knowingly use a pseudo prime N as if it were prime; you may then encounter an ``impossible'' situation, but this would usually exhibit a factor of N, enabling you to refine the factorization and go on. Or you might run an expensive computation at low precision to guess the size of the output, hence the right precision to use. You can then encounter errors like ``precision loss in truncation'', e.g when trying to convert 1E1000, known to 28 digits of accuracy, to an integer; or ``division by 0'', e.g inverting 0E1000 when all accuracy has been lost, and no significant digit remains. It would be enough to restart part of the computation at a slightly higher precision.

We now describe error trapping, a useful mechanism which alleviates much of the pain in the first situation, and provides a satisfactory way out of the second one. Everything is handled via the trap function whose different modes we now describe.

Break loop

A break loop is a special debugging mode that you enter whenever an error occurs, freezing the gp state, and preventing cleanup until you get out of the loop. Any error: syntax error, library error, user error (from error), even user interrupts like C-c (Control-C). When a break loop starts, a prompt is issued (break > ). You can type in a gp command, which is evaluated when you hit the < Return > key, and the result is printed as during the main gp loop, except that no history of results is kept Then the break loop prompt reappears and you can type further commands as long as you do not exit the loop. If you are using readline, the history of commands is kept, and line editing is available as usual. If you type in a command that results in an error, you are sent back to the break loop prompt (errors does not terminate the loop).

To get out of a break loop, you can use next, break, return, or C-d (EOF), any of which will let gp perform its usual cleanup, and send you back to the gp prompt. If the error is not fatal, inputing an empty line, i.e hitting the < Return > key at the break > prompt, will continue the temporarily interrupted computation. An empty line has no effect in case of a fatal error, to ensure you do not get out of the loop prematurely, thus losing most debugging data during the cleanup (since user variables will be restored to their former values).

In current version 2.3.5, an error is non-fatal if and only if it was initiated by a C-c typed by the user.

Break loops are useful as a debugging tool to inspect the values of gp variables to understand why an error occurred, or to change gp's state in the middle of a computation (increase debugging level, start storing results in a logfile, set variables to different values...): hit C-c, type in your modifications, then let the computation go on as explained above.

A break loop looks like this:

  ? for(v = -2, 2, print(1/v))
  -1/2
  -1
    ***   division by zero in gdiv, gdivgs or ginv
    ***   Starting break loop (type 'break' to go back to GP):
    ***   for(v=-2,2,print(1/v))
                              ^--
  break>

So the standard error message is printed first, except now we always have context, whether the error comes from the library or the parser. The break > at the bottow is a prompt, and hitting v then < Return > , we see:

  break> v
  0

explaining the problem. We could have typed any gp command, not only the name of a variable, of course. There is no special set of commands becoming available during a break loop, as they would in most debuggers.

Important Note: upon startup, this mechanism is off. Type trap() (or include it in a script) to start trapping errors in this way. By default, you will be sent back to the prompt.

Technical Note: When you enter a break loop due to a PARI stack overflow, the PARI stack is reset so that you can run commands (otherwise the stack would immediately overflow again). Still, as explained above, you do not lose the value of any gp variable in the process.

Error handlers.

The break loop described above is a (sophisticated) example of an error handler: a function that is executed whenever an error occurs, supposedly to try and recover. The break loop is quite a satisfactory error handler, but it may not be adequate for some purposes, for instance when gp runs in non-interactive mode, detached from a terminal.

So, you can define a different error handler, to be used in place of the break loop. This is the purpose of the second argument of trap: to specify an error handler. (We will discuss the first argument at the very end.) For instance:

  ? { trap( ,                \\@ note the comma: arg1 is omitted
        print(reorder);
        writebin("crash")) }

After that, whenever an error occurs, the list of all user variables is printed, and they are all saved in binary format in file crash, ready for inspection. Of course break loops are no longer available: the new handler has replaced the default one. Besides user-defined handlers as above, there are two special handlers you can use in trap, which are

* trap(, "") (do-nothing handler): to disable the trapping mechanism and let errors propagate, which is the default situation on startup.

* trap(, ) (omitted argument, default handler): to trap errors by a break loop.

Protecting code.

Finally trap can define a temporary handler used within the scope of a code frament, protecting it from errors, by providing replacement code should the trap be activated. The expression

trap( , recovery, statements)

evaluates and returns the value of statements, unless an error occurs during the evaluation in which case the value of recovery is returned. As in an if/else clause, with the difference that statements has been partially evaluated, with possible side effects. For instance one could define a fault tolerant inversion function as follows:

  ? inv(x) = trap (, "oo", 1/x)
  ? for (i=-1,1, print(inv(i)))
  -1
  oo
  1

Protected codes can be nested without adverse effect, the last trap seen being the first to spring.

Trapping specific exceptions.

We have not yet seen the use of the first argument of trap, which has been omitted in all previous examples. It simply indicates that only errors of a specific type should be intercepted, to be chosen among

accurer: accuracy problem

gdiver: division by 0

invmoder: impossible inverse modulo

archer: not available on this architecture or operating system

typeer: wrong type

errpile: the PARI stack overflows

Omitting the error name means we are trapping all errors. For instance, the following can be used to check in a safe way whether install works correctly in your gp:

  broken_install() =
  {
    trap(archer, return ("OS"),
      install(addii,GG)
    );
    trap(, "USE",
      if (addii(1,1) != 2, "BROKEN")
    )
  }

The function returns 0 if everything works (the omitted else clause of the if), OS if the operating system does not support install, USE if using an installed function triggers an error, and BROKEN if the installed function did not behave as expected.


Interfacing GP with other languages

The PARI library was meant to be interfaced with C programs. This specific use will be dealt with extensively in Chapter 4. gp itself provides a convenient, if simple-minded, interpreter, which enables you to execute rather intricate scripts (see Label se:programming).

Scripts, when properly written, tend to be shorter and clearer than C programs, and are certainly easier to write, maintain or debug. You don't need to deal with memory management, garbage collection, pointers, declarations, and so on. Because of their intrinsic simplicity, they are more robust as well. They are unfortunately somewhat slower. Thus their use will remain complementary: it is suggested that you test and debug your algorithms using scripts, before actually coding them in C for the sake of speed. The GP2C compiler often eases this part.

Note also that the install command enables you to concentrate on critical parts of your programs only (which can of course be written with the help of other mathematical libraries than PARI!), and to efficiently import foreign functions for use under gp (see Label se:install).

We are aware of four PARI-related public domain packages to embed PARI in other languages. We neither endorse nor support any of them; you might want to give them a try if you are familiar with the languages they are based on. The first is the Math::Pari Perl module (see any CPAN mirror), written by Ilya Zakharevich. The second is PariPython FOOTNOTE<<< see http://www.fermigier.com/fermigier/PariPython/ >>>,

by Stéfane Fermigier, which is no more maintained. Starting from Fermigier's work, Wiliam Stein has embedded PARI into his Python-based SAGEFOOTNOTE<<< see http://modular.fas.harvard.edu/sage/ >>> system. Finally, Michael Stoll has integrated PARI into CLISP FOOTNOTE<<< see http://clisp.cons.org >>>, which is a Common Lisp implementation by Bruno Haible, Marcus Daniels and others; this interface has been updated for pari-2 by Sam Steingold.

These provide interfaces to gp functions for use in perl, python or Lisp programs, respectively.


Defaults

There are many internal variables in gp, defining how the system will behave in certain situations, unless a specific override has been given. Most of them are a matter of basic customization (colors, prompt) and will be set once and for all in your preferences file (see Label se:gprc), but some of them are useful interactively (set timer on, increase precision, etc.).

The function used to manipulate these values is called default, which is described in Label se:default. The basic syntax is

default(def, value),

which sets the default def to value. In interactive use, most of these can be abbreviated using historic gp metacommands (mostly, starting with \b), which we shall describe in the next section.

Here we will only describe the available defaults and how they are used. Just be aware that typing default by itself will list all of them, as well as their current values (see \d). Just after the default name, we give between parentheses the initial value when gp starts (assuming you did not tamper with it using command-line switches or a gprc).

Note: the suffixes k, M or G can be appended to a value which is a numeric argument, with the effect of multiplying it by 10^3, 10^6 and 10^9 respectively. Case is not taken into account there, so for instance 30k and 30K both stand for 30000. This is mostly useful to modify or set the defaults primelimit or stacksize which typically involve a lot of trailing zeroes.

(somewhat technical) Note: As we will see in Label se:strings, the second argument to default will be subject to string context expansion, which means you can use run-time values. In other words, something like

    a = 3;
    default(logfile, "\var{some filename}" a ".log")

logs the output in some filename3.log.

Some defaults will be expanded further when the values are used, after the above expansion has been performed:

* time expansion: the string is sent through the library function strftime. This means that %char combinations have a special meaning, usually related to the time and date. For instance, %H = hour (24-hour clock) and %M = minute [00,59] (on a Unix system, you can try man strftime at your shell prompt to get a complete list). This is applied to prompt, psfile, and logfile. For instance,

default(prompt,"(%H:%M) ? ")

will prepend the time of day, in the form (hh:mm) to gp's usual prompt.

* environment expansion: When the string contains a sequence of the form SOMEVAR, e.g. HOME, the environment is searched and if SOMEVAR is defined, the sequence is replaced by the corresponding value. Also the ~ symbol has the same meaning as in many shells --- ~ by itself stands for your home directory, and ~user is expanded to user's home directory. This is applied to all filenames.

colors (default "")

this default is only usable if gp is running within certain color-capable terminals. For instance rxvt, color_xterm and modern versions of xterm under X Windows, or standard Linux/DOS text consoles. It causes gp to use a small palette of colors for its output. With xterms, the colormap used corresponds to the resources Xterm*colorn where n ranges from 0 to 15 (see the file misc/color.dft for an example). Accepted values for this default are strings "a_1,...,a_k" where k <= 7 and each a_i is either

* the keyword no (use the default color, usually black on transparent background)

* an integer between 0 and 15 corresponding to the aforementioned colormap

* a triple [c_0,c_1,c_2] where c_0 stands for foreground color, c_1 for background color, and c_2 for attributes (0 is default, 1 is bold, 4 is underline).

The output objects thus affected are respectively error messages, history numbers, prompt, input line, output, help messages, timer (that's seven of them). If k < 7, the remaining a_i are assumed to be no. For instance

  default(colors, "9, 5, no, no, 4")

typesets error messages in color 9, history numbers in color 5, output in color 4, and does not affect the rest.

A set of default colors for dark (reverse video or PC console) and light backgrounds respectively is activated when colors is set to darkbg, resp. lightbg (or any proper prefix: d is recognized as an abbreviation for darkbg). A bold variant of darkbg, called boldfg, is provided if you find the former too pale.

 In the present version, this default is incompatible with Emacs.
Changing it will just fail silently (the alternative would be to display
escape sequences as is, since Emacs will refuse to interpret them). On the
other hand, you can customize highlighting in your C<.emacs> so as to mimic
exactly this behaviour. See C<emacs/pariemacs.txt>.

Technical note: If you use an old readline library (version number less than 2.0), you should do as in the example above and leave a_3 and a_4 (prompt and input line) strictly alone. Since old versions of readline did not handle escape characters correctly (or more accurately, treated them in the only sensible way since they did not care to check all your terminal capabilities: it just ignored them), changing them would result in many annoying display bugs.

The specific thing to look for is to check the readline.h include file, wherever your readline include files are, for the string RL_PROMPT_START_IGNORE. If it is there, you are safe. Another sensible way is to make some experiments, and get a more recent readline if yours doesn't work the way you would like it to. See the file misc/gprc.dft for some examples.

compatible (default 0)

The GP function names and syntax have changed tremendously between versions 1.xx and 2.00. To help you cope with this we provide some kind of backward compatibility, depending on the value of this default:

  compatible = 0: no backward compatibility. In this mode, a very handy function, to be described in Label se:whatnow, is whatnow, which tells you what has become of your favourite functions, which gp suddenly can't seem to remember.

  compatible = 1: warn when using obsolete functions, but otherwise accept them. The output uses the new conventions though, and there may be subtle incompatibilities between the behaviour of former and current functions, even when they share the same name (the current function is used in such cases, of course!). We thought of this one as a transitory help for gp old-timers. Thus, to encourage switching to compatible = 0, it is not possible to disable the warning.

  compatible = 2: use only the old function naming scheme (as used up to version 1.39.15), but taking case into account. Thus I ( = sqrt {-1}) is not the same as i (user variable, unbound by default), and you won't get an error message using i as a loop index as used to be the case.

  compatible = 3: try to mimic exactly the former behaviour. This is not always possible when functions have changed in a fundamental way. But these differences are usually for the better (they were meant to, anyway), and will probably not be discovered by the casual user.

One adverse side effect is that any user functions and aliases that have been defined before changing compatible will get erased if this change modifies the function list, i.e. if you move between groups {0,1} and {2,3} (variables are unaffected). We of course strongly encourage you to try and get used to the setting compatible = 0.

Note that the default new_galois_format is another compatibility setting, which is completely independent of compatible.

datadir (default: the location of installed precomputed data)

the name of directory containing the optional data files. For now, only the galdata and elldata packages.

debug (default 0)

debugging level. If it is non-zero, some extra messages may be printed (some of it in French), according to what is going on (see \g).

debugfiles (default 0)

file usage debugging level. If it is non-zero, gp will print information on file descriptors in use, from PARI's point of view (see \gf).

debugmem (default 0)

memory debugging level. If it is non-zero, gp will regularly print information on memory usage. If it's greater than 2, it will indicate any important garbage collecting and the function it is taking place in (see \gm).

Important Note: As it noticeably slows down the performance, the first functionality (memory usage) is disabled if you're not running a version compiled for debugging (see Appendix A).

echo (default 0)

this is a toggle, which can be either 1 (on) or 0 (off). When echo mode is on, each command is reprinted before being executed. This can be useful when reading a file with the \r or read commands. For example, it is turned on at the beginning of the test files used to check whether gp has been built correctly (see \e).

factor_add_primes (default 0)

if this is set, the integer factorization machinery will call addprimes on primes factor that were difficult to find, so they are automatically tried first in other factorizations. If a routine is performing (or has performed) a factorization and is interrupted by an error or via Control-C, this let you recover the prime factors already found.

format

(default "g0.28" and "g0.38" on 32-bit and 64-bit machines, respectively): of the form xm.n, where x is a letter in {e,f,g}, and n, m are integers. If x is f, real numbers will be printed in fixed floating point format with no explicit exponent (e.g. 0.000033), unless their integer part is not defined (not enough significant digits); if the letter is e, they will be printed in scientific format, always with an explicit exponent (e.g. 3.3e-5). If the letter is g, real numbers will be printed in f format, except when their absolute value is less than 2^{-32} or they are real zeroes (of arbitrary exponent), in which case they are printed in e format.

The number n is the number of significant digits printed for real numbers, except if n < 0 where all the significant digits will be printed (initial default 28, or 38 for 64-bit machines), and the number m is the number of characters to be used for printing integers, but is ignored if equal to 0 (which is the default). This is a feeble attempt at formatting.

help (default: the location of the gphelp script)

the name of the external help program which will be used from within gp when extended help is invoked, usually through a ?? or ??? request (see Label se:exthelp), or M-H under readline (see Label se:readline).

histsize (default 5000)

gp keeps a history of the last histsize results computed so far, which you can recover using the % notation (see Label se:history). When this number is exceeded, the oldest values are erased. Tampering with this default is the only way to get rid of the ones you do not need anymore.

lines (default 0)

if set to a positive value, gp prints at most that many lines from each result, terminating the last line shown with [+++] if further material has been suppressed. The various print commands (see Label se:gp_program) are unaffected, so you can always type print(%), \a, or \b to view the full result. If the actual screen width cannot be determined, a ``line'' is assumed to be 80 characters long.

log (default 0)

this can be either 0 (off) or 1, 2, 3 (on, see below for the various modes). When logging mode is turned on, gp opens a log file, whose exact name is determined by the logfile default. Subsequently, all the commands and results will be written to that file (see \l). In case a file with this precise name already existed, it will not be erased: your data will be appended at the end.

The specific positive values of log have the following meaning

1: plain logfile

2: emit color codes to the logfile (if colors is set).

3: write LaTeX output to the logfile (can be further customized using TeXstyle).

logfile (default "pari.log")

name of the log file to be used when the log toggle is on. Environment and time expansion are performed.

new_galois_format (default 0)

if this is set, the polgalois command will use a different, more consistent, naming scheme for Galois groups. This default is provided to ensure that scripts can control this behaviour and do not break unexpectedly. Note that the default value of 0 (unset) will change to 1 (set) in the next major version.

output (default 1)

there are four possible values: 0 ( =  raw), 1 ( =  prettymatrix), 2 ( =  prettyprint), or 3 ( =  external prettyprint). This means that, independently of the default format for reals which we explained above, you can print results in four ways: either in raw format, i.e. a format which is equivalent to what you input, including explicit multiplication signs, and everything typed on a line instead of two dimensional boxes. This can have several advantages, for instance it allows you to pick the result with a mouse or an editor, and to paste it somewhere else.

The second format is the prettymatrix format. The only difference to raw format is that matrices are printed as boxes instead of horizontally. This is prettier, but takes more space and cannot be used for input. Column vectors are still printed horizontally.

The third format is the prettyprint format, or beautified format. In the present version 2.3.5, this is not beautiful at all.

The fourth format is external prettyprint, which pipes all gp output in TeX format to an external prettyprinter, according to the value of prettyprinter. The default script (tex2mail) converts its input to readable two-dimensional text.

Independently of the setting of this default, an object can be printed in any of the three formats at any time using the commands \a, \m and \b respectively (see below).

parisize

(default 4M, resp. 8M on a 32-bit, resp. 64-bit machine): gp, and in fact any program using the PARI library, needs a stack in which to do its computations. parisize is the stack size, in bytes. It is strongly recommended you increase this default (using the -s command-line switch, or a gprc) if you can afford it. Don't increase it beyond the actual amount of RAM installed on your computer or gp will spend most of its time paging.

In case of emergency, you can use the allocatemem function to increase parisize, once the session is started.

path (default ``.

~:~/gp``> on UNIX systems, ".;C:\;C:\GP on DOS, OS/2 and Windows, and "." otherwise): This is a list of directories, separated by colons ':' (semicolons ';' in the DOS world, since colons are pre-empted for drive names). When asked to read a file whose name does not contain / (i.e. no explicit path was given), gp will look for it in these directories, in the order they were written in path. Here, as usual, '.' means the current directory, and '..' its immediate parent. Environment expansion is performed.

prettyprinter

(default "tex2mail -TeX -noindent -ragged -by_par") the name of an external prettyprinter to use when output is 3 (alternate prettyprinter). Note that the default tex2mail looks much nicer than the built-in ``beautified format'' (output = 2).

primelimit (default 500k)

gp precomputes a list of all primes less than primelimit at initialization time. These are used by many arithmetical functions. If you don't plan to invoke any of them, you can just set this to 1. The maximal value is a little less than 2^32 (resp 2^64) on a 32-bit (resp. 64-bit) machine.

prompt (default "? ")

a string that will be printed as prompt. Note that most usual escape sequences are available there: \e for Esc, \n for Newline,..., \\ for \. Time expansion is performed.

This string is sent through the library function strftime (on a Unix system, you can try man strftime at your shell prompt). This means that % constructs have a special meaning, usually related to the time and date. For instance, %H = hour (24-hour clock) and %M = minute [00,59] (use %% to get a real %).

If you use readline, escape sequences in your prompt will result in display bugs. If you have a relatively recent readline (see the comment at the end of Label se:colors), you can brace them with special sequences (\[ and \]), and you will be safe. If these just result in extra spaces in your prompt, then you'll have to get a more recent readline. See the file misc/gprc.dft for an example.

S< >Caution: Emacs needs to know about the prompt pattern to separate your input from previous gp results, without ambiguity. It is not a trivial problem to adapt automatically this regular expression to an arbitrary prompt (which can be self-modifying!). Thus, in this version 2.3.5, Emacs relies on the prompt being the default one. So, do not tamper with the prompt variable unless you modify it simultaneously in your .emacs file (see emacs/pariemacs.txt and misc/gprc.dft for examples).

prompt_cont (default "")

a string that will be printed to prompt for continuation lines (e.g. in between braces, or after a line-terminating backslash). Everything that applies to prompt applies to prompt_cont as well.

psfile (default "pari.ps")

name of the default file where gp is to dump its PostScript drawings (these are appended, so that no previous data are lost). Environment and time expansion are performed.

readline (default 1)

switches readline line-editing facilities on and off. This may be useful if you are running gp in a Sun cmdtool, which interacts badly with readline. Of course, until readline is switched on again, advanced editing features like automatic completion and editing history are not available.

realprecision (default 28 and 38 on 32-bit and 64-bit machines respectively)

the number of significant digits and, at the same time, the number of printed digits of real numbers (see \p). Note that PARI internal precision works on a word basis (32 or 64 bits), hence may not coincide with the number of decimal digits you input. For instance to get 2 decimal digits you need one word of precision which, on a 32-bit machine, actually gives you 9 digits (9 < log _{10}(2^{32}) < 10):

  ? default(realprecision, 2)
        realprecision = 9 significant digits (2 digits displayed)

secure (default 0)

this is a toggle which can be either 1 (on) or 0 (off). If on, the system and extern command are disabled. These two commands are potentially dangerous when you execute foreign scripts since they let gp execute arbitrary UNIX commands. gp will ask for confirmation before letting you (or a script) unset this toggle.

seriesprecision (default 16)

number of significant terms when converting a polynomial or rational function to a power series (see \ps).

simplify (default 1)

this is a toggle which can be either 1 (on) or 0 (off). When the PARI library computes something, the type of the result is not always the simplest possible. The only type conversions which the PARI library does automatically are rational numbers to integers (when they are of type t_FRAC and equal to integers), and similarly rational functions to polynomials (when they are of type t_RFRAC and equal to polynomials). This feature is useful in many cases, and saves time, but can be annoying at times. Hence you can disable this and, whenever you feel like it, use the function simplify (see Chapter 3) which allows you to simplify objects to the simplest possible types recursively (see \y).

strictmatch (default 1)

this is a toggle which can be either 1 (on) or 0 (off). If on, unused characters after a sequence has been processed will produce an error. Otherwise just a warning is printed. This can be useful when you're not sure how many parentheses you have to close after complicated nested loops.

TeXstyle (default 0)

the bits of this default allow gp to use less rigid TeX formatting commands in the logfile. This default is only taken into account when log = 3. The bits of TeXstyle have the following meaning

2: insert \right / \left pairs where appropriate.

4: insert discretionary breaks in polynomials, to enhance the probability of a good line break.

timer (default 0)

this is a toggle which can be either 1 (on) or 0 (off). If on, every instruction sequence (anything ended by a newline in your input) is timed, to some accuracy depending on the hardware and operating system. The time measured is the user CPU time, not including the time for printing the results (see # and ##).


Simple metacommands

Simple metacommands are meant as shortcuts and should not be used in GP scripts (see Label se:programming). Beware that these, as all of gp input, are case sensitive. For example, \Q is not identical to \q. In the following list, braces are used to denote optional arguments, with their default values when applicable, e.g. {n = 0} means that if n is not there, it is assumed to be 0. Whitespace (or spaces) between the metacommand and its arguments and within arguments is optional. (This can cause problems only with \w, when you insist on having a filename whose first character is a digit, and with \r or \w, if the filename itself contains a space. In such cases, just use the underlying read or write function; see Label se:write).

? {command}

gp on-line help interface. If you type ?n where n is a number from 1 to 11, you will get the list of functions in Section 3.n of the manual (the list of sections being obtained by simply typing ?).

These names are in general not informative enough. More details can be obtained by typing ?function, which gives a short explanation of the function's calling convention and effects. Of course, to have complete information, read Chapter 3 of this manual (the source code is at your disposal as well, though a trifle less readable).

If the line before the copyright message indicates that extended help is available (this means perl is present on your system and the PARI distribution was correctly installed), you can add more ? signs for extended functionalities:

?? keyword yields the functions description as it stands in this manual, usually in Chapter 2 or 3. If you're not satisfied with the default chapter chosen, you can impose a given chapter by ending the keyword with @ followed by the chapter number, e.g. ?? Hello@2 will look in Chapter 2 for section heading Hello (which doesn't exist, by the way).

All operators (e.g. +, &&, etc.) are accepted by this extended help, as well as a few other keywords describing key gp concepts, e.g. readline (the line editor), integer, nf (``number field'' as used in most algebraic number theory computations), ell (elliptic curves), etc.

In case of conflicts between function and default names (e.g log, simplify), the function has higher priority. To get the default help, use

    ?? default(log)
    ?? default(simplify)

??? pattern produces a list of sections in Chapter 3 of the manual related to your query. As before, if pattern ends by @ followed by a chapter number, that chapter is searched instead; you also have the option to append a simple @ (without a chapter number) to browse through the whole manual.

If your query contains dangerous characters (e.g ? or blanks) it is advisable to enclose it within double quotes, as for GP strings (e.g ??? "elliptic curve").

Note that extended help is much more powerful than the short help, since it knows about operators as well: you can type ?? * or ?? &&, whereas a single ? would just yield a not too helpful

*** unknown identifier.

message. Also, you can ask for extended help on section number n in Chapter 3, just by typing ?? n (where ?n would yield merely a list of functions). Finally, a few key concepts in gp are documented in this way: metacommands (e.g ?? "??"), defaults (e.g ?? psfile) and type names (e.g t_INT or integer), as well as various miscellaneous keywords such as edit (short summary of line editor commands), operator, member, "user defined", nf, ell,...

Last but not least: ?? without argument will open a dvi previewer (xdvi by default, $GPXDVI if it is defined in your environment) containing the full user's manual. ??tutorial and ??refcard do the same with the tutorial and reference card respectively.

Technical note: these functionalities are provided by an external perl script that you are free to use outside any gp session (and modify to your liking, if you are perl-knowledgeable). It is called gphelp, lies in the doc subdirectory of your distribution (just make sure you run Configure first, see Appendix A) and is really two programs in one. The one which is used from within gp is gphelp which runs TeX on a selected part of this manual, then opens a previewer. gphelp -detex is a text mode equivalent, which looks often nicer especially on a colour-capable terminal (see misc/gprc.dft for examples). The default help selects which help program will be used from within gp. You are welcome to improve this help script, or write new ones (and we would like to know about it so that we may include them in future distributions). By the way, outside of gp you can give more than one keyword as argument to gphelp.

/*...*/

comment. Everything between the stars is ignored by gp. These comments can span any number of lines.

\\

one-line comment. The rest of the line is ignored by gp.

\a {n}

prints the object number n (%n) in raw format. If the number n is omitted, print the latest computed object (%).

\b {n}

Same as \a, in prettyprint (i.e. beautified) format.

\c

prints the list of all available hardcoded functions under gp, not including operators written as special symbols (see Label se:operators). More information can be obtained using the ? metacommand (see above). For user-defined functions / member functions, see \u and \um.

\d

prints the defaults as described in the previous section (shortcut for default(), see Label se:default).

\e {n}

switches the echo mode on (1) or off (0). If n is explicitly given, set echo to n.

\g {n}

sets the debugging level debug to the non-negative integer n.

\gf {n}

sets the file usage debugging level debugfiles to the non-negative integer n.

\gm {n}

sets the memory debugging level debugmem to the non-negative integer n.

\h {m-n}

outputs some debugging info about the hashtable. If the argument is a number n, outputs the contents of cell n. Ranges can be given in the form m-n (from cell m to cell n, $ = last cell). If a function name is given instead of a number or range, outputs info on the internal structure of the hash cell this function occupies (a struct entree in C). If the range is reduced to a dash ('-'), outputs statistics about hash cell usage.

\l {logfile}

switches log mode on and off. If a logfile argument is given, change the default logfile name to logfile and switch log mode on.

\m

as \a, but using prettymatrix format.

\o {n}

sets output mode to n (0: raw, 1: prettymatrix, 2: prettyprint, 3: external prettyprint).

\p {n}

sets realprecision to n decimal digits. Prints its current value if n is omitted.

\ps {n}

sets seriesprecision to n significant terms. Prints its current value if n is omitted.

\q

quits the gp session and returns to the system. Shortcut for the function quit (see Label se:quit).

\r {filename}

reads into gp all the commands contained in the named file as if they had been typed from the keyboard, one line after the other. Can be used in combination with the \w command (see below). Related but not equivalent to the function read (see Label se:read); in particular, if the file contains more than one line of input, there will be one history entry for each of them, whereas read would only record the last one. If filename is omitted, re-read the previously used input file (fails if no file has ever been successfully read in the current session). If a gp binary file (see Label se:writebin) is read using this command, it is silently loaded, without cluttering the history.

Assuming gp figures how to decompress files on your machine, this command accepts compressed files in compressed (.Z) or gzipped (.gz or .z) format. They will be uncompressed on the fly as gp reads them, without changing the files themselves.

\s

prints the state of the PARI stack and heap. This is used primarily as a debugging device for PARI.

\t

prints the internal longword format of all the PARI types. The detailed bit or byte format of the initial codeword(s) is explained in Chapter 4, but its knowledge is not necessary for a gp user.

\u

prints the definitions of all user-defined functions.

\um

prints the definitions of all user-defined member functions.

\v

prints the version number and implementation architecture (680x0, Sparc, Alpha, other) of the gp executable you are using. In library mode, you can use instead the two character strings PARIVERSION and PARIINFO, which correspond to the first two lines printed by gp just before the Copyright message.

\w {n} {filename}

writes the object number n ( %n ) into the named file, in raw format. If the number n is omitted, writes the latest computed object ( % ). If filename is omitted, appends to logfile (the GP function write is a trifle more powerful, as you can have arbitrary filenames).

\x

prints the complete tree with addresses and contents (in hexadecimal) of the internal representation of the latest computed object in gp. As for \s, this is used primarily as a debugging device for PARI, and the format should be self-explanatory (a * before an object -- typically a modulus -- means the corresponding component is out of stack). However, used on a PARI integer, it can be used as a decimal-->hexadecimal converter.

\y {n}

switches simplify on (1) or off (0). If n is explicitly given, set simplify to n.

#

switches the timer on or off.

##

prints the time taken by the latest computation. Useful when you forgot to turn on the timer.


The preferences file

This file, called gprc in the sequel, is used to modify or extend gp default behaviour, in all gp sessions: e.g customize default values or load common user functions and aliases. gp opens the gprc file and processes the commands in there, before doing anything else, e.g. creating the PARI stack. If the file does not exist or cannot be read, gp will proceed to the initialization phase at once, eventually emitting a prompt. If any explicit command line switches are given, they override the values read from the preferences file.

Syntax.

The syntax in the gprc file (and valid in this file only) is simple-minded, but should be sufficient for most purposes. The file is read line by line; as usual, white space is ignored unless surrounded by quotes and the standard multiline constructions using braces, \, or = are available (multiline comments between /* ... */ are also recognized).

Preprocessor: Two types of lines are first dealt with by a preprocessor
* comments are removed. This applies to all text surrounded by /* ... */ as well as to everything following \\ on a given line.

* lines starting with #if boolean are treated as comments if boolean evaluates to false, and read normally otherwise. The condition can be negated using either #if not (or #if !). If the rest of the current line is empty, the test applies to the next line (same behaviour as = under gp). Only three tests can be performed:

EMACS: true if gp is running in an Emacs or TeXmacs shell (see Label se:emacs).

READL: true if gp is compiled with readline support (see Label se:readline).

VERSION op number: where op is in the set { > , < , <= , >= }, and number is a PARI version number of the form Major.Minor.patch, where the last two components can be omitted (i.e. 1 is understood as versio 1.0.0). This is true if gp's version number satisfies the required inequality.

Commands: After the preprocessing the remaining lines are executed as sequence of expressions (as usual, separated by ; if necessary). Only two kinds of expressions are recognized
* default = value, where default is one of the available defaults (see Label se:defaults), which will be set to value on actual startup. Don't forget the quotes around strings (e.g. for prompt or help).

* read "some_GP_file" where some_GP_file is a regular GP script this time, which will be read just before gp prompts you for commands, but after initializing the defaults. In particular, file input is delayed until the gprc has been fully loaded. This is the right place to input files containing alias commands, or your favorite macros.

For instance you could set your prompt in the following portable way:

  \\ self modifying prompt looking like \rm(18:03) B<gp>C<E<gt> >
  prompt   = "(%H:%M) \e[1mgp\e[m > "
  \\ readline wants non-printing characters to be braced between ^A/^B pairs
  #if READL prompt = "(%H:%M) ^A\e[1m^Bgp^A\e[m^B > "
  \\ escape sequences not supported under emacs
  #if EMACS prompt = "(%H:%M) gp > "

Note that any of the last two lines could be broken in the following way

  #if EMACS
    prompt = "(%H:%M) gp > "

since the preprocessor directive applies to the next line if the current one is empty.

A sample gprc file called misc/gprc.dft is provided in the standard distribution. It is a good idea to have a look at it and customize it to your needs. Since this file does not use multiline constructs, here is one (note the terminating ; to separate the expressions):

  #if VERSION > 2.2.3
  {
    read "my_scripts";     \\ syntax errors in older versions
    new_galois_format = 1; \\ default introduced in 2.2.4
  }
  #if ! EMACS
  {
    colors = "9, 5, no, no, 4, 1, 2";
    help   = "gphelp -detex -ch 4 -cb 0 -cu 2";
  }

Where is it?

When gp is started, it looks for a customization file, or gprc in the following places (in this order, only the first one found will be loaded):

* On the Macintosh (only), gp looks in the directory which contains the gp executable itself for a file called gprc.

* gp checks whether the environment variable GPRC is set. Under DOS, you can set it in AUTOEXEC.BAT. On Unix, this can be done with something like:

  GPRC = /my/dir/anyname; export GPRC in sh syntax (for instance in your .profile),

  setenv GPRC /my/dir/anyname in csh syntax (in your .login or .cshrc file).

If so, the file named by $GPRC is the gprc.

* If GPRC is not set, and if the environment variable HOME is defined, gp then tries

$HOME/.gprc on a Unix system

HOME\_$gprc on a DOS, OS/2, or Windows system.

* If HOME also leaves us clueless, we try

~/.gprc on a Unix system (where as usual ~ stands for your home directory), or

\_$$gprc on a DOS, OS/2, or Windows system.

* Finally, if no gprc was found among the user files mentioned above we look for /etc/gprc (\etc\gprc) for a system-wide gprc file (you will need root privileges to set up such a file yourself).

Note that on Unix systems, the gprc's default name starts with a '.' and thus is hidden to regular ls commands; you need to type ls -a to list it.


Using GNU Emacs

If GNU Emacs is installed on your machine, it is possible to use gp as a subprocess in Emacs. To use this, you should include in your .emacs file the following lines:

  (autoload 'gp-mode "pari" nil t)
  (autoload 'gp-script-mode "pari" nil t)
  (autoload 'gp "pari" nil t)
  (autoload 'gpman "pari" nil t)
  (setq auto-mode-alist
    (cons '("\\.gp$" . gp-script-mode) auto-mode-alist))

which autoloads functions from pari.el. See also pariemacs.txt. These files are included in the PARI distribution and are installed at the same time as gp.

Once this is done, under GNU Emacs if you type M-x gp (where as usual M is the Meta key, i.e. Escape, or on SUN keyboards, the Left key), a special shell will be started, which in particular launches gp with the default stack size, prime limit and input buffer size. If you type instead C-u M-x gp, you will be asked for the name of the gp executable, the stack size and the prime limit before the execution of gp begins. If for any of these you simply type return, the default value will be used. On UNIX machines it will be the place you told Configure (usually /usr/local/bin/gp) for the executable, 10M for the stack and 500k for the prime limit.

You can then work as usual under gp, but with two notable advantages (which don't really matter if readline is available to you, see below). First and foremost, you have at your disposal all the facilities of a text editor like Emacs, in particular for correcting or copying blocks. Second, you can have an on-line help which is much more complete than what you obtain by typing ?name. This is done by typing M-?. In the minibuffer, Emacs asks what function you want to describe, and after your reply you obtain the description which is in the users manual, including the description of functions (such as \, %) which use special symbols.

This help system can also be menu-driven, by using the command M-\char`\c which opens a help menu window which enables you to choose the category of commands for which you want an explanation.

Nevertheless, if extended help is available on your system (see Label se:exthelp), you should use it instead of the above, since it's nicer (it ran through TeX) and understands many more keywords.

Finally you can use command completion in the following way. After the prompt, type the first few letters of the command, then < TAB > where < TAB > is the TAB key. If there exists a unique command starting with the letters you have typed, the command name will be completed. If not, either the list of commands starting with the letters you typed will be displayed in a separate window (which you can then kill by typing as usual C-x 1 or by typing in more letters), or ``no match found'' will be displayed in the Emacs command line. If your gp was linked with the readline library, read the section on completion in the section below (the paragraph on online help is not relevant).

Note that if for some reason the session crashes (due to a bug in your program or in the PARI system), you will usually stay under Emacs, but the gp buffer will be killed. To recover it, simply type again M-x gp (or C-u M-x gp), and a new session of gp will be started after the old one, so you can recover what you have typed. Note that this will of course not work if for some reason you kill Emacs and start a new session.

You also have at your disposal a few other commands and many possible customizations (colours, prompt). Read the file emacs/pariemacs.txt in standard distribution for details.


Using readline

Thanks to the initial help of Ilya Zakharevich, there is a possibility of line editing and command name completion outside of an Emacs buffer if you have compiled gp with the GNU readline library. If you do not have Emacs available, or cannot stand using it, we really advise you to make sure you get this very useful library before configuring or compiling gp. In fact, with readline, even line editing becomes more powerful outside an Emacs buffer!

A (too) short introduction to readline

The basics are as follows (read the readline user manual !), assume that C- stands for ``the Control key combined with another'' and the same for M- with the Meta key (generally C- combinations act on characters, while the M- ones operate on words). The Meta key might be called Alt on some keyboards, will display a black diamond on most others, and can safely be replaced by Esc in any case. Typing any ordinary key inserts text where the cursor stands, the arrow keys enabling you to move in the line. There are many more movement commands, which will be familiar to the Emacs user, for instance C-a/C-e will take you to the start/end of the line, M-b/M-f move the cursor backward/forward by a word, etc. Just press the < Return > key at any point to send your command to gp.

All the commands you type in are stored in a history (with multiline commands being saved as single concatenated lines). The Up and Down arrows (or C-p/C-n) will move you through it, M- < /M- > sending you to the start/end of the history. C-r/C-s will start an incremental backward/forward search. You can kill text (C-k kills till the end of line, M-d to the end of current word) which you can then yank back using the C-y key (M-y will rotate the kill-ring). C-_ will undo your last changes incrementally (M-r undoes all changes made to the current line). C-t and M-t will transpose the character (word) preceding the cursor and the one under the cursor.

Keeping the M- key down while you enter an integer (a minus sign meaning reverse behaviour) gives an argument to your next readline command (for instance M-- C-k will kill text back to the start of line). If you prefer Vi--style editing, M-C-j will toggle you to Vi mode.

Of course you can change all these default bindings. For that you need to create a file named .inputrc in your home directory. For instance (notice the embedding conditional in case you would want specific bindings for gp):

  C<if Pari-GP
    set show-all-if-ambiguous
    "\C-h": backward-delete-char
    "\e\C-h": backward-kill-word
    "\C-xd": dump-functions
    (: "\C-v()\C-b"       # can be annoying when copy-pasting !
    [: "\C-v[]\C-b"
  >endif

C-x C-r will re-read this init file, incorporating any changes made to it during the current session.

Note: By default, ( and [ are bound to the function pari-matched-insert which, if ``electric parentheses'' are enabled (default: off) will automatically insert the matching closure (respectively ) and ]). This behaviour can be toggled on and off by giving the numeric argument -2 to ( (M--2(), which is useful if you want, e.g to copy-paste some text into the calculator. If you do not want a toggle, you can use M--0 / M--1 to specifically switch it on or off).

Note: In some versions of readline (2.1 for instance), the Alt or Meta key can give funny results (output 8-bit accented characters for instance). If you do not want to fall back to the Esc combination, put the following two lines in your .inputrc:

    set convert-meta on
    set output-meta off

Command completion and online help.

As in the Emacs shell, < TAB > will complete words for you. But, under readline, this mechanism will be context-dependent: gp will strive to only give you meaningful completions in a given context (it will fail sometimes, but only under rare and restricted conditions).

For instance, shortly after a ~, we expect a user name, then a path to some file. Directly after default( has been typed, we would expect one of the default keywords. After whatnow( , we expect the name of an old function, which may well have disappeared from this version. After a '.', we expect a member keyword. And generally of course, we expect any GP symbol which may be found in the hashing lists: functions (both yours and GP's), and variables.

If, at any time, only one completion is meaningful, gp will provide it together with

* an ending comma if we are completing a default,

* a pair of parentheses if we are completing a function name. In that case hitting < TAB > again will provide the argument list as given by the online helpFOOTNOTE<<< recall that you can always undo the effect of the preceding keys by hitting C-_ >>>.

Otherwise, hitting < TAB > once more will give you the list of possible completions. Just experiment with this mechanism as often as possible, you will probably find it very convenient. For instance, you can obtain default(seriesprecision,10), just by hitting def < TAB > se < TAB > 10, which saves 18 keystrokes (out of 27).

Hitting M-h will give you the usual short online help concerning the word directly beneath the cursor, M-H will yield the extended help corresponding to the help default program (usually opens a dvi previewer, or runs a primitive tex-to-ASCII program). None of these disturb the line you were editing.