[BACK]Return to usersch4.tex CVS log [TXT][DIR] Up to [local] / OpenXM_contrib / pari / doc

Annotation of OpenXM_contrib/pari/doc/usersch4.tex, Revision 1.1.1.1

1.1       maekawa     1: \chapter{Programming PARI in Library Mode}
                      2:
                      3: \section{Introduction: initializations, universal objects}
                      4: \label{se:intro4}
                      5:
                      6: \noindent
                      7: To be able to use PARI in \idx{library mode}, you must write a C program and
                      8: link it to the PARI library. See the installation guide (in Appendix~A)
                      9: on how to create and install the library and include files. A sample Makefile
                     10: is presented in Appendix~B.
                     11:
                     12: Probably the best way to understand how programming is done is to work
                     13: through a complete example. We will write such a program in
                     14: \secref{se:prog}. Before doing this, a few explanations are in order.
                     15:
                     16: First, one must explain to the outside world what kind of objects and
                     17: routines we are going to use. This is done simply with the statement
                     18:
                     19: \bprog%
                     20: \#include <pari.h>
                     21: \eprog
                     22: \noindent
                     23: This file \tet{pari.h} imports all the necessary constants,
                     24: variables and functions, defines some important macros, and also defines the
                     25: fundamental type for all PARI objects: the type \teb{GEN}, which is
                     26: simply a pointer to \kbd{long}.
                     27:
                     28: \misctitle{Technical note}: we would have liked to define a type \kbd{GEN}
                     29: to be a pointer to itself. This unfortunately is not possible in C, except by
                     30: using structures, but then the names become unwieldy. The result of this is
                     31: that when we use a component of a PARI object, it will be a \kbd{long},
                     32: hence will need to be typecast to a \kbd{GEN} again if we want to avoid
                     33: warnings from the compiler. This will sometimes be quite tedious, but of
                     34: course is trivially done. See the discussion on typecasts in the next
                     35: section.
                     36:
                     37: After declaring the use of the file \kbd{pari.h}, the first executable
                     38: statement of a main program should be to initialize the PARI system, and in
                     39: particular the PARI stack which will be both a scratchboard and a repository
                     40: for computed objects. This is done with a call to the function%
                     41: \sidx{pari\string\_init}
                     42:
                     43: \kbd{void \key{pari\_init}(long size, long maxprime)}.
                     44:
                     45: \noindent The first argument is the number of bytes given to PARI to work
                     46: with (it should not reasonably be taken below 500000), and the second is the
                     47: upper limit on a precomputed prime number table. If you don't want prime
                     48: numbers, just put $\kbd{maxprime} = 2$. Be careful because lots a PARI
                     49: functions need this table (certainly all the ones of interest to number
                     50: theorists). If you wind up with the error message ``not enough precomputed
                     51: primes'', try to increase this value.
                     52:
                     53: \noindent We have now at our disposal:
                     54:
                     55: $\bullet$ a large PARI {\it \idx{stack}\/} containing nothing. It's a big
                     56: connected chunk of memory whose size you chose when invoking
                     57: \kbd{pari\_init}. All your computations are going to take place here.
                     58: When doing large computations, unwanted intermediate results clutter up
                     59: memory very fast so some kind of garbage collecting is needed. Most large
                     60: systems do garbage collecting when the memory is getting scarce, and this slows
                     61: down the performance. In PARI we have taken a different approach: you must do
                     62: your own cleaning up when the intermediate results are not needed anymore.
                     63: Special purpose routines have been written to do this; we will see later how
                     64: (and when, if at all) you should use them.
                     65:
                     66: $\bullet$ the following {\it universal objects\/} (by definition, objects
                     67: which do not belong on the stack): the integers 0, 1 and 2 (respectively
                     68: called \teb{gzero}, \teb{gun}, and \teb{gdeux}), the
                     69: fraction $\dfrac{1}{2}$ (\teb{ghalf}), the complex number $i$
                     70: (\teb{gi}). All of these are of type \kbd{GEN}.
                     71:
                     72: In addition, space is reserved for the polynomials $x_v$
                     73: \sidx{variable}
                     74: (\kbd{\teb{polx}[$v$]}), and the polynomials $1_v$ (\kbd{\teb{polun}[$v$]}).
                     75: Here, $x_v$ is the name of variable number $v$, where $0\le v\le
                     76: \kbd{\idx{MAXVARN}}$ (the exact value of which depends on your machine, at
                     77: least 16383 in any case). Both \kbd{polun} and \kbd{polx} are arrays of
                     78: \kbd{GEN}s, the index being the polynomial variable number.
                     79:
                     80: However, except for the ones corresponding to variables $0$ and \kbd{MAXVARN},
                     81: these polynomials are {\it not\/} created upon initialization. It
                     82: is the programmer's responsibility to fill them before use. We'll see how
                     83: this is done in \secref{se:vars} ({\it never\/} through direct assignment).
                     84:
                     85: $\bullet$ a {\it \idx{heap}\/} which is just a linked list of permanent
                     86: universal objects. For now, it contains exactly the ones listed above. You
                     87: will probably very rarely use the heap yourself; and if so, only as a
                     88: collection of individual copies of objects taken from the stack
                     89: (called \idx{clone}s in the sequel). Thus you need not bother with its
                     90: internal structure, which may change as PARI evolves. Some complex PARI
                     91: functions may create clones for special garbage collecting purposes, usually
                     92: destroying them when returning.
                     93:
                     94: $\bullet$ a table of primes (in fact of {\it differences\/} between
                     95: consecutive primes), called \teb{diffptr}, of type \kbd{byteptr}
                     96: (pointer to \kbd{unsigned char}). Its use is described in appendix~C.
                     97:
                     98: $\bullet$ access to all the built-in functions of the PARI library.
                     99: These are declared to the outside world when you include \kbd{pari.h}, but
                    100: need the above things to function properly. So if you forget the call to
                    101: \kbd{pari\_init}, you will immediately get a fatal error when running your
                    102: program (usually a segmentation fault).
                    103:
                    104: \section{Important technical notes}
                    105:
                    106: \subsec{Typecasts}.\label{se:typecast}\sidx{typecast}
                    107:
                    108: \noindent
                    109: We have seen that, due to the non-recursiveness of the PARI types from the
                    110: compiler's point of view, many typecasts will be necessary when programming
                    111: in PARI. To take an example, a vector $V$ of dimension 2 (two components)
                    112: will be represented by a chunk of memory pointed to by the \kbd{GEN}~\kbd{V}.
                    113: \kbd{V[0]} contains coded information, in particular about the type of the
                    114: object, its length, etc. \kbd{V[1]} and \kbd{V[2]} contain pointers to
                    115: the two components of \kbd{V}. Those coefficients \kbd{V[i]} themselves are in
                    116: chunks of memory whose complexity depends on their own types, and so on. This
                    117: is where typecasting will be necessary: a priori, \kbd{V[i]} (for
                    118: $\kbd{i}=1,2$) is a \kbd{long}, but we will want to use it as a \kbd{GEN}.
                    119: The following two constructions will be exceedingly frequent (\kbd{x} and
                    120: \kbd{V} are \kbd{GEN}s):
                    121: %
                    122: \bprog%
                    123:   V[i] = (long) x;
                    124:   x = (GEN) V[i];
                    125: \eprog
                    126: \noindent Note that a typecast is not a valid lvalue (cannot be put on the
                    127: left side of an assignment), so \kbd{(GEN)V[i] = x} would be incorrect, though
                    128: some compilers may accept it.
                    129:
                    130: Due to this annoyance, the PARI functions and variables that occur most
                    131: frequently have analogues which are macros including the typecast. The complete
                    132: list can be found in the file \kbd{paricast.h} (which is included by
                    133: \kbd{pari.h} and can be found at the same place). For instance you can
                    134: abbreviate:
                    135: %
                    136: \bprogtabs\+
                    137: -----------------&--------&
                    138: \cr\+
                    139: (long) gzero  & -----> &\idx{zero}
                    140: \cr\+
                    141: (long) gun    & -----> &\idx{un}
                    142: \cr\+
                    143: (long) polx[v]& -----> &\idx{lpolx}[v]
                    144: \cr\+
                    145: (long) gadd(x,y)& -----> &\idx{ladd(x,y)}
                    146: \cr\eprog
                    147: \noindent
                    148: In general, replacing a leading \kbd{g} by an \kbd{l} in the name of a PARI
                    149: function will typecast the result to \kbd{long}. Note that \kbd{ldiv} is an
                    150: ANSI C function which is is hidden in PARI by a macro of the same name
                    151: representing \kbd{(long)gdiv}.
                    152:
                    153: The macro $\teb{coeff}(x,m,n)$ exists with exactly the meaning of \kbd{x[m,n]}
                    154: under GP when \kbd{x} is a matrix. This is a purely syntactical trick
                    155: to reduce the number of typecasts and thus does not create a copy of the
                    156: coefficient (contrary to all the library {\it functions\/}). It can be put on
                    157: the left side of an assignment statement, and its value, of type \kbd{long}
                    158: integer, is a pointer to the desired coefficient object. The macro
                    159: \kbd{gcoeff} is a synonym for \kbd{(GEN) coeff}, hence cannot be put on
                    160: the left side of an assignment.
                    161:
                    162: To retrieve the values of elements of lists of \dots\ of
                    163: lists of vectors, without getting infuriated by gigantic lists of typecasts,
                    164: we have the \teb{mael} macros (for {\bf m}ultidimensional {\bf a}rray {\bf
                    165: el}ement). The syntax is $\key{mael}n(x,a_1,\dots,a_n)$, where $x$ is a
                    166: \kbd{GEN}, the $a_i$ are indexes, and $n$ is an integer between $2$ and $5$
                    167: (with a standalone \kbd{mael} as a synonym for \kbd{mael2}). This stands
                    168: for $x[a_1][a_2]\dots[a_n]$ (with all the necessary typecasts), and returns a
                    169: \kbd{long} (i.e.~they are valid lvalues). The $\kbd{gmael}n$ macros are
                    170: synonyms for $\kbd{(GEN) mael}n$. Note that due to the implementation of matrix
                    171: types in PARI (i.e.~as horizontal lists of vertical vectors), \kbd{coeff(x,y)}
                    172: is actually completely equivalent to \kbd{mael(y,x)}. It is suggested that
                    173: you use \kbd{coeff} in matrix context, and \kbd{mael} otherwise.
                    174:
                    175: \subsec{Variations on basic functions}.\label{se:low_level} In the library
                    176: syntax descriptions in Chapter~3, we have only given the basic names of the
                    177: functions. For example \kbd{gadd}$(x,y)$ assumes that $x$ and $y$ are PARI
                    178: objects (of type \kbd{GEN}), and {\it creates\/} the result $x+y$ on the PARI
                    179: stack. For most of the basic operators and functions, many other variants
                    180: are available. We give some examples for \kbd{gadd}, but the same is true for
                    181: all the basic operators, as well as for some simple common functions (the
                    182: complete list is given in Chapter~5):
                    183:
                    184: \kbd{GEN \teb{gaddgs}(GEN x, long y)}
                    185:
                    186: \kbd{GEN \teb{gaddsg}(long x, GEN y)}
                    187:
                    188: \noindent In the following three, \kbd{z} is a preexisting \kbd{GEN} and the
                    189: result of the corresponding operation is put into~\kbd{z}. The size of the PARI
                    190: stack does not change:
                    191:
                    192: \kbd{void \teb{gaddz}(GEN x, GEN y, GEN z)}
                    193:
                    194: \kbd{void \teb{gaddgsz}(GEN x, long y, GEN z)}
                    195:
                    196: \kbd{void \teb{gaddsgz}(GEN x, GEN y, GEN z)}
                    197:
                    198: \noindent There are also low level functions which are special cases of the
                    199: above:
                    200:
                    201: \kbd{GEN \teb{addii}(GEN x, GEN y)}: here $x$ and $y$ are \kbd{GEN}s of type
                    202: \typ{INT} (this is not checked).
                    203:
                    204: \kbd{GEN \teb{addrr}(GEN x, GEN y)}: here $x$ and $y$ are \kbd{GEN} reals
                    205: (type \typ{REAL}).
                    206:
                    207: \noindent
                    208: There also exist functions \teb{addir}, \teb{addri}, \teb{mpadd} (whose
                    209: two arguments can be of type integer or real), \teb{addis} (to add a \typ{INT}
                    210: and a \kbd{long}) and so on.
                    211:
                    212: All these functions can of course be called by the user but we feel that
                    213: the few microseconds lost in calling more general functions (in this case
                    214: \kbd{gadd}) are compensated by the fact that one needs to remember a much
                    215: smaller number of functions, and also because there is a hidden danger here:
                    216: the types of the objects that you use, if they are themselves results of a
                    217: previous computation, are not completely predetermined. For instance the
                    218: multiplication of a type real \typ{REAL} by a type integer \typ{INT}
                    219: {\it usually\/} gives a result of type real, except when the integer is~0, in
                    220: which case according to the PARI philosophy the result is the exact integer~0.
                    221: Hence if afterwards you call a function which specifically needs a real
                    222: type argument, you are going to be in trouble.
                    223:
                    224: If you really want to use these functions, their names are self-explanatory
                    225: once you know that {\bf i} stands for a PARI integer, {\bf r} for a PARI
                    226: real, {\bf mp} for i or r, {\bf s} for an ordinary signed long, whereas {\bf
                    227: z} (as a suffix) means that the result is not created on the PARI
                    228: stack but assigned to a preexisting GEN object passed as an extra argument.
                    229:
                    230: For completeness, Chapter 5 gives a description of all these
                    231: low-level functions.
                    232:
                    233: Please note that in the present version \vers{} the names of the functions
                    234: are not always consistent. This will be changed. Hence anyone programming in
                    235: PARI must be aware that the names of almost all functions that he uses might
                    236: be subject to change. If the need arises (i.e.~if there really are people out
                    237: there who delve into the innards of PARI), updated versions with no name
                    238: changes will be released.
                    239:
                    240: \subsec{Portability: 32-bit / 64-bit architectures}.
                    241:
                    242: \noindent
                    243: PARI supports both 32-bit and 64-bit based machines, but not simultaneously!
                    244: The library will have been compiled assuming a given architecture (a~priori
                    245: following a guess by the \kbd{Configure} program, see Appendix~A), and some
                    246: of the header files you include (through \kbd{pari.h}) will have been modified
                    247: to match the library.
                    248:
                    249: Portable macros are defined to bypass most machine dependencies. If you
                    250: want your programs to run identically on 32-bit and 64-bit machines, you will
                    251: have to use these, and not the corresponding numeric values, whenever the
                    252: precise size of your \kbd{long} integers might matter. Here are the most
                    253: important ones:
                    254:
                    255: \bprogtabs\+
                    256: ------------------&----------&------------&\cr
                    257: \+
                    258:                 & {\rm 64-bit} & {\rm 32-bit}
                    259: \cr\+
                    260: BITS\_IN\_LONG  & 64 & 32
                    261: \cr\+
                    262: LONG\_IS\_64BIT & {\rm defined} & {\rm undefined}
                    263: \cr\+
                    264: DEFAULTPREC     & 3 & 4 & {\rm ($\approx$ 19 decimal digits, %
                    265:  see formula below)}
                    266: \cr\+
                    267: MEDDEFAULTPREC  & 4 & 6 & {\rm ($\approx$ 38 decimal digits)}
                    268: \cr\+
                    269: BIGDEFAULTPREC  & 5 & 8 & {\rm ($\approx$ 57 decimal digits)}
                    270: \cr
                    271: \eprog
                    272: \sidx{DEFAULTPREC}
                    273: \sidx{MEDDEFAULTPREC}
                    274: \sidx{BIGDEFAULTPREC}
                    275: \sidx{LONG\string\_IS\string\_64BIT}
                    276: \sidx{BITS\string\_IN\string\_LONG}
                    277:
                    278: \noindent
                    279: For instance, suppose you call a transcendental function, such as
                    280:
                    281: \kbd{GEN \key{gexp}(GEN x, long prec)}.
                    282:
                    283: \noindent The last argument \kbd{prec} is only used if \kbd{x} is an exact
                    284: object (otherwise the relative precision is determined by the precision
                    285: of~\kbd{x}). But since \kbd{prec} sets the size of the inexact result counted
                    286: in (\kbd{long}) {\it words\/} (including codewords), the same value of
                    287: \kbd{prec} will yield different results on 32-bit and 64-bit machines. Real
                    288: numbers have two codewords (see~\secref{se:impl}), so the formula for
                    289: computing the bit accuracy is\sidx{bit\string\_accuracy}
                    290: $$ \kbd{bit\_accuracy}(\kbd{prec}) = (\kbd{prec} - 2) * \kbd{BITS\_IN\_LONG}$$
                    291: (this is actually the definition of a macro). The corresponding accuracy
                    292: expressed in decimal digits would be
                    293: %
                    294: $$ \kbd{bit\_accuracy(prec)} * \log(2) / \log(10).$$
                    295: %
                    296: For example if the value of \kbd{prec} is 5, the corresponding accuracy for
                    297: 32-bit machines is $(5-2)*\log(2^{32})/\log(10)\approx 28$ decimal digits,
                    298: while for 64-bit machines it is $(5-2)*\log(2^{64})/\log(10)\approx 57$
                    299: decimal digits.
                    300:
                    301: Thus, you must take care to change the \kbd{prec} parameter you are supplying
                    302: according to the bit size, either using the default precisions given by the
                    303: various \kbd{DEFAULTPREC}s, or by using conditional constructs of the form:
                    304: %
                    305: \bprog%
                    306: \#ifndef LONG\_IS\_64BIT
                    307: \q prec = 4;
                    308: \#else
                    309: \q prec = 6;
                    310: \#endif
                    311: \eprog
                    312: \noindent which is in this case equivalent to the statement
                    313: \kbd{prec = MEDDEFAULTPREC;}.
                    314:
                    315: Note that for parity reasons, half the accuracies available on 32-bit
                    316: architectures (the odd ones) have no precise equivalents on 64-bit machines.
                    317:
                    318: \section{Creation of PARI objects, assignments, conversions}
                    319:
                    320: \subsec{Creation of PARI objects}.\sidx{creation}
                    321: The basic function which creates a PARI object is the function
                    322: \teb{cgetg} whose prototype is:
                    323:
                    324: \kbd{GEN \key{cgetg}(long length, long type)}.
                    325:
                    326: \noindent
                    327: Here \kbd{length} specifies the number of longwords to be allocated to the
                    328: object, and type is the type number of the object, preferably in symbolic
                    329: form (see \secref{se:impl} for the list of these). The precise effect of
                    330: this function is as follows: it first creates on the PARI {\it stack\/} a
                    331: chunk of memory of size \kbd{length} longwords, and saves the address of the
                    332: chunk which it will in the end return.  If the stack has been used up, a
                    333: message to the effect that ``the PARI stack overflows'' will be printed,
                    334: and an error raised. Otherwise, it sets the type and length of the PARI object.
                    335: In effect, it fills correctly and completely its first codeword (\kbd{z[0]} or
                    336: \kbd{*z}).  Many PARI objects also have a second codeword (types \typ{INT},
                    337: \typ{REAL},  \typ{PADIC}, \typ{POL}, and \typ{SER}). In case you want to
                    338: produce one of those from scratch (this should be exceedingly rare), {\it it
                    339: is your responsibility to fill this second codeword}, either explicitly (using
                    340: the macros described in \secref{se:impl}), or implicitly using an assignment
                    341: statement (using \kbd{gaffect}).
                    342:
                    343: Note that the argument \kbd{length} is predetermined for a number of types:
                    344: 3 for types \typ{INTMOD}, \typ{FRAC}, \typ{FRACN}, \typ{COMPLEX},
                    345: \typ{POLMOD}, \typ{RFRAC} and \typ{RFRACN}, 4 for type \typ{QUAD}
                    346: and \typ{QFI}, and 5 for type \typ{PADIC} and \typ{QFR}. However for the sake
                    347: of efficiency, no checking is done in the function \kbd{cgetg}, so
                    348: disasters will occur if you give an incorrect length.
                    349:
                    350: \misctitle{Notes}:
                    351: 1)  The main use of this function is to prepare for later assigments
                    352: (see \secref{se:assign}). Most of the time you will use \kbd{GEN} objects
                    353: as they are created and returned by PARI functions. In this case you don't need
                    354: to use \kbd{cgetg} to create space to hold them.
                    355:
                    356: \noindent 2) For the creation of leaves, i.e.~integers or reals, which is
                    357: very common,
                    358:
                    359: \kbd{GEN \teb{cgeti}(long length)}
                    360:
                    361: \kbd{GEN \teb{cgetr}(long length)}
                    362:
                    363: \noindent should be used instead of \kbd{cgetg(length, t\_INT)} and
                    364: \kbd{cgetg(length, t\_REAL)} respectively.
                    365:
                    366: \noindent 3) The macros \teb{lgetg}, \teb{lgeti}, \teb{lgetr} are
                    367: predefined as \kbd{(long)cgetg}, \kbd{(long)cgeti}, \kbd{(long)cgetr},
                    368: respectively.
                    369:
                    370: \misctitle{Examples}: 1) \kbd{z = cgeti(DEFAULTPREC)} and
                    371: \kbd{cgetg(DEFAULTPREC, t\_INT)} create an integer object whose ``precision''
                    372: is \kbd{bit\_accuracy(DEFAULTPREC)} = 64. This means \kbd{z} can hold rational
                    373: integers of absolute value less than $2^{64}$. Note that in both cases, the
                    374: second codeword will {\it not\/} be filled. Of course we could use numerical
                    375: values, e.g.~\kbd{cgeti(4)}, but this would have different meanings on
                    376: different machines as \kbd{bit\_accuracy(4)} equals 64 on 32-bit machines,
                    377: but 128 on 64-bit machines.
                    378:
                    379: \noindent 2) The following creates a type ``complex'' object whose real and
                    380: imaginary parts can hold real numbers of precision
                    381: $\kbd{bit\_accuracy(MEDDEFAULTPREC)} = 96\hbox{ bits:}$
                    382: %
                    383: \bprog%
                    384:   z = cgetg(3, t\_COMPLEX);
                    385:   z[1] = lgetr(MEDDEFAULTPREC);
                    386:   z[2] = lgetr(MEDDEFAULTPREC);
                    387: \eprog
                    388:
                    389: \noindent 3) To create a matrix object for $4\times 3$ matrices:
                    390: %
                    391: \bprog%
                    392:   z = cgetg(4, t\_MAT);
                    393:   for(i=1; i<4; i++) z[i] = lgetg(5, t\_COL);
                    394: \eprog
                    395: %
                    396: \noindent If one wishes to create space for the matrix elements themselves,
                    397: one has to follow this with a double loop to fill each column vector.
                    398:
                    399: These last two examples illustrate the fact that since PARI types are
                    400: recursive, all the branches of the tree must be created. The function
                    401: \teb{cgetg} creates only the ``root'', and other calls to \kbd{cgetg} must be
                    402: made to produce the whole tree.  For matrices, a common mistake is to think
                    403: that \kbd{z = cgetg(4, t\_MAT)} (for example) will create the root of the
                    404: matrix: one needs also to create the column vectors of the matrix (obviously,
                    405: since we specified only one dimension in the first \kbd{cgetg}!). This is
                    406: because a matrix is really just a row vector of column vectors (hence a
                    407: priori not a basic type), but it has been given a special type number so that
                    408: operations with matrices become possible.
                    409:
                    410: \subsec{Assignments}.
                    411: Firstly, if \kbd{x} and \kbd{y} are both declared as \kbd{GEN} (i.e.~pointers
                    412: to something), the ordinary C assignment \kbd{y = x} makes perfect sense: we
                    413: are just moving a pointer around. However, physically modifying either
                    414: \kbd{x} or \kbd{y} (for instance, \kbd{x[1] = 0}) will also change the other
                    415: one, which is usually not desirable. \label{se:assign}
                    416:
                    417: \misctitle{Very important note}: Using the functions described in this
                    418: paragraph is very inefficient and often awkward: one of the \tet{gerepile}
                    419: functions (see~\secref{se:garbage}) should be preferred. See the paragraph
                    420: end for some exceptions to this rule.
                    421:
                    422: \noindent
                    423: The general PARI \idx{assignment} function is the function \teb{gaffect} with
                    424: the following syntax:
                    425:
                    426: \kbd{void \key{gaffect}(GEN x, GEN y)}
                    427:
                    428: \noindent
                    429: Its effect is to assign the PARI object \kbd{x} into the {\it preexisting\/}
                    430: object \kbd{y}. This copies the whole structure of \kbd{x} into \kbd{y} so
                    431: many conditions must be met for the assignment to be possible. For instance
                    432: it is allowed to assign an integer into a real number, but the converse is
                    433: forbidden.  For that, you must use the truncation or rounding function of
                    434: your choice (see section 3.2). It can also happen that \kbd{y} is not large
                    435: enough or does not have the proper tree structure to receive the object
                    436: \kbd{x}. As an extreme example, assume \kbd{y} is the zero integer with length
                    437: equal to 2. Then all assignments of a non-zero integer into \kbd{y} will
                    438: result in an error message since \kbd{y} is not large enough to accommodate
                    439: a non-zero integer.  In general common sense will tell you what is possible,
                    440: keeping in mind the PARI philosophy which says that if it makes sense it is
                    441: legal. For instance, the assignment of an imprecise object into a precise one
                    442: does {\it not\/} make sense. However, a change in precision of imprecise
                    443: objects is allowed.
                    444:
                    445: All functions ending in ``\kbd{z}'' such as \teb{gaddz}
                    446: (see~\secref{se:low_level}) implicitly use this function. In fact what they
                    447: exactly do is record {\teb{avma}} (see~\secref{se:garbage}), perform the
                    448: required operation, \teb{gaffect} the result to the last operand, then
                    449: restore the initial \kbd{avma}.
                    450:
                    451: You can assign ordinary C long integers into a PARI object (not necessarily
                    452: of type \typ{INT}). Use the function \teb{gaffsg} with the following
                    453: syntax:
                    454:
                    455: \kbd{void \key{gaffsg}(long s, GEN y)}
                    456:
                    457: \misctitle{Note}: due to the requirements mentionned above, it's usually
                    458: a bad idea to use \tet{gaffect} statements. Two exceptions:
                    459:
                    460: $\bullet$ for simple objects (e.g.~leaves) whose size is controlled, they can
                    461: be easier to use than gerepile, and about as efficient.
                    462:
                    463: $\bullet$ to coerce an inexact object to a given precision. For instance
                    464: \bprog%
                    465: gaffect(x, (tmp=cgetr(3))); x = tmp;
                    466: \eprog
                    467: \noindent at the beginning of a routine where precision can be kept to a
                    468: minimum (otherwise the precision of \kbd{x} will be used in all subsequent
                    469: computations, which will be a disaster if \kbd{x} is known to thousands of
                    470: digits).
                    471:
                    472: \subsec{Copy}. It is also very useful to \idx{copy} a PARI object, not
                    473: just by moving around a pointer as in the \kbd{y = x} example, but by
                    474: creating a copy of the whole tree structure, without pre-allocating a
                    475: possibly complicated \kbd{y} to use with \kbd{gaffect}. The function which
                    476: does this is called \teb{gcopy}, with the predefined macro
                    477: \teb{lcopy} as a synonym for \kbd{(long)gcopy}. Its syntax is:
                    478:
                    479: \kbd{GEN \key{gcopy}(GEN x)}
                    480:
                    481: \noindent and the effect is to create a new copy of x on the PARI stack.
                    482: Beware that universal objects which occur in specific components of certain
                    483: types (mainly moduli for types \typ{INTMOD} and \typ{PADIC}) are not copied,
                    484: as they are assumed to be permanent. In this case, \kbd{gcopy} only copies
                    485: the pointer. Use \kbd{GEN \teb{forcecopy}(GEN x)} if you want a
                    486: complete copy.
                    487:
                    488: Please be sure at this point that you really understand the difference between
                    489: \kbd{y = x}, \kbd{y = gcopy(x)}, and \kbd{gaffect(x,y)}: this will save you
                    490: from many ``obvious'' mistakes later on.
                    491:
                    492: \subsec{Clones}.\sidx{clone}
                    493: Sometimes, it may be more efficient to create a {\it permanent\/} copy of a
                    494: PARI object. This will not be created on the stack but on the heap. The
                    495: function which does this is called \teb{gclone}, with the predefined macro
                    496: \teb{lclone} as a synonym for \kbd{(long)gclone}. Its syntax is:
                    497:
                    498: \kbd{GEN \key{gclone}(GEN x)}
                    499:
                    500: A clone can be removed from the heap (thus destroyed) using
                    501:
                    502: \kbd{void \key{gunclone}(GEN x)}
                    503:
                    504: \noindent No PARI object should keep references to a clone which has been
                    505: destroyed. If you want to copy a clone back to the stack then delete it, use
                    506: \tet{forcecopy} and not \tet{gcopy}, otherwise some components might not be
                    507: copied (moduli of \typ{INTMOD}s and \typ{POLMOD}s for instance).
                    508:
                    509: \subsec{Conversions}.\sidx{conversions}
                    510: The following functions convert C objects to PARI objects (creating them on
                    511: the stack as usual):
                    512:
                    513: \kbd{GEN \teb{stoi}(long s)}: C \kbd{long} integer  (``small'') to
                    514: PARI integer (\typ{INT})
                    515:
                    516: \kbd{GEN \teb{dbltor}(double s)}: C \kbd{double} to PARI real
                    517: (\typ{REAL}). The accuracy of the result is 19 decimal digits, i.e.~a type
                    518: \typ{REAL} of length \kbd{DEFAULTPREC}, although on 32-bit machines only 16
                    519: of them will be significant.
                    520:
                    521: \noindent We also have the converse functions:
                    522:
                    523: \kbd{long \teb{itos}(GEN x)}: \kbd{x} must be of type \typ{INT},
                    524:
                    525: \kbd{double \teb{rtodbl}(GEN x)}: \kbd{x} must be of type \typ{REAL},
                    526:
                    527: \noindent as well as the more general ones:
                    528:
                    529: \kbd{long \teb{gtolong}(GEN x)},
                    530:
                    531: \kbd{double \teb{gtodouble}(GEN x)}.
                    532:
                    533: \section{Garbage collection}\label{se:garbage}\sidx{garbage collecting}
                    534:
                    535: \subsec{Why and how}.
                    536:
                    537: \noindent
                    538: As we have seen, the \kbd{pari\_init} routine allocates a big range of
                    539: addresses (the {\it stack\/}) that are going to be used throughout. Recall that
                    540: all PARI objects are pointers. But for universal objects, they will all point
                    541: at some part of the stack.
                    542:
                    543: The stack starts at the address \kbd{bot} and ends just before \kbd{top}. This
                    544: means that the quantity
                    545: %
                    546: $$ (\kbd{top} - \kbd{bot})\,/\,\kbd{sizeof(long)} $$
                    547: %
                    548: is equal to the \kbd{size} argument of \kbd{pari\_init}. The PARI
                    549: stack also has a ``current stack pointer'' called \teb{avma}, which
                    550: stands for {\bf av}ailable {\bf m}emory {\bf a}ddress. These three variables
                    551: are global (declared for you by \kbd{pari.h}). For historical reasons they
                    552: are of type \kbd{long} and not of type \kbd{GEN} as would seem more natural.
                    553:
                    554: The stack is oriented upside-down: the more recent an object, the closer to
                    555: \kbd{bot}. Accordingly, initially \kbd{avma} = \kbd{top}, and \kbd{avma} gets
                    556: {\it decremented\/} as new objects are created. As its name indicates,
                    557: \kbd{avma} always points just {\it after\/} the first free address on the
                    558: stack, and \kbd{(GEN)avma} is always (a pointer to) the latest created object.
                    559: When \kbd{avma} reaches \kbd{bot}, the stack overflows, aborting all
                    560: computations, and an error message is issued. To avoid this {\it you\/} will
                    561: need to clean up the stack from time to time, when some bunch of intermediate
                    562: objects will not be needed anymore. This is called ``{\it garbage
                    563: collecting}.''
                    564:
                    565: We are now going to describe briefly how this is done. We will see many
                    566: concrete examples in the next subsection.
                    567:
                    568: \noindent$\bullet$
                    569: First, PARI routines will do their own garbage collecting, which
                    570: means that whenever a documented function from the library returns, only its
                    571: result(s) will have been added to the stack (non-documented ones may not do
                    572: this, for greater speed). In particular, a PARI function that does not return
                    573: a \kbd{GEN} does not clutter the stack. Thus, if your computation is small
                    574: enough (i.e.~you call few PARI routines, or most of them return \kbd{long}
                    575: integers), then you don't need to do any garbage collecting. This will probably
                    576: be the case in many of your subroutines. Of course the objects that were on
                    577: the stack {\it before\/} the function call are left alone. Except for the ones
                    578: listed below, PARI functions only collect their own garbage.
                    579:
                    580: \noindent$\bullet$
                    581: It may happen that you need to preserve {\it some\/} but not
                    582: {\it all\/} objects that were created after a certain point~--- for instance,
                    583: if the final result you need is not a \kbd{GEN}, or if some search proved
                    584: futile. Then, it is enough to record the value of \kbd{avma} just
                    585: {\it before\/} the first garbage is created, and restore it upon exit:
                    586:
                    587: \bprog%
                    588: long ltop = avma; /* record initial avma */
                    589: \h
                    590: garbage ...
                    591: avma = ltop; /* restore it */
                    592: \eprog
                    593: \noindent All objects created in the \kbd{garbage} zone will eventually
                    594: be overwritten: they should not be accessed anymore once \kbd{avma} has been
                    595: restored.
                    596:
                    597: \noindent$\bullet$
                    598: If you want to destroy (i.e.~give back the memory occupied by) the
                    599: latest PARI object on the stack (e.g.~the latest one obtained from a function
                    600: call), and the above method is not available (because the initial value of
                    601: \kbd{avma} has been lost), just use the function\sidx{destruction}%
                    602: \vadjust{\penalty500}%discourage page break
                    603:
                    604: \kbd{void \teb{cgiv}(GEN z)}
                    605:
                    606: \noindent where \kbd{z} is the object you want to give back.
                    607:
                    608: \noindent$\bullet$
                    609: Unfortunately life is not so simple, and sometimes you will want
                    610: to give back accumulated garbage {\it during\/} a computation without losing
                    611: recent data. For this you need the \kbd{gerepile} function (or one of its
                    612: variants described hereafter):
                    613:
                    614: \kbd{GEN \teb{gerepile}(long ltop, long lbot, GEN q)}
                    615:
                    616: \noindent
                    617: This function cleans up the stack between \kbd{ltop} and \kbd{lbot}, where
                    618: $\kbd{lbot} < \kbd{ltop}$, and returns the updated object \kbd{q}. This means:
                    619:
                    620: 1) we translate (copy) all the objects in the interval
                    621: $[\kbd{avma}, \kbd{lbot}[$, so that its right extremity abuts the address
                    622: \kbd{ltop}. Graphically
                    623:
                    624: \vbox{
                    625: \bprogtabs\+
                    626: {\rm end of stack}  &|-&-----------&|++++++&|-/-/-/-/-/-/-&|++++++++&|
                    627: \cr\+
                    628:             &bot  &       &avma  &lbot         &ltop    &top
                    629: \cr\+
                    630: {\rm end of stack}  |------------[++++++[-/-/-/-/-/-/-|++++++++|\q
                    631: {\rm beginning of stack}
                    632: \cr\+
                    633:              & &{\rm free memory}
                    634: \cr\eprog
                    635: }\noindent becomes:
                    636:
                    637: \vbox{
                    638: \bprogtabs\+
                    639: {\rm end of stack}  &|--------&------------------&|++++++&|++++++++&|
                    640: \cr\+
                    641:              &bot      &                  &avma   &ltop     &top
                    642: \cr\+
                    643: {\rm end of stack} |--------------------------[++++++[++++++++|\q
                    644: {\rm beginning of stack}
                    645: \cr\+
                    646:                       &&{\rm free memory}
                    647: \cr\eprog
                    648: }
                    649: \noindent where \kbd{++} denote significant objects, \kbd{--} the unused part
                    650: of the stack, and \kbd{-/-} the garbage we remove.
                    651:
                    652: 2) The function then inspects all the PARI objects between \kbd{avma} and
                    653: \kbd{lbot} (i.e.~the ones that we want to keep and that have been translated)
                    654: and looks at every component of such an object which is not a codeword. Each
                    655: such component is a pointer to an object whose address is either
                    656:
                    657: --- between \kbd{avma} and \kbd{lbot}, in which case it will be suitably
                    658: updated,
                    659:
                    660: --- larger than or equal to \kbd{ltop}, in which case it will not change, or
                    661:
                    662: --- between \kbd{lbot} and \kbd{ltop} in which case \kbd{gerepile} will
                    663: scream an error message at you (``significant pointers lost in gerepile'').
                    664:
                    665: 3) \key{avma} is updated (we add $\kbd{ltop} - \kbd{lbot}$ to the old value).
                    666:
                    667: 4) We return the (possibly updated) object \kbd{q}: if \kbd{q} initially
                    668: pointed between \kbd{avma} and \kbd{lbot}, we return the translated
                    669: address, as in~2). If not, the original address is still valid (and we return
                    670: it!).
                    671:
                    672: As stated above, no component of the remaining objects (in particular
                    673: \kbd{q}) should belong to the erased segment [\kbd{lbot}, \kbd{ltop}[, and
                    674: this is checked within \kbd{gerepile}. But beware as well that the addresses
                    675: of all the objects in the translated zone will have changed after a call to
                    676: \kbd{gerepile}: every pointer you may have kept around elsewhere, outside the
                    677: stack objects, which previously pointed into the zone below \kbd{ltop}
                    678: must be discarded. If you need to recover more than one object, use one of
                    679: the \kbd{gerepilemany} functions below.
                    680:
                    681: As a consequence of the preceding explanation, we must now state the most
                    682: important law about programming in PARI:
                    683:
                    684: {\bf If a given PARI object is to be relocated by \hbox{gerepile} then,
                    685: apart from universal objects, the chunks of memory used by its components
                    686: should be in consecutive memory locations}. All \kbd{GEN}s created by
                    687: documented PARI function are guaranteed to satisfy this.
                    688:
                    689: This is because the \kbd{gerepile} function knows only about {\it two
                    690: connected zones\/}: the garbage that will be erased (between \kbd{lbot} and
                    691: \kbd{ltop}) and the  significant pointers that will be copied and updated.
                    692: If there is garbage interspersed with your objects, disasters will occur when
                    693: we try to update them and consider the corresponding ``pointers''. So be
                    694: {\it very\/} wary when you allow objects to become disconnected. Have a look
                    695: at the examples, it's not as complicated as it seems.
                    696:
                    697: \noindent In practice this is achieved by the following programming idiom:
                    698: \bprog%
                    699:   ltop=avma; garbage(); lbot=avma; q=anything();
                    700:   return gerepile(ltop, lbot, q);  /* returns the updated q */
                    701: \eprog
                    702:
                    703: \noindent Beware that
                    704: \bprog%
                    705:   ltop=avma; garbage();
                    706:   return gerepile(ltop, avma, anything())
                    707: \eprog
                    708:
                    709: \noindent might work, but should be frowned upon. We can't predict whether
                    710: \kbd{avma} is going to be evaluated after or before the call to
                    711: \kbd{anything()}: it depends on the compiler. If we are out of luck, it will
                    712: be {\it after\/} the call, so the result will belong to the garbage zone and
                    713: the \kbd{gerepile} statement becomes equivalent to \kbd{avma = ltop}. Thus we
                    714: would return a pointer to random garbage.
                    715:
                    716: \noindent$\bullet$ A simple variant is
                    717:
                    718: \kbd{GEN \teb{gerepileupto}(long ltop, GEN q)}
                    719:
                    720: \noindent which cleans the stack between \kbd{ltop} and the {\it connected\/}
                    721: object \kbd{q} and returns \kbd{q} updated. For this to work, \kbd{q} must
                    722: have been created {\it before\/} all its components, otherwise they would
                    723: belong to the garbage zone! Documented PARI functions guarantee this. If you
                    724: stumble upon one that does not, consider it a bug worth reporting.
                    725:
                    726: \noindent$\bullet$
                    727: To cope with complicated cases where many objects have to be
                    728: preserved, you can use
                    729:
                    730: \kbd{void \teb{gerepilemany}(long ltop, GEN *gptr[],
                    731: \kbd{long} n)}
                    732:
                    733: \noindent which cleans up the most recent part of the stack (between
                    734: \kbd{ltop} and \kbd{avma}). All the \kbd{GEN}s pointed at by the elements of
                    735: the array \kbd{gptr} (of length \kbd{n}) are updated. A copy is done just
                    736: before the cleaning to preserve them, so they don't need to be connected
                    737: before the call. This is the most robust of the gerepile functions (the less
                    738: prone to user error), but also the slowest.
                    739:
                    740: \noindent$\bullet$ More efficient, but trickier to use is
                    741:
                    742: \kbd{void \teb{gerepilemanysp}(long ltop, long lbot, GEN *gptr[], long n)}
                    743:
                    744: \noindent which cleans the stack between \kbd{lbot} and \kbd{ltop} and
                    745: updates the \kbd{GEN}s pointed at by the elements of \kbd{gptr} without doing
                    746: any copying. This is subject to the same restrictions as \kbd{gerepile}, the
                    747: only difference being that more than one address gets updated.
                    748:
                    749: \subsec{Examples}.
                    750:
                    751: \noindent
                    752: Let \kbd{x} and \kbd{y} be two preexisting PARI objects and suppose that we
                    753: want to compute $\kbd{x}^2+ \kbd{y}^2$. This can trivially be done using the
                    754: following program (we skip the necessary declarations; everything in sight is
                    755: a \kbd{GEN}):
                    756:
                    757: \kbd{p1 = gsqr(x); p2 = gsqr(y); z = gadd(p1,p2);}
                    758:
                    759: \noindent
                    760: The \kbd{GEN} \kbd{z} indeed points at the desired quantity. However,
                    761: consider the stack: it contains as unnecessary garbage \kbd{p1} and \kbd{p2}.
                    762: More precisely it contains (in this order) \kbd{z}, \kbd{p2}, \kbd{p1}
                    763: (recall that, since the stack grows downward from the top, the most recent
                    764: object comes first). We need a way to get rid of this garbage (in this case
                    765: it causes no harm except that it occupies memory space, but in other cases
                    766: it could disconnect other PARI objects and this is dangerous).
                    767:
                    768: It would not have been possible to get rid of \kbd{p1}, \kbd{p2} before
                    769: \kbd{z} is computed, since they are used in the final operation. We cannot
                    770: record \kbd{avma} before \kbd{p1} is computed and restore it later, since
                    771: this would destroy \kbd{z} as well. It is not possible either to use the
                    772: function \kbd{cgiv} since \kbd{p1} and \kbd{p2} are not at the bottom of the
                    773: stack and we don't want to give back~\kbd{z}.
                    774:
                    775: But using \kbd{gerepile}, we can give back the memory locations corresponding
                    776: to \kbd{p1}, \kbd{p2}, and move the object \kbd{z} upwards so that no
                    777: space is lost. Specifically:
                    778: \bprog%
                    779:   ltop = avma; /* remember the current address of the top of the stack */
                    780:   p1 = gsqr(x); p2 = gsqr(y);
                    781:   lbot = avma; /* keep the address of the bottom of the garbage pile */
                    782:   z = gadd(p1, p2); /* z is now the last object on the stack */
                    783:   z = gerepile(ltop, lbot, z); /* garbage collecting */
                    784: \eprog
                    785: \noindent Of course, the last two instructions could also have been
                    786: written more simply:
                    787:
                    788: \kbd{z = gerepile(ltop, lbot, gadd(p1,p2));}
                    789:
                    790: \noindent In fact \kbd{gerepileupto} is even simpler to use, because the
                    791: result of \kbd{gadd} will be the last object on the stack and \kbd{gadd} is
                    792: guaranteed to return an object suitable for \kbd{gerepileupto}:
                    793: \bprog%
                    794:   ltop = avma;
                    795:   z = gerepileupto(ltop, gadd(gsqr(x), gsqr(y)));
                    796: \eprog
                    797: \noindent
                    798: As you can see, in simple conditions the use of \kbd{gerepile} is not really
                    799: difficult. However make sure you understand exactly what has happened before
                    800: you go on (use the figure from the preceding section).
                    801:
                    802: \misctitle{Important remark}: as we will see presently it is often
                    803: necessary to do several \kbd{gerepile}s during a computation. However, the
                    804: fewer the better.  The only condition for \kbd{gerepile} to work is that the
                    805: garbage be connected. If the computation can be arranged so that there is a
                    806: minimal number of connected pieces of garbage, then it should be done that
                    807: way.
                    808:
                    809: For example suppose we want to write a function of two \kbd{GEN} variables
                    810: \kbd{x} and \kbd{y} which creates the vector $\kbd{[x}^2+\kbd{y},
                    811: \kbd{y}^2+\kbd{x]}$. Without garbage collecting, one would write:
                    812: %
                    813: \bprog%
                    814:   p1 = gsqr(x); p2 = gadd(p1, y);
                    815:   p3 = gsqr(y); p4 = gadd(p3, x);
                    816:   z = cgetg(3,t\_VEC); z[1] = (long)p2; z[2] = (long)p4;
                    817: \eprog
                    818: \noindent
                    819: This leaves a dirty stack containing (in this order) \kbd{z}, \kbd{p4},
                    820: \kbd{p3}, \kbd{p2}, \kbd{p1}. The garbage here consists of \kbd{p1} and
                    821: \kbd{p3}, which are separated by \kbd{p2}. But if we compute \kbd{p3}
                    822: {\it before\/} \kbd{p2} then the garbage becomes connected, and we get the
                    823: following program with garbage collecting:
                    824: %
                    825: \bprog%
                    826:   ltop = avma; p1 = gsqr(x); p3 = gsqr(y); lbot = avma;
                    827:   z = cgetg(3,t\_VEC); z[1] = ladd(p1,y); z[2] = ladd(p3,x);
                    828:   z = gerepile(ltop,lbot,z);
                    829: \eprog
                    830:
                    831: \noindent Finishing by \kbd{z = gerepileupto(ltop, z)} would be ok as well.
                    832: But when you have the choice, it's usually clearer to brace the garbage
                    833: between \kbd{ltop}~/ \kbd{lbot} pairs.
                    834:
                    835: \noindent Beware that
                    836: \bprog%
                    837:   ltop = avma; p1 = gadd(gsqr(x), y); p3 = gadd(gsqr(y), x);
                    838:   z = cgetg(3,t\_VEC); z[1] = (long)p1; z[2] = (long)p3
                    839:   z = gerepileupto(ltop,z); /* WRONG !!!~*/%
                    840: \eprog
                    841: \noindent would be a disaster since \kbd{p1} and \kbd{p3} would be created
                    842: before \kbd{z}, so the call to \kbd{gerepileupto} would overwrite them,
                    843: leaving \kbd{z[1]} and \kbd{z[2]} pointing at random data!
                    844:
                    845: We next want to write a program to compute the product of two complex numbers
                    846: $x$ and $y$, using a method which takes only 3 multiplications instead of 4.
                    847: Let $z = x*y$, and set $x = x_r + i*x_i$ and similarly for $y$ and $z$. The
                    848: well-known trick is to compute $p_1 = x_r*y_r$, $p_2=x_i*y_i$,
                    849: $p_3=(x_r+x_i)*(y_r+y_i)$, and then we have $z_r=p_1-p_2$,
                    850: $z_i=p_3-(p_1+p_2)$. The program is essentially as follows:
                    851: %
                    852: \bprog%
                    853: ltop = avma; p1 = gmul(x[1],y[1]); p2 = gmul(x[2],y[2]);
                    854: p3 = gmul(gadd(x[1],x[2]), gadd(y[1],y[2]));
                    855: p4 = gadd(p1,p2); lbot = avma;
                    856: z = cgetg(3,t\_COMPLEX); z[1] = lsub(p1,p2); z[2] = lsub(p3,p4);
                    857: z = gerepile(ltop,lbot,z);
                    858: \eprog
                    859: \noindent
                    860: ``Essentially,'' because for instance \kbd{x[1]} is a \kbd{long} and not a
                    861: \kbd{GEN}, so we need to insert many annoying typecasts:
                    862: \kbd{p1 = gmul((GEN)x[1], (GEN)y[1])} and so on.
                    863:
                    864: Let us now look at a less trivial example where more than one \kbd{gerepile}
                    865: is needed in practice (at the expense of efficiency, one can always use only
                    866: one using \kbd{gcopy}; see below). Suppose that we want to write a function
                    867: which multiplies a line vector by a matrix (such a function is of course
                    868: already part of \kbd{gmul}, but let's ignore this for a moment). Then the
                    869: most natural way is to do a \kbd{cgetg} of the result immediately, and then a
                    870: \kbd{gerepile} for each coefficient of the result vector to get rid of the
                    871: garbage which has accumulated while this particular coefficient was computed.
                    872: We leave the details to the reader, who can look at the answer in the file
                    873: \kbd{basemath/gen1.c}, in the function \kbd{gmul}, case \typ{VEC} times case
                    874: \typ{MAT}. It would theoretically be possible to have a single connected
                    875: piece of garbage, but it would be a much less natural and unnecessarily
                    876: complicated program.
                    877:
                    878: Let us now take an example which is probably the least trivial way of using
                    879: \kbd{gerepile}, but is unfortunately sometimes necessary. Although it is not
                    880: an infrequent occurrence, we will not give a specific example but a general
                    881: one: suppose that we want to do a computation (usually inside a larger
                    882: function) producing more than one PARI object as a result, say two for
                    883: instance. Then even if we set up the work properly, before cleaning up we
                    884: will have a stack which has the desired results \kbd{z1}, \kbd{z2} (say),
                    885: and then connected garbage from lbot to ltop. If we write
                    886:
                    887: \kbd{z1 = gerepile(ltop,lbot,z1);}
                    888:
                    889: \noindent
                    890: then the stack will be cleaned, the pointers fixed up, but we will have lost
                    891: the address of \kbd{z2}. This is where we need one of the \idx{gerepilemany}
                    892: functions: we declare
                    893: \bprog%
                    894:   GEN *gptr[2]; /* Array of pointers to GENs */
                    895:   gptr[0] = \&z1; gptr[1] = \&z2;
                    896: \eprog
                    897: \noindent and now the call \kbd{gerepilemany(ltop, gptr, 2)} copies \kbd{z1}
                    898: and \kbd{z2} to new locations, cleans the stack from \kbd{ltop} to the old
                    899: \kbd{avma}, and updates the pointers \kbd{z1} and \kbd{z2}. Here we don't
                    900: assume anything about the stack: the garbage can be disconnected and
                    901: \kbd{z1}, \kbd{z2} need not be at the bottom of the stack. If all of these
                    902: assumptions are in fact satisfied, then we can call \kbd{gerepilemanysp}
                    903: instead, which will be faster since we don't need the initial copy.
                    904:
                    905: Another important usage is ``random'' garbage collection during loops
                    906: whose size requirements we cannot control in advance:
                    907: \bprog%
                    908: \q  long ltop = avma, limit = (avma+bot)/2;
                    909: \q  GEN x, y;
                    910: \h
                    911: \q  while (...)
                    912: \q  $\{$
                    913: \q\q  garbage(); x = anything();
                    914: \q\q  garbage(); y = anything()
                    915: \q\q  garbage();
                    916: \q\q  if (avma < limit) /* memory is running low (half spent since entry) */
                    917: \q\q  $\{$
                    918: \q\q\q   GEN *gptr[2];
                    919: \q\q\q   gptr[0] = \&x; gptr[1] = \&y;
                    920: \q\q\q   gerepilemany(ltop, gptr, 2);
                    921: \q\q  $\}$
                    922: \q  $\}$
                    923: \eprog
                    924: \noindent Here we assume that only \kbd{x} and \kbd{y} are needed from one
                    925: iteration to the next. As it would be too costly to call gerepile once for
                    926: each iteration, we only do it when it seems to have become necessary. Of
                    927: course, when the need arises, you can use bigger \kbd{gptr} arrays: in the
                    928: PARI library source code, we once needed to preserve up to 10 objects at a
                    929: time (in a variant of the LLL algorithm)!
                    930:
                    931: \misctitle{Technical note:} the statement \kbd{limit = (avma+bot)/2} is
                    932: dangerous since the addition can overflow, which would result in
                    933: \kbd{limit} being negative. This will prevent garbage collection in the
                    934: loop. To avoid this problem, we provide a robust macro
                    935: \kbd{stack\_lim(avma,$n$)}\sidx{stack\string\_lim}, which denotes an
                    936: address where $2^{n-1} / (2^{n-1}+1)$ of the total stack space is
                    937: exhausted ($1/2$ for $n=1$, $2/3$ for $n=2$). Hence, the above snippet should be written as
                    938:
                    939: \bprog%
                    940: \q  long ltop = avma, limit = stack\_lim(avma,1);
                    941: \q  \dots
                    942: \eprog
                    943:
                    944: \subsec{Some hints and tricks}. Even for the authors, the use of
                    945: \kbd{gerepile} was not evident at first. Hence we give some indications on
                    946: how to avoid most problems connected with garbage collecting:
                    947:
                    948: First, although it looks complicated, \kbd{gerepile} has turned out to be a
                    949: very flexible and fast garbage collector, which compares very favorably
                    950: with much more sophisticated methods used in other systems. A few tests that
                    951: we have done indicate that the price paid for using \kbd{gerepile}, when
                    952: properly used, is usually around 1 or 2 percents of the total time, which is
                    953: quite acceptable.
                    954:
                    955: Secondly, in many cases, in particular when the tree structure and the size of
                    956: the PARI objects which will appear in a computation are under control, one
                    957: can avoid \kbd{gerepile} altogether by creating sufficiently large objects at
                    958: the beginning (using \teb{cgetg}), and then using assignment statements and
                    959: operations ending with z (such as \teb{gaddz}). Coming back to our first
                    960: example, note that if we know that x and y are of type real and of length
                    961: less than or equal to 5, we can program without using \kbd{gerepile} at all:
                    962:
                    963: \bprog%
                    964:   z = cgetr(5); ltop = avma;
                    965:   p1 = gsqr(x); p2 = gsqr(y); gaddz(p1,p2,z);
                    966:   avma = ltop;%
                    967: \eprog
                    968: \noindent This practice will usually be {\it slower\/} than a craftily used
                    969: \kbd{gerepile} though, and is certainly more cumbersome to use. As a rule,
                    970: assignment statements should generally be avoided.
                    971: \smallskip
                    972:
                    973: Thirdly, the philosophy of \kbd{gerepile} is the following: keep the value of
                    974: the stack pointer \kbd{avma} at the beginning, and just {\it before\/} the
                    975: last operation.  Afterwards, it would be too late since the lower end address
                    976: of the garbage zone would have been lost. Of course you can always use
                    977: \kbd{gerepileupto}, but you will have to assume that the object was created
                    978: {\it before\/} its components.
                    979:
                    980: Finally, if everything seems hopeless, at the expense of speed you can do the
                    981: following: after saving the value of \kbd{avma} in \kbd{ltop}, perform your
                    982: computation as you wish, in any order, leaving a messy stack. Let \kbd{z} be
                    983: your result. Then write the following:
                    984:
                    985: \kbd{z = gerepileupto(ltop, gcopy(z));}
                    986:
                    987: \noindent
                    988: The trick is to force a copy of \kbd{z} to be created at the bottom of the
                    989: stack, hence all the rest including the initial \kbd{z} becomes connected
                    990: garbage. If you need to keep more than one result, use \kbd{gerepilemany}
                    991: (of which the above is just a special case).
                    992:
                    993: \smallskip If you followed us this far, congratulations, and rejoice: the
                    994: rest is much easier.
                    995:
                    996: \section{Implementation of the PARI types}
                    997: \label{se:impl}
                    998:
                    999: \noindent
                   1000: Although it is a little tedious, we now go through each type and explain its
                   1001: implementation. Let \kbd{z} be a \kbd{GEN}, pointing at a PARI object. In
                   1002: the following paragraphs, we will constantly mix two points of view: on the
                   1003: one hand, \kbd{z} will be treated as the C pointer it is (in the context of
                   1004: program fragments like \kbd{z[1]}), on the other, as PARI's handle on (the
                   1005: internal representation of) some mathematical entity, so we will shamelessly
                   1006: write $\kbd{z} \ne 0$ to indicate that the {\it value\/} thus represented
                   1007: is nonzero (in which case the {\it pointer\/}~\kbd{z} certainly will be
                   1008: non-\kbd{NULL}). We offer no apologies for this style. In fact, you had
                   1009: better feel comfortable juggling both views simultaneously in your mind if
                   1010: you want to write correct PARI programs.
                   1011:
                   1012: Common to all the types is the
                   1013: first codeword \kbd{z[0]}, which we don't have to worry about since this is
                   1014: taken care of by \kbd{cgetg}. Its precise structure will depend on the
                   1015: machine you are using, but it always contain the following data: the
                   1016: {\it internal \idx{type number}\/} associated to the symbolic type name, the
                   1017: {\it\idx{length}\/} of the root in longwords, and a technical bit which
                   1018: indicates whether the object is a clone (see below) or not. This last one is
                   1019: used by GP for internal garbage collecting, you won't have to worry about it.
                   1020:
                   1021: \noindent These data can be handled through the following {\it macros\/}:
                   1022:
                   1023: \kbd{long \teb{typ}(GEN z)} returns the type number of \kbd{z}.
                   1024:
                   1025: \kbd{void \teb{settyp}(GEN z, long n)} sets the type number of \kbd{z}
                   1026: to \kbd{n} (you should not have to use this function if you
                   1027: use \kbd{cgetg}).
                   1028:
                   1029: \kbd{long \teb{lg}(GEN z)} returns the length (in longwords) of the
                   1030: root of \kbd{z}.
                   1031:
                   1032: \kbd{long \teb{setlg}(GEN z, long l)} sets the length of \kbd{z}
                   1033: to \kbd{l} (you should not have to use this function if you use
                   1034: \kbd{cgetg}; however, see an advanced example in \secref{se:prog}).
                   1035:
                   1036: \noindent
                   1037: (If you know enough about PARI to need to access the ``clone'' bit, then you'll
                   1038: be able to find usage hints in the code (esp. \kbd{killbloc()} and
                   1039: \kbd{matrix\_block()}). It {\it is\/} technical after all.)
                   1040:
                   1041: These macros are written in such a way that you don't need to worry about
                   1042: type casts when using them: i.e.~if \kbd{z} is a \kbd{GEN}, \kbd{typ(z[2])}
                   1043: will be accepted by your compiler, without your having to explicitly type
                   1044: \kbd{typ((GEN)z[2])}. Note that for the sake of efficiency, none of the
                   1045: codeword-handling macros check the types of their arguments even when there
                   1046: are stringent restrictions on their use.
                   1047:
                   1048: The possible second codeword is used differently by the different types, and
                   1049: we will describe it as we now consider each of them in turn:
                   1050:
                   1051: \def\sectype#1#2{ \subsec{Type \typ{#1} (#2s):}\sidx{#2} }
                   1052: \def\sectypes#1#2#3{ \subsec{Types \typ{#1} and \typ{#2} (#3s):}\sidx{#3} }
                   1053: \def\sectypeindex#1#2#3{ \subsec{Type \typ{#1} (#2):}\sidx{#3} }
                   1054:
                   1055: \sectype{INT}{integer} this type has a second codeword \kbd{z[1]} which
                   1056: contains the following information:
                   1057:
                   1058: the sign of \kbd{z}: coded as $1$, $0$ or $-1$ if $\kbd{z} > 0$, $\kbd{z} = 0$,
                   1059: $\kbd{z} < 0$ respectively.
                   1060:
                   1061: the {\it effective length\/} of \kbd{z}, i.e.~the total number of significant
                   1062: longwords. This means the following: apart from the integer 0, every integer
                   1063: is ``normalized'', meaning that the first mantissa longword (i.e.~\kbd{z[2]})
                   1064: is non-zero. However, the integer may have been created with a longer length.
                   1065: Hence the ``length'' which is in \kbd{z[0]} can be larger than the
                   1066: ``effective length'' which is in \kbd{z[1]}. Accessing \kbd{z[i]}
                   1067: for \kbd{i} larger than or equal to the effective length will yield random
                   1068: results.
                   1069:
                   1070: \noindent This information is handled using the following macros:
                   1071:
                   1072: \kbd{long \teb{signe}(GEN z)} returns the sign of \kbd{z}.
                   1073:
                   1074: \kbd{void \teb{setsigne}(GEN z, long s)} sets the sign of
                   1075: \kbd{z} to \kbd{s}.
                   1076:
                   1077: \kbd{long \teb{lgefint}(GEN z)} returns the \idx{effective length}
                   1078: of \kbd{z}.
                   1079:
                   1080: \kbd{void \teb{setlgefint}(GEN z, long l)} sets the effective length
                   1081: of \kbd{z} to \kbd{l}.
                   1082:
                   1083: The integer 0 can be recognized either by its sign being~0, or by its
                   1084: effective length being equal to~2. When $\kbd{z} \ne 0$, the word
                   1085: \kbd{z[2]} exists and is non-zero, and the absolute value of \kbd{z}
                   1086: is (\kbd{z[2]},\kbd{z[3]},\dots,\kbd{z[lgefint(z)-1]}) in base
                   1087: \kbd{2\pow BITS\_IN\_LONG}, where as usual in this notation \kbd{z[2]} is
                   1088: the highest order longword.
                   1089:
                   1090: \noindent The following further macros are available:
                   1091:
                   1092: \kbd{long \teb{mpodd}(GEN x)} which is 1 if \kbd{x} is odd, and 0
                   1093: otherwise.
                   1094:
                   1095: \kbd{long \teb{mod2}(GEN x)}, \kbd{\key{mod4}(x)}, and so on up
                   1096: to \kbd{\key{mod64}(x)}, which give the residue class of \kbd{x} modulo the
                   1097: corresponding power of 2, {\it for positive\/}~\kbd{x} (you will obtain weird
                   1098: results if you use these on the integer 0 or on negative numbers).
                   1099:
                   1100: These macros directly access the binary data and are thus much faster than
                   1101: the generic modulo functions. Besides, they return long integers instead of
                   1102: \kbd{GEN}s, so they don't clutter up the stack.
                   1103:
                   1104: \sectype{REAL}{real number} this type has a second codeword z[1] which
                   1105: also encodes its sign (obtained or set using the same functions as for the
                   1106: integers), and a biased binary exponent (i.e.~the actual exponent value plus
                   1107: some constant bias, actually a power of~2, whose value is given by
                   1108: \kbd{HIGHEXPOBIT}). This exponent can be handled using the following macros:
                   1109:
                   1110: \kbd{long \teb{expo}(GEN z)} returns the true (unbiased) exponent
                   1111: of \kbd{z}. This is defined even when \kbd{z} is equal to zero, see
                   1112: \secref{se:whatzero}.
                   1113:
                   1114: \kbd{void \teb{setexpo}(GEN z, long e)} sets the exponent of \kbd{z}
                   1115: to \kbd{e}, of course after adding the bias.
                   1116:
                   1117: \noindent Note the functions:
                   1118:
                   1119: \kbd{long \teb{gexpo}(GEN z)} which tries to return an exponent
                   1120: for \kbd{z}, even if \kbd{z} is not a real number.
                   1121:
                   1122: \kbd{long \teb{gsigne}(GEN z)} which returns a sign for \kbd{z},
                   1123: even when \kbd{z} is neither real nor integer (a rational number for
                   1124: instance).
                   1125:
                   1126: The real zero is characterized by having its sign equal to 0. However,
                   1127: usually the first mantissa word \kbd{z[2]} is defined and equal to~0. This
                   1128: fact must {\it never\/} be used to recognize a real~0. If \kbd{z} is not equal
                   1129: to~0, the first mantissa word \kbd{z[2]} is normalized, i.e.~its most
                   1130: significant bit is~1. The mantissa is (\kbd{z[2]},\kbd{z[3]},\dots,%
                   1131: \kbd{z[lg(z]-1]}) in base \kbd{2\pow BITS\_IN\_LONG}. Here, \kbd{z[2]} is
                   1132: the most significant longword, and the mantissa takes values between
                   1133: 1 (included) and 2 (excluded). Thus, assume that \kbd{sizeof(long)} is 32 and
                   1134: the length is 4, the real number $3.5$ is represented as \kbd{z[0]} (encoding
                   1135: $\kbd{type} = \typ{REAL}$, $\kbd{lg} = 4$), \kbd{z[1]} (encoding $\kbd{sign} =
                   1136: 1$, $\kbd{expo} = 1$), $\kbd{z[2]} = \kbd{0xe0000000}$,
                   1137: $\kbd{z[3]} = \kbd{0x0}$.
                   1138:
                   1139: \sectype{INTMOD}{integermod} \kbd{z[1]} points to the modulus, and \kbd{z[2]}
                   1140: at the number representing the class \kbd{z}. Both are separate \kbd{GEN}
                   1141: objects, and both must be of type integer.
                   1142: In principle \kbd{z[1]} $>$ 0 and 0 $\le$ \kbd{z[2]} $<$ \kbd{z[1]}, but this
                   1143: rule does not have to be strictly obeyed by the user. Any integermod obtained
                   1144: as the result of a PARI function call will satisfy these conditions.
                   1145:
                   1146: It is good practice to keep the modulus object on the heap, so that new
                   1147: integermods resulting from operations can point at this common object,
                   1148: instead of carrying along their own copies of it on the stack. The library
                   1149: functions implement this practice almost by default.
                   1150:
                   1151: \sectypes{FRAC}{FRACN}{rational number} \kbd{z[1]} points to the numerator,
                   1152: and \kbd{z[2]} to the denominator. Both must be of type integer. In principle
                   1153: $\kbd{z[2]} > 0$, but this rule does not have to be strictly obeyed. Note
                   1154: that a type \typ{FRACN} rational number can be converted to irreducible
                   1155: form using the function \kbd{GEN \teb{gred}(GEN x)}.
                   1156:
                   1157: \sectype{COMPLEX}{complex number} \kbd{z[1]} points to the real part, and
                   1158: \kbd{z[2]} to the imaginary part. A priori \kbd{z[1]} and \kbd{z[2]} can be
                   1159: of any type, but only certain types are useful and make sense.
                   1160:
                   1161: \sectypeindex{PADIC}{$p$-adic numbers}{p-adic number} this type has a second
                   1162: codeword \kbd{[1]} which contains the following information: the $p$-adic
                   1163: precision (the exponent of $p$ modulo which the $p$-adic unit corresponding
                   1164: to \kbd{z} is defined if \kbd{z} is not~0), i.e.~one less than the number
                   1165: of significant $p$-adic digits, and the biased exponent of \kbd{z} (the
                   1166: bias being equal to \kbd{HIGHVALPBIT} here). This information can be
                   1167: handled using the following functions:
                   1168:
                   1169: \kbd{long \teb{precp}(GEN z)} returns the $p$-adic precision of
                   1170: \kbd{z}.
                   1171:
                   1172: \kbd{void \teb{setprecp}(GEN z, long l)} sets the $p$-adic precision
                   1173: of \kbd{z} to \kbd{l}.
                   1174:
                   1175: \kbd{long \teb{valp}(GEN z)} returns the $p$-adic valuation of
                   1176: \kbd{z} (i.e. the unbiased exponent). This is defined even if \kbd{z} is
                   1177: equal to~0, see \secref{se:whatzero}.
                   1178:
                   1179: \kbd{void \teb{setvalp}(GEN z, long e)} sets the $p$-adic valuation
                   1180: of \kbd{z} to \kbd{e}.
                   1181:
                   1182: In addition to this codeword, \kbd{z[2]} points to the prime $p$, \kbd{z[3]}
                   1183: points to $p^{\text{precp(z)}}$, and \kbd{z[4]} points to an integer
                   1184: representing the $p$-adic unit associated to \kbd{z} modulo \kbd{z[3]} (or
                   1185: points to zero if \kbd{z} is zero). To summarize, we have the equality:
                   1186: $$ \kbd{z} = p^{\text{valp(z)}} * (\kbd{z[4]} + O(\kbd{z[3]})) =
                   1187:      p^{\text{valp(z)}} * (\kbd{z[4]} + O(p^{\text{precp(z)}})) $$
                   1188:
                   1189: \sectype{QUAD}{quadratic number} \kbd{z[1]} points to the polynomial defining
                   1190: the quadratic field, \kbd{z[2]} to the ``real part'' and \kbd{z[3]} to the
                   1191: ``imaginary part'', which are to be taken as the coefficients of \kbd{z} with
                   1192: respect to the ``canonical'' basis $(1,w)$, see~\secref{se:compquad}. Complex
                   1193: numbers are a particular case of quadratics but deserve a separate type.
                   1194:
                   1195: \sectype{POLMOD}{polmod} exactly as for integermods, \kbd{z[1]} points to
                   1196: the modulus, and \kbd{z[2]} to a polynomial representing the class of~\kbd{z}.
                   1197: Both must be of type polynomial. However, one must obey the rules
                   1198: explained in Chapter 2 concerning the hierarchical structure of the variables
                   1199: of a polymod.
                   1200:
                   1201: \sectype{POL}{polynomial} this type has a second codeword which is analogous
                   1202: to the one for integers. It contains a ``{\it sign\/}'': 0 if the polynomial
                   1203: is equal to~0, and 1 if not (see however the important remark below), a {\it
                   1204: variable number\/} (e.g.~0 for $x$, 1 for $y$, etc\dots), and an {\it
                   1205: effective length}.
                   1206:
                   1207: \noindent These data can be handled with the following macros:
                   1208:
                   1209: \teb{signe} and \teb{setsigne} as for reals and integers.
                   1210:
                   1211: \kbd{long \teb{lgef}(GEN z)} returns the \idx{effective length} of \kbd{z}.
                   1212:
                   1213: \kbd{void \teb{setlgef}(GEN z, long l)} sets the effective length
                   1214: of \kbd{z} to \kbd{l}.
                   1215:
                   1216: \kbd{long \teb{varn}(GEN z)} returns the variable number of the object \kbd{z}.
                   1217:
                   1218: \kbd{void \teb{setvarn}(GEN z, long v)} sets the variable number
                   1219: of \kbd{z} to \kbd{v}.
                   1220:
                   1221: Note also the function \kbd{long \teb{gvar}(GEN z)} which tries
                   1222: to return a \idx{variable number} for \kbd{z}, even if \kbd{z} is not a
                   1223: polynomial or power series. The variable number of a scalar type is set by
                   1224: definition equal to \tet{BIGINT}.
                   1225:
                   1226: The components \kbd{z[2]}, \kbd{z[3]},\dots \kbd{z[lgef(z)-1]} point to the
                   1227: coefficients of the polynomial {\it in ascending order}, with \kbd{z[2]}
                   1228: being the constant term and so on. Note that the {\it \idx{degree}\/} of the
                   1229: polynomial is equal to its effective length minus three. The function
                   1230:
                   1231: \kbd{long \teb{degree}(GEN x)} returns the degree of \kbd{x} with
                   1232: respect to its main variable even when \kbd{x} is not a polynomial (a
                   1233: rational function for instance). By convention, the degree of $0$ is~$-1$.
                   1234:
                   1235: \misctitle{Important remark}. A zero polynomial can be characterized by the
                   1236: fact that its sign is~0. However, its effective length may be equal to 2, or
                   1237: greater than 2. If it is greater than 2, this means that all the coefficients
                   1238: of the polynomial are equal to zero (as they should for a zero polynomial),
                   1239: but not all of these zeros are exact zeros, and more precisely the leading
                   1240: term \kbd{z[lgef(z)-1]} is not an exact zero.
                   1241:
                   1242: \sectypeindex{SER}{power series}{power series} This type also has a second
                   1243: codeword, which encodes a ``{\it sign\/}'', i.e.~0 if the power series is 0,
                   1244: and 1 if not, a {\it variable number\/} as for polynomials, and a {\it biased
                   1245: exponent\/} with a bias of \kbd{HIGHVALPBIT}. This information can be handled
                   1246: with the following functions: \teb{signe}, \teb{setsigne}, \teb{varn},
                   1247: \teb{setvarn} as for polynomials, and \teb{valp}, \teb{setvalp} for the
                   1248: exponent as for $p$-adic numbers. Beware: do {\it not\/} use \teb{expo} and
                   1249: \teb{setexpo} on power series.
                   1250:
                   1251: If the power series is non-zero, \kbd{z[2]}, \kbd{z[3]},\dots
                   1252: \kbd{z[lg(z)-1]} point to the coefficients of \kbd{z} in ascending order,
                   1253: \kbd{z[2]} being the first non-zero coefficient.  Note that the exponent of a
                   1254: power series can be negative, i.e.~we are then dealing with a Laurent series
                   1255: (with a finite number of negative terms).
                   1256:
                   1257: \sectypes{RFRAC}{RFRACN}{rational function} \kbd{z[1]} points to the
                   1258: numerator, and \kbd{z[2]} on the denominator. Both must be of type
                   1259: polynomial. Note that a type \typ{RFRACN} rational function can be
                   1260: converted to irreducible form using the function \teb{gred}.
                   1261:
                   1262: \sectype{QFR}{indefinite binary quadratic form} \kbd{z[1]}, \kbd{z[2]},
                   1263: \kbd{z[3]} point to the three coefficients of the form and should be of type
                   1264: integer. \kbd{z[4]} is Shanks's distance function, and should be of type
                   1265: real.
                   1266:
                   1267: \sectype{QFI}{definite binary quadratic form} \kbd{z[1]}, \kbd{z[2]},
                   1268: \kbd{z[3]} point to the three coefficients of the form. All three should be of
                   1269: type integer.
                   1270:
                   1271: \sectypes{VEC}{COL}{vector}\sidx{row vector}\sidx{column vector}
                   1272: \kbd{z[1]}, \kbd{z[2]},\dots \kbd{z[lg(z)-1]}
                   1273: point to the components of the vector.
                   1274:
                   1275: \sectypeindex{MAT}{matrices}{matrix} \kbd{z[1]}, \kbd{z[2]},\dots
                   1276: \kbd{z[lg(z)-1]} point to the column vectors of \kbd{z}, i.e.~they must be of
                   1277: type \typ{COL} and of the same length.
                   1278:
                   1279: \noindent The last two were introduced for specific GP use, and you'll be
                   1280: much better off using the standard malloc'ed C constructs when programming
                   1281: in library mode. We quote them just for completeness (advising you not to
                   1282: use them):
                   1283:
                   1284: \sectype{LIST}{list} This one has a second codeword which contains an
                   1285: effective length (handled through \teb{lgef}~/ \teb{setlgef}).
                   1286: \kbd{z[2]},\dots, \kbd{z[lgef(z)-1]} contain the components of the list.
                   1287:
                   1288: \sectype{STR}{character string} \kbd{\teb{GSTR}(z)} (= \kbd{(z+1)}) points to
                   1289: the first character of the (\kbd{NULL}-terminated) string.
                   1290:
                   1291: \section{PARI variables}\label{se:vars}
                   1292: \subsec{Multivariate objects}
                   1293:
                   1294: \noindent
                   1295: We now consider variables and formal computations. As we have seen in
                   1296: \secref{se:impl}, the codewords for types \typ{POL} and \typ{SER}
                   1297: encode a ``variable number''. This is an integer, ranging from $0$ to
                   1298: \kbd{MAXVARN}. The lower it is, the higher the variable priority. PARI does
                   1299: not know anything about intelligent ``sparse'' representation of polynomials.
                   1300: So a multivariate polynomial in PARI is just a polynomial (in one variable),
                   1301: whose coefficients are themselves (arbitrary) polynomials. All computations
                   1302: are then just done formally on the coefficients as if the polynomial was
                   1303: univariate.
                   1304:
                   1305: In fact, the way an object will be considered in formal computations depends
                   1306: entirely on its ``principal variable number'' which is given by the function
                   1307:
                   1308: \kbd{long \teb{gvar}(GEN z)}
                   1309:
                   1310: \noindent which returns a \idx{variable number} for \kbd{z}, even if \kbd{z}
                   1311: is not a polynomial or power series. The variable number of a scalar type is
                   1312: set by definition equal to \tet{BIGINT} which is bigger than any legal
                   1313: variable number. The variable number of a recursive type which is not a
                   1314: polynomial or power series is the minimal variable number of its components.
                   1315: But for polynomials and power series only the ``outermost'' number counts:
                   1316: the representation is not symmetrical at all.
                   1317:
                   1318: Under GP, one need not worry too much since the interpreter will define
                   1319: the variables as it sees them and do the right thing with the polynomials
                   1320: produced (however, have a look at the remark in \secref{se:rempolmod}). But
                   1321: in library mode, they are tricky objects if you intend to build polynomials
                   1322: yourself (and not just let PARI functions produce them, which is usually less
                   1323: efficient). For instance, it does not make sense to have a variable number
                   1324: occur in the components of a polynomial whose main variable has a higher
                   1325: number (lower priority), even though there's nothing PARI can do to prevent
                   1326: you from doing it.
                   1327:
                   1328: \subsec{Creating variables}
                   1329: A basic difficulty is to ``create'' a variable. As we have seen in
                   1330: \secref{se:intro4}, a plethora of objects is associated to variable
                   1331: number~$v$. Here is the complete list: \teb{polun}$[v]$ and
                   1332: \teb{polx}$[v]$, which you can use in library mode and which represent,
                   1333: respectively, the monic monomials of degrees 0 and 1 in~$v$;
                   1334: \teb{varentries}$[v]$, and \teb{polvar}$[v]$. The latter two are only
                   1335: meaningful to GP, but they have to be set nevertheless. All of them must be
                   1336: properly defined before you can use a given integer as a variable number.
                   1337:
                   1338: Initially, this is done for $0$ (the variable \kbd{x} under GP), and
                   1339: \tet{MAXVARN}, which is there to address the need for a ``temporary'' new
                   1340: variable, which would not be used in regular objects (created by the
                   1341: library). We call the latter type a ``temporary variable''. The regular
                   1342: variables meant to be used in regular objects, are called ``user
                   1343: variables\sidx{variable (user)}''.
                   1344:
                   1345: \subsubsec{User variables}\sidx{variable (user)}:
                   1346: When the program starts, \kbd{x} is the only user variable (number~$0$). To
                   1347: define new ones, use
                   1348:
                   1349: \kbd{long \key{fetch\_user\_var}(char *$s$)}%
                   1350: \sidx{fetch\string\_user\string\_var}
                   1351:
                   1352: \noindent which inspects the user variable named $s$ (creating it if
                   1353: needed), and returns its variable number.
                   1354: \bprog%
                   1355: long v = fetch\_user\_var("y");
                   1356: GEN gy = polx[v];
                   1357: \eprog
                   1358: This function raises an error if $s$ is already known as a function name to
                   1359: the interpreter.
                   1360:
                   1361: \misctitle{Caveat:} it is possible to use \teb{flissexpr}
                   1362: (see~\secref{se:flisexpr}) to execute a GP command and create GP variables
                   1363: on the fly as needed:
                   1364:
                   1365: \bprog%
                   1366: GEN gy = flissexpr("y"); /* supposedly returns polx[$v$], for some $v$ */
                   1367: long v = gvar(gy);
                   1368: \eprog
                   1369:
                   1370: \noindent This is dangerous, especially when programming functions that
                   1371: will be used under GP. The code above reads the value of \kbd{y}, as it is
                   1372: currently known by the GP interpreter (possibly creating it in the
                   1373: process). All is well and good if \kbd{y} hasn't been tampered with in
                   1374: previous GP commands. But if \kbd{y} has been modified (e.g \kbd {y = 1}),
                   1375: then the value of \kbd{gy} is not what you expected it to be and corresponds
                   1376: instead to the current value of the GP variable (e.g \kbd{gun}).
                   1377:
                   1378: \subsubsec{Temporary variables}\sidx{variable (temporary)}:
                   1379: \kbd{MAXVARN} should be enough for most cases, but you can create more
                   1380: temporary variables using
                   1381:
                   1382: \kbd{long \key{fetch\_var}()}\sidx{fetch\string\_var}\label{se:fetch_var}
                   1383:
                   1384: \noindent
                   1385: This returns a variable number which is guaranteed to be unused by the
                   1386: library at the time you get it and as long as you do not delete it (we'll see
                   1387: how to do that shortly). This has {\it lower\/} number (i.e.~{\it higher\/}
                   1388: priority) than any temporary variable produced so far (\kbd{MAXVARN} is
                   1389: assumed to be the first such). This call updates all the aforementioned
                   1390: internal arrays. In particular, after the statement \kbd{v = fetch\_var()},
                   1391: you can use \kbd{polun[v]} and \kbd{polx[v]}. The variables created in this
                   1392: way have no identifier assigned to them though, and they will be printed as
                   1393: \kbd{\#<\text{number}>}, except for \kbd{MAXVARN} which will be printed
                   1394: as~\kbd{\#}. You can assign a name to a temporary variable, after creating
                   1395: it, by calling the function
                   1396:
                   1397: \kbd{void \key{name\_var}(long n, char *s)}\sidx{name\string\_var}
                   1398:
                   1399: \noindent after which the output machinery will use the name \kbd{s} to
                   1400: represent the variable number~\kbd{n}. The GP parser will {\it not\/}
                   1401: recognize it by that name, however, and calling this on a variable known
                   1402: to~GP will raise an error. Temporary variables are meant to be used as free
                   1403: variables, and you should never assign values or functions to them as you
                   1404: would do with variables under~GP. For that, you need a user variable.
                   1405:
                   1406: All objects created by \kbd{fetch\_var} are on the heap and not on the stack,
                   1407: thus they are not subject to standard garbage collecting (they won't be
                   1408: destroyed by a \kbd{gerepile} or \kbd{avma = ltop} statement). When you don't
                   1409: need a variable number anymore, you can delete it using
                   1410:
                   1411: \kbd{long \key{delete\_var}()}\sidx{delete\string\_var}
                   1412:
                   1413: \noindent which deletes the {\it latest\/} temporary variable created and
                   1414: returns the variable number of the previous one (or simply returns 0 if you
                   1415: try, in vain, to delete \kbd{MAXVARN}). Of course you should make sure that
                   1416: the deleted variable does not appear anywhere in the objects you use later
                   1417: on. Here is an example:
                   1418:
                   1419: \bprog\obr
                   1420: \q  long first = fetch\_var();
                   1421: \q  long n1 = fetch\_var();
                   1422: \q  long n2 = fetch\_var(); /* prepare three variables for internal use */
                   1423: \q  ...
                   1424: \q  /* delete all variables before leaving */
                   1425: \q  do \obr\ num = delete\_var(); \cbr\ while (num \&\& num <= first);
                   1426: \cbr\eprog
                   1427:
                   1428: \noindent
                   1429: The (dangerous) statement
                   1430:
                   1431: \bprog%
                   1432: while (delete\_var()) /* empty */;
                   1433: \eprog
                   1434:
                   1435: \noindent removes all temporary variables that were in use, except
                   1436: \kbd{MAXVARN} which cannot be deleted.
                   1437:
                   1438: \section{Input and output}
                   1439:
                   1440: \noindent
                   1441: Two important aspects have not yet been explained which are specific to
                   1442: library mode: input and output of PARI objects.
                   1443:
                   1444: \subsec{Input}.
                   1445:
                   1446: \noindent
                   1447: For \idx{input}, PARI provides you with two powerful high level functions
                   1448: which enables you to input your objects as if you were under GP. In fact,
                   1449: the second one {\it is\/} essentially the GP syntactical parser, hence you
                   1450: can use it not only for input but for (most) computations that you can do
                   1451: under GP. These functions are called \teb{flisexpr} and \teb{flisseq}. The
                   1452: first one has the following syntax:\label{se:flisexpr}
                   1453:
                   1454: \kbd{GEN \teb{flisexpr}(char *s)}
                   1455:
                   1456: \noindent
                   1457: Its effect is to analyze the input string s and to compute the result as in
                   1458: GP.  However it is limited to one expression. If you want to read and
                   1459: evaluate a sequence of expressions, use
                   1460:
                   1461: \kbd{GEN \teb{flisseq}(char *s)}
                   1462:
                   1463: \noindent\sidx{filter}
                   1464: In fact these two functions start by {\it filtering\/} out all spaces and
                   1465: comments in the input string (that's what the initial \kbd{f} stands for).
                   1466: They then call the underlying basic functions, the GP parser proper: \kbd{GEN
                   1467: \teb{lisexpr}(char *s)} and \kbd{GEN \teb{lisseq}(char *s)}, which are
                   1468: slightly faster but which you probably don't need.
                   1469:
                   1470: To read a \kbd{GEN} from a file, you can use the simpler interface
                   1471:
                   1472: \kbd{GEN \teb{lisGEN}(FILE *file)}
                   1473:
                   1474: which reads a character string of arbitrary length from the stream \kbd{file}
                   1475: (up to the first newline character), applies \kbd{flisexpr} to it, and
                   1476: returns the resulting \kbd{GEN}. This way, you won't have to worry about
                   1477: allocating buffers to hold the string. To interactively input an expression,
                   1478: use \kbd{lisGEN(stdin)}.
                   1479:
                   1480: Once in a while, it may be necessary to evaluate a GP expression sequence
                   1481: involving a call to a function you have defined in~C. This is easy using
                   1482: \teb{install} which allows you to manipulate quite an arbitrary function (GP
                   1483: knows about pointers!). The syntax is
                   1484:
                   1485: \kbd{void \teb{install}(void *f, char *name, char *code)}
                   1486:
                   1487: \noindent where \kbd{f} is the (address of) the function (cast to the C type
                   1488: \kbd{void*}), \kbd{name} is the name by which you want to access your
                   1489: function from within your GP expressions, and \kbd{code} is a character
                   1490: string describing the function call prototype (see~\secref{se:gp.interface}
                   1491: for the precise description of prototype strings). In case the function
                   1492: returns a \kbd{GEN}, it should satisfy \kbd{gerepileupto} assumptions (see
                   1493: \secref{se:garbage}).
                   1494:
                   1495: \subsec{Output}.
                   1496:
                   1497: \noindent
                   1498: For \idx{output}, there exist essentially three different functions (with
                   1499: variants), corresponding to the three main GP output formats (as described in
                   1500: \secref{se:output}), plus three extra ones, respectively devoted to
                   1501: \TeX\ output, string output, and (advanced) debugging.
                   1502:
                   1503: \noindent $\bullet$ ``raw'' format, obtained by using the function
                   1504: \teb{brute} with the following syntax:
                   1505:
                   1506: \kbd{void \teb{brute}(GEN obj, char x, long n);}
                   1507:
                   1508: \noindent
                   1509: This prints the PARI object \kbd{obj} in \idx{format} \kbd{x0.n}, using the
                   1510: notations from \secref{se:format}. Recall that here \kbd{x} is either
                   1511: \kbd{'e'}, \kbd{'f'} or \kbd{'g'} corresponding to the three numerical output
                   1512: formats, and \kbd{n} is the number of printed significant digits, and should
                   1513: be set to $-1$ if all of them are wanted (these arguments only affect the
                   1514: printing of real numbers). Usually you won't need that much flexibility, so
                   1515: most of the time you will get by with the function
                   1516:
                   1517: \kbd{void \teb{outbrute}(GEN obj)}, which is equivalent to
                   1518: \kbd{brute(x,'g',-1)},
                   1519:
                   1520: \noindent or even better, with
                   1521:
                   1522: \kbd{void \teb{output}(GEN obj)} which is equivalent to \kbd{outbrute(obj)}
                   1523: followed by a newline and a buffer flush. This is especially nice during
                   1524: debugging. For instance using \kbd{dbx} or \kbd{gdb}, if \kbd{obj} is a
                   1525: \kbd{GEN}, typing \kbd{print output(obj)} will enable you to see the content
                   1526: of \kbd{obj} (provided the optimizer has not put it into a register, but it's
                   1527: rarely a good idea to debug optimized code).
                   1528:
                   1529: \noindent $\bullet$ ``prettymatrix'' format: this format is identical to the
                   1530: preceding one except for matrices. The relevant functions are:
                   1531:
                   1532: \kbd{void \teb{matbrute}(GEN obj, char x, long n)}
                   1533:
                   1534: \kbd{void \teb{outmat}(GEN obj)}, which is followed by a newline
                   1535: and a buffer flush.
                   1536:
                   1537: \noindent $\bullet$ ``prettyprint'' format: the basic function has an
                   1538: additional parameter \kbd{m}, corresponding to the (minimum) field width
                   1539: used for printing integers:
                   1540:
                   1541: \kbd{void \teb{sor}(GEN obj, char x, long n, long m)}
                   1542:
                   1543: \noindent The simplified version is
                   1544:
                   1545: \kbd{void \teb{outbeaut}(GEN obj)} which is equivalent to
                   1546: \kbd{sor(obj,'g',-1,0)} followed by a newline and a buffer flush.
                   1547:
                   1548: \noindent $\bullet$ The first extra format corresponds to the \teb{texprint}
                   1549: function of GP, and gives a \TeX{} output of the result. It is obtained by
                   1550: using:
                   1551:
                   1552: \kbd{void \teb{texe}(GEN obj, char x, long n)}
                   1553:
                   1554: \noindent $\bullet$ The second one is the function \teb{GENtostr} which
                   1555: converts a PARI \kbd{GEN} to an ASCII string. The syntax is
                   1556:
                   1557: \kbd{char* \teb{GENtostr}(GEN obj)}, wich returns a
                   1558: \kbd{malloc}'ed character string (which you should \kbd{free} after use).
                   1559:
                   1560: \noindent $\bullet$ The third and final one outputs the \idx{hexadecimal tree}
                   1561: corresponding to the GP command \kbd{\b x} using the function
                   1562:
                   1563: \kbd{void \teb{voir}(GEN obj, long nb)}, which will only output the first
                   1564: \kbd{nb} words corresponding to leaves (very handy when you have a look at
                   1565: big recursive structures). If you set this parameter to $-1$ all significant
                   1566: words will be printed. Usually this last type of output would only be used for
                   1567: debugging purposes.
                   1568:
                   1569: \misctitle{Remark}. Apart from \teb{GENtostr}, all PARI output is done on
                   1570: the stream \teb{outfile}, which by default is initialized to \teb{stdout}. If
                   1571: you want that your output be directed to another file, you should use the
                   1572: function \kbd{void \teb{switchout}(char *name)} where \kbd{name} is a
                   1573: character string giving the name of the file you are going to use. The
                   1574: output will be {\it appended\/} at the end of the file. In order to close
                   1575: the file, simply call \kbd{switchout(NULL)}.
                   1576:
                   1577: Similarly, errors are sent to the stream \teb{errfile} (\teb{stderr}
                   1578: by default), and input is done on the stream \teb{infile}, which you can change
                   1579: using the function \teb{switchin} which is analogous to \teb{switchout}.
                   1580:
                   1581: \misctitle{(Advanced) Remark}. All output is done according to the values
                   1582: of the \teb{pariOut}~/ \teb{pariErr} global variables which are pointers to
                   1583: structs of pointer to functions. If you really intend to use these, this
                   1584: probably means you are rewriting GP. In that case, have a look at the code in
                   1585: \kbd{language/es.c} (\kbd{init80()} or \kbd{GENtostr()} for instance).
                   1586:
                   1587: \subsec{Errors}.\sidx{error}\sidx{talker}
                   1588:
                   1589: \noindent
                   1590: If you want your functions to issue error messages, you can use the general
                   1591: error handling routine \teb{err}. The basic syntax is
                   1592: %
                   1593: \bprog%
                   1594:   err(talker, "error message");
                   1595: \eprog
                   1596:
                   1597: \noindent
                   1598: This will print the corresponding error message and exit the program (in
                   1599: library mode; go back to the GP prompt otherwise).\label{se:err} You can
                   1600: also use it in the more versatile guise
                   1601: \bprog%
                   1602:   err(talker, format, ...);
                   1603: \eprog\noindent
                   1604: where \kbd{format} describes the format to use to write the remaining
                   1605: operands, as in the \teb{printf} function (however, see the next section).
                   1606: The simple syntax above is just a special case with a constant format and no
                   1607: remaining arguments.
                   1608:
                   1609: \noindent
                   1610: The general syntax is
                   1611:
                   1612: \kbd{void \teb{err}(numerr,...)}
                   1613:
                   1614: \noindent where \kbd{numerr} is a codeword which indicates what to do with
                   1615: the remaining arguments and what message to print. The list of valid keywords
                   1616: is in \kbd{language/errmessages.c} together with the basic corresponding
                   1617: message. For instance, \kbd{err(typeer,"matexp")} will print the message:
                   1618:
                   1619: \kbd{ ***   incorrect type in matexp.}
                   1620:
                   1621: \noindent
                   1622: Among the codewords are {\it warning\/} keywords (all those which start with
                   1623: the prefix \kbd{warn}). In that case, \teb{err} does {\it not\/} abort the
                   1624: computation, just print the requested message and go on. The basic example is
                   1625:
                   1626: \kbd{err(warner, "Strategy 1 failed. Trying strategy 2")}
                   1627:
                   1628: \noindent which is the exact equivalent of \kbd{err(talker,...)} except that
                   1629: you certainly don't want to stop the program at this point, just inform the
                   1630: user that something important has occured (in particular, this output would be
                   1631: suitably highlighted under GP, whereas a simple \kbd{printf} would not).
                   1632:
                   1633: \subsec{Debugging output}.\sidx{debugging}\sidx{format}\label{se:dbg_output}
                   1634:
                   1635: \noindent
                   1636: The global variables \teb{DEBUGLEVEL} and \teb{DEBUGMEM} (corresponding
                   1637: to the default \teb{debug} and \teb{debugmem}, see \secref{se:defaults})
                   1638: are used throughout the PARI code to govern the amount of diagnostic and
                   1639: debugging output, depending on their values. You can use them to debug your
                   1640: own functions, especially after having made them accessible under GP through
                   1641: the command \teb{install} (see \secref{se:install}).
                   1642:
                   1643: For debugging output, you can use \kbd{printf} and the standard output
                   1644: functions (\teb{brute} or \teb{output} mainly), but also some special purpose
                   1645: functions which embody both concepts, the main one being
                   1646:
                   1647: \kbd{void \teb{fprintferr}(char *pariformat, ...)}
                   1648:
                   1649: \noindent
                   1650: Now let's define what a PARI format is. It is a character string, similar
                   1651: to the one \kbd{printf} uses, where \kbd{\%} characters have a special
                   1652: meaning. It describes the format to use when printing the remaining operands.
                   1653: But, in addition to the standard format types, you can use \kbd{\%Z} to
                   1654: denote a \kbd{GEN} object (we would have liked to pick \kbd{\%G} but it was
                   1655: already in use!). For instance you could write:
                   1656:
                   1657: \kbd{err(talker, "x[\%d] = \%Z is not invertible!", i, x[i])},
                   1658:
                   1659: \noindent since the \teb{err} function accepts PARI formats. Here \kbd{i} is an
                   1660: \kbd{int}, \kbd{x} a \kbd{\idx{GEN}} which is not a leaf and this would
                   1661: insert in raw format the value of the \kbd{GEN} \kbd{x[i]}.
                   1662:
                   1663: \subsec{Timers and timing output}.
                   1664:
                   1665: \noindent
                   1666: To profile your functions, you can use the PARI timer. The functions
                   1667: \kbd{long \teb{timer}()} and \kbd{long \teb{timer2}()} return the
                   1668: elapsed time since the last call of the same function (in milliseconds). Two
                   1669: different functions (identical except for their independent time-of-last-call
                   1670: memories!) are provided so you can have both global timing and fine tuned
                   1671: profiling.
                   1672:
                   1673: You can also use \kbd{void \teb{msgtimer}(char *format,...)},
                   1674: which prints prints \kbd{Time}, then the remaining arguments as specified by
                   1675: \kbd{format} (which is a PARI format), then the output of \kbd{timer2}.
                   1676:
                   1677: \section{A complete program}
                   1678: \label{se:prog}
                   1679:
                   1680: \noindent
                   1681: Now that the preliminaries are out of the way, the best way to learn how to
                   1682: use the library mode is to work through a detailed non-trivial example of a
                   1683: main program. We will write a program which computes the exponential of a
                   1684: square matrix~$x$.  The complete listing is given in Appendix~B, but each
                   1685: part of the program will be produced and explained here. We will use an
                   1686: algorithm which is not optimal but is not far from the one used for the PARI
                   1687: function \teb{gexp} (in fact embodied in the function \kbd{mpexp1}). This
                   1688: consists in calculating the sum of the series:
                   1689: $$e^{x/(2^n)}=\sum_{k=0}^\infty \dfrac{(x/(2^n))^k}{k!}$$
                   1690: for a suitable positive integer $n$, and then computing $e^x$ by repeated
                   1691: squarings.  First, we will need to compute the $L^2$-norm of the matrix~$x$,
                   1692: i.e.~the quantity:
                   1693: $$z=\|x\|_2=\sqrt{\sum_{i,j}x_{i,j}^2}.$$
                   1694: We will then choose the integer $n$ such that the $L^2$-norm of $x/(2^n)$ is
                   1695: less than or equal to~1, i.e.
                   1696: $$ n = \left\lceil{\ln(z)}\big/{\ln(2)}\right\rceil $$
                   1697: if $z\ge1$, and~$n=0$ otherwise. Then the series will converge at least as
                   1698: fast as the usual one for $e^1$, and the cutoff error will be easy to
                   1699: estimate. In fact a larger value of $n$ would be preferable, but this is
                   1700: slightly machine dependent and more complicated, and will be left to the
                   1701: reader.
                   1702:
                   1703: Let us start writing our program. So as to be able to use it in other
                   1704: contexts, we will structure it in the following way: a main program which
                   1705: will do the input and output, and a function which we shall call \kbd{matexp}
                   1706: which does the real work. The main program is easy to write. It can be
                   1707: something like this:
                   1708:
                   1709: \bprog%
                   1710: \#include <pari.h>
                   1711: \h
                   1712: GEN matexp(GEN x, long prec);
                   1713: \h
                   1714: int
                   1715: main()
                   1716: \obr
                   1717: \q long d, prec = 3;
                   1718: \q GEN x;
                   1719: \h
                   1720: \q /* take a stack of a 10\pow 6 bytes, no prime table */
                   1721: \q pari\_init(1000000,2);
                   1722: \q printf("precision of the computation in decimal digits:\bs n");
                   1723: \q d = itos(lisGEN(stdin));
                   1724: \q if (d > 0) prec = (long) (d*pariK1+3);
                   1725: \h
                   1726: \q printf("input your matrix in GP format:\bs n");
                   1727: \q x = matexp(lisGEN(stdin), prec);
                   1728: \h
                   1729: \q sor(x,'g',d,0);
                   1730: \q exit(0);
                   1731: \cbr\eprog
                   1732: \noindent
                   1733: The variable \kbd{prec} represents the length in longwords of the real
                   1734: numbers used. \teb{pariK1} is a constant (defined in \kbd{paricom.h}) equal
                   1735: to $\ln(10) / (\ln(2) * \kbd{BITS\_IN\_LONG})$, which allows us to convert
                   1736: from a number of decimal digits to a number of longwords, independently of
                   1737: the actual bit size of your long integers. The function \teb{lisGEN} reads an
                   1738: expression (here from standard input) and converts it to a \kbd{GEN}, like
                   1739: the GP parser itself would. This means it takes care of whitespace etc.\ in
                   1740: the input, and can do computations (e.g.~\kbd{matid(2)} or \kbd{[1,0; 0,1]}
                   1741: are equally valid inputs).
                   1742:
                   1743: Finally, \kbd{sor} is the general output routine. We have chosen to give
                   1744: \kbd{d} significant digits since this is what was asked for. Note that there
                   1745: is a trick hidden here: if a negative \kbd{d} was input, then the computation
                   1746: will be done in precision 3 (i.e.~about 9.7 decimal digits for 32-bit
                   1747: machines and 19.4 for 64-bit machines) and in the function \kbd{sor}, giving
                   1748: a negative third argument outputs all the significant digits, which is entirely
                   1749: appropriate. Now let us attack the main course, the function \kbd{matexp}:
                   1750: %
                   1751: \bprog%
                   1752: GEN
                   1753: matexp(GEN x, long prec)
                   1754: \obr
                   1755: \q  long lx=lg(x),i,k,n,lbot, ltop = avma;
                   1756: \q  GEN y,r,s,p1,p2;
                   1757: \h
                   1758: \q /* check that x is a square matrix */
                   1759: \q if (typ(x) != t\_MAT) err(talker,"this expression is not a matrix");
                   1760: \q if (lx == 1) return cgetg(1, t\_MAT);
                   1761: \q if (lx != lg(x[1])) err(talker,"not a square matrix");
                   1762: \h
                   1763: \q /* compute the L2 norm of x */
                   1764: \q s = gzero;
                   1765: \q for (i=1; i<lx; i++)
                   1766: \q\q s = gadd(s, gnorml2((GEN)x[i]));
                   1767: \q if (typ(s) == t\_REAL) setlg(s,3);
                   1768: \q s = gsqrt(s,3); /* we do not need much precision on s */
                   1769: \h
                   1770: \q /* if s<1, we are happy */
                   1771: \q k = expo(s);
                   1772: \q if (k < 0) \obr\ n = 0; p1 = x; \cbr
                   1773: \q else \obr\ n = k+1; p1 = gmul2n(x,-n); setexpo(s,-1); \cbr\eprog
                   1774: \noindent
                   1775: Before continuing, several remarks are in order.
                   1776:
                   1777: First, before starting this computation which will produce garbage on the
                   1778: stack, we have carefully saved the value of the stack pointer \kbd{avma} in
                   1779: \kbd{ltop}. Note that we are going to assume throughout that the garbage does
                   1780: not overflow the currently available stack. If it ever did, we would
                   1781: have several options~--- allocate a larger stack in the main program (for
                   1782: instance change 1000000 into 2000000), do some \kbd{gerepile}ing along the
                   1783: way, or (if you know what you are doing) use \tet{allocatemoremem}.
                   1784:
                   1785: Secondly, the \teb{err} function is the general error handler for the
                   1786: PARI library. This will abort the program after printing the required
                   1787: message.
                   1788:
                   1789: Thirdly, notice how we handle the special case $\kbd{lx} = 1$ (empty matrix)
                   1790: {\it before\/} accessing \kbd{lx(x[1])}. Doing it the other way round could
                   1791: produce a fatal error (a segmentation fault or a bus error, most probably).
                   1792: Indeed, if \kbd{x} is of length 1, then \kbd{x[1]} is not a component of
                   1793: \kbd{x}. It is just the contents of the memory cell which happens to follow
                   1794: the one pointed to by \kbd{x}, and thus has no reason to be a valid \kbd{GEN}.
                   1795: Now recall that none of the codeword handling macros do any kind of type
                   1796: checking (see \secref{se:impl}), thus \teb{lg} would consider \kbd{x[1]}
                   1797: as a valid address, and try to access \kbd{*((GEN)x[1])} (the first codeword)
                   1798: which is unlikely to be a legal memory address.
                   1799:
                   1800: In the fourth place, to compute the square of the $L^2$-norm of \kbd{x} we
                   1801: just add the squares of the $L^2$-norms of the column vectors which we obtain
                   1802: using the library function \teb{gnorml2}. Had this function not existed, the
                   1803: norm computation would of course have been just as easy to write, but we would
                   1804: have needed a double loop.
                   1805:
                   1806: We then take the square root of \kbd{s}, in precision~3 (the smallest
                   1807: possible). The \kbd{prec} argument of transcendental functions (here~$3$) is
                   1808: only taken into account when the arguments are {\it exact\/} objects, and thus
                   1809: no a priori precision can be determined from the objects themselves. To cater
                   1810: for this possibility, if \kbd{s} is of type \typ{REAL}, we use the function
                   1811: \teb{setlg} which effectively sets the precision of \kbd{s} to the required
                   1812: value. Note that here, since we are using a numeric value for a \kbd{cget}
                   1813: function, the program will run slightly differently on 32-bit and 64-bit
                   1814: machines: we want to use the smallest possible bit accuracy, and this is equal
                   1815: to \kbd{BITS\_IN\_LONG}.
                   1816:
                   1817: Note that the matrix \kbd{x} is allowed to have complex entries, but the
                   1818: function \kbd{gnorml2} guarantees that \kbd{s} is a non-negative real number
                   1819: (not necessarily of type \typ{REAL} of course). If we had not known this fact,
                   1820: we would simply have added the instruction \kbd{s = greal(s);} just after the
                   1821: \kbd{for} loop.
                   1822:
                   1823: Note also that the function \kbd{gnorml2} works as desired on matrices, so we
                   1824: really did not need this loop at all (\kbd{s = gnorml2(x)} would have been
                   1825: enough), but we wanted to give examples of function usage. Similarly, it is of
                   1826: course not necessary to take the square root for testing whether the norm
                   1827: exceeds~$1$.
                   1828:
                   1829: In the fifth place, note that we initialized the sum \kbd{s} to \teb{gzero},
                   1830: which is an exact zero. This is logical, but has some disadvantages: if all
                   1831: the entries of the matrix are integers (or rational numbers), the computation
                   1832: will take rather long, about twice as long as with real numbers of the same
                   1833: length. It would be better to initialize \kbd{s} to a real zero, using for
                   1834: instance the instructions:
                   1835:
                   1836: \kbd{s = cgetr(prec+1); gaffsg(0,s);}
                   1837:
                   1838: \noindent
                   1839: This raises the question: which real zero does this produce (have a look
                   1840: at~\secref{se:whatzero})? In fact, the following choice has been made: it will
                   1841: give you the zero with exponent equal to $-\kbd{BITS\_IN\_LONG}$ times the
                   1842: number of longwords in the mantissa, i.e.~$-\kbd{bit\_accuracy(lg(s))}$.
                   1843: Instead of the above idiom, you can also use the function
                   1844: \kbd{GEN \teb{realzero}(long prec)}, which simply returns a real zero to
                   1845: accuracy \kbd{-bit\_accuracy(prec)}.
                   1846:
                   1847: The sixth remark here is about how to determine the approximate size
                   1848: of a real number. The fastest way to do this is to look at its binary
                   1849: exponent. Hence we need to have \kbd{s} actually represented as a real number,
                   1850: and not as an integer or a rational number. The result of transcendental
                   1851: functions is guaranteed to be of type \typ{REAL}, or complex with \typ{REAL}
                   1852: components, thus this is indeed the case after the call to \kbd{gsqrt} since
                   1853: its argument is a nonnegative (real) number.
                   1854:
                   1855: Finally, note the use of the function \teb{gmul2n}. It has the following
                   1856: syntax:
                   1857:
                   1858: \kbd{GEN \teb{gmul2n}(GEN x, long n);}
                   1859:
                   1860: \noindent and the effect is simply to multiply \kbd{x} by $2^{\text n}$,
                   1861: where \kbd{n} can be positive or negative. This is much faster than
                   1862: \kbd{gmul} or \kbd{gmulgs}.
                   1863:
                   1864: There is another function \teb{gshift} with exactly the same syntax.
                   1865: When \kbd{n} is non-negative, the effects of these two functions are the same.
                   1866: However, when \kbd{n} is negative, \kbd{gshift} acts like a right shift of
                   1867: \kbd{-n}, hence does not noramlly perform an exact division on integers. The
                   1868: function  \kbd{gshift} is the PARI analogue of the C or GP operators \kbd{<<}
                   1869: and~\kbd{>>}.
                   1870:
                   1871: We now come to the heart of the function. We have a \kbd{GEN} \kbd{p1} which
                   1872: points to a certain matrix of which we want to take the exponential. We will
                   1873: want to transform this matrix into a matrix with real (or complex of real)
                   1874: entries before starting the computation. To do this, we simply multiply by
                   1875: the real number 1 in precision $\kbd{prec}+1$ (to be on the side of safety).
                   1876: To sum the series, we will use three variables: a variable \kbd{p2} which at
                   1877: stage $k$ will contain $\kbd{p1}^k/k!$, a variable \kbd{y} which will contain
                   1878: $\sum_{i=0}^k \kbd{p1}^i/i!$, and a variable \kbd{r} which will contain the
                   1879: size estimate $\kbd{s}^k/k!$. Note that we do not use Horner's rule. This is
                   1880: simply because we are lazy and do not want to compute in advance the number
                   1881: of terms that we need. We leave this modification (and many other
                   1882: improvements!) to the reader. The program continues as follows:
                   1883:
                   1884: \bprog%
                   1885: \q /* initializations before the loop */
                   1886: \q r = cgetr(prec+1); gaffsg(1,r); p1 = gmul(r,p1);
                   1887: \q y = gscalmat(r,lx-1); /* creates scalar matrix with r on diagonal */
                   1888: \q p2 = p1; r = s; k = 1;
                   1889: \q y = gadd(y,p2);
                   1890: \h
                   1891: \q /* now the main loop */
                   1892: \q while (expo(r) >= -BITS\_IN\_LONG*(prec-1))
                   1893: \q \obr
                   1894: \q\q k++; p2 = gdivgs(gmul(p2,p1),k);
                   1895: \q\q r = gdivgs(gmul(s,r),k); y = gadd(y,p2);
                   1896: \q \cbr
                   1897: \h
                   1898: \q  /* now square back n times if necessary */
                   1899: \q if (!n) \obr\ lbot = avma; y = gcopy(y); \cbr
                   1900: \q else
                   1901: \q \obr
                   1902: \q\q for (i=0; i<n; i++) \obr\ lbot = avma; y = gsqr(y); \cbr
                   1903: \q \cbr
                   1904: \q return gerepile(ltop,lbot,y);
                   1905: \cbr\eprog
                   1906: \noindent
                   1907: A few remarks once again. First note the use of the function
                   1908: \teb{gscalmat} with the following syntax:
                   1909:
                   1910: \kbd{GEN \teb{gscalmat}(GEN x, long m);}
                   1911:
                   1912: \noindent
                   1913: The effect of this function is to create the $\kbd{m}\times\kbd{m}$ scalar
                   1914: matrix whose diagonal entries are~\kbd{x}. Hence the length of the matrix
                   1915: including the codeword will in fact be \kbd{m+1}.  There is a corresponding
                   1916: function \teb{gscalsmat} which takes a long as a first argument.
                   1917:
                   1918: If we refer to what has been said above, the main loop should be self-evident.
                   1919:
                   1920: When we do the final squarings, according to the fundamental dogma on the
                   1921: use of \teb{gerepile}, we keep the value of \kbd{avma} in \kbd{lbot} just {\it
                   1922: before\/} the squaring, so that if it is the last one, \kbd{lbot} will indeed
                   1923: be the bottom address of the garbage pile, and \kbd{gerepile} will work. Note
                   1924: that it takes a completely negligible time to do this in each loop compared
                   1925: to a matrix squaring.  However, when \kbd{n} is initially equal to 0, no
                   1926: squaring has to be done, and we have our final result ready but we lost the
                   1927: address of the bottom of the garbage pile. Hence we use the trick of copying
                   1928: \kbd{y} again to the top of the stack. This is inefficient, but does the trick.
                   1929: If we wanted to avoid this using only \kbd{gerepile}, the best thing to do
                   1930: would be to put the instruction \kbd{lbot=avma} just before both occurrences
                   1931: of the instruction \kbd{y=gadd(p2,y)}. Of course, we could also rewrite the
                   1932: last block as follows:
                   1933:
                   1934: \bprog%
                   1935: \q /* now square back n times */
                   1936: \q for (i=0; i<n; i++) y = gsqr(y);
                   1937: \q return gerepileupto(ltop,y);
                   1938: \cbr\eprog
                   1939: \noindent
                   1940: because it does not matter to \teb{gerepileupto} that we have lost the address
                   1941: just before the final result (note that the loop is not executed if \kbd{n}
                   1942: is~0). It is safe to use \kbd{gerepileupto} here as \kbd{y} will have been
                   1943: created by either \kbd{gsqr} or \kbd{gadd}, both of which are guaranteed to
                   1944: return suitable objects.
                   1945:
                   1946: \misctitle{Remarks}. As such, the program should work most of the time if
                   1947: \kbd{x} is a square matrix with real or complex entries. Indeed, since
                   1948: essentially the first thing that we do is to multiply by the real number~1,
                   1949: the program should work for integer, real, rational, complex or quadratic
                   1950: entries. This is in accordance with the behavior of transcendental functions.
                   1951:
                   1952: Furthermore, since this program is intended to be only an illustrative
                   1953: example, it has been written a little sloppily. In particular many error
                   1954: checks have been omitted, and the efficiency is far from optimal. An evident
                   1955: improvement would be the use of \kbd{gerepileupto} mentioned above. Another
                   1956: improvement is to multiply the matrix x by the real number 1 right at the
                   1957: beginning, speeding up the computation of the $L^2$-norm in many cases. These
                   1958: improvements are included in the version given in Appendix~B. Still another
                   1959: improvement would come from a better choice of~\kbd{n}. If the reader takes a
                   1960: look at the implementation of the function \kbd{mpexp1} in the file
                   1961: \kbd{basemath/trans1.c}, he can make the necessary changes himself. Finally,
                   1962: there exist other algorithms of a different nature to compute the exponential
                   1963: of a matrix.
                   1964:
                   1965: \section{Adding functions to PARI}
                   1966: \subsec{Nota Bene}.
                   1967: %
                   1968: As already mentioned, modified versions of the PARI package should NOT be
                   1969: spread without our prior approval. If you do modify PARI, however, it is
                   1970: certainly for a good reason, hence we would like to know about it, so that
                   1971: everyone can benefit from it. There is then a good chance that the
                   1972: modifications that you have made will be incorporated into the next release.
                   1973:
                   1974: (Recall the e-mail address: \kbd{pari@math.u-bordeaux.fr}, or use the mailing
                   1975: lists).
                   1976:
                   1977: Roughly four types of modifications can be made. The first type includes all
                   1978: improvements to the documentation, in a broad sense. This includes correcting
                   1979: typos or inacurracies of course, but also items which are not really covered
                   1980: in this document, e.g.~if you happen to write a tutorial, or pieces of code
                   1981: exemplifying some fine points that you think were unduly omitted.
                   1982:
                   1983: The second type is to expand or modify the configuration routines and skeleton
                   1984: files (the \kbd{Configure} script and anything in the \kbd{config/}
                   1985: subdirectory) so that compilation is possible (or easier, or more efficient)
                   1986: on an operating system previously not catered for. This includes discovering
                   1987: and removing idiosyncrasies in the code that would hinder its portability.
                   1988:
                   1989: The third type is to modify existing (mathematical) code, either to correct
                   1990: bugs, to add new functionalities to existing functions, or to improve their
                   1991: efficiency.
                   1992:
                   1993: Finally the last type is to add new functions to PARI. We explain here how
                   1994: to do this, so that in particular the new function can be called from GP.
                   1995:
                   1996: \subsec{The calling interface from GP, parser codes}.
                   1997: \label{se:gp.interface}
                   1998: A \idx{parser code} is a character string describing all the GP parser
                   1999: needs to know about the function prototype. It contains a sequence of the
                   2000: following atoms:
                   2001:
                   2002: \settabs\+\indent&\kbd{Dxxx}\quad&\cr
                   2003: \noindent $\bullet$ Syntax requirements, used by functions like
                   2004:  \kbd{for}, \kbd{sum}, etc.:
                   2005: %
                   2006: \+& \kbd{=} & separator \kbd{=} required at this point (between two
                   2007: arguments)\cr
                   2008:
                   2009: \noindent$\bullet$ Mandatory arguments, appearing in the same order as the
                   2010: input arguments they describe:
                   2011: %
                   2012: \+& \kbd{G} & \kbd{GEN}\cr
                   2013: \+& \kbd{\&}& \kbd{*GEN}\cr
                   2014: \+& \kbd{L} & long {\rm (we implicitly identify \kbd{int} with \kbd{long})}\cr
                   2015: \+& \kbd{S} & symbol (i.e.~GP identifier name). Function expects a
                   2016: \kbd{*entree}\cr
                   2017: \+& \kbd{V} & variable (as \kbd{S}, but rejects symbols associated to
                   2018: functions)\cr
                   2019: \+& \kbd{n} & variable, expects a \idx{variable number} (a \kbd{long}, not an
                   2020: \kbd{*entree})\cr
                   2021: \+& \kbd{I} & string containing GP code (useful for control statements, %
                   2022:  to be processed with \kbd{lisexpr}\cr
                   2023: \+&&\quad or \kbd{lisseq})\cr
                   2024: \+& \kbd{r} & raw input (treated as a string without quotes). Quoted %
                   2025:  args are copied as strings.\cr
                   2026: \+&&\quad Stops at first unquoted \kbd{')'} or \kbd{','}. Special chars can
                   2027: be quoted using '\kbd{\bs{}}'.\cr
                   2028: \+&&\quad Example: \kbd{aa"b\bs n)"c} yields the string \kbd{"aab\bs{n})c"}\cr
                   2029: \+& \kbd{s} & expanded string. Example: \kbd{Pi"x"2} yields \kbd{"3.142x2"}.\cr
                   2030: \+&& Unquoted components can be of any PARI type (converted following current
                   2031: output format)\cr
                   2032:
                   2033: \noindent$\bullet$ Optional arguments:
                   2034: %
                   2035: \+& \kbd{s*} & any number of strings, possibly 0 (see \kbd{s})\cr
                   2036: \+& \kbd{s*p} & idem, setting $\kbd{prettyp} = 1$ (i.e.~in beautified
                   2037: format)\cr
                   2038: \+& \kbd{s*t} & idem, in \TeX\ format\cr
                   2039: \+& \kbd{D\var{xxx}} &  argument has a default value.\cr
                   2040:
                   2041: The format to indicate a default value (atom starts with a \kbd{D}) is
                   2042: ``\kbd{D\var{value},\var{type},}'', where \var{type} is the code for any
                   2043: mandatory atom (previous group), \var{value} is any valide GP expression
                   2044: which is converted according to \var{type}, and the ending comma is
                   2045: mandatory. For instance \kbd{D0,L,} stands for ``this optional argument will
                   2046: be converted to a \kbd{long}, and is \kbd{0} by default''. So if the
                   2047: user-given argument reads \kbd{1 + 3} at this point, \kbd{(long)4} is sent to
                   2048: the function (via \tet{itos}$()$); and \kbd{(long)0} if the argument is
                   2049: ommitted. The following special syntaxes are available:
                   2050:
                   2051: \begingroup
                   2052: \settabs\+\indent\indent&\kbd{Dxxx}\quad& optional \kbd{*GEN},&\cr
                   2053: \+&\kbd{DG}& optional \kbd{GEN}, & send {\tt NULL} if argument omitted.\cr
                   2054:
                   2055: \+&\kbd{D\&}& optional \kbd{*GEN}, send {\tt NULL} if argument omitted.\cr
                   2056:
                   2057: \+&\kbd{DV}& optional \kbd{*entree}, send {\tt NULL} if argument omitted.\cr
                   2058:
                   2059: \+&\kbd{DI}& optional \kbd{*char}, send {\tt NULL} if argument omitted.\cr
                   2060:
                   2061: \+&\kbd{Dn}& optional variable number, $-1$ if omitted.\cr
                   2062: \endgroup
                   2063:
                   2064: \noindent$\bullet$ Automatic arguments:
                   2065: %
                   2066: \+& \kbd{f} &  Fake \kbd{*long}. C function requires a pointer but we
                   2067: don't use the resulting \kbd{long}\cr
                   2068: \+& \kbd{p} &  real precision (default \kbd{realprecision})\cr
                   2069: \+& \kbd{P} &  series precision (default \kbd{seriesprecision},
                   2070:  global variable \kbd{precdl} for the library)\cr
                   2071:
                   2072: \noindent $\bullet$ Return type: \kbd{GEN} by default, otherwise the
                   2073: following can appear anywhere in the code string:
                   2074: %
                   2075: \+& \kbd{l} & return \kbd{long}\cr
                   2076: \+& \kbd{v} & return \kbd{void}\cr
                   2077:
                   2078: No more than 8 arguments can be given (syntax requirements and return types
                   2079: are not considered as arguments). This is currently hardcoded but can
                   2080: trivially be changed by modifying the definition of \kbd{argvec} in
                   2081: \kbd{anal.c:identifier()}. This limitation should disappear in future
                   2082: versions.
                   2083:
                   2084: When the function is called under GP, the prototype is scanned and each time
                   2085: an atom corresponding to a mandatory argument is met, a user-given argument
                   2086: is read (GP outputs an error message it the argument was missing). Each time
                   2087: an optional atom is met, a default value is inserted if the user omits the
                   2088: argument. The ``automatic'' atoms fill in the argument list transparently,
                   2089: supplying the current value of the corresponding variable (or a dummy
                   2090: pointer).
                   2091:
                   2092: For instance, here is how you would code the following prototypes (which
                   2093: don't involve default values):
                   2094: \bprogtabs\+\indent& void name(GEN x, GEN y, long prec)\quad& ---->\quad&\cr
                   2095: \+& GEN name(GEN x, GEN y, long prec)  & ----> & "GGp"\cr
                   2096: \+& void name(GEN x, long y, long prec) & ----> & "vGLp" {\rm (or %
                   2097:  \kbd{"GvLp"})}\cr
                   2098: \+& long name(GEN x) & ----> & "Gl"\cr
                   2099: \eprog
                   2100:
                   2101: If you want more examples, GP gives you easy access to the parser codes
                   2102: associated to all GP functions: just type \kbd{\b{h} \var{function}}. You
                   2103: can then compare with the C prototypes as they stand in the code.
                   2104:
                   2105: \misctitle{Remark}: If you need to implement complicated control statements
                   2106: (probably for some improved summation functions), you'll need to know about
                   2107: the \teb{entree} type, which is not documented. Check the comment before
                   2108: the function list at the end of \kbd{language/init.c} and the source code
                   2109: in \kbd{language/sumiter.c}. You should be able to make something of it.
                   2110: \smallskip
                   2111:
                   2112: \subsec{Coding guidelines}.
                   2113: \noindent
                   2114: Code your function in a file of its own, using as a guide other functions
                   2115: in the PARI sources. One important thing to remember is to clean the stack
                   2116: before exiting your main function (usually using \kbd{gerepile}), since
                   2117: otherwise successive calls to the function will clutter the stack with
                   2118: unnecessary garbage, and stack overflow will occur sooner. Also, if it
                   2119: returns a \kbd{GEN} and you want it to be accessible to GP, you have to
                   2120: make sure this \kbd{GEN} is suitable for \kbd{gerepileupto} (see
                   2121: \secref{se:garbage}).
                   2122:
                   2123: If error messages are to be generated in your function, use the general
                   2124: error handling routine \kbd{err} (see \secref{se:err}). Recall that, apart
                   2125: from the \kbd{warn} variants, this function does not return but ends with
                   2126: a \kbd{longjmp} statement. As well, instead of explicit \kbd{printf}~/
                   2127: \kbd{fprintf} statements, use the following encapsulated variants:
                   2128:
                   2129: \kbd{void \teb{pariputs}(char *s)}: write \kbd{s} to the GP output stream.
                   2130:
                   2131: \kbd{void \teb{fprintferr}(char *s)}: write \kbd{s} to the GP error
                   2132: stream (this function is in fact much more versatile, see
                   2133: \secref{se:dbg_output}).
                   2134:
                   2135: Declare all public functions in \kbd{paridecl.h} (you want the outside
                   2136: world to know about them). The other ones should be declared \kbd{static} in
                   2137: your file.
                   2138:
                   2139: Your function is now ready to be used in library mode after compilation and
                   2140: creation of the library. If possible, compile it as a shared library (see
                   2141: the \kbd{Makefile} coming with the \kbd{matexp} example in the
                   2142: distribution). It is however still inaccessible from GP.\smallskip
                   2143:
                   2144: \subsec{Integration with GP as a shared module}
                   2145:
                   2146: To tell GP about your function, you must do the following. First, find a
                   2147: name for it. It does not have to match the one used in library mode, but
                   2148: consistency is nice. It has to be a valid GP identifier, i.e.~use only
                   2149: alphabetic characters, digits and the underscore character (\kbd{\_}), the
                   2150: first character being alphabetic.
                   2151:
                   2152: Then you have to figure out the correct \idx{parser code} corresponding to
                   2153: the function prototype. This has been explained above
                   2154: (\secref{se:gp.interface}).
                   2155:
                   2156: Now, assuming your Operating System is supported by \tet{install}, simply
                   2157: write a GP script like the following:
                   2158:
                   2159: \bprog%
                   2160: install(\var{name}, \var{code}, \var{gpname}, \var{library})
                   2161: addhelp(\var{gpname}, \var{some help text})
                   2162: \eprog
                   2163: \noindent(see \secref{se:addhelp} and~\ref{se:install}). The \idx{addhelp}
                   2164: part is not mandatory, but very useful if you want others to use your
                   2165: module.
                   2166:
                   2167: Read that file from your GP session (from your \idx{preferences file} for
                   2168: instance, see \secref{se:gprc}), and that's it, you can use the new
                   2169: function \var{gpname} under GP (and we would very much like to hear about
                   2170: it!).
                   2171:
                   2172: \subsec{Integration the hard way}
                   2173:
                   2174: If \tet{install} is not available for your Operating System, it's more
                   2175: complicated: you have to hardcode your function in the GP binary (or
                   2176: install \idx{Linux}). Here's what needs to be done:
                   2177:
                   2178: In the definition of \kbd{functions\_basic} (file \kbd{language/init.c}),
                   2179: add your entry in exact alphabetical order by its GP name (note that digits
                   2180: come before letters), in a line of the form:
                   2181:
                   2182: \kbd{\obr"gpname",V,(void*)libname,secno,"code"\cbr,}
                   2183:
                   2184: \noindent where
                   2185:
                   2186: \kbd{libname} is the name of your function in library mode,
                   2187:
                   2188: \kbd{gpname} the name that you have chosen to call it under GP,
                   2189:
                   2190: \kbd{secno} is the section number of Chapter~3 in which this function would
                   2191: belong (type \kbd{?} in GP to see the list),
                   2192:
                   2193: \kbd{V} is a number between 0 and 99. Right now, there are only two
                   2194: significant values: zero means that it's possible to call the function
                   2195: without argument, and non-zero means it needs at least one argument.
                   2196:
                   2197: \kbd{code} is the parser code.
                   2198:
                   2199: Once this has been done, in the file \kbd{language/helpmessages.c} add in
                   2200: exact alphabetical order a short message describing the effect of your
                   2201: function:
                   2202: \kbd{"name(x,y,...)=short descriptive message",}
                   2203:
                   2204: The message must be a single line, of arbitrary length. Do not use
                   2205: \kbd{\bs{n}}; the necessary newlines will be inserted by GP's online help
                   2206: functions. Optional arguments should be shown between braces (see the other
                   2207: messages for comparison).\smallskip
                   2208:
                   2209: Now, you can recompile GP.
                   2210:
                   2211: \subsec{Example}.
                   2212: %
                   2213: A complete description could look like this:
                   2214:
                   2215: \bprog%
                   2216: \obr
                   2217: \q  install(bnfinit0, GD0,L,DGp, ClassGroupInit, "libpari.so")
                   2218: \q  addhelp(ClassGroupInit, "ClassGroupInit(P,\obr flag=0\cbr,\obr data=[]\cbr):
                   2219: \q\q    compute the necessary data for ...")
                   2220: \cbr
                   2221: \eprog
                   2222: which means we have a function \kbd{ClassGroupInit} under GP, which calls the
                   2223: library function \kbd{bnfinit0} . The function has one mandatory
                   2224: argument (\kbd{V} is non-zero), and possibly two more (two \kbd{'D'} in the
                   2225: code), plus the current real precision. More precisely, the first argument
                   2226: is a \kbd{GEN}, the second one is converted to a \kbd{long} using
                   2227: \kbd{itos} (\kbd{0} is passed if it is omitted), and the third one is also
                   2228: a \kbd{GEN}, but we pass \kbd{NULL} if no argument was supplied by the
                   2229: user. This matches the C prototype (from \kbd{paridecl.h}):
                   2230: %
                   2231: \bprog%
                   2232:   GEN bnfinit0(GEN P, long flag, GEN data, long prec)
                   2233: \eprog
                   2234:
                   2235: This function is in fact coded in \kbd{basemath/buch2.c}, and will in this
                   2236: case be completely identical to the GP function \kbd{bnfinit} but GP does
                   2237: not need to know about this, only that it can be found somewhere in the
                   2238: shared library \kbd{libpari.so}.
                   2239:
                   2240: \misctitle{Important note} You see in this example that it is the
                   2241: function's responsibility to correctly interpret its operands: \kbd{data =
                   2242: NULL} is interpreted {\it by the function\/} as an empty vector. Note that
                   2243: since \kbd{NULL} is never a valid \kbd{GEN} pointer, this trick always
                   2244: enables you to distinguish between a default value and actual input: the
                   2245: user could explicitly supply an empty vector!
                   2246:
                   2247: \misctitle{Note} If \kbd{install} were not available we would have to
                   2248: modify \kbd{language/helpmessages.c}, and \kbd{language/init.c} and
                   2249: recompile GP. The entry in \kbd{functions\_basic} corresponding to the
                   2250: function above is actually
                   2251: \bprog\obr
                   2252: "bnfinit", 91, (void*)bnfinit0, 6, "GD0,L,DGp"
                   2253: \cbr\eprog
                   2254: \vfill\eject

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>