\chapter{Specific use of the {\bf \ref{GP}} calculator}

Originally, GP was designed as a debugging tool for the PARI system library,
and hence not much thought had been given to make it user-friendly. The
situation has now changed, and GP is very useful as a standalone
tool. Hence many new functionalities have been added.
The operations and functions available in PARI
and GP will be described  in the next chapter; in the present one we describe
the specific use of the GP programmable calculator.

GP (and in fact any program using the PARI library) needs a stack in which
to do its computations, and a table of primes, which may be very small.
The default stack size is 1000000 bytes on the Mac, and 4000000 on
other machines. The prime number limit is by default
200000 on the MacII, and 500000 on other machines. These defaults can be
changed by adding parameters to the input line. To start the
calculator, the general syntax is:

\centerline{\tt gp [-s stacksize] [-p primelimit] [-b buffersize]}

where as usual items within brackets are optional. The buffersize option is
to allow for overly large input files read into GP, for example large
matrices. The default is 30000, which is usually more than plenty.

(Note that on the Macintosh, even after clicking on the gp icon,
once in the MPW Shell, you still need to type explicitly the above command.
If you are uusing the standalone version SAGp, the limits are hardwired and
cannot be changed.)

If you have GNUemacs, it is strongly advised to work in a special emacs
shell (see section 3.12), which is started by typing {\tt M-x gp}
(where as usual {\tt M} is the Meta key) if you accept the default
stack, prime and buffer sizes, or {\tt C-u M-x gp} which will ask you for
the name of the gp executable, the stack size, the prime limit and the
buffersize. 
\smallskip
A copyright message then appears which includes the version
number. Please note this number, so as to be sure to have the most recent
version if you wish to have updates of PARI. The present manual is written
for version \vers, but only details will change (like new and faster functions,
less bugs, better output, etc\dots ) until the next major revision 2.00.

After the copyright, the computer works for a few seconds (it is in fact
computing and storing a table of primes), writes the top-level
help information, the initial defaults, and then waits after its
prompt, initially ``?''.

Note that at any point the user can type ``Ctrl-C'' in GP, and the
current computation is interrupted and control is given again to the user
at the GP prompt.

\section{Metacommands.}

The top-level help information tells you that (as in many systems), to
get help you should type a ``{\tt ?}''. When you do this, a menu appears,
describing the ten main categories of available functions and what to do
to get more precise help. If you now type ``{\tt ?n}'' with $1\le n\le11$
you will get the list of commands corresponding to category $n$ and
simultaneously to Section $3.n$ of this manual. 

If you type ``{\tt ?functionname}'' where {\tt functionname} is the
name of a PARI function, you will get a short explanation about this
function.

Finally, if you type ``{\tt ?$\backslash$}'' you will get a short
description of the metacommands. In the rest of this section, we will
describe these commands in more detail.

As a general rule, under GP, commands starting with ``$\backslash$'' and some
other symbols like ``?'', are not computing commands, but are metacommands
which correspond to information exchange with GP. The available commands of 
this sort can be divided among simple commands (explained here) and default
setting commands (explained in the next section).

Simple commands are case insensitive. For example, $\backslash$Q is identical 
to $\backslash$q.

\subsec{$\backslash\backslash$}: comment. The rest of the line
is ignored by GP.

\subsec{$\backslash${\bf a}}$n$: print the object number $n$ ($\%n$)
in raw format. If the number $n$ is omitted, print the latest computed object
( $\%$ ).

\subsec{$\backslash${\bf b}}$n$: print the object number $n$ ($\%n$)
in prettyprint (i.e. beautified) format. If the number $n$ is omitted,
print the latest computed object ( $\%$ ).

\subsec{$\backslash${\bf c}}: prints the list of all available functions
\sref{available commands}
under GP, not including functions using a special character (specifically
$+$ , $-$ , $*$ , $/$, $\backslash$ , $\hat{\ }$ , $!$ , $\tilde{\ }$ ,
$\_$ , $\%$ , $\&$, $|$). These names being in general not
informative enough, more information can be obtained by typing
``{\bf ?}command'', which gives in short form the effect of the command
and the name and syntax of the corresponding library function.
Of course, to have complete information, read chapter 3 of this
manual. Much better help can be obtained if you work under GNUemacs
(see section 3.12). As already mentioned, if you type ``{\bf ?}n''
where $n$ is a number from 1 to 11, you will only get the list of
functions in section $3.n$ of the manual (the list of sections
being obtained by simply typing ``{\bf ?}'').

\subsec{$\backslash${\bf d}}: prints the \ref{defaults} (see the next
section), including the stacksize, primelimit and buffersize. This
command is always executed (without user intervention), when GP is started.

\subsec{$\backslash${\bf e}}: switches the echo mode on and off (the default
is off). When echo mode is on, the command is reprinted before being executed.
This can be useful when reading a file by the $\backslash$r command. It is
for example the first command of the test file {\tt testin} used to check
the correctness of GP installation.

\subsec{$\backslash${\bf g}}$n$: set the debugging level equal to the positive
integer $n$. The default is $n=0$. If the debugging level is nonzero, some
messages may be printed (in French) according to what is going on. 

\subsec{$\backslash${\bf k}}: kill and reinitialize GP. Apart from the
initial message, this is equivalent to exiting from GP and starting it again,
apart from the fact that the variables which have been used are still known
to GP. 

{\bf Warning.} In the present version \vers, do not use this command
after a stack doubling has occured. In this case, if you really want to kill
the session, simply finish the session and restart.

\subsec{$\backslash${\bf l}}: switch the logfile on/off. Initially, the GP
session does not have a log file where all the commands and results are stored.
Typing $\backslash$l will open a file named {\tt pari.log} (and destroy any
previous file with that name), and until a subsequent $\backslash$l, all the
commands and results will be written in that file.

\subsec{$\backslash${\bf m}}: print the object number $n$ ($\%n$)
in prettymatrix format. If the number $n$ is omitted, print the latest
computed object ( $\%$ ).

\subsec{$\backslash${\bf p}}: changes the default format from raw
\sref{raw format} to prettymatrix\sref{prettymatrix format} to
prettyprint (i.e. beautified)\sref{prettyprint format} to raw format.

\subsec{$\backslash${\bf q}}: \ref{quit}s GP and returns to the system.

\subsec{$\backslash${\bf r}} filename: \ref{read}s into GP all the objects written
 on the named file using the $\backslash$w command (see 2.1.13.).

\subsec{$\backslash${\bf s}}: prints the state of the PARI \ref{stack}, and
in
particular the amount of memory used, expressed as a percentage. This enables
the user to see whether the stack is getting too full.

\subsec{$\backslash${\bf s}$(n)$}: prints the state of the PARI
stack,
and in addition the explicit \ref{hexadecimal representation}s of the first $n$
longwords of the stack (going down) if $n$ is positive, and the complete
stack
if $n$ is negative. This is used primarily as a debugging device for PARI,
and is not intended for the casual user.

\subsec{$\backslash${\bf t}}: prints the \ref{internal longword format}
of all the PARI types. The detailed bit or byte format of the initial
codeword(s) is explained in the technical reference manual, but its knowledge
is not necessary for a GP user.

\subsec{$\backslash${\bf v}}: prints the \ref{version number} type of
implementation (680x0, sparc, other) of the program you are using. Note
that the subversion may be omitted (e.g. 1.37 instead of 1.37.3).

\subsec{$\backslash${\bf w}}$n$ filename: \ref{write} the object number $n$
( $\%n$ ) on the named file, in raw format. If the number $n$ is omitted,
write the latest computed object ( $\%$ ).

\subsec{$\backslash${\bf x}}: print the complete tree with
addresses and contents in hexadecimal, of the \ref{internal representation} of
the latest computed object in GP. As for $\backslash$s, this is used primarily
as a debugging device for PARI, and is not intended for the casual user.
However, used on a PARI integer, it can be used as a 
decimal$\rightarrow$hexadecimal converter.

\subsec{$\backslash${\bf y}}: switches the \ref{automatic simplification}
feature on or off. When the Pari library makes a computation, 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 4 and equal to integers), and similarly rational functions
to polynomials (when they are of type 13 and equal to polynomials). This
feature is useful in many cases, and saves time, but can be often annoying
in practice. Hence there exists the function {\tt simplify} (see Chapter 3)
which allows to simplify to the simplest possible types recursively.

When automatic simplification is on, the function {\tt simplify} is called
at the end of any GP computation, so that all printed results are simplified.
However, the intermediate results will not be simplified otherwise the loss
of time would be too large. By default, automatic simplification is turned
on. 

\subsec{\#}: switches the \ref{timer} on or off. The timer counts electrical
cycles, so is precise only to $\pm20$ms in Europe and $\pm16.7$ms in North 
America. The time measured is the user \ref{CPU time}, {\it not} including the
time for printing. By default, when GP is launched, the timer is switched off.

\section{Defaults and \ref{output formats}.}

The other commands starting with ``$\backslash$'' are for setting the
defaults.
Note that in the syntax given below, the ``='' sign must be written
explicitly, and $n$ represents a non negative integer.

\subsec{$\backslash$\ref{precision}}$=n$:
Sets to $n$ the number of significant digits, and at the same time the
number of printed digits of real numbers. The initial default is 28.
Note that one can also use the function {\tt setprecision} (see chapter 3)
to achieve the same goal, and this {\sl must} be done if it is inside a
GP expression or program.

\subsec{$\backslash$\ref{serieslength}}$=n$:
Sets to $n$ the number of significant terms in power series. The initial
default is 16. Note that one can also use the function {\tt setserieslength}
(see chapter 3) to achieve the same goal, and this {\sl must} be done if it 
is inside a GP expression or program.

\subsec{$\backslash$\ref{format}}=x$n.m$ (where x is a letter): if the letter
is ``f'', real
numbers will be printed in \ref{fixed floating point format} with no explicit
exponent (e.g. 0.000033); if the letter is ``e'', they will be printed
in \ref{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}$, in which case
they are printed in ``e'' format. The initial default is ``g''.

The number $n$ is the number of significant digits printed for real numbers
except if $n\le0$ where all the significant digits will be printed
(initial default 28), and the number $m$ is the number of characters to be
used for printing integers, but is ignored if is equal to zero (initial
default 0). This is a feeble attempt at formatting.

\subsec{$\backslash$\ref{prompt}}=string:
Sets the prompt equal to the given string. The initial default is ``?''.

\subsec{Raw, prettymatrix and beautified format}: in addition to the default
formats which can be set as explained above, you can print results in three 
ways. Either in ``raw''\sref{raw format} 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 put it
somewhere else.

The second format is the ``prettymatrix''\sref{prettymatrix format}. The only
difference with the 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. This is the default.

The third format is the ``prettyprint''\sref{prettyprint format} or beautified
format. In the present version \vers, this is not beautiful at all. The command
$\backslash p$ is used to navigate between these formats as explained above,
and independently of the default format, an object can be printed in any of the
three formats using the commands $\backslash a$, $\backslash m$ and 
$\backslash b$ respectively.

\subsec{Note on the output formats.}

A zero real number is printed in ``e'' format as $0.Exx$ where $xx$ is the
(usually negative) {\it decimal\/} exponent of the number (cf. 1.2.6.).
This allows the user to check the accuracy of the zero in question
(this could also be done using $\backslash$x, but it would be more technical).

When the integer part of a real number $x$ is not significant because the
exponent of $x$ is greater than the internal precision, an approximation to
the integer part is printed, followed by a ``$*$'' instead of a
decimal point, indicating \ref{corrupt digits} on the left.

Note also that a number of type integer or real is written without
enclosing parentheses, while most other types have them. Hence, if you see
printed the expression $( 3.14 )$, it is not of type real, but probably of
type complex with zero imaginary part (if you want to be sure, type
$\backslash$x).

Finally note that in the present version \vers, the printing of 0, 1, and
-1 as coefficients in beautified format, although understandable, is buggy.
Hence the default is the raw format until this is improved.

\section{Input formats for the PARI types.}

Apart from commands, the general input in GP after the prompt is a sequence of legal
expressions. Before describing this in detail in the next section, let us see
here how to input the different types of PARI.

Note that blanks are ignored in an expression.

\subsec{\ref{Integer}s} (type 1): type the integer (with an initial
$+$ or $-$ if desired) with no decimal point.

\subsec{\ref{Real number}s} (type 2): type the number with a decimal
point. The internal precision of the real number will be the supremum of the
input precision and the default precision. For example, if the default
precision is 28 digits, typing 2. will give a number with internal precision
28, but typing a 45 significant digit real number will give 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''
(like 6.02 E 23 or 1e-5).

\subsec{\ref{Integermod}s} (type 3): to enter $n \mod m$, type
$\text{mod} ( n, m )$, not $n\% m$ (see 3.2.15.).

\subsec{\ref{Rational number}s} (types 4 and 5): under GP, all
fractions are automatically reduced to lowest terms, so it is not possible
to enter a non-irreducible fraction (type 5), although of course in
library mode this is easy. To enter $n/m$ just type it as written.
As explained in section 3.1.4., division will {\sl not} be performed, only
reduction to lowest terms.

\subsec{\ref{Complex number}s} (type 6): to enter $x+iy$, type
$x+I*y$ or $x+i*y$. The letters $I$ and $\ref{i}$ stand for $\sqrt{-1}$. Recall
from chapter 1 that $x$ and $y$ can be of type integer, real, integermod
fraction, or $p$-adic.

\subsec{$p$-adic numbers}\sref{p-adic number} (type 7): to enter a $p$-adic number,
simply write a rational or integer expression and add to it $O(p\hat{\ }k)$,
where
$p$ and $k$ are integers. This last expression indicates three things to GP:
first that it is dealing with a $p$-adic (the fact that $p$ is an integer),
second the ``prime'' $p$ (note that no verification is done that $p$ is
indeed prime; you can work on 10-adics if you want, but beware of disasters
as soon as you do something non trivial like taking a square root), and
finally the number of significant $p$-adic digits $k$.

For example, to obtain the $7$-adic number
$$2*7\hat{\ }(-1)+3+4*7+2*7\hat{\ }2+O(7\hat{\ }3),$$ you can type it
exactly as shown, or equivalently as $$905/7+O(7\hat{\ }3).$$

\subsec{\ref{Quadratic number}s} (type 8): first, you must define the default
quadratic order or field in which you want to work. This is done using the
{\tt \ref{quadgen}} function, in the following way. Write something like

\centerline{\tt w=quadgen(d)}

where {\tt d} is the {\sl discriminant} of the quadratic order in which you
want to work (hence $d\equiv 0{\rm\ or\ }1\mod 4$). The name {\tt w} is of course
just a suggestion, but corresponds to traditional usage. You can of course use
any variable name that you like.
However, quadratic numbers are always printed with a {\tt 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.

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

\subsec{\ref{Polymod}s} (type 9): exactly as for integermods,
to enter $x \mod y$ (where $x$ and $y$ are polynomials), type
$\text{mod} ( x, y )$, not $x\% y$ (see 3.2.12.). Note that when $y$ is an
irreducible polynomial in one variable, polymods whose modulus is $y$ are 
simply algebraic numbers in the finite extension defined by the polynomial $y$.
This allows us to work easily in \ref{number field}s, finite extensions of 
the $p$-adic field $\Bbb Q_p$, or \ref{finite field}s.

{\bf Important remark.} Since the variables occurring in a polymod are not
free variables, it is essential in order to avoid inconsistencies, that
all polymods have the same structure, i.e. the main variable will be number 0,
the next number 1, etc\dots. In other words, since 0 is the variable number
of ``X'', do {\bf not} use expressions like {\tt mod(Y,Y\^{}2+1)} since PARI 
will not recognize that this is identical to {\tt mod(X,X\^{}2+1)}. Another 
consequence is that an operation like {\tt X+mod(X,X\^{}2+1)} gives exactly 
the same thing as a result (meaning $X+i$ where $i^2=-1$), and not 
{\tt mod(2*X,X\^{}2+1)}.

\subsec{\ref{Polynomial}s} (type 10): type the polynomial in a natural
way, not forgetting to put a ``$*$'' between a coefficient and a formal
variable (this $*$ does not appear on beautified output). Any variable name can be used
except for the reserved names {\tt i} (used exclusively for the square root
of $-1$), {\tt pi} ($3.14\dots$) and {\tt euler} (Euler's constant).
The total number of different variable names is limited to $256$, which
should be enough. If you ever need
hundreds of variables, you should probably use vectors instead.

\subsec{\ref{Power series}} (type 11): type a rational function or
polynomial expression and add to it $O(expr\hat{\ }k)$, where $expr$ is an
expression
having a non zero valuation, like a polynomial, power series, or a
rational function (the most common cases being simply $expr=$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 its main variable
(to check the order of the variables, or to modify it, use the function
{\tt reorder} see 3.11.4.6).

\subsec{\ref{Rational function}s} (types 13 and 14): under GP, all
fractions are automatically reduced to lowest terms, so it is not possible
to enter a non-irreducible rational function (type 14), although of course in
library mode this is easy. To enter $x/y$ just type it as written.
As explained in section 3.1.4., division will {\sl not} be performed, only
reduction to lowest terms.

\subsec{\ref{Binary quadratic form}s of positive discriminant} (type 15):
enter a 4-component (row or column) vector, and transform it into a binary
quadratic form using the function {\tt qfr} (see 3.4.45). The fourth component
(which is related to the regulator, more precisely to Shanks' ``distance'')
must be a real number. See also the function {\tt pf} which directly creates
a prime form of given discriminant (see 3.4.37).

\subsec{\ref{Binary quadratic form}s of negative discriminant} (type 16):
enter a 3-component (row or column) vector, and transform it into a binary
quadratic form using the function {\tt qfi} (see 3.4.44). See also the
function {\tt pf} which directly creates a prime form of given discriminant
(see 3.4.37).

\subsec{Row and column vectors} 
\sref{Row vector}\sref{Column vector}
(types 17 and 18):
to enter a row vector, type the components separated by commas ``,'',
and enclosed between brackets ``['' and ``]'', e.g. $[x,y,z]$.
To enter a column vector, type the vector horizontally, and add a tilde
``$\tilde{\ }$'' to transpose.

\subsec{Matrices} (type 19):\sref{Matrix} 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]$.

Note that although the internal representation is essentially the same,
(only the type number being different), a row vector of column vectors is
{\sl not} a matrix; for example, multiplication will not work in the same way.
To transform it into a matrix, use the function {\tt mat} (see 3.8.38).

\section{The general GP input line.}

A general GP session goes as follows: a sequence of characters is typed by the
user after the prompt. This can be either a function definition, or an
expression or a sequence of expressions (i.e. a program). In this case, after
the last expression is computed the result is
put in an internal array. The successive elements of this array are called
$\%1$, $\%2$, \dots under GP, and they can also be used in library mode with the names 
{\tt g[1], g[2], \dots}\sref{g[]} In this case, the array is not automatically filled for you.
As a shortcut, the last computed expression can also be called $\%$.

If you want to suppress the printing of the result, for example because it is
a long unimportant intermediate result, end the expression with a ``;'' sign.
This same sign is used as an instruction separator when several instructions
are written on the same line (note that the ``:'' sign can also be used, but
we will try to keep C-style conventions).
Note that the last expression you have computed, even if not printed,
still has the name ($\%1$, $\%2$, \dots) so care must be used when using it
subsequently since its number does not appear explicitly. Of course, if it
is simply used on the next line, use $\%$ as usual.

Any legal expressions can be typed, and it is evaluated using the usual
conventions about operator priorities and left to right evaluation
(including raising to a power), using the available operator
symbols, function names (including user-defined functions), and special
variables. Please note that in general there\sref{case distinction}
is no distinction between lowercase. and uppercase
Also, note that blanks are completely ignored in the input to GP.

The special variable names used by GP are {\tt \ref{euler}} (Euler's
constant=0.577\dots), {\tt \ref{i}} (the square root of $-1$),
{\tt \ref{pi}} (3.14\dots), which are really functions without parameters, and {\tt \ref{O}} whose syntax is the following:

{\tt O}$(expr\hat{\ }k)$

When $expr$ is an integer or a
rational number, creates a $expr$-adic number (zero in fact) of precision $k$.
When $expr$ is a polynomial, a power series or a rational function whose main
variable is $X$, say, this creates
a power series (also zero) of precision $v*k$ where $v$ is the
$X$-adic valuation of $expr$ (see 2.3.6 and 2.3.9.).

Note: as usual, lowercase {\bf o} is allowed, but we do not
advise to use it since it has a different mathematical meaning.

\vfill\eject