@node Pari, Parity, Parext, Module List
@unnumbered Perl interface to PARI.


@unnumberedsec NAME

@code{Math::Pari} - Perl interface to PARI.

@unnumberedsec SYNOPSIS

@example
use Math::Pari;
$a = PARI 2;
print $a**10000;
@end example

or

@example
use Math::Pari qw(mod);
$a = mod(3,5);
print $a**10000;
@end example

@unnumberedsec DESCRIPTION

This package allows use of most PARI functions as Perl functions. In
what follows we suppose prior knowledge of what PARI is (see
@samp{ftp:} in this node).

@unnumberedsec EXPORT

@table @asis
@item DEFAULT
By default the package exports functions PARI(), PARIcol() and
PARImat() that converts its argument(s) to a 
PARI object. (In fact PARI() is just an alias for @code{new Math::Pari}).
The function PARI() accepts following data as its arguments

@table @asis
@item One integer
Is converted to a PARI integer.

@item One float
Is converted to a PARI float.

@item One string
Is executed as a PARI expresion (so should not contain whitespace).

@item PARI object
Is passed unchanged.

@item Reference to a Perl array
Each element is converted using the same rules, PARI vector-row with these
elements is returned.

@item Several of above
The same as with a reference to array.

@end table
@item Conflicts of rules in PARI()
In deciding what rule of the above to apply the preference is given to
the uppermost choice of available now, if none matches, then the string
rule is used. So @code{PARI(1)} returns integer, @code{PARI(1.)} returns
float, @code{PARI("1")} evaluates "1" as a PARI expression, though all
these data can be converted inside Perl into integer, float or
string. Only what the argument @emph{is now} is important.

@item PARIcol() and PARImat()
PARIcol() behaves in the same way as PARI() unless given several
arguments. In the latter case it returns a vector-column instead of
vector-row. 

PARImat() constructs a matrix out of the given arguments. It will work
if PARI() will construct a vector of vectors given the same arguments.

@item use with arguments
If arguments are specified in the @code{use Math::Pari} directive, the
PARI functions appearing as arguments are exported in the caller context. In
this case the function PARI() and friends is not exported, so if you
need them, you should include them into export list explicitely. 

@end table
@unnumberedsec Available functions

@unnumberedsubsec Directly accessible from Perl

This package supports all the functions from the PARI library with
a signature from a short list. This means that when you update the
PARI library, the newly added function will we available without any change
to this package (provided their signature is in the supported
list). You can reach unsupported functions using
string argument of PARI() function.

A perl script @code{parifonc} is provided that lists the functions from
the current release of PARI that are unavailable with the current
release of this glue code. You should specify two arguments to this
script: a path to @code{anal.c} file of PARI/GP distribution, and path to
the file  @code{Pari.xs} from your truely package.

@unnumberedsubsec Arguments

Arguments to PARI functions are converted to @code{long} or PARI type
depending on what type the actual library function requires. No error
checking on arguments is done, so if @code{gp} rejects your code since a
particular argument should be of @code{type 1} (i.e., a Pari integer),
@code{Math::Pari} will silently convert it to @code{long}. Each argument is
converted by the rules applicable to PARI().

@unnumberedsubsec Return values

PARI functions return PARI type or a @code{long} depending on what the
actual library function returns. 

@unnumberedsubsec Additional functions

Some PARI functions are available in @code{gp} (i.e., in PARI
calculator) via infix notation only. In @code{Math::Pari} these functions
are available in functional notations too. Some other convenience
functions are also made available.

@table @asis
@item Infix, prefix and postfix operations
are available under names

@example
gneg, gadd, gsub, gmul, gdiv, gdivent, gmod, gpui,
gle, gge, glt, ggt, geq, gne, gegal, gor, gand,
gcmp, gcmp0, gcmp1, gcmp_1.
@end example

@code{gdivent} means euclidean quotient, @code{gpui} is power, @code{gegal} checks
whether two objects are equal, @code{gcmp} is applicable to two real
numbers only, @code{gcmp0}, @code{gcmp1}, @code{gcmp_1} compare with 0, 1 and -1
correspondingly  (see PARI user manual for details).

@item Convenience functions
@example
pari2iv, pari2nv, pari2num, pari2pv, pari2bool
@end example

convert a PARI object to an integer, float, integer/float (whatever is
better), string, and a boolean value correspondingly. Most the time
you do not need these functions due to automatic conversions.

@item Constant functions
Some mathematical constant appear as function without arguments in
PARI. Corresponding functions are made available under Perl. If you
export them like in

@example
use Math::Pari wq(pi i euler);
@end example

they can be used as barewords in your program, with the usual
restrictions that sometimes you should disambiguate the call like in

@example
$negOne = exp(pi() * i);
@end example

The parentheses after @code{pi} are needed since Perl thinks you want to call
@code{pi} with argument @code{*i} otherwise (since @code{*i} is a legal Perl
expression, and function calls are greedy on the right).

@end table
@unnumberedsec PARI objects

Functions from PARI library take as arguments and/or return objects of
type @code{GEN} (in C notations). In Perl these data are encapsulated
into special kind of Perl variables: PARI objects. You can check for a
variable @code{$obj} to be a PARI object using

@example
ref $obj eq @'Math::Pari@';
@end example

Most the time you do not need this due to automatic conversions.

@unnumberedsec PARI polynomials and Perl barewords

Some bareletters denote Perl operators, like q, x, @code{y},
s. This can lead to errors in Perl parsing your expression. Say, while

@example
print sin(tan(x))-tan(sin(x))-asin(atan(x))+atan(asin(x));
@end example

parses OK (after @code{use Math::Pari qw(sin tan asin atan)}),

@example
print sin(tan(y))-tan(sin(y))-asin(atan(y))+atan(asin(y));
@end example

does not. You should avoid lower-case barewords used as PARI variables.

@unnumberedsec Overloading and automatic conversion

Whenever an arithmetic operation includes a PARI object the other
arguments are converted to a PARI type and the corresponding PARI
library functions is used to implement the operation. Numeric
comparison operations use @code{gcmp} and friends, string comparisons compare in
lexicographical order using @code{lex}. Currently the following arithmetic
operations are overloaded:

@example
unary -, +, -, *, /, %, **, abs, cos, sin, exp, log, sqrt.
@end example

Whenever a PARI object appears in a situation that requires integer,
numeric, boolean or string data, it is converted to the corresponding
type. Boolean conversion is subject to usual PARI pitfalls related to
imprecise zeros (see documentation of @code{gcmp0} in PARI reference).

@unnumberedsec PREREQUISITES

@unnumberedsubsec Perl

To compile the extension you need to have at least @code{MakeMaker}
version 3.7. In the versions of perl earlier than 5.001 negative
constants were converted to floats, so to use PARI operations that do
different things on integers and floats you would like to use a more
recent version of perl. Overloading was buggy in 5.000.

@unnumberedsubsec PARI

You need at least version 1.39 of PARI. (See
@samp{ftp:} in this node.)

@unnumberedsec ENVIRONMENT

No environment variables are used.

@unnumberedsec BUGS

@itemize @bullet
@item 
Not all the PARI functions are directly available.

@item 
Many others...

@end itemize
@unnumberedsec AUTHOR

Ilya Zakharevich, @emph{ilya@@math.mps.ohio-state.edu}

