Annotation of OpenXM_contrib/pari-2.2/doc/usersch1.tex, Revision 1.1.1.1
1.1 noro 1: % $Id: usersch1.tex,v 1.6 2000/11/06 18:59:01 karim Exp $
2: % Copyright (c) 2000 The PARI Group
3: %
4: % This file is part of the PARI/GP documentation
5: %
6: % Permission is granted to copy, distribute and/or modify this document
7: % under the terms of the GNU Free Documentation License
8: \chapter{Overview of the PARI system}
9:
10: \section{Introduction}
11:
12: \noindent
13: The PARI system is a package which is capable of doing formal computations
14: on recursive types at high speed; it is primarily aimed at number
15: theorists, but can be used by anybody whose primary need is speed.
16:
17: Although quite an amount of symbolic manipulation is possible in PARI, this
18: system does very badly compared to much more sophisticated systems like
19: Axiom, Macsyma, Maple, Mathematica or Reduce on such manipulations
20: (e.g.~multivariate polynomials, formal integration, etc\dots). On the other
21: hand, the three main advantages of the system are its speed (which can be
22: between 5 and 100 times better on many computations), the possibility of
23: using directly data types which are familiar to mathematicians, and its
24: extensive algebraic number theory module which has no equivalent in the
25: above-mentioned systems.
26:
27: It is possible to use PARI in two different ways:
28:
29: \quad 1) as a library, which can be called from an upper-level language
30: application (for instance written in C, C$++$, Pascal or Fortran);
31:
32: \quad 2) as a sophisticated programmable calculator, named {\bf GP}, which
33: contains most of the control instructions of a standard language like C.
34:
35: The use of GP is explained in chapters 2 and 3, and the programming in library
36: mode is explained in chapters 3, 4 and 5. In the present Chapter 1, we give
37: an overview of the system.
38:
39: \subsectitle{Important note:} A tutorial for GP is provided in the standard
40: distribution (\kbd{tutorial.dvi}) and you should read this first (at
41: least the beginning of it, you can skip the specialized topics you're not
42: interested in). You can then start over and read the more boring stuff which
43: lies ahead. But you should do that eventually, at the very least the various
44: Chapter headings. You can have a quick idea of what is available by looking
45: at the GP reference card (\kbd{refcard.dvi} or \kbd{refcard.ps}). In case
46: of need, you can then refer to the complete function description in Chapter 3.
47:
48: \subsectitle{How to get the latest version?}
49:
50: \noindent
51: This package can be obtained by anonymous ftp from quite a number of sites
52: (ask \kbd{archie} or your favourite Web search engine for the site nearest to
53: you). But, if you want the very latest version (including development
54: versions), you should use the anonymous ftp address
55:
56: \kbd{ftp://megrez.math.u-bordeaux.fr/pub/pari}
57:
58: \noindent
59: where you will find all the different ports and possibly some
60: binaries. A lot of version information, mailing list archives, and various
61: tips can be found on PARI's (fledgling) home page:
62:
63: \kbd{\wwwsite}
64:
65: \subsectitle{Implementation notes:} (You can skip this section and switch to
66: \secref{se:start} if you're not interested in hardware technicalities. You
67: won't miss anything that would be mentioned here.)
68:
69: The PARI package contains essentially three versions. The first one is a
70: specific implementation for 680x0 based computers which contains a kernel
71: (for the elementary arithmetic operations on multiprecise integers and real
72: numbers, and binary/decimal conversion routines) entirely written in
73: MC68020 assembly language (around 6000 lines), the rest being at present
74: entirely written in ANSI C with a C++-compatible syntax. The system runs on
75: SUN-3/xx, Sony News, NeXT cubes and on 680x0 based Macs with x$\ge$2. It
76: should be very easy to port on any other 680x0 based machine like for
77: instance the Apollo Domain workstations.
78:
79: Note that the assembly language source code uses the SUN syntax, which for
80: some strange reason differs from the Motorola standard used by most other
81: 680x0 machines in the world. In the Mac distribution, we have included a
82: program which automatically converts from the SUN syntax into the standard
83: one, at least for the needed PARI assembly file. On the Unix distribution,
84: we have included other versions of the assembly file, using different
85: syntaxes. {\bf This version is not really maintained anymore since we lack
86: the hardware to update/test it.}
87:
88: The second version is a version where most of the kernel routines are written
89: in C, but the time-critical parts are written in a few hundred lines
90: of assembler at most. At present there exist three versions for the Sparc
91: architecture: one for Sparc version 7 (e.g.~Sparcstation 1, 1+, IPC, IPX or 2),
92: one for Sparc version 8 with supersparc processors (e.g.~Sparcstation 10
93: and 20) and one for Sparc version 8 with microsparc I or II processors
94: (e.g.~Sparcclassic or Sparcstation 4 and 5). No specific version is written
95: for the Ultrasparc since it can use the microsparc II version. In addition,
96: versions exist for the HP-PA architecture, for the PowerPC architecture
97: (only for the 601), for the Intel family starting at the 386 (under Linux,
98: OS/2, MSDOS, or Windows), and finally for the DEC Alpha 64-bit processors.
99:
100: Finally, a third version is written entirely in C, and should be portable
101: without much trouble to any 32 or 64-bit computer having no real memory
102: constraints. It is about 2 times slower than versions with a small assembly
103: kernel. This version has been tested for example on MIPS based DECstations
104: 3100 and 5000 and SGI computers.
105:
106: In addition to Unix workstations and Macs, PARI has been ported to a
107: considerable number of smaller and larger machines, for example the VAX,
108: 68000-based machines like the Atari, Mac Classic or Amiga 500, 68020 machines
109: such as the Amiga 2500 or 3000, and even to MS-DOS 386 or better machines,
110: using the \tet{EMX} port of the GNU C compiler and DOS-extender.
111:
112: \section{The PARI types}
113: \label{se:start}\sidx{types}
114:
115: \noindent
116: The crucial word in PARI is \idx{recursiveness}: most of the types it knows
117: about are recursive. For example, the basic type {\bf Complex} exists (actually
118: called \typ{COMPLEX}). However, the components (i.e.~the real and imaginary
119: part) of such a ``complex number'' can be of any type. The only sensible ones
120: are integers (we are then in $\Z[i]$), rational numbers ($\Q[i]$), real
121: numbers ($\R[i]=\C$), or even elements of $\Z/n\Z$ ($(\Z/n\Z)[i]$ when this
122: makes sense), or $p$-adic numbers when $p\equiv 3 \mod 4$ ($\Q_{p}[i]$).
123:
124: This feature must of course not be used too rashly: for example you are in
125: principle allowed to create objects which are ``complex numbers of complex
126: numbers'', but don't expect PARI to make sensible use of such objects: you
127: will mainly get nonsense.
128:
129: On the other hand, one thing which {\it is\/} allowed is to have components
130: of different, but compatible, types. For example, taking again complex
131: numbers, the real part could be of type integer, and the imaginary part of
132: type rational.
133:
134: By compatible, we mean types which can be freely mixed in operations like $+$
135: or $\times$. For example if the real part is of type real, the imaginary part
136: cannot be of type integermod (integers modulo a given number $n$).
137:
138: Let us now describe the types. As explained above, they are built recursively
139: from basic types which are as follows. We use the letter $T$ to designate any
140: type; the symbolic names correspond to the internal representations of the
141: types.\medskip
142: \settabs\+xxx&typexxxxxxxxxxxx&xxxxxxxxxxxxxxxx&xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\cr
143: %
144: \+&type \tet{t_INT}& $\Z$& Integers (with
145: arbitrary precision)\sidx{integer}\cr
146: %
147: \+&type \tet{t_REAL}& $\R$& Real numbers
148: (with arbitrary precision)\sidx{real number}\cr
149: %
150: \+&type \tet{t_INTMOD}& $\Z/n\Z$&
151: Integermods (integers modulo $n$)\sidx{integermod}\cr
152: %
153: \+&type \tet{t_FRAC}& $\Q$& Rational numbers
154: (in irreducible form)\sidx{rational number}\cr
155: %
156: \+&type \tet{t_FRACN}& $\Q$& Rational numbers
157: (not necessarily in irreducible form)\cr
158: %
159: \+&type \tet{t_COMPLEX}& $T[i]$& Complex
160: numbers\sidx{complex number}\cr
161: %
162: \+&type \tet{t_PADIC}& $\Q_p$&
163: $p$-adic\sidx{p-adic number} numbers\cr
164: %
165: \+&type \tet{t_QUAD}& $\Q[w]$& Quadratic Numbers
166: (where $[\Z[w]:\Z]=2$)\sidx{quadratic number}\cr
167: %
168: \+&type \tet{t_POLMOD}& $T[X]/P(X)T[X]$&
169: Polmods (polynomials modulo $P$)\sidx{polmod}\cr
170: %
171: \+&type \tet{t_POL}& $T[X]$& Polynomials
172: \sidx{polynomial}\cr
173: %
174: \+&type \tet{t_SER}& $T((X))$& Power series
175: (finite Laurent series)\sidx{power series}\cr
176: %
177: \+&type \tet{t_RFRAC}& $T(X)$& Rational
178: functions (in irreducible form)\sidx{rational function}\cr
179: %
180: \+&type \tet{t_RFRACN}& $T(X)$& Rational functions
181: (not necessarily in irreducible form)\cr
182: %
183: \+&type \tet{t_VEC}& $T^n$& Row (i.e.~horizontal)
184: vectors\sidx{row vector}\cr
185: %
186: \+&type \tet{t_COL}& $T^n$& Column (i.e.~vertical)
187: vectors\sidx{column vector}\cr
188: %
189: \+&type \tet{t_MAT}& ${\cal M}_{m,n}(T)$&
190: Matrices\sidx{matrix}\cr
191: %
192: \+&type \tet{t_LIST}& $T^n$&
193: Lists\sidx{list}\cr
194: %
195: \+&type \tet{t_STR}& &
196: Character strings\sidx{string}\cr
197: \noindent
198: and where the types $T$ in recursive types can be different in each component.
199:
200: In addition, there exist types \tet{t_QFR} and \tet{t_QFI} for binary
201: quadratic forms of respectively positive and negative
202: discriminants,\sidx{binary quadratic form} which can be used in specific
203: operations, but which may disappear in future versions.
204:
205: Every PARI object (called \tet{GEN} in the sequel) belongs to one of these
206: basic types. Let us have a closer look.
207:
208: \subsec{Integers and reals}:\sidx{integer}\sidx{real number}
209: they are of arbitrary and varying length (each number carrying in its
210: internal representation its own length or precision) with the following mild
211: restrictions (given for 32-bit machines, the restrictions for 64-bit machines
212: being so weak as to be considered inexistent): integers must be in absolute
213: value less than $2^{268435454}$ (i.e.~roughly 80807123 digits). The
214: precision of real numbers is also at most 80807123 significant decimal
215: digits, and the binary exponent must be in absolute value less than
216: $2^{23}=8388608$.
217:
218: Note that PARI has been optimized so that it works as fast as possible on
219: numbers with at most a few thousand decimal digits. In particular, not too
220: much effort has been put into fancy multiplication techniques (only the
221: Karatsuba multiplication is implemented). Hence, although it is possible to
222: use PARI to do computations with $10^7$ decimal digits, much better programs
223: can be written for such huge numbers.
224:
225: Integers and real numbers are completely non-recursive types and are
226: sometimes called the \tet{leaves}.
227:
228: \subsec{Integermods, rational numbers (irreducible or not),
229: $p$-adic numbers, polmods, and
230: rational functions}:\sidx{integermod}\sidx{rational number}\sidx{p-adic number}
231: \sidx{polmod} these are recursive, but in a restricted way.
232:
233: For integermods or polmods, there are two components: the modulus, which
234: must be of type integer (resp.\ polynomial), and the representative number
235: (resp.\ polynomial).
236:
237: For rational numbers or rational functions, there are also only two
238: components: the numerator and the denominator, which must both be of type
239: integer (resp.\ polynomial).
240:
241: \def\limproj{{\displaystyle\lim_{\textstyle\longleftarrow}}}
242:
243: Finally, $p$-adic numbers have three components: the prime $p$, the
244: ``modulus'' $p^k$, and an approximation to the $p$-adic number. Here $\Z_p$
245: is considered as $\limproj \Z/p^k\Z$, and $\Q_p$ as its field of
246: fractions. Like real numbers, the codewords contain an exponent (giving
247: essentially the $p$-adic valuation of the number) and also the information on
248: the precision of the number (which is in fact redundant with $p^k$, but is
249: included for the sake of efficiency).
250:
251: \subsec{Complex numbers and quadratic numbers}:
252: \sidx{complex number}\sidx{quadratic number}
253: quadratic numbers are numbers of the form $a+bw$, where $w$ is such that
254: $[\Z[w]:\Z]=2$, and more precisely $w=\sqrt d/2$ when $d\equiv 0 \mod 4$,
255: and $w=(1+\sqrt d)/2$ when $d\equiv 1 \mod 4$, where $d$ is the discriminant
256: of a quadratic order. Complex numbers correspond to the very important
257: special case $w=\sqrt{-1}$.\label{se:compquad}
258:
259: Complex and quadratic numbers are partially recursive: the two components
260: $a$ and $b$ can be of type integer, real, rational, integermod or $p$-adic,
261: and can be mixed, subject to the limitations mentioned above. For example,
262: $a+bi$ with $a$ and $b$ $p$-adic is in $\Q_p[i]$, but this is equal to
263: $\Q_p$ when $p\equiv 1 \mod 4$, hence we must exclude these $p$ when one
264: explicitly uses a complex $p$-adic type.
265:
266: \subsec{Polynomials, power series, vectors, matrices and lists}:
267: \sidx{polynomial}\sidx{power series}\sidx{vector}\sidx{matrix}
268: they are completely recursive: their components can be of any type, and types
269: can be mixed (however beware when doing operations). Note in particular that
270: a polynomial in two variables is simply a polynomial with polynomial
271: coefficients.
272:
273: Note that in the present version \vers{} of PARI, there is a bug in the
274: handling of power series of power series (i.e.~power series in several
275: variables). However power series of polynomials (which are power series in
276: several variables of a special type) are OK. The reason for this bug is
277: known, but it is difficult to correct because the mathematical problem itself
278: contains some amount of imprecision.
279:
280: \subsec{Strings}: These contain objects just as they would be printed by the
281: GP calculator.
282:
283: \subsec{Notes}:
284:
285: \subsubsec{Exact and imprecise objects}: \sidx{imprecise object}we have
286: already said that integers and reals are called the \idx{leaves} because they
287: are ultimately at the end of every branch of a tree representing a PARI
288: object. Another important notion is that of an {\bf \idx{exact object}}: by
289: definition, numbers of basic type real, $p$-adic or power series are
290: imprecise, and we will say that a PARI object having one of these imprecise
291: types anywhere in its tree is not exact. All other PARI objects will be
292: called exact. This is a very important notion since no numerical analysis is
293: involved when dealing with exact objects.
294:
295: \subsubsec{Scalar types}:\sidx{scalar type} the first nine basic types, from
296: \typ{INT} to \typ{POLMOD}, will be called scalar types because they
297: essentially occur as coefficients of other more complicated objects. Note
298: that type \typ{POLMOD} is used to define algebraic extensions of a base ring,
299: and as such is a scalar type.
300:
301: \subsubsec{What is zero?} This is a crucial question in all computer
302: systems. The answer we give in PARI is the following. For exact types, all
303: zeros are equivalent and are exact, and thus are usually represented as an
304: integer \idx{zero}. The problem becomes non-trivial for imprecise types. For
305: $p$-adics the answer is as follows: every $p$-adic number (including 0) has
306: an exponent $e$ and a ``mantissa'' (a purist would say a ``significand'') $u$
307: which is a $p$-adic unit, except when the number is zero (in which case $u$
308: is zero), the significand having a certain ``precision'' $k$ (i.e.~being
309: defined modulo $p^k$). Then this $p$-adic zero is understood to be equal to
310: $O(p^e)$, i.e.~there are infinitely many distinct $p$-adic zeros. The number
311: $k$ is thus irrelevant.
312:
313: For power series the situation is similar, with $p$ replaced by $X$, i.e.~a
314: power series zero will be $O(X^e)$, the number $k$ (here the length of the
315: power series) being also irrelevant.\label{se:whatzero}
316:
317: For real numbers, the precision $k$ is also irrelevant, and a real zero will
318: in fact be $O(2^e)$ where $e$ is now usually a negative binary exponent. This
319: of course will be printed as usual for a real number ($0.0000\cdots$ in
320: \kbd{f} format or $0.Exx$ in \kbd{e} format) and not with a $O()$ symbol as
321: with $p$-adics or power series. With respect to the natural ordering on the
322: reals we make the following convention: whatever its exponent a real
323: zero is smaller than any positive number, and any two real zeroes are equal.
324:
325: \section{Operations and functions}
326:
327: \subsec{The PARI philosophy}.
328: The basic philosophy which governs PARI is that operations and functions
329: should, firstly, give as exact a result as possible, and secondly, be
330: permitted if they make any kind of sense.
331:
332: More specifically, if you do an operation (not a transcendental one) between
333: exact objects, you will get an exact object. For example, dividing 1 by 3
334: does not give $0.33333\cdots$ as you might expect, but simply the rational
335: number $(1/3)$. If you really want the result in type real, evaluate $1./3$
336: or add $0.$ to $(1/3)$.
337:
338: The result of operations between imprecise objects will be as precise as
339: possible. Consider for example one of the most difficult cases, that is the
340: addition of two real numbers $x$ and $y$. The \idx{accuracy} of the result is
341: {\it a priori\/} unpredictable; it depends on the precisions of $x$ and $y$,
342: on their sizes (i.e.~their exponents), and also on the size of $x+y$. PARI
343: works out automatically the right precision for the result, even when it is
344: working in calculator mode GP where there is a \idx{default precision}.
345:
346: In particular, this means that if an operation involves objects of
347: different accuracies, some digits will be disregarded by PARI. It is a
348: common source of errors to forget, for instance, that a real number is
349: given as $r + 2^e \varepsilon$ where $r$ is a rational approximation, $e$ a
350: binary exponent and $\varepsilon$ is a nondescript real number less than 1 in
351: absolute value\footnote{*}{this is actually not quite true: internally, the
352: format is $2^b (a + \varepsilon)$, where $a$ and $b$ are integers}. Hence,
353: any number less than $2^e$ may be treated as an exact zero:
354:
355: \bprog
356: ? 0.E-28 + 1.E-100
357: %1 = 0.E-28
358: ? 0.E100 + 1
359: %2 = 0.E100
360: @eprog
361: \noindent As an exercise, if \kbd{a = 2\pow (-100)}, why do \kbd{a + 0.} and
362: \kbd{a * 1.} differ ?
363:
364: The second part of the PARI philosophy is that PARI operations are in general
365: quite permissive. For instance taking the exponential of a vector should not
366: make sense. However, it frequently happens that a computation comes out with a
367: result which is a vector with many components, and one wants to get the
368: exponential of each one. This could easily be done either under GP or in
369: library mode, but in fact PARI assumes that this is exactly what you want to
370: do when you take the exponential of a vector, so no work is necessary. Most
371: transcendental functions work in the same way (see Chapter 3 for details).
372:
373: An ambiguity would arise with square matrices. PARI always considers that you
374: want to do componentwise function evaluation, hence to get for example the
375: exponential of a square matrix you would need to use a function with a
376: different name, \kbd{matexp} for instance. In the present version \vers, this
377: is not yet implemented. See however the program in Appendix C, which is a
378: first attempt for this particular function.
379:
380: The available operations and functions in PARI are described in detail in
381: Chapter 3. Here is a brief summary:
382:
383: \subsec{Standard operations}.
384:
385: \noindent
386: Of course, the four standard operators \kbd{+}, \kbd{-}, \kbd{*}, \kbd{/}
387: exist. It should once more be emphasized that division is, as far as possible,
388: an exact operation: $4$ divided by $3$ gives \kbd{(4/3)}. In addition to
389: this, operations on integers or polynomials, like \b{} (Euclidean
390: division), \kbd{\%} (Euclidean remainder) exist (and for integers, {\b{/}}
391: computes the quotient such that the remainder has smallest possible absolute
392: value). There is also the exponentiation operator \kbd{\pow }, when the
393: exponent is of type integer. Otherwise, it is considered as a transcendental
394: function. Finally, the logical operators \kbd{!} (\kbd{not} prefix operator),
395: \kbd{\&\&} (\kbd{and} operator), \kbd{||} (\kbd{or} operator) exist, giving
396: as results \kbd{1} (true) or \kbd{0} (false). Note that \kbd{\&} and \kbd{|}
397: are also accepted as synonyms respectively for \kbd{\&\&} and \kbd{||}.
398: However, there is no bitwise \kbd{and} or \kbd{or}.
399:
400: \subsec{Conversions and similar functions}.
401:
402: \noindent
403: Many conversion functions are available to convert between different types.
404: For example floor, ceiling, rounding, truncation, etc\dots. Other simple
405: functions are included like real and imaginary part, conjugation, norm,
406: absolute value, changing precision or creating an integermod or a polmod.
407:
408: \subsec{Transcendental functions}.
409:
410: \noindent
411: They usually operate on any object in $\C$, and some also on $p$-adics.
412: The list is everexpanding and of course contains all the elementary
413: functions, plus already a number of others. Recall that by extension, PARI
414: usually allows a transcendental function to operate componentwise on vectors
415: or matrices.
416:
417: \subsec{Arithmetic functions}.
418:
419: \noindent
420: Apart from a few like the factorial function or the Fibonacci numbers, these
421: are functions which explicitly use the prime factor decomposition of
422: integers. The standard functions are included. In the present version \vers,
423: a primitive, but useful version of Lenstra's Elliptic Curve Method (ECM) has
424: been implemented.
425:
426: There is now a very large package which enables the number theorist to work
427: with ease in algebraic number fields. All the usual operations on elements,
428: ideals, prime ideals, etc\dots are available.
429:
430: More sophisticated functions are also implemented, like solving Thue
431: equations, finding integral bases and discriminants of number fields,
432: computing class groups and fundamental units, computing in relative number
433: field extensions (including explicit class field theory), and also many
434: functions dealing with elliptic curves over $\Q$ or over local fields.
435:
436: \subsec{Other functions}.
437:
438: \noindent
439: Quite a number of other functions dealing with polynomials (e.g.~finding
440: complex or $p$-adic roots, factoring, etc), power series (e.g.~substitution,
441: reversion), linear algebra (e.g.~determinant, characteristic polynomial,
442: linear systems), and different kinds of recursions are also included. In
443: addition, standard numerical analysis routines like Romberg integration (open
444: or closed, on a finite or infinite interval), real root finding (when the
445: root is bracketed), polynomial interpolation, infinite series evaluation, and
446: plotting are included. See the last sections of Chapter~3 for details.
447: \vfill\eject
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to usersch1.tex CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM_contrib / pari-2.2 / doc