1Pari(3)               User Contributed Perl Documentation              Pari(3)
2
3
4

NAME

6       Math::Pari - Perl interface to PARI.
7

SYNOPSIS

9         use Math::Pari;
10         $a = PARI 2;
11         print $a**10000;
12
13       or
14
15         use Math::Pari qw(Mod);
16         $a = Mod(3,5);
17         print $a**10000;
18

DESCRIPTION

20       This package is a Perl interface to famous library PARI for
21       numerical/scientific/number-theoretic calculations.  It allows use of
22       most PARI functions as Perl functions, and (almost) seamless merging of
23       PARI and Perl data. In what follows we suppose prior knowledge of what
24       PARI is (see <ftp://megrez.math.u-bordeaux.fr/pub/pari>, or
25       Math::libPARI).
26

EXPORTed functions

28       DEFAULT
29           By default the package exports functions PARI(), PARIcol(),
30           PARIvar(), PARImat(), PARImat_tr() and parse_as_gp() which convert
31           their argument(s) to a PARI object. (In fact PARI() is just an
32           alias for "new Math::Pari").  The function PARI() accepts following
33           data as its arguments
34
35           One integer      Is converted to a PARI integer.
36
37           One float        Is converted to a PARI float.
38
39           One string       Is executed as a PARI expression (so should not
40                            contain whitespace).
41
42           PARI object      Is passed unchanged.
43
44           Reference to a Perl array
45                            Each element is converted using the same rules,
46                            PARI vector-row with these elements is returned.
47
48           Several of above The same as with a reference to array.
49
50       Conflicts of rules in PARI()
51           In deciding what rule of the above to apply the preference is given
52           to the uppermost choice of those available now.  If none matches,
53           then the string rule is used.  So PARI(1) returns integer,
54           "PARI(1.)"  returns float, "PARI("1")" evaluates 1 as a PARI
55           expression (well, the result is the same as PARI(1), only slower).
56
57           Note that for Perl these data are synonymous, since Perl freely
58           converts between integers, float and strings.  However, to PARI()
59           only what the argument is now is important.  If $v is 1 in the Perl
60           world, "PARI($v)" may convert it to an integer, float, or to the
61           result of evaluating the PARI program 1 (all depending on how $v
62           was created and accessed in Perl).
63
64           This is a fundamental limitation of creating an interface between
65           two systems, both with polymorphic objects, but with subtly
66           different semantic of the flavors of these objects.  In reality,
67           however, this is rarely a problem.
68
69       PARIcol(), PARImat() and PARImat_tr()
70           PARIcol() behaves in the same way as PARI() unless given several
71           arguments. In the latter case it returns a vector-column instead of
72           a vector-row.
73
74           PARImat() constructs a matrix out of the given arguments. It will
75           work if PARI() will construct a vector of vectors given the same
76           arguments.  The internal vectors become columns of the matrix.
77           PARImat_tr() behaves similarly, but the internal vectors become
78           rows of the matrix.
79
80           Since PARI matrices are similar to vector-rows of vector-columns,
81           PARImat() is quicker, but PARImat_tr() better corresponds to the
82           PARI input and output forms of matrices:
83
84             print PARImat    [[1,2], [3,4]];      # prints [1,3;2,4]
85             print PARImat_tr [[1,2], [3,4]];      # prints [1,2;3,4]
86
87       parse_as_gp()
88           Did you notice that when taking a string, PARI() requires that
89           there is no whitespace there (outside of string constants)?  This
90           is exactly as the "PARI" library parses strings.  However, to
91           simplify human interaction, the "gp" calculator allows whitespace,
92           comments, breaking into multiple lines, many independent
93           expressions (such as function definitions).
94
95           We do not include the corresponding C code from the calculator, but
96           provide a Perl clone.  It supports whitespace, "\\"- and "/*
97           */"-comments, and, for multi-line arguments, it supports line
98           continuation via trailing "\", trailing binary ops, comma, opening
99           parenthesis/bracket; moreover, group of lines in "{}" are joined
100           into one line.  (Additionally, "\q" and "\p" are recognized, as
101           well as trailing allocatemem().  "\e" is tolerated.)
102
103           Keep in mind that this is just a convenience function, and no
104           attempt was performed to make it particularly quick.  Moreover, the
105           PARI user functions (or maybe it is better to call them user
106           macros?) are currently not automatically importable into Perl, so
107           to access functions defined in parse_as_gp()' argument may be
108           awkward.  (The temporary fix is to use a temporary convenience
109           function __wrap_PARI_macro():
110
111               parse_as_gp <<EOP;
112             add2(x) = x + 2
113             EOP
114               *add2 = Math::Pari::__wrap_PARI_macro 'add2';
115               print add2(17);
116
117           but keep in mind that the generated this way wrapper is also not
118           designed to be quick.)
119
120           With "TRUE" optional second argument, it would return an
121           unevaluated array of strings instead of the result of evaluation.
122           Special strings "\q" etc. are replaced by references to appropriate
123           (undocumented) Perl arrays.
124
125           With "TRUE" optional third argument, would "echo" the commands
126           (preceded by "? ") before execution.  With "TRUE" optional fourth
127           argument (command counter), would "echo" the result too (preceded
128           by "%C = ", with "C" being the command counter, which is
129           incremented).
130
131       "use" with arguments
132           If arguments are specified in the "use Math::Pari" directive, the
133           PARI functions appearing as arguments are exported in the caller
134           context. In this case the function PARI() and friends is not
135           exported, so if you need them, you should include them into export
136           list explicitly, or include ":DEFAULT" tag:
137
138             use Math::Pari qw(factorint PARI);
139             use Math::Pari qw(:DEFAULT factorint);
140
141           or simply do it in two steps
142
143             use Math::Pari;
144             use Math::Pari 'factorint';
145
146           The other tags recognized are ":PARI", ":all", "prec=NUMBER",
147           number tags (e.g., ":4"), overloaded constants tags (":int",
148           ":float", ":hex") and section names tags.  The number tags export
149           functions from the PARI library from the given class (except for
150           ":PARI", which exports all of the classes).  Tag ":all" exports all
151           of the exportable symbols and ":PARI".
152
153           Giving "?" command to "gp" (PARI calculator) lists the following
154           classes (this list depends significantly on the version; so better
155           use symbolic names):
156
157             1: Standard monadic or dyadic OPERATORS
158             2: CONVERSIONS and similar elementary functions
159             3: TRANSCENDENTAL functions
160             4: NUMBER THEORETICAL functions
161             5: Functions related to ELLIPTIC CURVES
162             6: Functions related to general NUMBER FIELDS
163             7: POLYNOMIALS and power series
164             8: Vectors, matrices, LINEAR ALGEBRA and sets
165             9: SUMS, products, integrals and similar functions
166             10: GRAPHIC functions
167             11: PROGRAMMING under GP
168
169           One can use section names instead of number tags.  Recognized names
170           are
171
172             :standard :conversions :transcendental :number :elliptic
173             :fields :polynomials :vectors :sums :graphic :programming
174
175           One can get the list of all of the functions accessible by
176           "Math::Pari", or the accessible functions from the given section
177           using listPari() function.
178
179           Starting from version 5.005 of Perl, three constant-overload tags
180           are supported: ":int", ":float", ":hex".  If used, all the
181           integer/float/hex-or-octal-or-binary literals in Perl will be
182           automatically converted to became PARI objects.  For example,
183
184             use Math::Pari ':int';
185             print 2**1000;
186
187           is equivalent to
188
189             print PARI(2)**PARI(1000);
190
191           (The support for this Perl feature is buggy before the Perl version
192           5.005_57 - unless Perl uses mymalloc options; you can check for
193           this with "perl -V:usemymalloc".)  Note also that (at least with
194           some versions of Perl) one should enable ':float' for conversion of
195           long integer literals (Perl may consider them as floats, since they
196           won't fit into Perl integers); note that it is PARI which
197           determines which PARI subtype is assigned to each such literal:
198
199             use Math::Pari ':float', 'type_name';
200             print type_name 22222222222222222222222;
201
202           prints "t_INT".
203

Available functions

205   Directly accessible from Perl
206       This package supports all the functions from the PARI library with a
207       signature which can be recognized by Math::Pari.  This means that when
208       you update the PARI library, the newly added functions will we
209       available without any change to this package; only a recompile is
210       needed.  In fact no recompile will be needed if you link libPARI
211       dynamically (you need to modify the Makefile manually to do this).
212
213       You can "reach" unsupported functions via going directly to PARI parser
214       using the string flavor of PARI() function, as in
215
216         3 + PARI('O(x^17)');
217
218       For some "unreachable" functions there is a special wrapper functions,
219       such as "O(variable,power)").
220
221       The following functions are specific to GP calculator, thus are not
222       available to Math::Pari in any way:
223
224         default error extern input print print1 printp printp1
225         printtex quit read system whatnow write write1 writetex
226
227       whatnow() function is useless, since Math::Pari does not support the
228       "compatibility" mode (with older PARI library).  The functionality of
229       print(), write() and variants is available via automatic string
230       translation, and pari_print() function and its variants (see "Printout
231       functions").
232
233       default() is the only important function with functionality not
234       supported by the current interface.  Note however, that four most
235       important default() actions are supported by allocatemem(),
236       setprimelimit(), setprecision() and setseriesprecision() functions.
237       (When called without arguments, these functions return the current
238       values.)
239
240       allocatemem($bytes) should not be called from inside Math::Pari
241       functions (such as forprimes()).
242
243   Arguments
244       Arguments to PARI functions are automatically converted to "long" or a
245       PARI object depending on the signature of the actual library function.
246       The arguments are forced into the given type, so even if "gp" rejects
247       your code similar to
248
249         func(2.5);                    # func() takes a long in C
250
251       arguing that a particular argument should be of "type T_INT" (i.e., a
252       Pari integer), the corresponding code will work in "Math::Pari", since
253       2.5 is silently converted to "long", per the function signature.
254
255   Return values
256       PARI functions return a PARI object or a Perl's integer depending on
257       what the actual library function returns.
258
259   Additional functions
260       Some PARI functions are available in "gp" (i.e., in "PARI" calculator)
261       via infix notation only. In "Math::Pari" these functions are available
262       in functional notations too.  Some other convenience functions are also
263       made available.
264
265       Infix, prefix and postfix operations
266            are available under names
267
268              gneg, gadd, gsub, gmul, gdiv, gdivent, gmod, gpui,
269              gle, gge, glt, ggt, geq, gne, gegal, gor, gand,
270              gcmp, gcmp0, gcmp1, gcmp_1.
271
272            "gdivent" means euclidean quotient, "gpui" is power, "gegal"
273            checks whether two objects are equal, "gcmp" is applicable to two
274            real numbers only, "gcmp0", "gcmp1", "gcmp_1" compare with 0, 1
275            and -1 correspondingly (see PARI user manual for details, or
276            Math::libPARI).  Note that all these functions are more readily
277            available via operator overloading, so instead of
278
279              gadd(gneg($x), $y)
280
281            one can write
282
283              -$x+$y
284
285            (as far as overloading may be triggered, see overload, so we
286            assume that at least one of $x or $y is a PARI object).
287
288       Conversion functions
289              pari2iv, pari2nv, pari2num, pari2pv, pari2bool
290
291            convert a PARI object to an integer, float, integer/float
292            (whatever is better), string, and a boolean value correspondingly.
293            Most the time you do not need these functions due to automatic
294            conversions.
295
296       Printout functions
297              pari_print, pari_pprint, pari_texprint
298
299            perform the same conversions to strings as their PARI
300            counterparts, but do not print the result.  The difference of
301            pari_print() with pari2pv() is the number of significant digits
302            they output, and whitespace in the output.  pari2pv(), which is
303            intended for "computer-readable strings", outputs as many digits
304            as is supported by the current precision of the number; while
305            pari_print(), which targets human-readable strings, takes into
306            account the currently specified output precision too.
307
308       Constant functions
309            Some mathematical constants appear as function without arguments
310            in PARI.  These functions are available in Math::Pari too.  If you
311            export them as in
312
313              use Math::Pari qw(:DEFAULT Pi I Euler);
314
315            they can be used as barewords in your program:
316
317              $x = Pi ** Euler;
318
319       Low-level functions
320            For convenience of low-level PARI programmers some low-level
321            functions are made available as well (all except type_name() and
322            changevalue() are not exportable):
323
324              typ($x)
325              lg($x)
326              lgef($x)
327              lgefint($x)
328              longword($x, $n)
329              type_name($x)
330              changevalue($name,$newvalue)
331
332            Here longword($x,$n) returns $n-th word in the memory
333            representation of $x (including non-code words).  type_name()
334            differs from the PARI function type(): type() returns a PARI
335            object, while type_name() returns a Perl string.  (PARI objects of
336            string type behave very non-intuitive w.r.t. string comparison
337            functions; remember that they are compared using lex() to the
338            results of evaluation of other argument of comparison!)
339
340            The function listPari($number) outputs a list of names of PARI
341            functions in the section $number.  Use listPari(-1) to get the
342            list across all of the sections.
343
344       Uncompatible functions
345              O
346
347            Since implementing "O(7**6)" would be very tedious, we provide a
348            two-argument form "O(7,6)" instead (meaning the same as "O(7^6)"
349            in PARI).  Note that with polynomials there is no problem like
350            this one, both "O($x,6)" and "O($x**6)" work.
351
352              ifact(n)
353
354            integer factorial functions, available from "gp" as "n!".
355
356   Looping functions
357       PARI has a big collection of functions which loops over some set.  Such
358       a function takes two special arguments: loop variable, and the code to
359       execute in the loop.
360
361       The code can be either a string (which contains PARI code to execute -
362       thus should not contain whitespace), or a Perl code reference.  The
363       loop variable can be a string giving the name of PARI variable (as in
364
365         fordiv(28, 'j', 'a=a+j+j^2');
366
367       or
368
369         $j= 'j';
370         fordiv(28, $j, 'a=a+j+j^2');
371
372       ), a PARI monomial (as in
373
374         $j = PARI 'j';
375         fordiv(28, $j, sub { $a += $j + $j**2 });
376
377       ), or a "delayed Math::Pari variable" (as in
378
379         $j = PARIvar 'j';
380         fordiv(28, $j, 'a=a+j+j^2');
381
382       ).  If none of these applies, as in
383
384         my $j;        # Have this in a separate statement
385         fordiv(28, $j, sub { $a += $j + $j**2 });
386
387       then during the execution of the "sub", Math::Pari would autogenerate a
388       PARI variable, and would put its value in $j; this value of $j is
389       temporary only, the old contents of $j is restored when fordiv()
390       returns.
391
392       Note that since you have no control over this name, you will not be
393       able to use this variable from your PARI code; e.g.,
394
395         $j = 7.8;
396         fordiv(28, $j, 'a=a+j+j^2');
397
398       will not make "j" mirror $j (unless you explicitly set up "j" to be a
399       no-argument PARI function mirroring $j, see "Accessing Perl functions
400       from PARI code").
401
402       Caveats.  There are 2 flavors of the "code" arguments (string/"sub"),
403       and 4 types of the "variable" arguments
404       (string/monomial/"PARIvar"/other).  However, not all 8 combinations
405       make sense.  As we already explained, an "other" variable cannot work
406       with a "string" code.
407
408       Useless musing alert! Do not read the rest of this section! Do not use
409       "string" variables with "sub" code, and do not ask why!
410
411       Additionally, the following code will not do what you expect
412
413         $x = 0;
414         $j = PARI 'j';
415         fordiv(28, 'j', sub { $x += $j } );   # Use $j as a loop variable!
416
417       since the PARI function "fordiv" localizes the PARI variable "j" inside
418       the loop, but $j will still reference the old value; the old value is a
419       monomial, not the index of the loop (which is an integer each time
420       "sub" is called).  The simplest workaround is not to use the above
421       syntax (i.e., not mixing literal loop variable with Perl loop code,
422       just using $j as the second argument to "fordiv" is enough):
423
424         $x = 0;
425         $j = PARI 'j';
426         fordiv(28, $j, sub { $x += $j } );
427
428       Alternately, one can make a delayed variable $j which will always
429       reference the same thing "j" references in PARI now by using "PARIvar"
430       constructor
431
432         $x = 0;
433         $j = PARIvar 'j';
434         fordiv(28, 'j', sub { $x += $j } );
435
436       (This problem is similar to
437
438         $ref = \$_;                   # $$ref is going to be old value even after
439                                       # localizing $_ in Perl's grep/map
440
441       not accessing localized values of $_ in the plain Perl.)
442
443       Another possible quirk is that
444
445         fordiv(28, my $j, sub { $a += $j + $j**2 });
446
447       will not work too - by a different reason.  "my" declarations change
448       the meaning of $j only after the end of the current statement; thus $j
449       inside "sub" will access a different variable $j (typically a non-
450       lexical, global variable $j) than one you declared on this line.
451
452   Accessing Perl functions from PARI code
453       Use the same name inside PARI code:
454
455         sub counter { $i += shift; }
456         $i = 145;
457         PARI 'k=5' ;
458         fordiv(28, 'j', 'k=k+counter(j)');
459         print PARI('k'), "\n";
460
461       prints
462
463          984
464
465       Due to a difference in the semantic of variable-number-of-parameters-
466       functions between PARI and Perl, if the Perl subroutine takes a
467       variable number of arguments (via "@" in the prototype or a missing
468       prototype), up to 6 arguments are supported when this function is
469       called from PARI.  If called from PARI with fewer arguments, the rest
470       of arguments will be set to be integers "PARI 0".
471
472       Note also that no direct import of Perl variables is available yet (but
473       you can write a function wrapper for this):
474
475         sub getv () {$v}
476
477       There is an unsupported (and undocumented ;-) function for explicitly
478       importing Perl functions into PARI, possibly with a different name, and
479       possibly with explicitly specifying number of arguments.
480

PARI objects

482       Functions from PARI library may take as arguments and/or return values
483       the objects of C type "GEN". In Perl these data are encapsulated into
484       special kind of Perl variables: PARI objects. You can check for a
485       variable $obj to be a PARI object using
486
487         ref $obj and $obj->isa('Math::Pari');
488
489       Most the time you do not need this due to automatic conversions and
490       overloading.
491

PARI monomials and Perl barewords

493       If very lazy, one can code in Perl the same way one does it in PARI.
494       Variables in PARI are denoted by barewords, as in "x", and in the
495       default configuration (no warnings, no strict) Perl allows the same -
496       up to some extent.  Do not do this, since there are many surprising
497       problems.
498
499       Some bareletters denote Perl operators, like "q", "x", "y", "s". This
500       can lead to errors in Perl parsing your expression. E.g.,
501
502         print sin(tan(t))-tan(sin(t))-asin(atan(t))+atan(asin(t));
503
504       may parse OK after "use Math::Pari qw(sin tan asin atan)".  Why?
505
506       After importing, the word "sin" will denote the PARI function sin(),
507       not Perl operator sin().  The difference is subtle: the PARI function
508       implicitly forces its arguments to be converted PARI objects; it gets
509       't' as the argument, which is a string, thus is converted to what "t"
510       denotes in PARI - a monomial.  While the Perl operator sin() grants
511       overloading (i.e., it will call PARI function sin() if the argument is
512       a PARI object), it does not force its argument; given 't' as argument,
513       it converts it to what sin() understands, a float (producing 0.), so
514       will give 0. as the answer.
515
516       However
517
518         print sin(tan(y))-tan(sin(y))-asin(atan(y))+atan(asin(y));
519
520       would not compile. You should avoid lower-case barewords used as PARI
521       variables, e.g., do
522
523         $y = PARI 'y';
524         print sin(tan($y))-tan(sin($y))-asin(atan($y))+atan(asin($y));
525
526       to get
527
528         -1/18*y^9+26/4725*y^11-41/1296*y^13+328721/16372125*y^15+O(y^16)
529
530       (BTW, it is a very good exercise to get the leading term by hand).
531
532       Well, the same advice again: do not use barewords anywhere in your
533       program!
534

Overloading and automatic conversion

536       Whenever an arithmetic operation includes at least one PARI object, the
537       other arguments are converted to a PARI object and the corresponding
538       PARI library functions is used to implement the operation.  Currently
539       the following arithmetic operations are overloaded:
540
541         unary -
542         + - * / % ** abs cos sin exp log sqrt
543         << >>
544         <= == => <  >  != <=>
545         le eq ge lt gt ne cmp
546         | & ^ ~
547
548       Numeric comparison operations are converted to "gcmp" and friends,
549       string comparisons compare in lexicographical order using "lex".
550
551       Additionally, whenever a PARI object appears in a situation that
552       requires integer, numeric, boolean or string data, it is converted to
553       the corresponding type. Boolean conversion is subject to usual PARI
554       pitfalls related to imprecise zeros (see documentation of "gcmp0" in
555       PARI reference).
556
557       For details on overloading, see overload.
558
559       Note that a check for equality is subject to same pitfalls as in PARI
560       due to imprecise values.  PARI may also refuse to compare data of
561       different types for equality if it thinks this may lead to
562       counterintuitive results.
563
564       Note also that in PARI the numeric ordering is not defined for some
565       types of PARI objects.  For string comparison operations we use PARI-
566       lexicographical ordering.
567

PREREQUISITES

569   Perl
570       In the versions of perl earlier than 5.003 overloading used a different
571       interface, so you may need to convert "use overload" line to %OVERLOAD,
572       or, better, upgrade.
573
574   PARI
575       Starting from version 2.0, this module comes without a PARI library
576       included.
577
578       For the source of PARI library see
579       <ftp://megrez.math.u-bordeaux.fr/pub/pari>.
580

Perl vs. PARI: different syntax

582       Note that the PARI notations should be used in the string arguments to
583       PARI() function, while the Perl notations should be used otherwise.
584
585       "^" Power is denoted by "**" in Perl.
586
587       "\" and "\/"
588           There are no such operators in Perl, use the word forms
589           "gdivent(x,y)" and "gdivround(x,y)" instead.
590
591       "~" There is no postfix "~" Perl operator.  Use mattranspose() instead.
592
593       "'" There is no postfix "'" Perl operator.  Use deriv() instead.
594
595       "!" There is no postfix "!" Perl operator.  Use factorial()/ifact()
596           instead (returning a real or an integer correspondingly).
597
598       big integers
599           Perl converts big literal integers to doubles if they could not be
600           put into C integers (the particular flavor can be found in the
601           output of "perl -V" in newer version of Perl, look for
602           "ivtype"/"ivsize").  If you want to input such an integer, use
603
604             while ($x < PARI('12345678901234567890')) ...
605
606           instead of
607
608             while ($x < 12345678901234567890) ...
609
610           Why?  Because conversion to double leads to precision loss
611           (typically above 1e15, see perlnumber), and you will get something
612           like 12345678901234567168 otherwise.
613
614           Starting from version 5.005 of Perl, if the tag ":int" is used on
615           the 'use Math::Pari' line, all of the integer literals in Perl will
616           be automatically converted to became PARI objects.  E.g.,
617
618             use Math::Pari ':int';
619             print 2**1000;
620
621           is equivalent to
622
623             print PARI(2)**PARI(1000);
624
625           Similarly, large integer literals do not lose precision.
626
627           This directive is lexically scoped.  There is a similar tag ":hex"
628           which affects hexadecimal, octal and binary constants.  One may
629           also need to use tag ":float" for auto-conversion of large integer
630           literals which Perl considers as floating point literals (see
631           ""use" with arguments" for details).
632
633       doubles
634           Doubles in Perl are typically of precision approximately 15 digits
635           (see perlnumber).  When you use them as arguments to PARI
636           functions, they are converted to PARI real variables, and due to
637           intermediate 15-digits-to-binary conversion of Perl variables the
638           result may be different than with the PARI many-digits-to-binary
639           conversion.  E.g., "PARI(0.01)" and "PARI('0.01')" differ at 19-th
640           place, as
641
642             setprecision(38);
643             print pari_print(0.01),   "\n",
644                   pari_print('0.01'), "\n";
645
646           shows.
647
648           Note that setprecision() changes the output format of pari_print()
649           and friends, as well as the default internal precision.  The
650           generic PARI===>string conversion does not take into account the
651           output format, thus
652
653             setprecision(38);
654             print PARI(0.01),       "\n",
655                   PARI('0.01'),     "\n",
656                   pari_print(0.01), "\n";
657
658           will print all the lines with different number of digits after the
659           point: the first one with 22, since the double 0.01 was converted
660           to a low-precision PARI object, the second one with 41, since
661           internal form for precision 38 requires that many digits for
662           representation, and the last one with 39 to have 38 significant
663           digits.
664
665           Starting from version 5.005 of Perl, if the tag ":float" is used on
666           the "use Math::Pari" line, all the float literals in Perl will be
667           automatically converted to became PARI objects.  E.g.,
668
669             use Math::Pari ':float';
670             print atan(1.);
671
672           is equivalent to
673
674             print atan(PARI('1.'));
675
676           Similarly, large float literals do not lose precision.
677
678           This directive is lexically scoped.
679
680       array base
681           Arrays are 1-based in PARI, are 0-based in Perl.  So while array
682           access is possible in Perl, you need to use different indices:
683
684             $nf = PARI 'nf';      # assume that PARI variable nf contains a number field
685             $a = PARI('nf[7]');
686             $b = $nf->[6];
687
688           Now $a and $b contain the same value.
689
690       matrices
691           Note that "PARImat([[...],...,[...])" constructor creates a matrix
692           with specified columns, while in PARI the command "[1,2,3;4,5,6]"
693           creates a matrix with specified rows.  Use a convenience function
694           PARImat_tr() which will transpose a matrix created by PARImat() to
695           use the same order of elements as in PARI.
696
697       builtin perl functions
698           Some PARI functions, like "length" and "eval", are Perl
699           (semi-)reserved words.  To reach these functions, one should either
700           import them:
701
702             use Math::Pari qw(length eval);
703
704           or call them with prefix (like &length) or the full name (like
705           "Math::Pari::length").
706

High-resolution graphics

708       If you have Term::Gnuplot Perl module installed, you may use high-
709       resolution graphic primitives of PARI.  Before the usage you need to
710       establish a link between Math::Pari and Term::Gnuplot by calling
711       link_gnuplot().  You can change the output filehandle by calling
712       set_plot_fh(), and output terminal by calling plotterm(), as in
713
714           use Math::Pari qw(:graphic asin);
715
716           link_gnuplot();             # automatically loads Term::Gnuplot
717           plotterm('emtex');
718           plot_outfile_set('out.tex');        # better do after plotterm()
719           ploth($x, .5, .999, sub {asin $x});
720           close FH or die;
721

libPARI documentation

723       libPARI documentation is included, see Math::libPARI.  It is converted
724       from Chapter 3 of PARI/GP documentation by the gphelp script of
725       GP/PARI.
726

ENVIRONMENT

728       No environment variables are used.
729

BUGS

731       ·    A few of PARI functions are available indirectly only.
732
733       ·    Using overloading constants with the Perl versions below 5.005_57
734            could lead to segfaults (at least without "-D usemymalloc"), as
735            in:
736
737              use Math::Pari ':int';
738              for ( $i = 0; $i < 10 ; $i++ ) { print "$i\n" }
739
740       ·    It may be possible that conversion of a Perl value which has both
741            the integer slot and the floating slot set may create a PARI
742            integer, even if the actual value is not an integer.
743
744       ·    problems with refcounting of array elements and Mod().
745
746            Workaround: make the modulus live longer than the result of Mod().
747            Until Perl version 5.6.1, one should exercise a special care so
748            that the modulus goes out of scope on a different statement than
749            the result:
750
751              { my $modulus = 125;
752                { my $res = Mod(34, $modulus);
753                  print $res;
754                }
755                $fake = 1;          # A (fake) statement here is required
756              }
757
758            Here $res is destructed before the "$fake = 1" statement, $modulus
759            is destructed before the first statement after the provided block.
760            However, if you remove the "$fake = 1" statement, both these
761            variables are destructed on the first statement after the provided
762            block (and in a wrong order!).
763
764            In 5.6.1 declaring $modulus before $res is all that is needed to
765            circumvent the same problem:
766
767              { my $modulus = 125;
768                my $res = Mod(34, $modulus);
769                print $res;
770              }                     # destruction will happen in a correct order.
771
772            Access to array elements may result in similar problems.  Hard to
773            fix since in PARI the data is not refcounted.
774
775       ·    Legacy implementations of dynalinking require the code of DLL to
776            be compiled to be "position independent" code (PIC).  This slows
777            down the execution, while allowing sharing the loaded copy of the
778            DLL between different processes.  [On contemporary architectures
779            the same effect is allowed without the position-independent hack.]
780
781            Currently, PARI assembler files are not position-independent.
782            When compiled for the dynamic linking on legacy systems, this
783            creates a DLL which cannot be shared between processes.  Some
784            legacy systems are reported to recognize this situation, and load
785            the DLL as a non-shared module.  However, there may be systems
786            (are there?) on which this can cause some "problems".
787
788            Summary: if the dynaloading on your system requires some kind of
789            "-fPIC" flag, using "assembler" compiles (anything but
790            "machine=none") *may* force you to do a static build (i.e.,
791            creation of a custom Perl executable with
792
793             perl Makefile.PL static
794             make perl
795             make test_static
796
797            ).
798
799       ·    isprime() is a misnomer before PARI version 2.3!
800
801            In older versions of PARI, the one-argument variant of the
802            function isprime() is actually checking for probable primes.
803            Moreover, it has certain problems.
804
805            POSSIBLE WORKAROUND (not needed for newer PARI): before version
806            2.3 of PARI, to get probability of misdetecting a prime below
807            1e-12, call isprime() twice; below 1e-18, call it 3 times; etc.
808            (The algorithm is probabilistic, and the implementation is such
809            that the result depends on which calls to isprime() were performed
810            ealier.)
811
812            The problems: first, while the default algorithm (before version
813            2.3) gives practically acceptable results in non-adversarial
814            situations, the worst-case behaviour is significantly worse than
815            the average behaviour.  The algorithm is looking for so-called
816            "witnesses" (with up to 10 tries) among random integers; usually,
817            witnesses are abundant.  However, there are non-prime numbers for
818            which the fraction of witnesses is close to the theoretical
819            minimum, 0.75; with 10 random tries, the probability of missing a
820            witness for such numbers is close to 1e-6.  (The known worst-case
821            numbers M have phi(M)/4 non-witnesses, with M=P(2P-1), prime P,
822            2P-1 and 4|P+1; the proportion of such numbers near K is expected
823            to be const/sqrt(K)log(K)^2.  Note that numbers which have more
824            than about 5% non-witnesses may also be candidates for false
825            positives.  Conjecturally, they are of the form (aD+1)(bD+1) with
826            a<b, ab <= const, prime aD+1, and bD+1, and D not divisible by
827            high power of 2 (above a=1, b=2 and D is odd); the proportion of
828            such numbers may have a similar asymptotic const/sqrt(K)log(K)^2.)
829
830            Second, the random number generator is "reset to known state" when
831            PARI library is initialized.  That means that the behaviour is
832            actually predictable if one knows which calls to isprime() are
833            performed; an adversary can find non-primes M which will trigger a
834            false positive exactly on the Nth call to isprime(M) (for
835            particular values of N).  With enough computing resources, one can
836            find non-primes M for which N is relatively small (with M about
837            1e9, one can achieve N as low as 1000).  Compare with similar (but
838            less abundant) examples for simpler algorithm, Carmichael numbers
839            <http://en.wikipedia.org/wiki/Carmichael_numbers>; see also
840            numbers with big proportion of non-witnesses
841            <http://oeis.org/A090659> and numbers with many non-witnesses
842            <http://oeis.org/A141768>, and the conjecture about proportion
843            <http://web.archive.org/web/*/http://www.ma.iup.edu/MAA/proceedings/vol1/higgins.pdf>.
844
845            See the discussion of isprime()
846            <https://rt.cpan.org/Public/Bug/Display.html?id=93652>.
847

INITIALIZATION

849       When Math::Pari is loaded, it examines variables $Math::Pari::initmem
850       and $Math::Pari::initprimes.  They specify up to which number the
851       initial list of primes should be precalculated, and how large should be
852       the arena for PARI calculations (in bytes).  (These values have safe
853       defaults.)
854
855       Since setting these values before loading requires either a "BEGIN"
856       block, or postponing the loading ("use" vs. "require"), it may be more
857       convenient to set them via Math::PariInit:
858
859         use Math::PariInit qw( primes=12000000 stack=1e8 );
860
861       "use Math::PariInit" also accepts arbitrary Math::Pari import
862       directives, see Math::PariInit.
863
864       These values may be changed at runtime too, via allocatemem() and
865       setprimelimit(), with performance penalties for
866       recalculation/reallocation.
867

AUTHOR

869       Ilya Zakharevich, ilyaz@cpan.org
870
871
872
873perl v5.32.0                      2020-07-28                           Pari(3)
Impressum