 NAME
 SYNOPSIS
 DESCRIPTION
 EXPORTed functions
 Available functions
 PARI objects
 PARI polynomials and Perl barewords
 Overloading and automatic conversion
 PREREQUISITES
 Perl vs. PARI: different syntax
 Highresolution graphics
 libPARI documentation
 ENVIRONMENT
 BUGS
 AUTHOR
NAME
Math::Pari
 Perl interface to PARI.
SYNOPSIS
use Math::Pari;
$a = PARI 2;
print $a**10000;
or
use Math::Pari qw(mod);
$a = mod(3,5);
print $a**10000;
DESCRIPTION
This package is a Perl interface to famous library PARI for numerical/scientific/numbertheoretic calculations. It allows use of most PARI functions as Perl functions, and (almost) seamless merging of PARI and Perl data. In what follows we suppose prior knowledge of what PARI is (see ftp://megrez.math.ubordeaux.fr/pub/pari).
EXPORTed functions
 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
new Math::Pari
). The function PARI() accepts following data as its arguments One integer

Is converted to a PARI integer.
 One float

Is converted to a PARI float.
 One string

Is executed as a PARI expresion (so should not contain whitespace).
 PARI object

Is passed unchanged.
 Reference to a Perl array

Each element is converted using the same rules, PARI vectorrow with these elements is returned.
 Several of above

The same as with a reference to array.
 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
PARI(1)
returns integer,PARI(1.)
returns float,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 is now is important.  PARIcol() and PARImat()

PARIcol() behaves in the same way as PARI() unless given several arguments. In the latter case it returns a vectorcolumn instead of vectorrow.
PARImat() constructs a matrix out of the given arguments. It will work if PARI() will construct a vector of vectors given the same arguments.
use
with arguments
If arguments are specified in the
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, or include:DEFAULT
tag.The other tags recognized are
:PARI
,:all
, and number tags, like:4
, and section names tags. The number tags export functions from the PARI library from the given class (except for:PARI
, which exports all the classes). Tag:all
exports all the exportable symbols and:PARI
.Giving
?
command togp
PARI calculator lists the following classes:1: Standard monadic or dyadic OPERATORS 2: CONVERSIONS and similar elementary functions 3: TRANSCENDENTAL functions 4: NUMBER THEORETICAL functions 5: Functions related to ELLIPTIC CURVES 6: Functions related to general NUMBER FIELDS 7: POLYNOMIALS and power series 8: Vectors, matrices, LINEAR ALGEBRA and sets 9: SUMS, products, integrals and similar functions 10: GRAPHIC functions 11: PROGRAMMING under GP
One can use section names instead of number tags. Recognized names are
:standard :conversions :transcendental :number :elliptic :fields :polynomials :vectors :sums :graphic :programming
One can get a list of all
Math::Pari
accessible functions usinglistPari()
function.
Available functions
Directly accessible from Perl
This package supports all the functions from the PARI library with a signature from a long 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, as in
3 + PARI('O(x^17)')
(or some special wrapper functions, like O(variable,power)
). A perl script parifonc
is provided that lists the functions from the current release of PARI that are unavailable with the current release of this glue code.
The output as of 9/22/97 is
Builtins, unsupported as functions (but available in Perl):
label, while, goto, until, read, pprint, print,
texprint, pprint1, print1, O, if, o
Total number of unsupported interfaces: 19:
Interface 16 used in 1 function(s): plotterm.
Interface 19 used in 2 function(s): rlinetype, rpointtype.
Interface 44 used in 1 function(s): rcopy.
Interface 45 used in 1 function(s): rplothraw.
Interface 57 used in 1 function(s): string.
Interface 59 used in 1 function(s): scale.
Interface 73 used in 1 function(s): rploth.
Interface 85 used in 1 function(s): kill.
Interface 86 used in 1 function(s): forstep.
Interface 87 used in 1 function(s): forvec.
Interface 89 used in 1 function(s): buchinitforcefu.
Interface 90 used in 1 function(s): buchinitfu.
Interface 91 used in 1 function(s): buchinit.
Interface 92 used in 1 function(s): buchgen.
Interface 94 used in 1 function(s): buchgenfu.
Interface 95 used in 1 function(s): buchgenforcefu.
Interface 96 used in 1 function(s): buchimag.
Interface 97 used in 1 function(s): buchreal.
Interface 99 used in 1 function(s): addhelp.
Total number of unsupported functions: 20:
group 4: buchimag, buchreal
group 6: buchgen, buchgenforcefu, buchgenfu, buchinit,
buchinitforcefu, buchinitfu
group 10: forstep, forvec, plotterm, rcopy, rlinetype,
rploth, rplothraw, rpointtype, scale, string
group 11: addhelp, kill
Arguments
Arguments to PARI functions are converted to long
or PARI type depending on what type the actual library function requires. No error checking on arguments is done, so if gp
rejects your code since a particular argument should be of type 1
(i.e., a Pari integer), Math::Pari
will silently convert it to long
. Each argument is converted by the rules applicable to PARI.
Return values
PARI functions return PARI type or a Perl's integer depending on what the actual library function returns.
Additional functions
Some PARI functions are available in gp
(i.e., in PARI
calculator) via infix notation only. In Math::Pari
these functions are available in functional notations too. Some other convenience functions are also made available.
 Infix, prefix and postfix operations

are available under names
gneg, gadd, gsub, gmul, gdiv, gdivent, gmod, gpui, gle, gge, glt, ggt, geq, gne, gegal, gor, gand, gcmp, gcmp0, gcmp1, gcmp_1.
gdivent
means euclidean quotient,gpui
is power,gegal
checks whether two objects are equal,gcmp
is applicable to two real numbers only,gcmp0
,gcmp1
,gcmp_1
compare with 0, 1 and 1 correspondingly (see PARI user manual for details). Note that all these functions are more readily available via operator overloading, so instead ofgadd($x, gneg($y))
one can write
$x+($y)
(as far as overloading may be triggered, so we assume that $x or $y is of PARI type already).
 Conversion functions

pari2iv, pari2nv, pari2num, pari2pv, pari2bool
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.
 Printout functions

pari_print, pari_pprint, pari_texprint
perform conversions to strings as their PARI counterparts, but do not print the result. The difference of pari_print() with pari2pv() is the number of significant digits they print.)
 Constant functions

Some mathematical constant appear as function without arguments in PARI. Perl has a facility to have similar functions. If you export them like in
use Math::Pari qw(:DEFAULT pi i euler);
they can be used as barewords in your program.
 Lowlevel functions

For convenience of lowlevel PARI programmers some lowlevel functions are made available as well (they are not exported):
typ(x) changevalue(name,newvalue)
 Uncompatible functions

O
Since implementing
O(7**6)
would be very tedious, we provide a twoargument formO(7,6)
instead. Note that with polynomials there is no problem like this one, bothO($x,6)
andO($x**6)
work.ifact(n)
integer factorial functions, available from
gp
asn!
.
Looping functions
PARI has a big collection of functions which loops over some set. Such a function takes two special arguments: loop variable, and the code to execute in the loop.
The code can be either a string (which contains PARI code to execute  thus should not contain whitespace), or a Perl code reference. The loop variable can be a string giving the name of PARI variable (as in
fordiv(28, 'j', 'a=a+j+j^2');
or
$j= 'j';
fordiv(28, $j, 'a=a+j+j^2');
), or a Perl variable containing a PARI variable (as in
$j = PARI 'j';
fordiv(28, $j, sub { $a += $j + $j**2 });
).
If the loop variable is not of these two types, then an appropriate name will be autogenerated. Note that since you have no control over this name, you will not be able to use this variable from your PARI code, say
$j = 7.8;
fordiv(28, $j, 'a=a+j+j^2');
will not (obviously) expand j
to mirror $j (unless you set up j
to mirror $j explicitely, see "Accessing Perl functions from PARI code").
Useless musing alert! Do not read the rest of this section!
In fact a very hairy type of access is also supported. Note that the following code will not do what you expect
$x = 0;
$j = PARI 'j';
fordiv(28, 'j', sub { $x += $j } );
since fordiv
will localize j
inside the loop, so $j will still reference the old value, which is an independent variable, not the index of the loop. The simplest workaround is not to use the above syntax (i.e., not mixing literal loop variable with Perl loop code, just using $j as the second argument to fordiv
is enough).
However, if absolutely required, one can make a delayed variable $j which will always reference the same thing j
references now by using PARIvar
constructor
$x = 0;
$j = PARIvar 'j';
fordiv(28, 'j', sub { $x += $j } );
This problem is related to
$ref = \$_; # $$ref is going to be old value even after
# localizing $_ in Perl's grep/map
not accessing localized values of $_ in the plain Perl.
Accessing Perl functions from PARI code
This is possible. Just use the same name for the function:
sub counter { $i += shift; }
$i = 145;
PARI 'k=5' ;
fordiv(28, 'j', 'k=k+counter(j)');
print PARI('k'), "\n";
prints
984
Note that if the subroutine takes a variable number of arguments, each @
in the prototype (or a missing prototype) counts as 6 optional arguments are supported. If called from PARI with fewer arguments optional arguments will be set to integer PARI 0.
Note also that no direct import of Perl variables is available yet (but you can write a function wrapper for this):
sub getv () {$v}
There is an undocumented function for explicitely importing Perl functions into Pari, possibly with a different name, and possibly with explicitely specifying number of arguments.
PARI objects
Functions from PARI library take as arguments and/or return objects of type GEN
(in C
notations). In Perl these data are encapsulated into special kind of Perl variables: PARI objects. You can check for a variable $obj
to be a PARI object using
ref $obj eq 'Math::Pari';
Most the time you do not need this due to automatic conversions.
PARI polynomials and Perl barewords
Some bareletters denote Perl operators, like q
, x
, y
, s
. This can lead to errors in Perl parsing your expression. Say, while
print sin(tan(x))tan(sin(x))asin(atan(x))+atan(asin(x));
may parse OK (after use Math::Pari qw(sin tan asin atan)
),
print sin(tan(y))tan(sin(y))asin(atan(y))+atan(asin(y));
does not. You should avoid lowercase barewords used as PARI variables, say, do
$y = PARI('y');
print sin(tan($y))tan(sin($y))asin(atan($y))+atan(asin($y));
to get
1/18*y^9+26/4725*y^1141/1296*y^13+328721/16372125*y^15+O(y^16)
Well, frankly speaking you should not use barewords anywhere in your program!
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 gcmp
and friends, string comparisons compare in lexicographical order using lex
. Currently the following arithmetic operations are overloaded:
unary 
+  * / % ** abs cos sin exp log sqrt
<= == => < > != <=>
le eq ge lt gt ne cmp
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 gcmp0
in PARI reference).
Note that a check for equality is subject to same pitfalls as in PARI due to imprecise values. PARI may also refuse to compare data of different types for equality if it thinks this may lead to counterintuitive results.
Note also that numeric ordering is not defined for some types of PARI objects. For string comparison operations we use PARIlexicographical ordering.
PREREQUISITES
Perl
In the versions of perl earlier than 5.003 overloading used a different interface, so you may need to convert use overload
line to %OVERLOAD
, or, better, upgrade.
PARI
Starting from version 0.5, this module comes with a PARI library included.
If you want to put in a different PARI library, you need at least version 1.39 of PARI. (See ftp://megrez.math.ubordeaux.fr/pub/pari.)
Perl vs. PARI: different syntax
Note that the PARI notations should be used in string arguments to PARI() function, while Perl notations should be used otherwise.
^

Power is denoted by
**
in Perl. \
and\/

There are no such operators in Perl, use the word forms
gdivent(x,y)
andgdivround(x,y)
instead. ~

There is no postfix
~
Perl operator. Use trans() instead. _

There is no postfix
_
Perl operator. Use conj() instead. '

There is no postfix
'
Perl operator. Use deriv() instead. !

There is no postfix
!
Perl operator. Use fact()/ifact() instead (returning a real or an integer correspondingly).  big integers

Currently Perl will convert big literal integers to doubles if they could not be put into C 32bit signed integers. If you want to input such an integer, use PARI('12345678901234567890').
 doubles

Doubles in Perl are of precision approximately 15 digits. When you use them as arguments to PARI functions, they are converted to PARI real variables, and due to intermediate 15decimaltobinary conversion of Perl variables the result may be different than with the PARI manydecimaltobinary conversion. Say,
PARI(0.01)
andPARI('0.01')
differ at 19th place, assetprecision(38); print pari_print(0.01), "\n", pari_print('0.01'), "\n";
shows.
 array base

Arrays are 1based in PARI, are 0based in Perl. So while array access is possible in Perl, you need to use different indices:
$nf = PARI 'nf'; # number field $a = PARI('nf[7]'); $b = $nf>[6];
Now $a nd $b contain the same value.
 matrices

Note that
PARImat([[...],...,[...])
constructor creates a matrix with specified columns, while PARI's[1,2,3;4,5,6]
constructor creates a matrix with specified rows. Use a convenience function PARImat_tr() which will transpose a matrix created by PARImat() to use the same order of elements as in PARI.  builtin perl functions

Some PARI functions, like
length
andeval
, are Perl (semi)reserved words. To reach these functions, one should either import them, or call them with prefix (like&length
) or the full name (likeMath::Pari::length
).  string($w, $text)

will not coerce a number into
8+3
format. You need to usesprintf "%8.3f", $text
explicitely.
Highresolution graphics
If you have Term::Gnuplot installed, you may use highresolution graphic primitives of PARI. Before the usage you need to establish a link between Math::Pari and Term::Gnuplot by calling link_gnuplot(). You can change the output filehandle by calling set_plot_fh(), and output terminal by calling plotterm(), as in
use Math::Pari ':all';
open FH, '>out.tex' or die;
link_gnuplot();
set_plot_fh(\*FH);
plotterm('emtex');
ploth($x, .5, .999, sub {asin $x});
close FH or die;
libPARI documentation
libPARI documentation is included, see libPARI. It is converted from Chapter 3 of PARI/GP documentation by chap3_to_pod script.
ENVIRONMENT
No environment variables are used.
BUGS
A few of PARI functions are available indirectly only.
t/failing.t
This test suite exposes several bugs.
AUTHOR
Ilya Zakharevich, ilya@math.ohiostate.edu
1 POD Error
The following errors were encountered while parsing the POD:
 Around line 563:
Expected '=item *'