# This file is auto-generated by sage_setup/autogen/pari/generator.py

cdef class PariInstance_auto(ParentWithBase):
    """
    Part of the :class:`PariInstance` class containing auto-generated functions.

    You must never use this class directly (in fact, Sage may crash if
    you do), use the derived class :class:`PariInstance` instead.
    """
    def Catalan(self, long precision=0):
        r"""
        Catalan's constant :math:`G = \sum_{n >= 0}((-1)^n)/((2n+1)^2) = 0.91596...`.
        Note that :literal:`Catalan` is one of the few reserved names which cannot be
        used for user variables.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        precision = prec_bits_to_words(precision)
        pari_catch_sig_on()
        cdef GEN _ret = mpcatalan(precision)
        return pari_instance.new_gen(_ret)

    def Euler(self, long precision=0):
        r"""
        Euler's constant :math:`\gamma = 0.57721...`. Note that
        :literal:`Euler` is one of the few reserved names which cannot be used for
        user variables.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        precision = prec_bits_to_words(precision)
        pari_catch_sig_on()
        cdef GEN _ret = mpeuler(precision)
        return pari_instance.new_gen(_ret)

    def I(self):
        r"""
        The complex number :math:`\sqrt{-1}`.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        pari_catch_sig_on()
        cdef GEN _ret = gen_I()
        return pari_instance.new_gen(_ret)

    def Pi(self, long precision=0):
        r"""
        The constant :math:`\Pi` (:math:`3.14159...`). Note that :literal:`Pi` is one of the few
        reserved names which cannot be used for user variables.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        precision = prec_bits_to_words(precision)
        pari_catch_sig_on()
        cdef GEN _ret = mppi(precision)
        return pari_instance.new_gen(_ret)

    def addhelp(self, sym, str):
        r"""
        Changes the help message for the symbol :literal:`sym`. The string :emphasis:`str`
        is expanded on the spot and stored as the online help for :literal:`sym`. It is
        recommended to document global variables and user functions in this way,
        although :literal:`gp` will not protest if you don't.
        
        You can attach a help text to an alias, but it will never be
        shown: aliases are expanded by the :literal:`?` help operator and we get the help
        of the symbol the alias points to. Nothing prevents you from modifying the
        help of built-in PARI functions. But if you do, we would like to hear why you
        needed it!
        
        Without :literal:`addhelp`, the standard help for user functions consists of its
        name and definition.
        
        ::
        
            gp> f(x) = x^2;
            gp> ?f
            f =
             (x)->x^2
            
        
        Once addhelp is applied to :math:`f`, the function code is no
        longer included. It can still be consulted by typing the function name:
        
        ::
        
            gp> addhelp(f, "Square")
            gp> ?f
            Square
            
            gp> f
            %2 = (x)->x^2
        """
        cdef PariInstance pari_instance = <PariInstance>self
        sym = str(sym)
        cdef char* _sym = <bytes?>sym
        str = str(str)
        cdef char* _str = <bytes?>str
        pari_catch_sig_on()
        addhelp(_sym, _str)
        pari_instance.clear_stack()

    def bernfrac(self, long x):
        r"""
        Bernoulli number :math:`B_x`,
        where :math:`B_0 = 1`, :math:`B_1 = -1/2`, :math:`B_2 = 1/6`,..., expressed as a rational number.
        The argument :math:`x` should be of type integer.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        pari_catch_sig_on()
        cdef GEN _ret = bernfrac(x)
        return pari_instance.new_gen(_ret)

    def bernpol(self, long n, v=None):
        r"""
        Bernoulli polynomial :math:`B_n` in variable :math:`v`.
        
        ::
        
            ? bernpol(1)
            %1 = x - 1/2
            ? bernpol(3)
            %2 = x^3 - 3/2*x^2 + 1/2*x
        """
        cdef PariInstance pari_instance = <PariInstance>self
        cdef long _v = -1
        if v is not None:
            _v = pari_instance.get_var(v)
        pari_catch_sig_on()
        cdef GEN _ret = bernpol(n, _v)
        return pari_instance.new_gen(_ret)

    def bernreal(self, long x, long precision=0):
        r"""
        Bernoulli number
        :math:`B_x`, as :literal:`bernfrac`, but :math:`B_x` is returned as a real number
        (with the current precision).
        """
        cdef PariInstance pari_instance = <PariInstance>self
        precision = prec_bits_to_words(precision)
        pari_catch_sig_on()
        cdef GEN _ret = bernreal(x, precision)
        return pari_instance.new_gen(_ret)

    def bernvec(self, long x):
        r"""
        Creates a vector containing, as rational numbers,
        the Bernoulli numbers :math:`B_0`, :math:`B_2`,..., :math:`B_{2x}`.
        This routine is obsolete. Use :literal:`bernfrac` instead each time you need a
        Bernoulli number in exact form.
        
        :strong:`Note.` This routine is implemented using repeated independent
        calls to :literal:`bernfrac`, which is faster than the standard recursion in exact
        arithmetic. It is only kept for backward compatibility: it is not faster than
        individual calls to :literal:`bernfrac`, its output uses a lot of memory space,
        and coping with the index shift is awkward.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        pari_catch_sig_on()
        cdef GEN _ret = bernvec(x)
        return pari_instance.new_gen(_ret)

    def default(self, key=None, val=None):
        r"""
        Returns the default corresponding to keyword :emphasis:`key`. If :emphasis:`val` is
        present, sets the default to :emphasis:`val` first (which is subject to string
        expansion first). Typing :literal:`default()` (or :literal:`\\d`) yields the complete
        default list as well as their current values. See ``defaults`` (in the PARI manual) for an
        introduction to GP defaults, ``gp_defaults`` (in the PARI manual) for a
        list of available defaults, and ``meta`` (in the PARI manual) for some shortcut
        alternatives. Note that the shortcuts are meant for interactive use and
        usually display more information than :literal:`default`.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        cdef char* _key
        if key is None:
            _key = NULL
        else:
            key = bytes(key)
            _key = <bytes?>key
        cdef char* _val
        if val is None:
            _val = NULL
        else:
            val = bytes(val)
            _val = <bytes?>val
        pari_catch_sig_on()
        cdef GEN _ret = default0(_key, _val)
        return pari_instance.new_gen(_ret)

    def ellmodulareqn(self, long N, x=None, y=None):
        r"""
        Return a vector [:literal:`eqn`,:math:`t`] where :literal:`eqn` is a modular equation of
        level :math:`N`, i.e. a bivariate polynomial with integer coefficients; :math:`t`
        indicates the type of this equation: either :emphasis:`canonical` (:math:`t = 0`) or
        :emphasis:`Atkin` (:math:`t = 1`). This function currently requires the package
        :literal:`seadata` to be installed and is limited to :math:`N < 500`, :math:`N` prime.
        
        Let :math:`j` be the :math:`j`-invariant function. The polynomial :literal:`eqn` satisfies
        the following functional equation, which allows to compute the values of the
        classical modular polynomial :math:`\Phi_N` of prime level :math:`N`, such that
        :math:`\Phi_N(j(\tau), j(N\tau)) = 0`, while being much smaller than the latter:
        
        - for canonical type:
          :math:`P(f(\tau),j(\tau)) = P(N^s/f(\tau),j(N \tau)) = 0`,
          where :math:`s = 12/\mathrm{gcd}(12,N-1)`;
        
        - for Atkin type:
          :math:`P(f(\tau),j(\tau)) = P(f(\tau),j(N \tau)) = 0`.
        
        In both cases, :math:`f` is a suitable modular function (see below).
        
        The following GP function returns values of the classical modular polynomial
        by eliminating :math:`f(\tau)` in the above two equations, for :math:`N <= 31` or
        :math:`N belongs to {41,47,59,71}`.
        
        ::
        
            classicaleqn(N, X='X, Y='Y)=
            {
             my(E=ellmodulareqn(N), P=E[1], t=E[2], Q, d);
             if(poldegree(P,'y)>2,error("level unavailable in classicaleqn"));
             if (t == 0,
             my(s = 12/gcd(12,N-1));
             Q = 'x^(N+1) * substvec(P,['x,'y],[N^s/'x,Y]);
             d = N^(s*(2*N+1)) * (-1)^(N+1);
             ,
             Q = subst(P,'y,Y);
             d = (X-Y)^(N+1));
             polresultant(subst(P,'y,X), Q) / d;
            }
        
        More precisely, let :math:`W_N(\tau) = ({-1})/({N \tau})` be the Atkin-Lehner
        involution; we have :math:`j(W_N(\tau)) = j(N \tau)` and the function :math:`f` also
        satisfies:
        
        - for canonical type:
          :math:`f(W_N(\tau)) = N^s/f(\tau)`;
        
        - for Atkin type:
          :math:`f(W_N(\tau)) = f(\tau)`.
        
        Furthermore, for an equation of canonical type, :math:`f` is the standard
        :math:`\eta`-quotient
        
        .. MATH::
        
            f(\tau) = N^s (\eta(N \tau) / \eta(\tau) )^{2 s},
        
        where :math:`\eta` is Dedekind's eta function, which is invariant under
        :math:`\Gamma_0(N)`.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        cdef long _x = -1
        if x is not None:
            _x = pari_instance.get_var(x)
        cdef long _y = -1
        if y is not None:
            _y = pari_instance.get_var(y)
        pari_catch_sig_on()
        cdef GEN _ret = ellmodulareqn(N, _x, _y)
        return pari_instance.new_gen(_ret)

    def extern(self, str):
        r"""
        The string :emphasis:`str` is the name of an external command (i.e. one you
        would type from your UNIX shell prompt). This command is immediately run and
        its output fed into :literal:`gp`, just as if read from a file.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        str = str(str)
        cdef char* _str = <bytes?>str
        pari_catch_sig_on()
        cdef GEN _ret = gpextern(_str)
        return pari_instance.new_gen(_ret)

    def externstr(self, str):
        r"""
        The string :emphasis:`str` is the name of an external command (i.e. one you
        would type from your UNIX shell prompt). This command is immediately run and
        its output is returned as a vector of GP strings, one component per output
        line.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        str = str(str)
        cdef char* _str = <bytes?>str
        pari_catch_sig_on()
        cdef GEN _ret = externstr(_str)
        return pari_instance.new_gen(_ret)

    def factorial(self, long x, long precision=0):
        r"""
        Factorial of :math:`x`. The expression :math:`x!` gives a result which is an integer,
        while :math:`factorial(x)` gives a real number.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        precision = prec_bits_to_words(precision)
        pari_catch_sig_on()
        cdef GEN _ret = mpfactr(x, precision)
        return pari_instance.new_gen(_ret)

    def fibonacci(self, long x):
        r"""
        :math:`x-th` Fibonacci number.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        pari_catch_sig_on()
        cdef GEN _ret = fibo(x)
        return pari_instance.new_gen(_ret)

    def galoisgetpol(self, long a, long b=0, long s=1):
        r"""
        Query the galpol package for a polynomial with Galois group isomorphic to
        GAP4(a,b), totally real if :math:`s = 1` (default) and totally complex if :math:`s = 2`. The
        output is a vector [:literal:`pol`, :literal:`den`] where
        
        - :literal:`pol` is the polynomial of degree :math:`a`
        
        - :literal:`den` is the denominator of :literal:`nfgaloisconj(pol)`.
          Pass it as an optional argument to :literal:`galoisinit` or :literal:`nfgaloisconj` to
          speed them up:
        
        ::
        
            ? [pol,den] = galoisgetpol(64,4,1);
            ? G = galoisinit(pol);
            time = 352ms
            ? galoisinit(pol, den); \\ passing 'den' speeds up the computation
            time = 264ms
            ? % == %`
            %4 = 1 \\ same answer
        
        If :math:`b` and :math:`s` are omitted, return the number of isomorphism classes of
        groups of order :math:`a`.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        pari_catch_sig_on()
        cdef GEN _ret = galoisgetpol(a, b, s)
        return pari_instance.new_gen(_ret)

    def getabstime(self):
        r"""
        Returns the CPU time (in milliseconds) elapsed since :literal:`gp` startup.
        This provides a reentrant version of :literal:`gettime`:
        
        ::
        
            my (t = getabstime());
            ...
            print("Time: ", getabstime() - t);
        
        For a version giving wall-clock time, see :literal:`getwalltime`.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        pari_catch_sig_on()
        cdef long _ret = getabstime()
        pari_instance.clear_stack()
        return _ret

    def getenv(self, s):
        r"""
        Return the value of the environment variable :literal:`s` if it is defined, otherwise return 0.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        s = str(s)
        cdef char* _s = <bytes?>s
        pari_catch_sig_on()
        cdef GEN _ret = gp_getenv(_s)
        return pari_instance.new_gen(_ret)

    def getheap(self):
        r"""
        Returns a two-component row vector giving the
        number of objects on the heap and the amount of memory they occupy in long
        words. Useful mainly for debugging purposes.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        pari_catch_sig_on()
        cdef GEN _ret = getheap()
        return pari_instance.new_gen(_ret)

    def getrand(self):
        r"""
        Returns the current value of the seed used by the
        pseudo-random number generator :literal:`random`. Useful mainly for debugging
        purposes, to reproduce a specific chain of computations. The returned value
        is technical (reproduces an internal state array), and can only be used as an
        argument to :literal:`setrand`.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        pari_catch_sig_on()
        cdef GEN _ret = getrand()
        return pari_instance.new_gen(_ret)

    def getstack(self):
        r"""
        Returns the current value of :math:`top-avma`, i.e. the number of
        bytes used up to now on the stack. Useful mainly for debugging purposes.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        pari_catch_sig_on()
        cdef long _ret = getstack()
        pari_instance.clear_stack()
        return _ret

    def gettime(self):
        r"""
        Returns the CPU time (in milliseconds) used since either the last call to
        :literal:`gettime`, or to the beginning of the containing GP instruction (if
        inside :literal:`gp`), whichever came last.
        
        For a reentrant version, see :literal:`getabstime`.
        
        For a version giving wall-clock time, see :literal:`getwalltime`.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        pari_catch_sig_on()
        cdef long _ret = gettime()
        pari_instance.clear_stack()
        return _ret

    def getwalltime(self):
        r"""
        Returns the time (in milliseconds) elapsed since the UNIX Epoch
        (1970-01-01 00:00:00 (UTC)).
        
        ::
        
            my (t = getwalltime());
            ...
            print("Time: ", getwalltime() - t);
        """
        cdef PariInstance pari_instance = <PariInstance>self
        pari_catch_sig_on()
        cdef GEN _ret = getwalltime()
        return pari_instance.new_gen(_ret)

    def input(self):
        r"""
        Reads a string, interpreted as a GP expression,
        from the input file, usually standard input (i.e. the keyboard). If a
        sequence of expressions is given, the result is the result of the last
        expression of the sequence. When using this instruction, it is useful to
        prompt for the string by using the :literal:`print1` function. Note that in the
        present version 2.19 of :literal:`pari.el`, when using :literal:`gp` under GNU Emacs (see
        ``emacs`` (in the PARI manual)) one :emphasis:`must` prompt for the string, with a string
        which ends with the same prompt as any of the previous ones (a :literal:`"? "`
        will do for instance).
        """
        cdef PariInstance pari_instance = <PariInstance>self
        pari_catch_sig_on()
        cdef GEN _ret = gp_input()
        return pari_instance.new_gen(_ret)

    def install(self, name, code, gpname=None, lib=None):
        r"""
        Loads from dynamic library :emphasis:`lib` the function :emphasis:`name`. Assigns to it
        the name :emphasis:`gpname` in this :literal:`gp` session, with :emphasis:`prototype`
        :emphasis:`code` (see below). If :emphasis:`gpname` is omitted, uses :emphasis:`name`.
        If :emphasis:`lib` is omitted, all symbols known to :literal:`gp` are available: this
        includes the whole of :literal:`libpari.so` and possibly others (such as
        :literal:`libc.so`).
        
        Most importantly, :literal:`install` gives you access to all non-static functions
        defined in the PARI library. For instance, the function \\kbd{GEN addii(GEN
        x, GEN y)} adds two PARI integers, and is not directly accessible under
        :literal:`gp` (it is eventually called by the :literal:`+` operator of course):
        
        ::
        
            ? install("addii", "GG")
            ? addii(1, 2)
            %1 = 3
        
        It also allows to add external functions to the :literal:`gp` interpreter.
        For instance, it makes the function :literal:`system` obsolete:
        
        ::
        
            ? install(system, vs, sys,/*omitted*/)
            ? sys("ls gp*")
            gp.c gp.h gp_rl.c
        
        This works because :literal:`system` is part of :literal:`libc.so`,
        which is linked to :literal:`gp`. It is also possible to compile a shared library
        yourself and provide it to gp in this way: use :literal:`gp2c`, or do it manually
        (see the :literal:`modules_build` variable in :literal:`pari.cfg` for hints).
        
        Re-installing a function will print a warning and update the prototype code
        if needed. However, it will not reload a symbol from the library, even if the
        latter has been recompiled.
        
        :strong:`Prototype.` We only give a simplified description here, covering
        most functions, but there are many more possibilities. The full documentation
        is available in :literal:`libpari.dvi`, see
        
        ::
        
             ??prototype
        
        - First character :literal:`i`, :literal:`l`, :literal:`v` : return type int / long /
          void. (Default: :literal:`GEN`)
        
        - One letter for each mandatory argument, in the same order as they appear
          in the argument list: :literal:`G` (:literal:`GEN`), :literal:`&`
          (:literal:`GEN*`), :literal:`L` (:literal:`long`), :literal:`s` (:literal:`char *`), :literal:`n`
          (variable).
        
        - :literal:`p` to supply :literal:`realprecision` (usually :literal:`long prec` in the
          argument list), :literal:`P` to supply :literal:`seriesprecision` (usually \kbd{long
          precdl}).
        
        We also have special constructs for optional arguments and default
        values:
        
        - :literal:`DG` (optional :literal:`GEN`, :literal:`NULL` if omitted),
        
        - :literal:`D&` (optional :literal:`GEN*`, :literal:`NULL` if omitted),
        
        - :literal:`Dn` (optional variable, :math:`-1` if omitted),
        
        For instance the prototype corresponding to
        
        ::
        
             long issquareall(GEN x, GEN *n = NULL)
        
        is :literal:`lGD&`.
        
        :strong:`Caution.` This function may not work on all systems, especially
        when :literal:`gp` has been compiled statically. In that case, the first use of an
        installed function will provoke a Segmentation Fault (this should never
        happen with a dynamically linked executable). If you intend to use this
        function, please check first on some harmless example such as the one above
        that it works properly on your machine.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        name = str(name)
        cdef char* _name = <bytes?>name
        code = str(code)
        cdef char* _code = <bytes?>code
        cdef char* _gpname
        if gpname is None:
            _gpname = ""
        else:
            gpname = bytes(gpname)
            _gpname = <bytes?>gpname
        cdef char* _lib
        if lib is None:
            _lib = ""
        else:
            lib = bytes(lib)
            _lib = <bytes?>lib
        pari_catch_sig_on()
        gpinstall(_name, _code, _gpname, _lib)
        pari_instance.clear_stack()

    def intnumgaussinit(self, long n=0, long precision=0):
        r"""
        Initialize tables for :math:`n`-point Gauss-Legendre integration of
        a smooth function :math:`f` lon a compact
        interval :math:`[a,b]` at current :literal:`realprecision`. If :math:`n` is omitted, make a
        default choice :math:`n ~ realprecision`, suitable for analytic
        functions on :math:`[-1,1]`. The error is bounded by
        
        .. MATH::
        
            ((b-a)^{2n+1} (n!)^4)/((2n+1)[(2n)!]^3) f^{(2n)} (\xi) ,
            a < \xi < b
        
        so, if the interval length increases, :math:`n` should be increased as well.
        
        ::
        
            ? T = intnumgaussinit();
            ? intnumgauss(t=-1,1,exp(t), T) - exp(1)+exp(-1)
            %1 = -5.877471754111437540 E-39
            ? intnumgauss(t=-10,10,exp(t), T) - exp(10)+exp(-10)
            %2 = -8.358367809712546836 E-35
            ? intnumgauss(t=-1,1,1/(1+t^2), T) - Pi/2
            %3 = -9.490148553624725335 E-22
            
            ? T = intnumgaussinit(50);
            ? intnumgauss(t=-1,1,1/(1+t^2), T) - Pi/2
            %5 = -1.1754943508222875080 E-38
            ? intnumgauss(t=-5,5,1/(1+t^2), T) - 2*atan(5)
            %6 = -1.2[...]E-8
        
        On the other hand, we recommend to split the integral and change variables
        rather than increasing :math:`n` too much, see :literal:`intnumgauss`.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        precision = prec_bits_to_words(precision)
        pari_catch_sig_on()
        cdef GEN _ret = intnumgaussinit(n, precision)
        return pari_instance.new_gen(_ret)

    def kill(self, sym):
        r"""
        Restores the symbol :literal:`sym` to its "undefined" status, and deletes any
        help messages associated to :literal:`sym` using :literal:`addhelp`. Variable names
        remain known to the interpreter and keep their former priority: you cannot
        make a variable "less important" by killing it!
        
        ::
        
            ? z = y = 1; y
            %1 = 1
            ? kill(y)
            ? y \\ restored to ``undefined'' status
            %2 = y
            ? variable()
            %3 = [x, y, z] \\ but the variable name y is still known, with y > z !
        
        For the same reason, killing a user function (which is an ordinary
        variable holding a :literal:`t_CLOSURE`) does not remove its name from the list of
        variable names.
        
        If the symbol is associated to a variable --- user functions being an
        important special case ---, one may use the quote operator
        :literal:`a = 'a` to reset variables to their starting values. However, this
        will not delete a help message associated to :literal:`a`, and is also slightly
        slower than :literal:`kill(a)`.
        
        ::
        
            ? x = 1; addhelp(x, "foo"); x
            %1 = 1
            ? x = 'x; x \\ same as 'kill', except we don't delete help.
            %2 = x
            ? ?x
            foo
        
        On the other hand, :literal:`kill` is the only way to remove aliases and installed
        functions.
        
        ::
        
            ? alias(fun, sin);
            ? kill(fun);
            
            ? install(addii, GG);
            ? kill(addii);
        """
        cdef PariInstance pari_instance = <PariInstance>self
        sym = str(sym)
        cdef char* _sym = <bytes?>sym
        pari_catch_sig_on()
        kill0(_sym)
        pari_instance.clear_stack()

    def localprec(self, long p):
        r"""
        Set the real precision to :math:`p` in the dynamic scope. All computations
        are performed as if :literal:`realprecision` was :math:`p`:
        transcendental constants (e.g. :literal:`Pi`) and
        conversions from exact to floating point inexact data use :math:`p` decimal
        digits, as well as iterative routines implicitly using a floating point
        accuracy as a termination criterion (e.g. :literal:`solve` or :literal:`intnum`).
        But :literal:`realprecision` itself is unaffected
        and is "unmasked" when we exit the dynamic (:emphasis:`not` lexical) scope.
        In effect, this is similar to
        
        ::
        
            my(prec = default(realprecision));
            default(realprecision,p);
            ...
            default(realprecision, prec);
        
        but is both less cumbersome, cleaner (no need to manipulate
        a global variable, which in fact never changes and is only temporarily masked)
        and more robust: if the above computation is interrupted or an exception
        occurs, :literal:`realprecision` will not be restored as intended.
        
        Such :literal:`localprec` statements can be nested, the innermost one taking
        precedence as expected. Beware that :literal:`localprec` follows the semantic of
        :literal:`local`, not :literal:`my`: a subroutine called from :literal:`localprec` scope
        uses the local accuracy:
        
        ::
        
            ? f()=precision(1.);
            ? f()
            %2 = 38
            ? localprec(19); f()
            %3 = 19
        
        :strong:`Warning.` Changing :literal:`realprecision` itself in programs is
        now deprecated in favor of :literal:`localprec`. Think about the
        :literal:`realprecision` default as an interactive command for the :literal:`gp`
        interpreter, best left out of GP programs. Indeed, the above rules
        imply that mixing both constructs yields surprising results:
        
        ::
        
            ? \p38
            ? localprec(19); default(realprecision,100); Pi
            %1 = 3.141592653589793239
            ? \p
             realprecision = 115 significant digits (100 digits displayed)
        
        Indeed, :literal:`realprecision` itself is ignored within
        :literal:`localprec` scope, so :literal:`Pi` is computed to a low accuracy. And when
        we leave :literal:`localprec` scope, :literal:`realprecision` only regains precedence,
        it is not "restored" to the original value.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        pari_catch_sig_on()
        localprec(p)
        pari_instance.clear_stack()

    def mathilbert(self, long n):
        r"""
        :math:`x` being a :literal:`long`, creates the
        Hilbert matrixof order :math:`x`, i.e. the matrix whose coefficient
        (:math:`i`,:math:`j`) is :math:`1/ (i+j-1)`.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        pari_catch_sig_on()
        cdef GEN _ret = mathilbert(n)
        return pari_instance.new_gen(_ret)

    def matid(self, long n):
        r"""
        Creates the :math:`n x n` identity matrix.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        pari_catch_sig_on()
        cdef GEN _ret = matid(n)
        return pari_instance.new_gen(_ret)

    def matpascal(self, long n, q=None):
        r"""
        Creates as a matrix the lower triangular
        Pascal triangle of order :math:`x+1` (i.e. with binomial coefficients
        up to :math:`x`). If :math:`q` is given, compute the :math:`q`-Pascal triangle (i.e. using
        :math:`q`-binomial coefficients).
        """
        cdef PariInstance pari_instance = <PariInstance>self
        cdef GEN _q = NULL
        if q is not None:
            q = objtogen(q)
            _q = (<gen>q).g
        pari_catch_sig_on()
        cdef GEN _ret = matqpascal(n, _q)
        return pari_instance.new_gen(_ret)

    def numtoperm(self, long n, k):
        r"""
        Generates the :math:`k`-th permutation (as a row vector of length :math:`n`) of the
        numbers :math:`1` to :math:`n`. The number :math:`k` is taken modulo :math:`n!`, i.e. inverse
        function of :literal:`permtonum`. The numbering used is the standard lexicographic
        ordering, starting at :math:`0`.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        k = objtogen(k)
        cdef GEN _k = (<gen>k).g
        pari_catch_sig_on()
        cdef GEN _ret = numtoperm(n, _k)
        return pari_instance.new_gen(_ret)

    def partitions(self, long k, a=None, n=None):
        r"""
        Returns the vector of partitions of the integer :math:`k` as a sum of positive
        integers (parts); for :math:`k < 0`, it returns the empty set :literal:`[]`, and for :math:`k
        = 0` the trivial partition (no parts). A partition is given by a
        :literal:`t_VECSMALL`, where parts are sorted in nondecreasing order:
        
        ::
        
            ? partitions(3)
            %1 = [Vecsmall([3]), Vecsmall([1, 2]), Vecsmall([1, 1, 1])]
        
        correspond to :math:`3`, :math:`1+2` and :math:`1+1+1`. The number
        of (unrestricted) partitions of :math:`k` is given
        by :literal:`numbpart`:
        
        ::
        
            ? #partitions(50)
            %1 = 204226
            ? numbpart(50)
            %2 = 204226
        
        Optional parameters :math:`n` and :math:`a` are as follows:
        
        - :math:`n = nmax` (resp. :math:`n = [nmin,nmax]`) restricts
          partitions to length less than :math:`nmax` (resp. length between
          :math:`nmin` and :math:`nmax`), where the :emphasis:`length` is the number of nonzero
          entries.
        
        - :math:`a = amax` (resp. :math:`a = [amin,amax]`) restricts the parts
          to integers less than :math:`amax` (resp. between :math:`amin` and
          :math:`amax`).
        
        ::
        
            ? partitions(4, 2) \\ parts bounded by 2
            %1 = [Vecsmall([2, 2]), Vecsmall([1, 1, 2]), Vecsmall([1, 1, 1, 1])]
            ? partitions(4,, 2) \\ at most 2 parts
            %2 = [Vecsmall([4]), Vecsmall([1, 3]), Vecsmall([2, 2])]
            ? partitions(4,[0,3], 2) \\ at most 2 parts
            %3 = [Vecsmall([4]), Vecsmall([1, 3]), Vecsmall([2, 2])]
        
        By default, parts are positive and we remove zero entries unless
        :math:`amin <= 0`, in which case :math:`nmin` is ignored and :math:`X` is of constant length
        :math:`nmax`:
        
        ::
        
            ? partitions(4, [0,3]) \\ parts between 0 and 3
            %1 = [Vecsmall([0, 0, 1, 3]), Vecsmall([0, 0, 2, 2]),\
             Vecsmall([0, 1, 1, 2]), Vecsmall([1, 1, 1, 1])]
        """
        cdef PariInstance pari_instance = <PariInstance>self
        cdef GEN _a = NULL
        if a is not None:
            a = objtogen(a)
            _a = (<gen>a).g
        cdef GEN _n = NULL
        if n is not None:
            n = objtogen(n)
            _n = (<gen>n).g
        pari_catch_sig_on()
        cdef GEN _ret = partitions(k, _a, _n)
        return pari_instance.new_gen(_ret)

    def polchebyshev(self, long n, long flag=1, a=None):
        r"""
        Returns the :math:`n-th`
        Chebyshev polynomial of the first kind :math:`T_n` (:math:`flag = 1`) or the second
        kind :math:`U_n` (:math:`flag = 2`), evaluated at :math:`a` (:literal:`'x` by default). Both series of
        polynomials satisfy the 3-term relation
        
        .. MATH::
        
            P_{n+1} = 2xP_n - P_{n-1},
        
        and are determined by the initial conditions :math:`U_0 = T_0 = 1`, :math:`T_1 = x`,
        :math:`U_1 = 2x`. In fact :math:`T_n' = n U_{n-1}` and, for all complex numbers :math:`z`, we
        have :math:`T_n(\cos z) = \cos (nz)` and :math:`U_{n-1}(\cos z) = \sin(nz)/\sin z`.
        If :math:`n >= 0`, then these polynomials have degree :math:`n`. For :math:`n < 0`,
        :math:`T_n` is equal to :math:`T_{-n}` and :math:`U_n` is equal to :math:`-U_{-2-n}`.
        In particular, :math:`U_{-1} = 0`.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        cdef GEN _a = NULL
        if a is not None:
            a = objtogen(a)
            _a = (<gen>a).g
        pari_catch_sig_on()
        cdef GEN _ret = polchebyshev_eval(n, flag, _a)
        return pari_instance.new_gen(_ret)

    def polcyclo(self, long n, a=None):
        r"""
        :math:`n`-th cyclotomic polynomial, evaluated at :math:`a` (:literal:`'x` by default). The
        integer :math:`n` must be positive.
        
        Algorithm used: reduce to the case where :math:`n` is squarefree; to compute the
        cyclotomic polynomial, use :math:`\Phi_{np}(x) = \Phi_n(x^p)/\Phi(x)`; to compute
        it evaluated, use :math:`\Phi_n(x) = \prod_{d \| n} (x^d-1)^{\mu(n/d)}`. In the
        evaluated case, the algorithm assumes that :math:`a^d - 1` is either :math:`0` or
        invertible, for all :math:`d \| n`. If this is not the case (the base ring has
        zero divisors), use :literal:`subst(polcyclo(n),x,a)`.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        cdef GEN _a = NULL
        if a is not None:
            a = objtogen(a)
            _a = (<gen>a).g
        pari_catch_sig_on()
        cdef GEN _ret = polcyclo_eval(n, _a)
        return pari_instance.new_gen(_ret)

    def polhermite(self, long n, a=None):
        r"""
        :math:`n-th` Hermite polynomial :math:`H_n` evaluated at :math:`a`
        (:literal:`'x` by default), i.e.
        
        .. MATH::
        
            H_n(x) = (-1)^n e^{x^2} (d^n)/(dx^n)e^{-x^2}.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        cdef GEN _a = NULL
        if a is not None:
            a = objtogen(a)
            _a = (<gen>a).g
        pari_catch_sig_on()
        cdef GEN _ret = polhermite_eval(n, _a)
        return pari_instance.new_gen(_ret)

    def pollegendre(self, long n, a=None):
        r"""
        :math:`n-th` Legendre polynomial evaluated at :math:`a` (:literal:`'x` by
        default).
        """
        cdef PariInstance pari_instance = <PariInstance>self
        cdef GEN _a = NULL
        if a is not None:
            a = objtogen(a)
            _a = (<gen>a).g
        pari_catch_sig_on()
        cdef GEN _ret = pollegendre_eval(n, _a)
        return pari_instance.new_gen(_ret)

    def polmodular(self, long L, long inv=0, x=None, y=None, long compute_derivs=0):
        r"""
        Return the modular polynomial of level :math:`L` in variables :math:`x` and :math:`y` for the
        :math:`j` function. If :math:`x` is given as :literal:`Mod(j, p)` or an element :math:`j` of a prime
        finite field, then return the modular polynomial of level :math:`L` evaluated at :math:`j`
        modulo :math:`p`. If :math:`j` is from a finite field and :emphasis:`compute_derivs` is
        non-zero, then return a triple where the last two elements are the first and
        second derivatives of the modular polynomial evaluated at :math:`j`.
        
        ::
        
            ? polmodular(3)
            %1 = x^4 + (-y^3 + 2232*y^2 - 1069956*y + 36864000)*x^3 + [...]
        """
        cdef PariInstance pari_instance = <PariInstance>self
        cdef GEN _x = NULL
        if x is not None:
            x = objtogen(x)
            _x = (<gen>x).g
        cdef long _y = -1
        if y is not None:
            _y = pari_instance.get_var(y)
        pari_catch_sig_on()
        cdef GEN _ret = polmodular(L, inv, _x, _y, compute_derivs)
        return pari_instance.new_gen(_ret)

    def polsubcyclo(self, long n, long d, v=None):
        r"""
        Gives polynomials (in variable :math:`v`) defining the sub-Abelian extensions
        of degree :math:`d` of the cyclotomic field :math:`\mathbb{Q}(\zeta_n)`, where :math:`d \| \phi(n)`.
        
        If there is exactly one such extension the output is a polynomial, else it is
        a vector of polynomials, possibly empty. To get a vector in all cases,
        use :literal:`concat([], polsubcyclo(n,d))`.
        
        The function :literal:`galoissubcyclo` allows to specify exactly which
        sub-Abelian extension should be computed.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        cdef long _v = -1
        if v is not None:
            _v = pari_instance.get_var(v)
        pari_catch_sig_on()
        cdef GEN _ret = polsubcyclo(n, d, _v)
        return pari_instance.new_gen(_ret)

    def poltchebi(self, long n, v=None):
        r"""
        Deprecated alias for :literal:`polchebyshev`
        """
        cdef PariInstance pari_instance = <PariInstance>self
        cdef long _v = -1
        if v is not None:
            _v = pari_instance.get_var(v)
        pari_catch_sig_on()
        cdef GEN _ret = polchebyshev1(n, _v)
        return pari_instance.new_gen(_ret)

    def polylog(self, long m, x, long flag=0, long precision=0):
        r"""
        One of the different polylogarithms, depending on :emphasis:`flag`:
        
        If :math:`flag = 0` or is omitted: :math:`m-th` polylogarithm of :math:`x`, i.e. analytic
        continuation of the power series :math:`{Li}_m(x) = \sum_{n >= 1}x^n/n^m`
        (:math:`x < 1`). Uses the functional equation linking the values at :math:`x` and :math:`1/x`
        to restrict to the case :math:`\|x\| <= 1`, then the power series when
        :math:`\|x\|^2 <= 1/2`, and the power series expansion in :math:`\log(x)` otherwise.
        
        Using :math:`flag`, computes a modified :math:`m-th` polylogarithm of :math:`x`.
        We use Zagier's notations; let :math:`\Re_m` denote :math:`\Re` or :math:`\Im` depending
        on whether :math:`m` is odd or even:
        
        If :math:`flag = 1`: compute :math:`~ D_m(x)`, defined for :math:`\|x\| <= 1` by
        
        .. MATH::
        
            \Re_m(\sum_{k = 0}^{m-1} ((-\log\|x\|)^k)/(k!){Li}_{m-k}(x)
            +((-\log\|x\|)^{m-1})/(m!)\log\|1-x\|).
        
        If :math:`flag = 2`: compute :math:`D_m(x)`, defined for :math:`\|x\| <= 1` by
        
        .. MATH::
        
            \Re_m(\sum_{k = 0}^{m-1}((-\log\|x\|)^k)/(k!){Li}_{m-k}(x)
            -(1)/(2)((-\log\|x\|)^m)/(m!)).
        
        If :math:`flag = 3`: compute :math:`P_m(x)`, defined for :math:`\|x\| <= 1` by
        
        .. MATH::
        
            \Re_m(\sum_{k = 0}^{m-1}(2^kB_k)/(k!)(\log\|x\|)^k{Li}_{m-k}(x)
            -(2^{m-1}B_m)/(m!)(\log\|x\|)^m).
        
        These three functions satisfy the functional equation
        :math:`f_m(1/x) = (-1)^{m-1}f_m(x)`.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        x = objtogen(x)
        cdef GEN _x = (<gen>x).g
        precision = prec_bits_to_words(precision)
        pari_catch_sig_on()
        cdef GEN _ret = polylog0(m, _x, flag, precision)
        return pari_instance.new_gen(_ret)

    def polzagier(self, long n, long m):
        r"""
        Creates Zagier's polynomial :math:`P_n^{(m)}` used in
        the functions :literal:`sumalt` and :literal:`sumpos` (with :math:`flag = 1`), see
        "Convergence acceleration of alternating series", Cohen et al.,
        :emphasis:`Experiment. Math.`, vol. 9, 2000, pp. 3--12.
        
        If :math:`m < 0` or :math:`m >= n`, :math:`P_n^{(m)} = 0`.
        We have
        :math:`P_n := P_n^{(0)}` is :math:`T_n(2x-1)`, where :math:`T_n` is the Legendre polynomial of
        the second kind. For :math:`n > m > 0`, :math:`P_n^{(m)}` is the :math:`m`-th difference with
        step :math:`2` of the sequence :math:`n^{m+1}P_n`; in this case, it satisfies
        
        .. MATH::
        
            2 P_n^{(m)}(sin^2 t) = (d^{m+1})/(dt^{m+1})(\sin(2t)^m \sin(2(n-m)t)).
        """
        cdef PariInstance pari_instance = <PariInstance>self
        pari_catch_sig_on()
        cdef GEN _ret = polzag(n, m)
        return pari_instance.new_gen(_ret)

    def prime(self, long n):
        r"""
        The :math:`n-th` prime number
        
        ::
        
            ? prime(10^9)
            %1 = 22801763489
        
        Uses checkpointing and a naive :math:`O(n)` algorithm.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        pari_catch_sig_on()
        cdef GEN _ret = prime(n)
        return pari_instance.new_gen(_ret)

    def read(self, filename=None):
        r"""
        Reads in the file
        :emphasis:`filename` (subject to string expansion). If :emphasis:`filename` is
        omitted, re-reads the last file that was fed into :literal:`gp`. The return
        value is the result of the last expression evaluated.
        
        If a GP :literal:`binary file` is read using this command (see
        ``writebin`` (in the PARI manual)), the file is loaded and the last object in the file
        is returned.
        
        In case the file you read in contains an :literal:`allocatemem` statement (to be
        generally avoided), you should leave :literal:`read` instructions by themselves,
        and not part of larger instruction sequences.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        cdef char* _filename
        if filename is None:
            _filename = ""
        else:
            filename = bytes(filename)
            _filename = <bytes?>filename
        pari_catch_sig_on()
        cdef GEN _ret = gp_read_file(_filename)
        return pari_instance.new_gen(_ret)

    def readstr(self, filename=None):
        r"""
        Reads in the file :emphasis:`filename` and return a vector of GP strings,
        each component containing one line from the file. If :emphasis:`filename` is
        omitted, re-reads the last file that was fed into :literal:`gp`.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        cdef char* _filename
        if filename is None:
            _filename = ""
        else:
            filename = bytes(filename)
            _filename = <bytes?>filename
        pari_catch_sig_on()
        cdef GEN _ret = readstr(_filename)
        return pari_instance.new_gen(_ret)

    def readvec(self, filename=None):
        r"""
        Reads in the file
        :emphasis:`filename` (subject to string expansion). If :emphasis:`filename` is
        omitted, re-reads the last file that was fed into :literal:`gp`. The return
        value is a vector whose components are the evaluation of all sequences
        of instructions contained in the file. For instance, if :emphasis:`file` contains
        
        ::
        
            1
            2
            3
        
        then we will get:
        
        ::
        
            ? \r a
            %1 = 1
            %2 = 2
            %3 = 3
            ? read(a)
            %4 = 3
            ? readvec(a)
            %5 = [1, 2, 3]
        
        In general a sequence is just a single line, but as usual braces and
        :literal:`\\` may be used to enter multiline sequences.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        cdef char* _filename
        if filename is None:
            _filename = ""
        else:
            filename = bytes(filename)
            _filename = <bytes?>filename
        pari_catch_sig_on()
        cdef GEN _ret = gp_readvec_file(_filename)
        return pari_instance.new_gen(_ret)

    def stirling(self, long n, long k, long flag=1):
        r"""
        Stirling number of the first kind :math:`s(n,k)` (:math:`flag = 1`, default) or
        of the second kind :math:`S(n,k)` (:emphasis:`flag` = 2), where :math:`n`, :math:`k` are non-negative
        integers. The former is :math:`(-1)^{n-k}` times the
        number of permutations of :math:`n` symbols with exactly :math:`k` cycles; the latter is
        the number of ways of partitioning a set of :math:`n` elements into :math:`k` non-empty
        subsets. Note that if all :math:`s(n,k)` are needed, it is much faster to compute
        
        .. MATH::
        
            \sum_k s(n,k) x^k = x(x-1)...(x-n+1).
        
        Similarly, if a large number of :math:`S(n,k)` are needed for the same :math:`k`,
        one should use
        
        .. MATH::
        
            \sum_n S(n,k) x^n = (x^k)/((1-x)...(1-kx)).
        
        (Should be implemented using a divide and conquer product.) Here are
        simple variants for :math:`n` fixed:
        
        ::
        
            /* list of s(n,k), k = 1..n */
            vecstirling(n) = Vec( factorback(vector(n-1,i,1-i*'x)) )
            
            /* list of S(n,k), k = 1..n */
            vecstirling2(n) =
            { my(Q = x^(n-1), t);
             vector(n, i, t = divrem(Q, x-i); Q=t[1]; simplify(t[2]));
            }
        """
        cdef PariInstance pari_instance = <PariInstance>self
        pari_catch_sig_on()
        cdef GEN _ret = stirling(n, k, flag)
        return pari_instance.new_gen(_ret)

    def system(self, str):
        r"""
        :emphasis:`str` is a string representing a system command. This command is
        executed, its output written to the standard output (this won't get into your
        logfile), and control returns to the PARI system. This simply calls the C
        :literal:`system` command.
        """
        cdef PariInstance pari_instance = <PariInstance>self
        str = str(str)
        cdef char* _str = <bytes?>str
        pari_catch_sig_on()
        gpsystem(_str)
        pari_instance.clear_stack()

    def varhigher(self, name, v=None):
        r"""
        Return a variable :emphasis:`name` whose priority is higher
        than the priority of :math:`v` (of all existing variables if :math:`v` is omitted).
        This is a counterpart to :literal:`varlower`.
        
        ::
        
            ? Pol([x,x], t)
             *** at top-level: Pol([x,x],t)
             *** ^------------
             *** Pol: incorrect priority in gtopoly: variable x <= t
            ? t = varhigher("t", x);
            ? Pol([x,x], t)
            %3 = x*t + x
        
        This routine is useful since new GP variables directly
        created by the interpreter always have lower priority than existing
        GP variables. When some basic objects already exist in a variable
        that is incompatible with some function requirement, you can now
        create a new variable with a suitable priority instead of changing variables
        in existing objects:
        
        ::
        
            ? K = nfinit(x^2+1);
            ? rnfequation(K,y^2-2)
             *** at top-level: rnfequation(K,y^2-2)
             *** ^--------------------
             *** rnfequation: incorrect priority in rnfequation: variable y >= x
            ? y = varhigher("y", x);
            ? rnfequation(K, y^2-2)
            %3 = y^4 - 2*y^2 + 9
        
        :strong:`Caution 1.`
        The :emphasis:`name` is an arbitrary character string, only used for display
        purposes and need not be related to the GP variable holding the result, nor
        to be a valid variable name. In particular the :emphasis:`name` can
        not be used to retrieve the variable, it is not even present in the parser's
        hash tables.
        
        ::
        
            ? x = varhigher("#");
            ? x^2
            %2 = #^2
        
        :strong:`Caution 2.` There are a limited number of variables and if no
        existing variable with the given display name has the requested
        priority, the call to :literal:`varhigher` uses up one such slot. Do not create
        new variables in this way unless it's absolutely necessary,
        reuse existing names instead and choose sensible priority requirements:
        if you only need a variable with higher priority than :math:`x`, state so
        rather than creating a new variable with highest priority.
        
        ::
        
            \\ quickly use up all variables
            ? n = 0; while(1,varhigher("tmp"); n++)
             *** at top-level: n=0;while(1,varhigher("tmp");n++)
             *** ^-------------------
             *** varhigher: no more variables available.
             *** Break loop: type 'break' to go back to GP prompt
            break> n
            65510
            \\ infinite loop: here we reuse the same 'tmp'
            ? n = 0; while(1,varhigher("tmp", x); n++)
        """
        cdef PariInstance pari_instance = <PariInstance>self
        name = str(name)
        cdef char* _name = <bytes?>name
        cdef long _v = -1
        if v is not None:
            _v = pari_instance.get_var(v)
        pari_catch_sig_on()
        cdef GEN _ret = varhigher(_name, _v)
        return pari_instance.new_gen(_ret)

    def varlower(self, name, v=None):
        r"""
        Return a variable :emphasis:`name` whose priority is lower
        than the priority of :math:`v` (of all existing variables if :math:`v` is omitted).
        This is a counterpart to :literal:`varhigher`.
        
        New GP variables directly created by the interpreter always
        have lower priority than existing GP variables, but it is not easy
        to check whether an identifier is currently unused, so that the
        corresponding variable has the expected priority when it's created!
        Thus, depending on the session history, the same command may fail or succeed:
        
        ::
        
            ? t; z; \\ now t > z
            ? rnfequation(t^2+1,z^2-t)
             *** at top-level: rnfequation(t^2+1,z^
             *** ^--------------------
             *** rnfequation: incorrect priority in rnfequation: variable t >= t
        
        Restart and retry:
        
        ::
        
            ? z; t; \\ now z > t
            ? rnfequation(t^2+1,z^2-t)
            %2 = z^4 + 1
        
        It is quite annoying for package authors, when trying to
        define a base ring, to notice that the package may fail for some users
        depending on their session history. The safe way to do this is as follows:
        
        ::
        
            ? z; t; \\ In new session: now z > t
            ...
            ? t = varlower("t", 'z);
            ? rnfequation(t^2+1,z^2-2)
            %2 = z^4 - 2*z^2 + 9
            ? variable()
            %3 = [x, y, z, t]
        
        ::
        
            ? t; z; \\ In new session: now t > z
            ...
            ? t = varlower("t", 'z); \\ create a new variable, still printed "t"
            ? rnfequation(t^2+1,z^2-2)
            %2 = z^4 - 2*z^2 + 9
            ? variable()
            %3 = [x, y, t, z, t]
        
        Now both constructions succeed. Note that in the
        first case, :literal:`varlower` is essentially a no-op, the existing variable :math:`t`
        has correct priority. While in the second case, two different variables are
        displayed as :literal:`t`, one with higher priority than :math:`z` (created in the first
        line) and another one with lower priority (created by :literal:`varlower`).
        
        :strong:`Caution 1.`
        The :emphasis:`name` is an arbitrary character string, only used for display
        purposes and need not be related to the GP variable holding the result, nor
        to be a valid variable name. In particular the :emphasis:`name` can
        not be used to retrieve the variable, it is not even present in the parser's
        hash tables.
        
        ::
        
            ? x = varlower("#");
            ? x^2
            %2 = #^2
        
        :strong:`Caution 2.` There are a limited number of variables and if no
        existing variable with the given display name has the requested
        priority, the call to :literal:`varlower` uses up one such slot. Do not create
        new variables in this way unless it's absolutely necessary,
        reuse existing names instead and choose sensible priority requirements:
        if you only need a variable with higher priority than :math:`x`, state so
        rather than creating a new variable with highest priority.
        
        ::
        
            \\ quickly use up all variables
            ? n = 0; while(1,varlower("x"); n++)
             *** at top-level: n=0;while(1,varlower("x");n++)
             *** ^-------------------
             *** varlower: no more variables available.
             *** Break loop: type 'break' to go back to GP prompt
            break> n
            65510
            \\ infinite loop: here we reuse the same 'tmp'
            ? n = 0; while(1,varlower("tmp", x); n++)
        """
        cdef PariInstance pari_instance = <PariInstance>self
        name = str(name)
        cdef char* _name = <bytes?>name
        cdef long _v = -1
        if v is not None:
            _v = pari_instance.get_var(v)
        pari_catch_sig_on()
        cdef GEN _ret = varlower(_name, _v)
        return pari_instance.new_gen(_ret)

    def version(self):
        r"""
        Returns the current version number as a :literal:`t_VEC` with three integer
        components (major version number, minor version number and patchlevel);
        if your sources were obtained through our version control system, this will
        be followed by further more precise arguments, including
        e.g. a :literal:`git` :emphasis:`commit hash`.
        
        This function is present in all versions of PARI following releases 2.3.4
        (stable) and 2.4.3 (testing).
        
        Unless you are working with multiple development versions, you probably only
        care about the 3 first numeric components. In any case, the :literal:`lex` function
        offers a clever way to check against a particular version number, since it will
        compare each successive vector entry, numerically or as strings, and will not
        mind if the vectors it compares have different lengths:
        
        ::
        
             if (lex(version(), [2,3,5]) >= 0,
             \\ code to be executed if we are running 2.3.5 or more recent.
             ,
             \\ compatibility code
             );
        
        On a number of different machines, :literal:`version()` could return either of
        
        ::
        
             %1 = [2, 3, 4] \\ released version, stable branch
             %1 = [2, 4, 3] \\ released version, testing branch
             %1 = [2, 6, 1, 15174, ""505ab9b"] \\ development
        
        In particular, if you are only working with released versions, the first
        line of the gp introductory message can be emulated by
        
        ::
        
             [M,m,p] = version();
             printf("GP/PARI CALCULATOR Version %s.%s.%s", M,m,p);
        
        If you :emphasis:`are` working with many development versions of
        PARI/GP, the 4th and/or 5th components can be profitably included in the
        name of your logfiles, for instance.
        
        :strong:`Technical note.` For development versions obtained via :literal:`git`,
        the 4th and 5th components are liable to change eventually, but we document
        their current meaning for completeness. The 4th component counts the number
        of reachable commits in the branch (analogous to :literal:`svn`'s revision
        number), and the 5th is the :literal:`git` commit hash. In particular, :literal:`lex`
        comparison still orders correctly development versions with respect to each
        others or to released versions (provided we stay within a given branch,
        e.g. :literal:`master`)!
        """
        cdef PariInstance pari_instance = <PariInstance>self
        pari_catch_sig_on()
        cdef GEN _ret = pari_version()
        return pari_instance.new_gen(_ret)

