.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.37
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Pari 3"
.TH Pari 3 "2009-11-11" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Math::Pari \- Perl interface to PARI.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  use Math::Pari;
\&  $a = PARI 2;
\&  print $a**10000;
.Ve
.PP
or
.PP
.Vb 3
\&  use Math::Pari qw(Mod);
\&  $a = Mod(3,5);
\&  print $a**10000;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This package is a Perl interface to famous library \s-1PARI\s0 for
numerical/scientific/number\-theoretic calculations.  It allows use of
most \s-1PARI\s0 functions as Perl functions, and (almost) seamless merging
of \s-1PARI\s0 and Perl data. In what follows we suppose prior knowledge of
what \s-1PARI\s0 is (see <ftp://megrez.math.u\-bordeaux.fr/pub/pari>, or
Math::libPARI).
.SH "EXPORTed functions"
.IX Header "EXPORTed functions"
.IP "\s-1DEFAULT\s0" 4
.IX Item "DEFAULT"
By default the package exports functions \s-1\fIPARI\s0()\fR, \fIPARIcol()\fR, \fIPARIvar()\fR,
\&\fIPARImat()\fR and \fIPARImat_tr()\fR which convert their argument(s) to a
\&\s-1PARI\s0 object. (In fact \s-1\fIPARI\s0()\fR is just an alias for \f(CW\*(C`new Math::Pari\*(C'\fR).
The function \s-1\fIPARI\s0()\fR accepts following data as its arguments
.RS 4
.IP "One integer" 17
.IX Item "One integer"
Is converted to a \s-1PARI\s0 integer.
.IP "One float" 17
.IX Item "One float"
Is converted to a \s-1PARI\s0 float.
.IP "One string" 17
.IX Item "One string"
Is executed as a \s-1PARI\s0 expresion (so should not contain whitespace).
.IP "\s-1PARI\s0 object" 17
.IX Item "PARI object"
Is passed unchanged.
.IP "Reference to a Perl array" 17
.IX Item "Reference to a Perl array"
Each element is converted using the same rules, \s-1PARI\s0 vector-row with these
elements is returned.
.IP "Several of above" 17
.IX Item "Several of above"
The same as with a reference to array.
.RE
.RS 4
.RE
.IP "Conflicts of rules in \s-1\fIPARI\s0()\fR" 4
.IX Item "Conflicts of rules in PARI()"
In deciding what rule of the above to apply the preference is given to
the uppermost choice of those available \fInow\fR.  If none matches, then
the string rule is used.  So \f(CWPARI(1)\fR returns integer, \f(CW\*(C`PARI(1.)\*(C'\fR
returns float, \f(CW\*(C`PARI("1")\*(C'\fR evaluates \f(CW1\fR as a \s-1PARI\s0 expression (well,
the result is the same as \f(CWPARI(1)\fR, only slower).
.Sp
Note that for Perl these data are synonimous, since Perl freely
converts between integers, float and strings.  However, to \s-1\fIPARI\s0()\fR only
what the argument \fIis now\fR is important.  If \f(CW$v\fR is \f(CW1\fR in the Perl
world, \f(CW\*(C`PARI($v)\*(C'\fR may convert it to an integer, float, or to the
result of evaluating the \s-1PARI\s0 program \f(CW1\fR (all depending on how \f(CW$v\fR
was created and accessed in Perl).
.Sp
This is a fundamental limitation of creating an interface between two
systems, both with polymorphic objects, but with subtly different
semantic of the flavors of these objects.  In reality, however, this
is rarely a problem.
.IP "\fIPARIcol()\fR, \fIPARImat()\fR and \fIPARImat_tr()\fR" 4
.IX Item "PARIcol(), PARImat() and PARImat_tr()"
\&\fIPARIcol()\fR behaves in the same way as \s-1\fIPARI\s0()\fR unless given several
arguments. In the latter case it returns a vector-column instead of
a vector\-row.
.Sp
\&\fIPARImat()\fR constructs a matrix out of the given arguments. It will work
if \s-1\fIPARI\s0()\fR will construct a vector of vectors given the same arguments.
The internal vectors become columns of the matrix.  \fIPARImat_tr()\fR
behaves similarly, but the internal vectors become rows of the matrix.
.Sp
Since \s-1PARI\s0 matrices are similar to vector-rows of vector\-columns,
\&\fIPARImat()\fR is quickier, but \fIPARImat_tr()\fR better corresponds to the \s-1PARI\s0
input and output forms of matrices:
.Sp
.Vb 2
\&  print PARImat    [[1,2], [3,4]];      # prints [1,3;2,4]
\&  print PARImat_tr [[1,2], [3,4]];      # prints [1,2;3,4]
.Ve
.ie n .IP """use"" with arguments" 4
.el .IP "\f(CWuse\fR with arguments" 4
.IX Item "use with arguments"
If arguments are specified in the \f(CW\*(C`use Math::Pari\*(C'\fR directive, the
\&\s-1PARI\s0 functions appearing as arguments are exported in the caller
context. In this case the function \s-1\fIPARI\s0()\fR and friends is not exported,
so if you need them, you should include them into export list
explicitely, or include \f(CW\*(C`:DEFAULT\*(C'\fR tag:
.Sp
.Vb 2
\&  use Math::Pari qw(factorint PARI);
\&  use Math::Pari qw(:DEFAULT factorint);
.Ve
.Sp
or simply do it in two steps
.Sp
.Vb 2
\&  use Math::Pari;
\&  use Math::Pari 'factorint';
.Ve
.Sp
The other tags recognized are \f(CW\*(C`:PARI\*(C'\fR, \f(CW\*(C`:all\*(C'\fR, \f(CW\*(C`prec=NUMBER\*(C'\fR,
number tags (e.g., \f(CW\*(C`:4\*(C'\fR), overloaded constants tags (\f(CW\*(C`:int\*(C'\fR,
\&\f(CW\*(C`:float\*(C'\fR, \f(CW\*(C`:hex\*(C'\fR) and section names tags.  The number tags export
functions from the \s-1PARI\s0 library from the given class (except for
\&\f(CW\*(C`:PARI\*(C'\fR, which exports all of the classes).  Tag \f(CW\*(C`:all\*(C'\fR exports all of the
exportable symbols and \f(CW\*(C`:PARI\*(C'\fR.
.Sp
Giving \f(CW\*(C`?\*(C'\fR command to \f(CW\*(C`gp\*(C'\fR (\fB\s-1PARI\s0\fR calculator) lists the following classes:
.Sp
.Vb 11
\&  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
.Ve
.Sp
One can use section names instead of number tags.  Recognized names are
.Sp
.Vb 2
\&  :standard :conversions :transcendental :number :elliptic
\&  :fields :polynomials :vectors :sums :graphic :programming
.Ve
.Sp
One can get the list of all of the functions accessible by \f(CW\*(C`Math::Pari\*(C'\fR,
or the accessible functions from the given section using \fIlistPari()\fR function.
.Sp
Starting from version 5.005 of Perl, three constant-overload tags are
supported: \f(CW\*(C`:int\*(C'\fR, \f(CW\*(C`:float\*(C'\fR, \f(CW\*(C`:hex\*(C'\fR.  If used, all the
integer/float/hex\-or\-octal\-or\-binary literals in Perl will be automatically
converted to became \s-1PARI\s0 objects.  For example,
.Sp
.Vb 2
\&  use Math::Pari ':int';
\&  print 2**1000;
.Ve
.Sp
is equivalent to
.Sp
.Vb 1
\&  print PARI(2)**PARI(1000);
.Ve
.Sp
(The support for this Perl feature is buggy before the Perl version 5.005_57 \-
unless Perl uses mymalloc options; you can check for this with \f(CW\*(C`perl
\&\-V:usemymalloc\*(C'\fR.)  Note also that (at least with some versions of Perl)
one should enable \f(CW':float'\fR for conversion of long integer literals
(\fIPerl\fR may consider them as floats, since they won't fit into Perl
integers); note that it is \s-1PARI\s0 which determines which \s-1PARI\s0 subtype is
assigned to each such literal:
.Sp
.Vb 2
\&  use Math::Pari ':float', 'type_name';
\&  print type_name 22222222222222222222222;
.Ve
.Sp
prints \f(CW\*(C`t_INT\*(C'\fR.
.SH "Available functions"
.IX Header "Available functions"
.Sh "Directly accessible from Perl"
.IX Subsection "Directly accessible from Perl"
This package supports \fIall\fR the functions from the \s-1PARI\s0 library with
a \fIsignature\fR which can be recognized by Math::Pari.  This means that
when you update the \s-1PARI\s0 library, the newly added functions will we
available without any change to this package; only a recompile is
needed.  In fact no recompile will be needed if you link libPARI
dynamically (you need to modify the \fIMakefile\fR manually to do
this).
.PP
You can \*(L"reach\*(R" unsupported functions via going directly to \s-1PARI\s0
parser using the string flavor of \s-1\fIPARI\s0()\fR function, as in
.PP
.Vb 1
\&  3 + PARI('O(x^17)');
.Ve
.PP
For some \*(L"unreachable\*(R" functions there is a special wrapper functions,
such as \f(CW\*(C`O(variable,power)\*(C'\fR).
.PP
The following functions are specific to \s-1GP\s0 calculator, thus are not
available to Math::Pari in any way:
.PP
.Vb 2
\&  default error extern input print print1 printp printp1
\&  printtex quit read system whatnow write write1 writetex
.Ve
.PP
\&\fIwhatnow()\fR function is useless, since Math::Pari does not support the
\&\*(L"compatibility\*(R" mode (with older \s-1PARI\s0 library).  The functionality of
\&\fIprint()\fR, \fIwrite()\fR and variants is available via automatic string
translation, and \fIpari_print()\fR function and its variants (see \*(L"Printout functions\*(R").
.PP
\&\fIdefault()\fR is the only important function with functionality not
supported by the current interface.  Note however, that three most
important \fIdefault()\fR actions are supported by \fIallocatemem()\fR,
\&\fIsetprimelimit()\fR, \fIsetprecision()\fR and \fIsetseriesprecision()\fR functions.
(When called without arguments, these functions return the current
values.)
.PP
allocatemem($bytes) should not be called from inside Math::Pari
functions (such as \fIforprimes()\fR).
.Sh "Arguments"
.IX Subsection "Arguments"
Arguments to \s-1PARI\s0 functions are automatically converted to \f(CW\*(C`long\*(C'\fR or
a \s-1PARI\s0 object depending on the signature of the actual library function.
The arguments are \fIforced\fR into the given type, so even if \f(CW\*(C`gp\*(C'\fR
rejects your code similar to
.PP
.Vb 1
\&  func(2.5);                    # func() takes a long in C
.Ve
.PP
arguing that a particular argument should be of \f(CW\*(C`type T_INT\*(C'\fR (i.e., a
Pari integer), the corresponding code will work in \f(CW\*(C`Math::Pari\*(C'\fR,
since 2.5 is silently converted to \f(CW\*(C`long\*(C'\fR, per the function
signature.
.Sh "Return values"
.IX Subsection "Return values"
\&\s-1PARI\s0 functions return a \s-1PARI\s0 object or a Perl's integer depending on
what the actual library function returns.
.Sh "Additional functions"
.IX Subsection "Additional functions"
Some \s-1PARI\s0 functions are available in \f(CW\*(C`gp\*(C'\fR (i.e., in \f(CW\*(C`PARI\*(C'\fR
calculator) via infix notation only. In \f(CW\*(C`Math::Pari\*(C'\fR these functions
are available in functional notations too.  Some other convenience
functions are also made available.
.IP "Infix, prefix and postfix operations" 5
.IX Item "Infix, prefix and postfix operations"
are available under names
.Sp
.Vb 3
\&  gneg, gadd, gsub, gmul, gdiv, gdivent, gmod, gpui,
\&  gle, gge, glt, ggt, geq, gne, gegal, gor, gand,
\&  gcmp, gcmp0, gcmp1, gcmp_1.
.Ve
.Sp
\&\f(CW\*(C`gdivent\*(C'\fR means euclidean quotient, \f(CW\*(C`gpui\*(C'\fR is power, \f(CW\*(C`gegal\*(C'\fR checks
whether two objects are equal, \f(CW\*(C`gcmp\*(C'\fR is applicable to two real
numbers only, \f(CW\*(C`gcmp0\*(C'\fR, \f(CW\*(C`gcmp1\*(C'\fR, \f(CW\*(C`gcmp_1\*(C'\fR compare with 0, 1 and \-1
correspondingly (see \s-1PARI\s0 user manual for details, or
Math::libPARI).  Note that all these functions are more readily
available via operator overloading, so instead of
.Sp
.Vb 1
\&  gadd(gneg($x), $y)
.Ve
.Sp
one can write
.Sp
.Vb 1
\&  -$x+$y
.Ve
.Sp
(as far as overloading may be triggered, see overload, so we assume
that at least one of \f(CW$x\fR or \f(CW$y\fR is a \s-1PARI\s0 object).
.IP "Conversion functions" 5
.IX Item "Conversion functions"
.Vb 1
\&  pari2iv, pari2nv, pari2num, pari2pv, pari2bool
.Ve
.Sp
convert a \s-1PARI\s0 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.
.IP "Printout functions" 5
.IX Item "Printout functions"
.Vb 1
\&  pari_print, pari_pprint, pari_texprint
.Ve
.Sp
perform the same conversions to strings as their \s-1PARI\s0 counterparts,
but do not print the result.  The difference of \fIpari_print()\fR with
\&\fIpari2pv()\fR is the number of significant digits they output, and
whitespace in the output.  \fIpari2pv()\fR, which is intended for
\&\*(L"computer\-readable strings\*(R", outputs as many digits as is supported by
the current precision of the number; while \fIpari_print()\fR, which targets
human-readable strings, takes into account the currently specified
output precision too.
.IP "Constant functions" 5
.IX Item "Constant functions"
Some mathematical constants appear as function without arguments in
\&\s-1PARI\s0.  These functions are available in Math::Pari too.  If you export
them as in
.Sp
.Vb 1
\&  use Math::Pari qw(:DEFAULT Pi I Euler);
.Ve
.Sp
they can be used as barewords in your program:
.Sp
.Vb 1
\&  $x = Pi ** Euler;
.Ve
.IP "Low-level functions" 5
.IX Item "Low-level functions"
For convenience of low-level \s-1PARI\s0 programmers some low-level functions
are made available as well (all except \fItype_name()\fR and \fIchangevalue()\fR
are not exportable):
.Sp
.Vb 7
\&  typ($x)
\&  lg($x)
\&  lgef($x)
\&  lgefint($x)
\&  longword($x, $n)
\&  type_name($x)
\&  changevalue($name,$newvalue)
.Ve
.Sp
Here longword($x,$n) returns \f(CW$n\fR\-th word in the memory
representation of \f(CW$x\fR (including non-code words).  \fItype_name()\fR differs
from the \s-1PARI\s0 function \fItype()\fR: \fItype()\fR returns a \s-1PARI\s0 object, while
\&\fItype_name()\fR returns a Perl string.  (\s-1PARI\s0 objects of string type
behave very non-intuitive w.r.t. string comparison functions; remember
that they are compared using \fIlex()\fR to \fIthe results of evaluation\fR of
other argument of comparison!)
.Sp
The function listPari($number) outputs a list of names of \s-1PARI\s0
functions in the section \f(CW$number\fR.  Use listPari(\-1) to get the list
across all of the sections.
.IP "Uncompatible functions" 5
.IX Item "Uncompatible functions"
.Vb 1
\&  O
.Ve
.Sp
Since implementing \f(CW\*(C`O(7**6)\*(C'\fR would be very tedious, we provide a
two-argument form \f(CW\*(C`O(7,6)\*(C'\fR instead (meaning the same as \f(CW\*(C`O(7^6)\*(C'\fR in
\&\s-1PARI\s0).  Note that with polynomials there is no problem like this one,
both \f(CW\*(C`O($x,6)\*(C'\fR and \f(CW\*(C`O($x**6)\*(C'\fR work.
.Sp
.Vb 1
\&  ifact(n)
.Ve
.Sp
integer factorial functions, available from \f(CW\*(C`gp\*(C'\fR as \f(CW\*(C`n!\*(C'\fR.
.Sh "Looping functions"
.IX Subsection "Looping functions"
\&\s-1PARI\s0 has a big collection of functions which loops over some set.
Such a function takes two \fIspecial\fR arguments: loop variable, and the
code to execute in the loop.
.PP
The code can be either a string (which contains \s-1PARI\s0 code to execute \-
thus should not contain whitespace), or a Perl code reference.  The
loop variable can be a string giving the name of \s-1PARI\s0 variable (as in
.PP
.Vb 1
\&  fordiv(28, 'j', 'a=a+j+j^2');
.Ve
.PP
or
.PP
.Vb 2
\&  $j= 'j';
\&  fordiv(28, $j, 'a=a+j+j^2');
.Ve
.PP
), a \s-1PARI\s0 monomial (as in
.PP
.Vb 2
\&  $j = PARI 'j';
\&  fordiv(28, $j, sub { $a += $j + $j**2 });
.Ve
.PP
), or a \*(L"delayed Math::Pari variable\*(R" (as in
.PP
.Vb 2
\&  $j = PARIvar 'j';
\&  fordiv(28, $j, 'a=a+j+j^2');
.Ve
.PP
).  If none of these applies, as in
.PP
.Vb 2
\&  my $j;        # Have this in a separate statement
\&  fordiv(28, $j, sub { $a += $j + $j**2 });
.Ve
.PP
then during the execution of the \f(CW\*(C`sub\*(C'\fR, Math::Pari would autogenerate
a \s-1PARI\s0 variable, and would put its value in \f(CW$j\fR; this value of \f(CW$j\fR is
temporary only, the old contents of \f(CW$j\fR is restored when \fIfordiv()\fR returns.
.PP
Note that since you have no control over this name, you will not be
able to use this variable from your \s-1PARI\s0 code; e.g.,
.PP
.Vb 2
\&  $j = 7.8;
\&  fordiv(28, $j, 'a=a+j+j^2');
.Ve
.PP
will not make \f(CW\*(C`j\*(C'\fR mirror \f(CW$j\fR (unless you explicitely set up \f(CW\*(C`j\*(C'\fR to be
a no-argument \s-1PARI\s0 function mirroring \f(CW$j\fR, see \*(L"Accessing Perl functions from \s-1PARI\s0 code\*(R").
.PP
\&\fBCaveats\fR.  There are 2 flavors of the \*(L"code\*(R" arguments
(string/\f(CW\*(C`sub\*(C'\fR), and 4 types of the \*(L"variable\*(R" arguments
(string/monomial/\f(CW\*(C`PARIvar\*(C'\fR/other).  However, not all 8 combinations
make sense.  As we already explained, an \*(L"other\*(R" variable cannot work
with a \*(L"string\*(R" code.
.PP
\&\fBUseless musing alert! Do not read the rest of this section!\fR Do not
use \*(L"string\*(R" variables with \f(CW\*(C`sub\*(C'\fR code, and do not ask \fIwhy\fR!
.PP
Additionally, the following code will not do what you expect
.PP
.Vb 3
\&  $x = 0;
\&  $j = PARI 'j';
\&  fordiv(28, 'j', sub { $x += $j } );   # Use $j as a loop variable!
.Ve
.PP
since the \s-1PARI\s0 function \f(CW\*(C`fordiv\*(C'\fR \fIlocalizes\fR the \s-1PARI\s0 variable \f(CW\*(C`j\*(C'\fR
inside the loop, but \f(CW$j\fR will still reference the old value; the old
value is a monomial, not the index of the loop (which is an integer
each time \f(CW\*(C`sub\*(C'\fR is called).  The simplest workaround is not to use
the above syntax (i.e., not mixing literal loop variable with Perl
loop code, just using \f(CW$j\fR as the second argument to \f(CW\*(C`fordiv\*(C'\fR is
enough):
.PP
.Vb 3
\&  $x = 0;
\&  $j = PARI 'j';
\&  fordiv(28, $j, sub { $x += $j } );
.Ve
.PP
Alternately, one can make a \fIdelayed\fR variable \f(CW$j\fR which will always
reference the same thing \f(CW\*(C`j\*(C'\fR references in \s-1PARI\s0 \fInow\fR by using
\&\f(CW\*(C`PARIvar\*(C'\fR constructor
.PP
.Vb 3
\&  $x = 0;
\&  $j = PARIvar 'j';
\&  fordiv(28, 'j', sub { $x += $j } );
.Ve
.PP
(This problem is similar to
.PP
.Vb 2
\&  $ref = \e$_;                   # $$ref is going to be old value even after
\&                                # localizing $_ in Perl's grep/map
.Ve
.PP
not accessing localized values of \f(CW$_\fR in the plain Perl.)
.PP
Another possible quirk is that
.PP
.Vb 1
\&  fordiv(28, my $j, sub { $a += $j + $j**2 });
.Ve
.PP
will not work too \- by a different reason.  \f(CW\*(C`my\*(C'\fR declarations change
the \fImeaning\fR of \f(CW$j\fR only \fIafter\fR the end of the current statement;
thus \f(CW$j\fR inside \f(CW\*(C`sub\*(C'\fR will access a \fIdifferent\fR variable \f(CW$j\fR
(typically a non\-lexical, global variable \f(CW$j\fR) than one you declared on this line.
.Sh "Accessing Perl functions from \s-1PARI\s0 code"
.IX Subsection "Accessing Perl functions from PARI code"
Use the same name inside \s-1PARI\s0 code:
.PP
.Vb 5
\&  sub counter { $i += shift; }
\&  $i = 145;
\&  PARI 'k=5' ;
\&  fordiv(28, 'j', 'k=k+counter(j)');
\&  print PARI('k'), "\en";
.Ve
.PP
prints
.PP
.Vb 1
\&   984
.Ve
.PP
Due to a difference in the semantic of
variable-number-of-parameters-functions between \s-1PARI\s0 and Perl, if the
Perl subroutine takes a variable number of arguments (via \f(CW\*(C`@\*(C'\fR in the
prototype or a missing prototype), up to 6 arguments are supported
when this function is called from \s-1PARI\s0.  If called from \s-1PARI\s0 with
fewer arguments, the rest of arguments will be set to be integers \f(CW\*(C`PARI 0\*(C'\fR.
.PP
Note also that no direct import of Perl variables is available yet
(but you can write a function wrapper for this):
.PP
.Vb 1
\&  sub getv () {$v}
.Ve
.PP
There is an unsupported (and undocumented ;\-) function for explicitely
importing Perl functions into \s-1PARI\s0, possibly with a different name,
and possibly with explicitely specifying number of arguments.
.SH "PARI objects"
.IX Header "PARI objects"
Functions from \s-1PARI\s0 library may take as arguments and/or return values
the objects of C type \f(CW\*(C`GEN\*(C'\fR. In Perl these data are encapsulated into
special kind of Perl variables: \s-1PARI\s0 objects. You can check for a
variable \f(CW$obj\fR to be a \s-1PARI\s0 object using
.PP
.Vb 1
\&  ref $obj and $obj->isa('Math::Pari');
.Ve
.PP
Most the time you do not need this due to automatic conversions and overloading.
.SH "PARI monomials and Perl barewords"
.IX Header "PARI monomials and Perl barewords"
If very lazy, one can code in Perl the same way one does it in \s-1PARI\s0.
Variables in \s-1PARI\s0 are denoted by barewords, as in \f(CW\*(C`x\*(C'\fR, and in the
default configuration (no warnings, no strict) Perl allows the same \-
up to some extent.  Do not do this, since there are many surprising problems.
.PP
Some bareletters denote Perl operators, like \f(CW\*(C`q\*(C'\fR, \f(CW\*(C`x\*(C'\fR, \f(CW\*(C`y\*(C'\fR,
\&\f(CW\*(C`s\*(C'\fR. This can lead to errors in Perl parsing your expression. E.g.,
.PP
.Vb 1
\&  print sin(tan(t))-tan(sin(t))-asin(atan(t))+atan(asin(t));
.Ve
.PP
may parse \s-1OK\s0 after \f(CW\*(C`use Math::Pari qw(sin tan asin atan)\*(C'\fR.  Why?
.PP
After importing, the word \f(CW\*(C`sin\*(C'\fR will denote the \s-1PARI\s0 function \fIsin()\fR,
not Perl operator \fIsin()\fR.  The difference is subtle: the \s-1PARI\s0 function
\&\fIimplicitly\fR forces its arguments to be converted \s-1PARI\s0 objects; it
gets \f(CW't'\fR as the argument, which is a string, thus is converted to
what \f(CW\*(C`t\*(C'\fR denotes in \s-1PARI\s0 \- a monomial.  While the Perl operator \fIsin()\fR
grants overloading (i.e., it will call \s-1PARI\s0 function \fIsin()\fR if the
argument is a \s-1PARI\s0 object), it does not \fIforce\fR its argument; given
\&\f(CW't'\fR as argument, it converts it to what \fIsin()\fR understands, a float
(producing \f(CW0.\fR), so will give \f(CW0.\fR as the answer.
.PP
However
.PP
.Vb 1
\&  print sin(tan(y))-tan(sin(y))-asin(atan(y))+atan(asin(y));
.Ve
.PP
would not compile. You should avoid lower-case barewords used as \s-1PARI\s0
variables, e.g., do
.PP
.Vb 2
\&  $y = PARI 'y';
\&  print sin(tan($y))-tan(sin($y))-asin(atan($y))+atan(asin($y));
.Ve
.PP
to get
.PP
.Vb 1
\&  -1/18*y^9+26/4725*y^11-41/1296*y^13+328721/16372125*y^15+O(y^16)
.Ve
.PP
(\s-1BTW\s0, it is a very good exercise to get the leading term by hand).
.PP
Well, the same advice again: do not use barewords anywhere in your program!
.SH "Overloading and automatic conversion"
.IX Header "Overloading and automatic conversion"
Whenever an arithmetic operation includes at least one \s-1PARI\s0 object,
the other arguments are converted to a \s-1PARI\s0 object and the corresponding
\&\s-1PARI\s0 library functions is used to implement the operation.  Currently
the following arithmetic operations are overloaded:
.PP
.Vb 6
\&  unary -
\&  + - * / % ** abs cos sin exp log sqrt
\&  << >>
\&  <= == => <  >  != <=>
\&  le eq ge lt gt ne cmp
\&  | & ^ ~
.Ve
.PP
Numeric comparison operations are converted to \f(CW\*(C`gcmp\*(C'\fR and friends, string
comparisons compare in lexicographical order using \f(CW\*(C`lex\*(C'\fR.
.PP
Additionally, whenever a \s-1PARI\s0 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 \s-1PARI\s0 pitfalls related to
imprecise zeros (see documentation of \f(CW\*(C`gcmp0\*(C'\fR in \s-1PARI\s0 reference).
.PP
For details on overloading, see overload.
.PP
Note that a check for equality is subject to same pitfalls as in \s-1PARI\s0
due to imprecise values.  \s-1PARI\s0 may also refuse to compare data of
different types for equality if it thinks this may lead to
counterintuitive results.
.PP
Note also that in \s-1PARI\s0 the numeric ordering is not defined for some
types of \s-1PARI\s0 objects.  For string comparison operations we use
PARI-lexicographical ordering.
.SH "PREREQUISITES"
.IX Header "PREREQUISITES"
.Sh "Perl"
.IX Subsection "Perl"
In the versions of perl earlier than 5.003 overloading used a
different interface, so you may need to convert \f(CW\*(C`use overload\*(C'\fR line
to \f(CW%OVERLOAD\fR, or, better, upgrade.
.Sh "\s-1PARI\s0"
.IX Subsection "PARI"
Starting from version 2.0, this module comes without a \s-1PARI\s0 library included.
.PP
For the source of \s-1PARI\s0 library see
<ftp://megrez.math.u\-bordeaux.fr/pub/pari>.
.SH "Perl vs. PARI: different syntax"
.IX Header "Perl vs. PARI: different syntax"
Note that the \s-1PARI\s0 notations should be used in the string arguments to
\&\s-1\fIPARI\s0()\fR function, while the Perl notations should be used otherwise.
.ie n .IP """^""" 4
.el .IP "\f(CW^\fR" 4
.IX Item "^"
Power is denoted by \f(CW\*(C`**\*(C'\fR in Perl.
.ie n .IP """\e""\fR and \f(CW""\e/""" 4
.el .IP "\f(CW\e\fR and \f(CW\e/\fR" 4
.IX Item " and /"
There are no such operators in Perl, use the word forms
\&\f(CW\*(C`gdivent(x,y)\*(C'\fR and \f(CW\*(C`gdivround(x,y)\*(C'\fR instead.
.ie n .IP """~""" 4
.el .IP "\f(CW~\fR" 4
.IX Item "~"
There is no postfix \f(CW\*(C`~\*(C'\fR Perl operator.  Use \fImattranspose()\fR instead.
.ie n .IP """'""" 4
.el .IP "\f(CW'\fR" 4
.IX Item "'"
There is no postfix \f(CW\*(C`'\*(C'\fR Perl operator.  Use \fIderiv()\fR instead.
.ie n .IP """!""" 4
.el .IP "\f(CW!\fR" 4
.IX Item "!"
There is no postfix \f(CW\*(C`!\*(C'\fR Perl operator.  Use \fIfactorial()\fR/\fIifact()\fR instead
(returning a real or an integer correspondingly).
.IP "big integers" 4
.IX Item "big integers"
Perl converts big \fIliteral\fR integers to doubles if they could not be
put into \fBC\fR integers (the particular flavor can be found in the
output of \f(CW\*(C`perl \-V\*(C'\fR in newer version of Perl, look for
\&\f(CW\*(C`ivtype\*(C'\fR/\f(CW\*(C`ivsize\*(C'\fR).  If you want to input such an integer, use
.Sp
.Vb 1
\&  while ($x < PARI('12345678901234567890')) ...
.Ve
.Sp
instead of
.Sp
.Vb 1
\&  while ($x < 12345678901234567890) ...
.Ve
.Sp
Why?  Because conversion to double leads to precision loss (typically
above 1e15, see perlnumber), and you will get something like
12345678901234567168 otherwise.
.Sp
Starting from version 5.005 of Perl, if the tag \f(CW\*(C`:int\*(C'\fR is used on the
\&'use Math::Pari' line, all of the integer literals in Perl will be
automatically converted to became \s-1PARI\s0 objects.  E.g.,
.Sp
.Vb 2
\&  use Math::Pari ':int';
\&  print 2**1000;
.Ve
.Sp
is equivalent to
.Sp
.Vb 1
\&  print PARI(2)**PARI(1000);
.Ve
.Sp
Similarly, large integer literals do not lose precision.
.Sp
This directive is lexically scoped.  There is a similar tag \f(CW\*(C`:hex\*(C'\fR
which affects hexadecimal, octal and binary constants.  One may
also need to use tag \f(CW\*(C`:float\*(C'\fR for auto-conversion of large integer literals
which Perl considers as floating point literals (see "\f(CW\*(C`use\*(C'\fR with arguments"
for details).
.IP "doubles" 4
.IX Item "doubles"
Doubles in Perl are typically of precision approximately 15 digits
(see perlnumber).  When you use them as arguments to \s-1PARI\s0
functions, they are converted to \s-1PARI\s0 real variables, and due to
intermediate 15\-digits\-to\-binary conversion of Perl variables the
result may be different than with the \s-1PARI\s0 many-digits-to-binary
conversion.  E.g., \f(CW\*(C`PARI(0.01)\*(C'\fR and \f(CW\*(C`PARI('0.01')\*(C'\fR differ at 19\-th
place, as
.Sp
.Vb 3
\&  setprecision(38);
\&  print pari_print(0.01),   "\en",
\&        pari_print('0.01'), "\en";
.Ve
.Sp
shows.
.Sp
Note that \fIsetprecision()\fR changes the output format of \fIpari_print()\fR and
friends, as well as the default internal precision.  The generic
PARI===>string conversion does not take into account the output
format, thus
.Sp
.Vb 4
\&  setprecision(38);
\&  print PARI(0.01),       "\en",
\&        PARI('0.01'),     "\en",
\&        pari_print(0.01), "\en";
.Ve
.Sp
will print all the lines with different number of digits after the
point: the first one with 22, since the double 0.01 was converted to a
low-precision \s-1PARI\s0 object, the second one with 41, since internal form
for precision 38 requires that many digits for representation, and the
last one with 39 to have 38 significant digits.
.Sp
Starting from version 5.005 of Perl, if the tag \f(CW\*(C`:float\*(C'\fR is used on
the \f(CW\*(C`use Math::Pari\*(C'\fR line, all the float literals in Perl will be
automatically converted to became \s-1PARI\s0 objects.  E.g.,
.Sp
.Vb 2
\&  use Math::Pari ':float';
\&  print atan(1.);
.Ve
.Sp
is equivalent to
.Sp
.Vb 1
\&  print atan(PARI('1.'));
.Ve
.Sp
Similarly, large float literals do not lose precision.
.Sp
This directive is lexically scoped.
.IP "array base" 4
.IX Item "array base"
Arrays are 1\-based in \s-1PARI\s0, are 0\-based in Perl.  So while array
access is possible in Perl, you need to use different indices:
.Sp
.Vb 3
\&  $nf = PARI 'nf';      # assume that PARI variable nf contains a number field
\&  $a = PARI('nf[7]');
\&  $b = $nf->[6];
.Ve
.Sp
Now \f(CW$a\fR and \f(CW$b\fR contain the same value.
.IP "matrices" 4
.IX Item "matrices"
Note that \f(CW\*(C`PARImat([[...],...,[...])\*(C'\fR constructor creates a matrix
with specified columns, while in \s-1PARI\s0 the command \f(CW\*(C`[1,2,3;4,5,6]\*(C'\fR
creates a matrix with specified rows.  Use a convenience function
\&\fIPARImat_tr()\fR which will transpose a matrix created by \fIPARImat()\fR to use
the same order of elements as in \s-1PARI\s0.
.IP "builtin perl functions" 4
.IX Item "builtin perl functions"
Some \s-1PARI\s0 functions, like \f(CW\*(C`length\*(C'\fR and \f(CW\*(C`eval\*(C'\fR, are Perl
(semi\-)reserved words.  To reach these functions, one should either
import them:
.Sp
.Vb 1
\&  use Math::Pari qw(length eval);
.Ve
.Sp
or call them with prefix (like \f(CW&length\fR) or the full name (like
\&\f(CW\*(C`Math::Pari::length\*(C'\fR).
.SH "High-resolution graphics"
.IX Header "High-resolution graphics"
If you have Term::Gnuplot Perl module installed, you may use high-resolution
graphic primitives of \fB\s-1PARI\s0\fR.  Before the usage you need to establish
a link between Math::Pari and Term::Gnuplot by calling \fIlink_gnuplot()\fR.
You can change the output filehandle by calling \fIset_plot_fh()\fR, and
output terminal by calling \fIplotterm()\fR, as in
.PP
.Vb 1
\&    use Math::Pari qw(:graphic asin);
.Ve
.PP
.Vb 6
\&    open FH, '>out.tex' or die;
\&    link_gnuplot();             # automatically loads Term::Gnuplot
\&    set_plot_fh(\e*FH);
\&    plotterm('emtex');
\&    ploth($x, .5, .999, sub {asin $x});
\&    close FH or die;
.Ve
.SH "libPARI documentation"
.IX Header "libPARI documentation"
libPARI documentation is included, see Math::libPARI.  It is converted
from Chapter 3 of \fB\s-1PARI/GP\s0\fR documentation by the \fIgphelp\fR script of \s-1GP/PARI\s0.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
No environment variables are used.
.SH "BUGS"
.IX Header "BUGS"
.IP "\(bu" 5
A few of \s-1PARI\s0 functions are available indirectly only.
.IP "\(bu" 5
Using overloading constants with the Perl versions below 5.005_57 could lead to
segfaults (at least without \f(CW\*(C`\-D usemymalloc\*(C'\fR), as in:
.Sp
.Vb 2
\&  use Math::Pari ':int';
\&  for ( $i = 0; $i < 10 ; $i++ ) { print "$i\en" }
.Ve
.IP "\(bu" 5
It may be possible that conversion of a Perl value which has both the
integer slot and the floating slot set may create a \s-1PARI\s0 integer, even
if the actual value is not an integer.
.IP "\(bu" 5
problems with refcounting of array elements and \fIMod()\fR.
.Sp
Workaround: make the modulus live longer than the result of \fIMod()\fR.
Until Perl version \f(CW5.6.1\fR, one should exercise a special care so
that the modulus goes out of scope on a different statement than the
result:
.Sp
.Vb 6
\&  { my $modulus = 125;
\&    { my $res = Mod(34, $modulus);
\&      print $res;
\&    }
\&    $fake = 1;          # A (fake) statement here is required
\&  }
.Ve
.Sp
Here \f(CW$res\fR is destructed before the \f(CW\*(C`$fake = 1\*(C'\fR statement, \f(CW$modulus\fR is
destructed before the first statement after the provided block.
However, if you remove the \f(CW\*(C`$fake = 1\*(C'\fR statement, both these
variables are destructed on the first statement after the provided
block (and in a wrong order!).
.Sp
In \f(CW5.6.1\fR declaring \f(CW$modulus\fR before \f(CW$res\fR is all that is needed to
circumvent the same problem:
.Sp
.Vb 4
\&  { my $modulus = 125;
\&    my $res = Mod(34, $modulus);
\&    print $res;
\&  }                     # destruction will happen in a correct order.
.Ve
.Sp
Access to array elements may result in similar problems.  Hard to fix
since in \s-1PARI\s0 the data is not refcounted.
.IP "\(bu" 5
Legacy implementations of dynalinking require the code of \s-1DLL\s0 to be
compiled to be \*(L"position independent\*(R" code (\s-1PIC\s0).  This slows down the
execution, while allowing sharing the loaded copy of the \s-1DLL\s0 between
different processes.  [On contemeporary architectures the same effect
is allowed without the position-independent hack.]
.Sp
Currently, \s-1PARI\s0 assembler files are not position\-independent.  When
compiled for the dynamic linking on legacy systems, this creates a \s-1DLL\s0
which cannot be shared between processes.  Some legacy systems are
reported to recognize this situation, and load the \s-1DLL\s0 as a non-shared
module.  However, there may be systems (are there?) on which this can
cause some \*(L"problems\*(R".
.Sp
Summary: if the dynaloading on your system requires some kind of \f(CW\*(C`\-fPIC\*(C'\fR flag, using \*(L"assembler\*(R" compiles (anything but \f(CW\*(C`machine=none\*(C'\fR) *may* force you to do a static build (i.e., creation of a custom Perl executable with
.Sp
.Vb 3
\& perl Makefile.PL static
\& make perl
\& make test_static
.Ve
.Sp
).
.SH "INITIALIZATION"
.IX Header "INITIALIZATION"
When Math::Pari is loaded, it examines variables \f(CW$Math::Pari::initmem\fR
and \f(CW$Math::Pari::initprimes\fR.  They specify up to which number the
initial list of primes should be precalculated, and how large should
be the arena for \s-1PARI\s0 calculations (in bytes).  (These values have
safe defaults.)
.PP
Since setting these values before loading requires either a \f(CW\*(C`BEGIN\*(C'\fR
block, or postponing the loading (\f(CW\*(C`use\*(C'\fR vs. \f(CW\*(C`require\*(C'\fR), it may be
more convenient to set them via Math::PariInit:
.PP
.Vb 1
\&  use Math::PariInit qw( primes=12000000 stack=1e8 );
.Ve
.PP
\&\f(CW\*(C`use Math::PariInit\*(C'\fR also accepts arbitrary Math::Pari import directives,
see Math::PariInit.
.PP
These values may be changed at runtime too, via \fIallocatemem()\fR and
\&\fIsetprimelimit()\fR, with performance penalties for recalculation/reallocation.
.SH "AUTHOR"
.IX Header "AUTHOR"
Ilya Zakharevich, \fIilyaz@cpan.org\fR