OpenXM_contrib/pari-2.2/doc/usersch4.tex - diff

Return to usersch4.tex CVS log

Up to [local] / OpenXM_contrib / pari-2.2 / doc

Diff for /OpenXM_contrib/pari-2.2/doc/Attic/usersch4.tex between version 1.1 and 1.2

version 1.1, 2001/10/02 11:16:58

version 1.2, 2002/09/11 07:26:43

Line 46 statement of a main program should be to initialize th

particular the PARI stack which will be both a scratchboard and a repository

for computed objects. This is done with a call to the function

\fun{void}{pari_init}{long size, long maxprime)}

\fun{void}{pari_init}{long size, ulong maxprime)}

\noindent The first argument is the number of bytes given to PARI to work

with (it should not reasonably be taken below 500000), and the second is the

Line 105 $\bullet$ access to all the built-in functions of the

These are declared to the outside world when you include \kbd{pari.h}, but

need the above things to function properly. So if you forget the call to

\tet{pari_init}, you will immediately get a fatal error when running your

program (usually a segmentation fault).

program.

\section{Important technical notes}

Line 149 abbreviate:

\kbdsidx{un}%

\kbdsidx{lpolx}

In general, replacing a leading \kbd{g} by an \kbd{l} in the name of a PARI

function will typecast the result to \kbd{long}. Note that \kbd{ldiv} is an

function will typecast the result to \kbd{long}. Note that \kbd{ldiv} is an ANSI C

ANSI C function which is is hidden in PARI by a macro of the same name

function which is hidden in PARI by a macro of the same name representing

representing \kbd{(long)gdiv}.

\kbd{(long)gdiv}.

The macro $\teb{coeff}(x,m,n)$ exists with exactly the meaning of \kbd{x[m,n]}

under GP when \kbd{x} is a matrix. This is a purely syntactical trick

Line 344 of efficiency, no checking is done in the function \kb

disasters will occur if you give an incorrect length.

\misctitle{Notes}:

1) The main use of this function is to prepare for later assigments

1) The main use of this function is to prepare for later assignments

(see \secref{se:assign}). Most of the time you will use \kbd{GEN} objects

as they are created and returned by PARI functions. In this case you don't need

to use \kbd{cgetg} to create space to hold them.

Line 450 syntax:

\fun{void}{gaffsg}{long s, GEN y}

\misctitle{Note}: due to the requirements mentionned above, it's usually

\misctitle{Note}: due to the requirements mentioned above, it's usually

a bad idea to use \tet{gaffect} statements. Two exceptions:

$\bullet$ for simple objects (e.g.~leaves) whose size is controlled, they can

Line 723 is less efficient than either \tet{gerepileupto} or \t

To cope with complicated cases where many objects have to be

preserved, you can use

\fun{void}{gerepilemany}{ulong ltop, GEN *gptr[], long n)}

\fun{void}{gerepileall}{ulong ltop, int n, ...}

\noindent which cleans up the most recent part of the stack (between

\noindent where the routine expects $n$ further arguments, which are the {\it

\kbd{ltop} and \kbd{avma}). All the \kbd{GEN}s pointed at by the elements of

addresses} of the \kbd{GEN}s you want to preserve. It cleans up the most

the array \kbd{gptr} (of length \kbd{n}) are updated. A copy is done just

recent part of the stack (between \kbd{ltop} and \kbd{avma}), updating all

before the cleaning to preserve them, so they don't need to be connected

the \kbd{GEN}s added to the argument list. A copy is done just before the

before the call. With \kbd{gerepilecopy}, this is the most robust of the

cleaning to preserve them, so they don't need to be connected before the

\kbd{gerepile} functions (the less prone to user error), but also the

call. With \kbd{gerepilecopy}, this is the most robust of the \kbd{gerepile}

slowest.

functions (the less prone to user error), but also the slowest.

An alternative, unnecessarily complicated, syntax is given by

\fun{void}{gerepilemany}{ulong ltop, GEN *gptr[], int n}

\noindent which works exactly as above, except that the preserved \kbd{GEN}s

are the elements of the array \kbd{gptr} (of length $n$): \kbd{gptr[0]},

\kbd{gptr[1]}, \dots, \kbd{gptr[$n$-1]}.

\noindent$\bullet$ More efficient, but tricky to use is

\fun{void}{gerepilemanysp}{ulong ltop, ulong lbot, GEN *gptr[], long n}

\fun{void}{gerepilemanysp}{ulong ltop, ulong lbot, GEN *gptr[], int n}

\noindent which cleans the stack between \kbd{lbot} and \kbd{ltop} and

updates the \kbd{GEN}s pointed at by the elements of \kbd{gptr} without doing

Line 907 assume anything about the stack: the garbage can be di

Line 915 assume anything about the stack: the garbage can be di

\kbd{z1}, \kbd{z2} need not be at the bottom of the stack. If all of these

assumptions are in fact satisfied, then we can call \kbd{gerepilemanysp}

instead, which will usually be faster since we don't need the initial copy

(on the other hand, it is less cache friendly).

(on the other hand, it is less cache friendly). The whole thing could (and

should) be abbreviated as

\bprog

gerepileall(ltop, 2, &z1, &z2)

@eprog

so that the array \kbd{gptr} is not needed anymore.

Another important usage is ``random'' garbage collection during loops

whose size requirements we cannot (or don't bother to) control in advance:

Line 921 whose size requirements we cannot (or don't bother to)

Line 934 whose size requirements we cannot (or don't bother to)

garbage(); y = anything()

garbage();

if (avma < limit) /*@Ccom memory is running low (half spent since entry) */

{

gerepileall(ltop, 2, &x, &y);

GEN *gptr[2];

gptr[0] = &x; gptr[1] = &y;

gerepilemany(ltop, gptr, 2);

}

@eprog

\noindent Here we assume that only \kbd{x} and \kbd{y} are needed from one

Line 1081 the highest order longword.

Line 1090 the highest order longword.

\fun{long}{mod2}{GEN x}, \fun{}{mod4}{x}, and so on up to \fun{}{mod64}{x},

which give the residue class of \kbd{x} modulo the corresponding power of

2, for {\it positive\/}~\kbd{x} (you will obtain weird results if you use

2, for {\it positive\/}~\kbd{x}. By definition, $\kbd{mod}n(x) :=

these on the integer 0 or on negative numbers).

\kbd{mod}n(|x|)$ for $x < 0$ (the macros disregard the sign), and the

result is undefined if $x = 0$.

These macros directly access the binary data and are thus much faster than

the generic modulo functions. Besides, they return long integers instead of

Line 1090 the generic modulo functions. Besides, they return lon

Line 1100 the generic modulo functions. Besides, they return lon

\subsec{Type \typ{REAL} (real number):}\kbdsidx{t_REAL}\sidx{real number}

this type has a second codeword z[1] which also encodes its sign (obtained

or set using the same functions as for the integers), and a biased binary

or set using the same functions as for the integers), and a binary

exponent (i.e.~the actual exponent value plus some constant bias, actually

exponent. This exponent can be handled using the following macros:

a power of~2, whose value is given by \kbd{HIGHEXPOBIT}). This exponent can

be handled using the following macros:

\fun{long}{expo}{GEN z} returns the true (unbiased) exponent of \kbd{z}.

\fun{long}{expo}{GEN z} returns the exponent of \kbd{z}.

This is defined even when \kbd{z} is equal to zero, see

\secref{se:whatzero}.

\fun{void}{setexpo}{GEN z, long e} sets the exponent of \kbd{z} to \kbd{e},

\fun{void}{setexpo}{GEN z, long e} sets the exponent of \kbd{z} to \kbd{e}.

of course after adding the bias.

\noindent Note the functions:

Line 1110 even if \kbd{z} is not a real number.

Line 1117 even if \kbd{z} is not a real number.

\fun{long}{gsigne}{GEN z} which returns a sign for \kbd{z}, even when

\kbd{z} is neither real nor integer (a rational number for instance).

The real zero is characterized by having its sign equal to 0. However,

The real zero is characterized by having its sign equal to 0. If \kbd{z} is

usually the first mantissa word \kbd{z[2]} is defined and equal to~0. This

not equal to~0, then is is represented as $2^e M$, where $e$ is the exponent,

fact must {\it never\/} be used to recognize a real~0. If \kbd{z} is not

and $M\in [1, 2[$ is the mantissa of $z$, whose digits are stored in

equal to~0, the first mantissa word \kbd{z[2]} is normalized, i.e.~its most

$\kbd{z[2]},\dots, \kbd{z[lg(z)-1]}$.

significant bit is~1. The mantissa is (\kbd{z[2]},\kbd{z[3]},\dots,%

\kbd{z[lg(z]-1]}) in base \kbd{2\pow BITS\_IN\_LONG}. Here, \kbd{z[2]} is

the most significant longword, and the mantissa takes values between

1 (included) and 2 (excluded). Thus, assume that \kbd{sizeof(long)} is 32 and

the length is 4, the real number $3.5$ is represented as \kbd{z[0]} (encoding

$\kbd{type} = \typ{REAL}$, $\kbd{lg} = 4$), \kbd{z[1]} (encoding $\kbd{sign} =

1$, $\kbd{expo} = 1$), $\kbd{z[2]} = \kbd{0xe0000000}$,

$\kbd{z[3]} = \kbd{0x0}$.

More precisely, let $m$ be the integer (\kbd{z[2]},\dots, \kbd{z[lg(z)-1]})

in base \kbd{2\pow BITS\_IN\_LONG}; here, \kbd{z[2]} is the most significant

longword and is normalized, i.e.~its most significant bit is~1. Then we have

$M := m \cdot 2^{1 - \kbd{bit\_accuracy(lg(z))}}$.

Thus, the real number $3.5$ to accuracy \kbd{bit\_accuracy(lg(z))} is

represented as \kbd{z[0]} (encoding $\kbd{type} = \typ{REAL}$, \kbd{lg(z)}),

\kbd{z[1]} (encoding $\kbd{sign} = 1$, $\kbd{expo} = 1$), $\kbd{z[2]} =

\kbd{0xe0000000}$, $\kbd{z[3]} =\dots = \kbd{z[lg(z)-1]} = \kbd{0x0}$.

\subsec{Type \typ{INTMOD} (integermod):}\kbdsidx{t_INTMOD}\sidx{integermod}

\kbd{z[1]} points to the modulus, and \kbd{z[2]} at the number representing

the class \kbd{z}. Both are separate \kbd{GEN} objects, and both must be of

Line 1151 are useful and make sense.

Line 1160 are useful and make sense.

\kbd{[1]} which contains the following information: the $p$-adic precision

(the exponent of $p$ modulo which the $p$-adic unit corresponding to

\kbd{z} is defined if \kbd{z} is not~0), i.e.~one less than the number of

significant $p$-adic digits, and the biased exponent of \kbd{z} (the bias

significant $p$-adic digits, and the exponent of \kbd{z}. This information

being equal to \kbd{HIGHVALPBIT} here). This information can be handled

can be handled using the following functions:

using the following functions:

\fun{long}{precp}{GEN z} returns the $p$-adic precision of \kbd{z}.

Line 1161 using the following functions:

Line 1169 using the following functions:

to \kbd{l}.

\fun{long}{valp}{GEN z} returns the $p$-adic valuation of \kbd{z} (i.e. the

unbiased exponent). This is defined even if \kbd{z} is equal to~0, see

exponent). This is defined even if \kbd{z} is equal to~0, see

\secref{se:whatzero}.

\fun{void}{setvalp}{GEN z, long e} sets the $p$-adic valuation of \kbd{z}

Line 1189 polynomial representing the class of~\kbd{z}. Both mus

Line 1197 polynomial representing the class of~\kbd{z}. Both mus

\typ{POL} in the same variable. However, \kbd{z[2]} is allowed to be a

simplification of such a polynomial, e.g a scalar. This is quite tricky

considering the hierarchical structure of the variables; in particular, a

polynomial in variable of \var{lesser} priority than the modulus variable

polynomial in variable of \var{lesser} priority (see \secref{se:priority})

is valid, since it can be considered as the constant term of a polynomial

than the modulus variable is valid, since it can be considered as the

of degree 0 in the correct variable. On the other hand a variable of

constant term of a polynomial of degree 0 in the correct variable. On the

\var{greater} priority would not be acceptable.

other hand a variable of \var{greater} priority would not be acceptable.

\subsec{Type \typ{POL} (polynomial):}\kbdsidx{t_POL}\sidx{polynomial} this

type has a second codeword which is analogous to the one for integers. It

Line 1214 not (see however the important remark below), a {\it v

Line 1222 not (see however the important remark below), a {\it v

\fun{void}{setvarn}{GEN z, long v} sets the variable number of \kbd{z} to

\kbd{v}.

The variable numbers encode the relative priorities of variables as discussed

in \secref{se:priority}. We will give more details in \secref{se:vars}.

Note also the function \fun{long}{gvar}{GEN z} which tries to return a

\idx{variable number} for \kbd{z}, even if \kbd{z} is not a polynomial or

power series. The variable number of a scalar type is set by definition

Line 1238 term \kbd{z[lgef(z)-1]} is not an exact zero.

Line 1248 term \kbd{z[lgef(z)-1]} is not an exact zero.

\subsec{Type \typ{SER} (power series):}\kbdsidx{t_SER}\sidx{power series} This

type also has a second codeword, which encodes a ``{\it sign\/}'', i.e.~0

if the power series is 0, and 1 if not, a {\it variable number\/} as for

polynomials, and a {\it biased exponent\/} with a bias of

polynomials, and an {\it exponent\/}. This information can be handled with

\kbd{HIGHVALPBIT}. This information can be handled with the following

the following functions: \teb{signe}, \teb{setsigne}, \teb{varn},

functions: \teb{signe}, \teb{setsigne}, \teb{varn}, \teb{setvarn} as for

\teb{setvarn} as for polynomials, and \teb{valp}, \teb{setvalp} for the

polynomials, and \teb{valp}, \teb{setvalp} for the exponent as for $p$-adic

exponent as for $p$-adic numbers. Beware: do {\it not\/} use \teb{expo} and

numbers. Beware: do {\it not\/} use \teb{expo} and \teb{setexpo} on power

\teb{setexpo} on power series.

series.

If the power series is non-zero, \kbd{z[2]}, \kbd{z[3]},\dots

\kbd{z[lg(z)-1]} point to the coefficients of \kbd{z} in ascending order,

Line 1293 contain the components of the list.

Line 1302 contain the components of the list.

\fun{char *}{GSTR}{z} (= \kbd{(z+1)}) points to the first character of the

(\kbd{NULL}-terminated) string.

\misctitle{Implementation note:} for the types including an exponent (or a

valuation), we actually store a biased non-negative exponent (bit-ORing the

biased exponent to the codeword), obtained by adding a constant to the true

exponent: either \kbd{HIGHEXPOBIT} (for \typ{REAL}) or \kbd{HIGHVALPBIT} (for

\typ{PADIC} and \typ{SER}). Of course, this is encapsulated by the

exponent/valuation-handling macros and need not concern the library user.

\section{PARI variables}\label{se:vars}

\subsec{Multivariate objects}

\subsec{Multivariate objects}\sidx{variable (priority)}

\noindent

We now consider variables and formal computations. As we have seen in

We now consider variables and formal computations, and give the technical

\secref{se:impl}, the codewords for types \typ{POL} and \typ{SER}

details corresponding to the general discussion in \secref{se:priority}. As

encode a ``variable number''. This is an integer, ranging from $0$ to

we have seen in \secref{se:impl}, the codewords for types \typ{POL} and

\kbd{MAXVARN}. The lower it is, the higher the variable priority. PARI does

\typ{SER} encode a ``variable number''. This is an integer, ranging from $0$

not know anything about intelligent ``sparse'' representation of polynomials.

to \kbd{MAXVARN}. The lower it is, the higher the variable priority.

So a multivariate polynomial in PARI is just a polynomial (in one variable),

whose coefficients are themselves (arbitrary) polynomials. All computations

are then just done formally on the coefficients as if the polynomial was

univariate.

In fact, the way an object will be considered in formal computations depends

entirely on its ``principal variable number'' which is given by the function

Line 1317 is not a polynomial or power series. The variable numb

Line 1329 is not a polynomial or power series. The variable numb

set by definition equal to \tet{BIGINT} which is bigger than any legal

variable number. The variable number of a recursive type which is not a

polynomial or power series is the minimal variable number of its components.

But for polynomials and power series only the ``outermost'' number counts:

But for polynomials and power series only the ``outermost'' number counts (we

the representation is not symmetrical at all.

directly access $\tet{varn}(x)$ in the codewords): the representation is not

symmetrical at all.

Under GP, one need not worry too much since the interpreter will define

the variables as it sees them and do the right thing with the polynomials

the variables as it sees them\footnote{*}{

produced (however, have a look at the remark in \secref{se:rempolmod}). But

More precisely, the first time a given identifier is read by the GP parser

in library mode, they are tricky objects if you intend to build polynomials

(and is not immediately interpreted as a function) a new variable is created,

yourself (and not just let PARI functions produce them, which is usually less

and it is assigned a strictly lower priority than any variable in use at this

efficient). For instance, it does not make sense to have a variable number

point. On startup, before any user input has taken place, 'x' is defined in

occur in the components of a polynomial whose main variable has a higher

this way and will thus always have maximal priority (and variable number $0$).}

number (lower priority), even though there's nothing PARI can do to prevent

you from doing it.

and do the right thing with the polynomials produced (however, have a look at

the remark in \secref{se:rempolmod}).

But in library mode, they are tricky objects if you intend to build

polynomials yourself (and not just let PARI functions produce them, which is

usually less efficient). For instance, it does not make sense to have a

variable number occur in the components of a polynomial whose main variable

has a higher number (lower priority), even though there's nothing PARI can do

to prevent you from doing it.

\subsec{Creating variables}

A basic difficulty is to ``create'' a variable. As we have seen in

\secref{se:intro4}, a plethora of objects is associated to variable

Line 1342 properly defined before you can use a given integer as

Line 1363 properly defined before you can use a given integer as

Initially, this is done for $0$ (the variable \kbd{x} under GP), and

\tet{MAXVARN}, which is there to address the need for a ``temporary'' new

variable, which would not be used in regular objects (created by the

variable in library mode and cannot be input under GP.

library). We call the latter type a ``temporary variable''. The regular

No documented library function can create from scratch an object involving

variables meant to be used in regular objects, are called ``user

\tet{MAXVARN} (of course, if the operands originally involve \kbd{MAXVARN},

the function will abide). We call the latter type a ``temporary variable''.

The regular variables meant to be used in regular objects, are called ``user

variables\sidx{variable (user)}''.

\subsubsec{User variables}\sidx{variable (user)}:

Line 1633 computation, just print the requested message and go o

Line 1656 computation, just print the requested message and go o

\noindent which is the exact equivalent of \kbd{err(talker,...)} except that

you certainly don't want to stop the program at this point, just inform the

user that something important has occured (in particular, this output would be

user that something important has occurred (in particular, this output would be

suitably highlighted under GP, whereas a simple \kbd{printf} would not).

\subsec{Debugging output}.\sidx{debugging}\sidx{format}\label{se:dbg_output}

Line 1681 prints \kbd{Time}, then the remaining arguments as spe

Line 1704 prints \kbd{Time}, then the remaining arguments as spe

\kbd{format} (which is a PARI format), then the output of \kbd{timer2}.

This mechanism is simple to use but not foolproof. If some other function

uses these timers, and many PARI functions do when DEBUGLEVEL is high enough,

uses these timers, and many PARI functions do use \kbd{timer2} when

the timings will be meaningless. The functions \fun{long}{gentimer}{long

\tet{DEBUGLEVEL} is high enough, the timings will be meaningless. To handle

id} or \fun{long}{genmsgtimer}{long id, char *format,...} are equivalent to

timing in a reentrant way, PARI defines a dedicated datatype,

\kbd{timer} and \kbd{msgtimer} respectively, except they will use a unique

\tet{pari_timer}. The functions

timer denoted by \kbd{id}. To get a valid identifier, use

\kbd{id = }\tet{get_timer}\kbd{(0)}.

This timer has to be deleted when it's not needed anymore

\fun{long}{TIMER}{pari\_timer *T}

(i.e.~when the main function returns), with a call to \kbd{get\_timer(id)}.

After such a call, the reserved identifier becomes available again.

\fun{long}{msgTIMER}{pari\_timer *T, char *format,...}

\noindent are equivalent to \kbd{timer} and \kbd{msgtimer} respectively,

except they use a unique timer \kbd{T} containing all the information needed,

so that no other function can mess with your timings. They are used as

follows:

\bprog

pari_timer T;

(void)TIMER(&T); /* initialize timer */

...

printf("Total time: %ld\n", TIMER(&T));

@eprog

\bprog

pari_timer T;

long i;

GEN L;

(void)TIMER(&T); /* initialize timer */

for (i = 1; i < 10; i++) {

...

msgTIMER(&T, "for i = %ld (L[i] = %Z)", i, L[i]);

}

@eprog

\section{A complete program}

\label{se:prog}

Line 1882 where \kbd{n} can be positive or negative. This is muc

Line 1927 where \kbd{n} can be positive or negative. This is muc

There is another function \teb{gshift} with exactly the same syntax.

When \kbd{n} is non-negative, the effects of these two functions are the same.

However, when \kbd{n} is negative, \kbd{gshift} acts like a right shift of

\kbd{-n}, hence does not noramlly perform an exact division on integers. The

\kbd{-n}, hence does not normally perform an exact division on integers. The

function \kbd{gshift} is the PARI analogue of the C or GP operators \kbd{<<}

and~\kbd{>>}.

Line 1995 lists).

Line 2040 lists).

Roughly four types of modifications can be made. The first type includes all

improvements to the documentation, in a broad sense. This includes correcting

typos or inacurracies of course, but also items which are not really covered

typos or inaccurracies of course, but also items which are not really covered

in this document, e.g.~if you happen to write a tutorial, or pieces of code

exemplifying some fine points that you think were unduly omitted.

Line 2055 output\cr

Line 2100 output\cr

\noindent$\bullet$ Optional arguments:

\+& \kbd{s*} & any number of strings, possibly 0 (see \kbd{s})\cr

\+& \kbd{s*p} & idem, setting $\kbd{prettyp} = 1$ (i.e.~in beautified

format)\cr

\+& \kbd{s*t} & idem, in \TeX\ format\cr

\+& \kbd{D\var{xxx}} & argument has a default value\cr

The \kbd{s*} code is technical and you probably do not need it, but we give

its description for completeness. It reads all remaining arguments in

\tev{string context} (see \secref{se:strings}), and sends a

(\kbd{NULL}-terminated) list of \kbd{GEN*} pointing to these. The automatic

concatenation rules in string context are implemented so that adjacent strings

are read as different arguments, as if they had been comma-separated. For

instance, if the remaining argument sequence is: \kbd{"xx" 1, "yy"}, the

\kbd{s*} atom will send a \kbd{GEN *g = \obr \&a, \&b, \&c, NULL\cbr}, where

$a$, $b$, $c$ are \kbd{GEN}s of type \typ{STR} (content \kbd{xx}), \typ{INT}

and \typ{STR} (content \kbd{yy}).

The format to indicate a default value (atom starts with a \kbd{D}) is

``\kbd{D\var{value},\var{type},}'', where \var{type} is the code for any

mandatory atom (previous group), \var{value} is any valide GP expression

mandatory atom (previous group), \var{value} is any valid GP expression

which is converted according to \var{type}, and the ending comma is

mandatory. For instance \kbd{D0,L,} stands for ``this optional argument will

be converted to a \kbd{long}, and is \kbd{0} by default''. So if the

user-given argument reads \kbd{1 + 3} at this point, \kbd{(long)4} is sent to

the function (via \tet{itos}$()$); and \kbd{(long)0} if the argument is

ommitted. The following special syntaxes are available:

omitted. The following special syntaxes are available:

\settabs\+\indent\indent&\kbd{Dxxx}\quad& optional \kbd{*GEN},&\cr

\+&\kbd{DG}& optional \kbd{GEN}, & send \kbd{NULL} if argument omitted.\cr

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