### Navigation

- index
- modules |
- next |
- previous |
- C/C++ Library Interfaces »

# PARI C-library interface

PARI C-library interface

AUTHORS:

- William Stein (2006-03-01): updated to work with PARI 2.2.12-beta
- William Stein (2006-03-06): added newtonpoly
- Justin Walker: contributed some of the function definitions
- Gonzalo Tornaria: improvements to conversions; much better error handling.
- Robert Bradshaw, Jeroen Demeyer, William Stein (2010-08-15): Upgrade to PARI 2.4.3 (#9343)
- Jeroen Demeyer (2011-11-12): rewrite various conversion routines (#11611, #11854, #11952)
- Peter Bruin (2013-11-17): split off this file from gen.pyx (#15185)
- Jeroen Demeyer (2014-02-09): upgrade to PARI 2.7 (#15767)

EXAMPLES:

    sage: pari('5! + 10/x')
    (120*x + 10)/x
    sage: pari('intnum(x=0,13,sin(x)+sin(x^2) + x)')
    85.1885681951527
    sage: f = pari('x^3-1')
    sage: v = f.factor(); v
    [x - 1, 1; x^2 + x + 1, 1]
    sage: v[0]   # indexing is 0-based unlike in GP.
    [x - 1, x^2 + x + 1]~
    sage: v[1]
    [1, 1]~

Arithmetic obeys the usual coercion rules:

    sage: type(pari(1) + 1)
    <type 'sage.libs.pari.gen.gen'>
    sage: type(1 + pari(1))
    <type 'sage.libs.pari.gen.gen'>

GUIDE TO REAL PRECISION AND THE PARI LIBRARY

The default real precision in communicating with the PARI library is the same as the default Sage real precision, which is 53 bits. Inexact Pari objects are therefore printed by default to 15 decimal digits (even if they are actually more precise).

Default precision example (53 bits, 15 significant decimals):

    sage: a = pari(1.23); a
    1.23000000000000
    sage: a.sin()
    0.942488801931698

Example with custom precision of 200 bits (60 significant decimals):

    sage: R = RealField(200)
    sage: a = pari(R(1.23)); a   # only 15 significant digits printed
    1.23000000000000
    sage: R(a)         # but the number is known to precision of 200 bits
    1.2300000000000000000000000000000000000000000000000000000000
    sage: a.sin()      # only 15 significant digits printed
    0.942488801931698
    sage: R(a.sin())   # but the number is known to precision of 200 bits
    0.94248880193169751002382356538924454146128740562765030213504

It is possible to change the number of printed decimals:

    sage: R = RealField(200)    # 200 bits of precision in computations
    sage: old_prec = pari.set_real_precision(60)  # 60 decimals printed
    sage: a = pari(R(1.23)); a
    1.23000000000000000000000000000000000000000000000000000000000
    sage: a.sin()
    0.942488801931697510023823565389244541461287405627650302135038
    sage: pari.set_real_precision(old_prec)  # restore the default printing behavior
    60

Unless otherwise indicated in the docstring, most Pari functions that return inexact objects use the precision of their arguments to decide the precision of the computation. However, if some of these arguments happen to be exact numbers (integers, rationals, etc.), an optional parameter indicates the precision (in bits) to which these arguments should be converted before the computation. If this precision parameter is missing, the default precision of 53 bits is used. The following first converts 2 into a real with 53-bit precision:

    sage: R = RealField()
    sage: R(pari(2).sin())
    0.909297426825682

We can ask for a better precision using the optional parameter:

    sage: R = RealField(150)
    sage: R(pari(2).sin(precision=150))
    0.90929742682568169539601986591174484270225497

Warning regarding conversions Sage - Pari - Sage: Some care must be taken when juggling inexact types back and forth between Sage and Pari. In theory, calling p=pari(s) creates a Pari object p with the same precision as s; in practice, the Pari library’s precision is word-based, so it will go up to the next word. For example, a default 53-bit Sage real s will be bumped up to 64 bits by adding bogus 11 bits. The function p.python() returns a Sage object with exactly the same precision as the Pari object p. So pari(s).python() is definitely not equal to s, since it has 64 bits of precision, including the bogus 11 bits. The correct way of avoiding this is to coerce pari(s).python() back into a domain with the right precision. This has to be done by the user (or by Sage functions that use Pari library functions in gen.pyx). For instance, if we want to use the Pari library to compute sqrt(pi) with a precision of 100 bits:

    sage: R = RealField(100)
    sage: s = R(pi); s
    3.1415926535897932384626433833
    sage: p = pari(s).sqrt()
    sage: x = p.python(); x  # wow, more digits than I expected!
    1.7724538509055160272981674833410973484
    sage: x.prec()           # has precision 'improved' from 100 to 128?
    128
    sage: x == RealField(128)(pi).sqrt()  # sadly, no!
    False
    sage: R(x)               # x should be brought back to precision 100
    1.7724538509055160272981674833
    sage: R(x) == s.sqrt()
    True

Elliptic curves and precision: If you are working with elliptic curves, you should set the precision for each method:

    sage: e = pari([0,0,0,-82,0]).ellinit()
    sage: eta1 = e.elleta(precision=100)[0]
    sage: eta1.sage()
    3.6054636014326520859158205642077267748
    sage: eta1 = e.elleta(precision=180)[0]
    sage: eta1.sage()
    3.60546360143265208591582056420772677481026899659802474544

Number fields and precision: TODO

TESTS:

Check that output from PARI’s print command is actually seen by Sage (ticket #9636):

    sage: pari('print("test")')
    test

class `sage.libs.pari.pari_instance.``PariInstance`

  Bases: `sage.structure.parent_base.ParentWithBase`

  Initialize the PARI system.

  INPUT:

  - `size` – long, the number of bytes for the initial PARI stack (see note below)
  - `maxprime` – unsigned long, upper limit on a precomputed prime number table (default: 500000)

  Note

  In Sage, the PARI stack is different than in GP or the PARI C library. In Sage, instead of the PARI stack holding the results of all computations, it only holds the results of an individual computation. Each time a new Python/PARI object is computed, it it copied to its own space in the Python heap, and the memory it occupied on the PARI stack is freed. Thus it is not necessary to make the stack very large. Also, unlike in PARI, if the stack does overflow, in most cases the PARI stack is automatically increased and the relevant step of the computation rerun.

  This design obviously involves some performance penalties over the way PARI works, but it scales much better and is far more robust for large projects.

  Note

  If you do not want prime numbers, put `maxprime=2`, but be careful because many PARI functions require this table. If you get the error message “not enough precomputed primes”, increase this parameter.

  `allocatemem`(s=0, silent=False)

    Change the PARI stack space to the given size (or double the current size if `s` is \(0\)).

    If \(s = 0\) and insufficient memory is avaible to double, the PARI stack will be enlarged by a smaller amount. In any case, a `MemoryError` will be raised if the requested memory cannot be allocated.

    The PARI stack is never automatically shrunk. You can use the command `pari.allocatemem(10^6)` to reset the size to \(10^6\), which is the default size at startup. Note that the results of computations using Sage’s PARI interface are copied to the Python heap, so they take up no space in the PARI stack. The PARI stack is cleared after every computation.

    It does no real harm to set this to a small value as the PARI stack will be automatically doubled when we run out of memory. However, it could make some calculations slower (since they have to be redone from the start after doubling the stack until the stack is big enough).

    INPUT:

    - `s` - an integer (default: 0). A non-zero argument should be the size in bytes of the new PARI stack. If \(s\) is zero, try to double the current stack size.

    EXAMPLES:

        sage: pari.allocatemem(10^7)
        PARI stack size set to 10000000 bytes
        sage: pari.allocatemem()  # Double the current size
        PARI stack size set to 20000000 bytes
        sage: pari.stacksize()
        20000000
        sage: pari.allocatemem(10^6)
        PARI stack size set to 1000000 bytes

    The following computation will automatically increase the PARI stack size:

        sage: a = pari('2^100000000')

    `a` is now a Python variable on the Python heap and does not take up any space on the PARI stack. The PARI stack is still large because of the computation of `a`:

        sage: pari.stacksize()
        16000000
        sage: pari.allocatemem(10^6)
        PARI stack size set to 1000000 bytes
        sage: pari.stacksize()
        1000000

    TESTS:

    Do the same without using the string interface and starting from a very small stack size:

        sage: pari.allocatemem(1)
        PARI stack size set to 1024 bytes
        sage: a = pari(2)^100000000
        sage: pari.stacksize()
        16777216

  `complex`(re, im)

    Create a new complex number, initialized from re and im.

  `debugstack`()

    Print the internal PARI variables `top` (top of stack), `avma` (available memory address, think of this as the stack pointer), `bot` (bottom of stack).

    EXAMPLE:

        sage: pari.debugstack()  # random
        top =  0x60b2c60
        avma = 0x5875c38
        bot =  0x57295e0
        size = 1000000

  `default`(variable, value=None)
  `double_to_gen`(x)
  `euler`(precision=0)

    Return Euler’s constant to the requested real precision (in bits).

    EXAMPLES:

        sage: pari.euler()
        0.577215664901533
        sage: pari.euler(precision=100).python()
        0.577215664901532860606512090082...

  `factorial`(n)

    Return the factorial of the integer n as a PARI gen.

    EXAMPLES:

        sage: pari.factorial(0)
        1
        sage: pari.factorial(1)
        1
        sage: pari.factorial(5)
        120
        sage: pari.factorial(25)
        15511210043330985984000000

  `genus2red`(Q, P)

    Let Q,P be polynomials with integer coefficients. Determine the reduction at p > 2 of the (proper, smooth) hyperelliptic curve C/Q: y^2+Qy = P, of genus 2. (The special fiber X_p of the minimal regular model X of C over Z.)

    EXAMPLES:

        sage: x = polygen(QQ)
        sage: pari.genus2red(x^3 - 2*x^2 - 2*x + 1, -5*x^5)
        [1416875, [2, -1; 5, 4; 2267, 1], x^6 - 240*x^4 - 2550*x^3 - 11400*x^2 - 24100*x - 19855, [[2, [2, [Mod(1, 2)]], []], [5, [1, []], ["[V] page 156", [3]]], [2267, [2, [Mod(432, 2267)]], ["[I{1-0-0}] page 170", []]]]]

  `get_debug_level`()

    Set the debug PARI C library variable.

  `get_real_precision`()

    Returns the current PARI default real precision.

    This is used both for creation of new objects from strings and for printing. It is the number of digits IN DECIMAL in which real numbers are printed. It also determines the precision of objects created by parsing strings (e.g. pari(‘1.2’)), which is not the normal way of creating new pari objects in Sage. It has no effect on the precision of computations within the pari library.

    EXAMPLES:

        sage: pari.get_real_precision()
        15

  `get_series_precision`()
  `getrand`()

    Returns PARI’s current random number seed.

    OUTPUT:

    GEN of type t_VECSMALL

    EXAMPLES:

        sage: pari.setrand(50)
        sage: a = pari.getrand(); a
        Vecsmall([...])
        sage: pari.setrand(a)
        sage: a == pari.getrand()
        True

  `init_primes`(M)

    Recompute the primes table including at least all primes up to M (but possibly more).

    EXAMPLES:

        sage: pari.init_primes(200000)

    We make sure that ticket trac ticket #11741 has been fixed:

        sage: pari.init_primes(2^30)
        Traceback (most recent call last):
        ...
        ValueError: Cannot compute primes beyond 436273290

  `matrix`(m, n, entries=None)

    matrix(long m, long n, entries=None): Create and return the m x n PARI matrix with given list of entries.

  `new_with_bits_prec`(s, precision)

    pari.new_with_bits_prec(self, s, precision) creates s as a PARI gen with (at most) precision bits of precision.

  `nth_prime`(n)
  `pari_version`()
  `pi`(precision=0)

    Return the value of the constant pi to the requested real precision (in bits).

    EXAMPLES:

        sage: pari.pi()
        3.14159265358979
        sage: pari.pi(precision=100).python()
        3.1415926535897932384626433832...

  `polcyclo`(n, v=-1)

    polcyclo(n, v=x): cyclotomic polynomial of degree n, in variable v.

    EXAMPLES:

        sage: pari.polcyclo(8)
        x^4 + 1
        sage: pari.polcyclo(7, 'z')
        z^6 + z^5 + z^4 + z^3 + z^2 + z + 1
        sage: pari.polcyclo(1)
        x - 1

  `polcyclo_eval`(n, v)

    polcyclo_eval(n, v): value of the nth cyclotomic polynomial at value v.

    EXAMPLES:

        sage: pari.polcyclo_eval(8, 2)
        17
        sage: cyclotomic_polynomial(8)(2)
        17

  `pollegendre`(n, v=-1)

    pollegendre(n, v=x): Legendre polynomial of degree n (n C-integer), in variable v.

    EXAMPLES:

        sage: pari.pollegendre(7)
        429/16*x^7 - 693/16*x^5 + 315/16*x^3 - 35/16*x
        sage: pari.pollegendre(7, 'z')
        429/16*z^7 - 693/16*z^5 + 315/16*z^3 - 35/16*z
        sage: pari.pollegendre(0)
        1

  `polsubcyclo`(n, d, v=-1)

    polsubcyclo(n, d, v=x): return the pari list of polynomial(s) defining the sub-abelian extensions of degree \(d\) of the cyclotomic field \(\QQ(\zeta_n)\), where \(d\) divides \(\phi(n)\).

    EXAMPLES:

        sage: pari.polsubcyclo(8, 4)
        [x^4 + 1]
        sage: pari.polsubcyclo(8, 2, 'z')
        [z^2 - 2, z^2 + 1, z^2 + 2]
        sage: pari.polsubcyclo(8, 1)
        [x - 1]
        sage: pari.polsubcyclo(8, 3)
        []

  `poltchebi`(n, v=-1)

    poltchebi(n, v=x): Chebyshev polynomial of the first kind of degree n, in variable v.

    EXAMPLES:

        sage: pari.poltchebi(7)
        64*x^7 - 112*x^5 + 56*x^3 - 7*x
        sage: pari.poltchebi(7, 'z')
        64*z^7 - 112*z^5 + 56*z^3 - 7*z
        sage: pari.poltchebi(0)
        1

  `polzagier`(n, m)
  `prime_list`(n)

    prime_list(n): returns list of the first n primes

    To extend the table of primes use pari.init_primes(M).

    INPUT:

    - `n` - C long

    OUTPUT:

    - `gen` - PARI list of first n primes

    EXAMPLES:

        sage: pari.prime_list(0)
        []
        sage: pari.prime_list(-1)
        []
        sage: pari.prime_list(3)
        [2, 3, 5]
        sage: pari.prime_list(10)
        [2, 3, 5, 7, 11, 13, 17, 19, 23, 29]
        sage: pari.prime_list(20)
        [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67, 71]
        sage: len(pari.prime_list(1000))
        1000

  `primes_up_to_n`(n)

    Return the primes <= n as a pari list.

    EXAMPLES:

        sage: pari.primes_up_to_n(1)
        []
        sage: pari.primes_up_to_n(20)
        [2, 3, 5, 7, 11, 13, 17, 19]

  `read`(filename)

    Read a script from the named filename into the interpreter. The functions defined in the script are then available for use from Sage/PARI. The result of the last command in `filename` is returned.

    EXAMPLES:

    Create a gp file:

        sage: import tempfile
        sage: gpfile = tempfile.NamedTemporaryFile(mode="w")
        sage: gpfile.file.write("mysquare(n) = {\n")
        sage: gpfile.file.write("    n^2;\n")
        sage: gpfile.file.write("}\n")
        sage: gpfile.file.write("polcyclo(5)\n")
        sage: gpfile.file.flush()

    Read it in Sage, we get the result of the last line:

        sage: pari.read(gpfile.name)
        x^4 + x^3 + x^2 + x + 1

    Call the function defined in the gp file:

        sage: pari('mysquare(12)')
        144

  `set_debug_level`(level)

    Set the debug PARI C library variable.

  `set_real_precision`(n)

    Sets the PARI default real precision in decimal digits.

    This is used both for creation of new objects from strings and for printing. It is the number of digits IN DECIMAL in which real numbers are printed. It also determines the precision of objects created by parsing strings (e.g. pari(‘1.2’)), which is not the normal way of creating new pari objects in Sage. It has no effect on the precision of computations within the pari library.

    Returns the previous PARI real precision.

    EXAMPLES:

        sage: pari.set_real_precision(60)
        15
        sage: pari('1.2')
        1.20000000000000000000000000000000000000000000000000000000000
        sage: pari.set_real_precision(15)
        60

  `set_series_precision`(n)
  `setrand`(seed)

    Sets PARI’s current random number seed.

    INPUT:

    - `seed` – either a strictly positive integer or a GEN of type `t_VECSMALL` as output by `getrand()`

    This should not be called directly; instead, use Sage’s global random number seed handling in `sage.misc.randstate` and call `current_randstate().set_seed_pari()`.

    EXAMPLES:

        sage: pari.setrand(50)
        sage: a = pari.getrand(); a
        Vecsmall([...])
        sage: pari.setrand(a)
        sage: a == pari.getrand()
        True

    TESTS:

    Check that invalid inputs are handled properly (trac ticket #11825):

        sage: pari.setrand(0)
        Traceback (most recent call last):
        ...
        PariError: incorrect type in setrand (t_INT)
        sage: pari.setrand("foobar")
        Traceback (most recent call last):
        ...
        PariError: incorrect type in setrand (t_POL)

  `stacksize`()

    Returns the current size of the PARI stack, which is \(10^6\) by default. However, the stack size is automatically doubled when needed. It can also be set directly using `pari.allocatemem()`.

    EXAMPLES:

        sage: pari.stacksize()
        1000000

  `vector`(n, entries=None)

    vector(long n, entries=None): Create and return the length n PARI vector with given list of entries.

    EXAMPLES:

        sage: pari.vector(5, [1, 2, 5, 4, 3])
        [1, 2, 5, 4, 3]
        sage: pari.vector(2, [x, 1])
        [x, 1]
        sage: pari.vector(2, [x, 1, 5])
        Traceback (most recent call last):
        ...
        IndexError: length of entries (=3) must equal n (=2)

`sage.libs.pari.pari_instance.``prec_bits_to_dec`(prec_in_bits)

  Convert from precision expressed in bits to precision expressed in decimal.

  EXAMPLES:

      sage: from sage.libs.pari.pari_instance import prec_bits_to_dec
      sage: prec_bits_to_dec(53)
      15
      sage: [(32*n, prec_bits_to_dec(32*n)) for n in range(1, 9)]
      [(32, 9),
      (64, 19),
      (96, 28),
      (128, 38),
      (160, 48),
      (192, 57),
      (224, 67),
      (256, 77)]

`sage.libs.pari.pari_instance.``prec_bits_to_words`(prec_in_bits)

  Convert from precision expressed in bits to pari real precision expressed in words. Note: this rounds up to the nearest word, adjusts for the two codewords of a pari real, and is architecture-dependent.

  EXAMPLES:

      sage: from sage.libs.pari.pari_instance import prec_bits_to_words
      sage: prec_bits_to_words(70)
      5   # 32-bit
      4   # 64-bit

      sage: [(32*n, prec_bits_to_words(32*n)) for n in range(1, 9)]
      [(32, 3), (64, 4), (96, 5), (128, 6), (160, 7), (192, 8), (224, 9), (256, 10)] # 32-bit
      [(32, 3), (64, 3), (96, 4), (128, 4), (160, 5), (192, 5), (224, 6), (256, 6)] # 64-bit

`sage.libs.pari.pari_instance.``prec_dec_to_bits`(prec_in_dec)

  Convert from precision expressed in decimal to precision expressed in bits.

  EXAMPLES:

      sage: from sage.libs.pari.pari_instance import prec_dec_to_bits
      sage: prec_dec_to_bits(15)
      49
      sage: [(n, prec_dec_to_bits(n)) for n in range(10, 100, 10)]
      [(10, 33),
      (20, 66),
      (30, 99),
      (40, 132),
      (50, 166),
      (60, 199),
      (70, 232),
      (80, 265),
      (90, 298)]

`sage.libs.pari.pari_instance.``prec_dec_to_words`(prec_in_dec)

  Convert from precision expressed in decimal to precision expressed in words. Note: this rounds up to the nearest word, adjusts for the two codewords of a pari real, and is architecture-dependent.

  EXAMPLES:

      sage: from sage.libs.pari.pari_instance import prec_dec_to_words
      sage: prec_dec_to_words(38)
      6   # 32-bit
      4   # 64-bit
      sage: [(n, prec_dec_to_words(n)) for n in range(10, 90, 10)]
      [(10, 4), (20, 5), (30, 6), (40, 7), (50, 8), (60, 9), (70, 10), (80, 11)] # 32-bit
      [(10, 3), (20, 4), (30, 4), (40, 5), (50, 5), (60, 6), (70, 6), (80, 7)] # 64-bit

`sage.libs.pari.pari_instance.``prec_words_to_bits`(prec_in_words)

  Convert from pari real precision expressed in words to precision expressed in bits. Note: this adjusts for the two codewords of a pari real, and is architecture-dependent.

  EXAMPLES:

      sage: from sage.libs.pari.pari_instance import prec_words_to_bits
      sage: prec_words_to_bits(10)
      256   # 32-bit
      512   # 64-bit
      sage: [(n, prec_words_to_bits(n)) for n in range(3, 10)]
      [(3, 32), (4, 64), (5, 96), (6, 128), (7, 160), (8, 192), (9, 224)]  # 32-bit
      [(3, 64), (4, 128), (5, 192), (6, 256), (7, 320), (8, 384), (9, 448)] # 64-bit

`sage.libs.pari.pari_instance.``prec_words_to_dec`(prec_in_words)

  Convert from precision expressed in words to precision expressed in decimal. Note: this adjusts for the two codewords of a pari real, and is architecture-dependent.

  EXAMPLES:

      sage: from sage.libs.pari.pari_instance import prec_words_to_dec
      sage: prec_words_to_dec(5)
      28   # 32-bit
      57   # 64-bit
      sage: [(n, prec_words_to_dec(n)) for n in range(3, 10)]
      [(3, 9), (4, 19), (5, 28), (6, 38), (7, 48), (8, 57), (9, 67)] # 32-bit
      [(3, 19), (4, 38), (5, 57), (6, 77), (7, 96), (8, 115), (9, 134)] # 64-bit

### Navigation

- index
- modules |
- next |
- previous |
- C/C++ Library Interfaces »