Overview of gmpy2

Tutorial

The mpz type is compatible with Python’s built-in int type but is significantly faster for large values. The cutover point for performance varies, but can be as low as 20 to 40 digits. A variety of additional integer functions are provided.

Operator overloading is fully supported. Coversion from native Python types is optimized for performance.

>>> import gmpy2
>>> from gmpy2 import mpz,mpq,mpfr,mpc
>>> gmpy2.set_context(gmpy2.context())
>>> mpz(99) * 43
mpz(4257)
>>> pow(mpz(99), 37, 59)
mpz(18)
>>> gmpy2.isqrt(99)
mpz(9)
>>> gmpy2.isqrt_rem(99)
(mpz(9), mpz(18))
>>> gmpy2.gcd(123,27)
mpz(3)
>>> gmpy2.lcm(123,27)
mpz(1107)
>>> (mpz(123) + 12) / 5
mpfr('27.0')
>>> (mpz(123) + 12) // 5
mpz(27)
>>> (mpz(123) + 12) / 5.0
mpfr('27.0')

The mpq type is compatible with the Fraction type included with Python.

>>> mpq(3,7)/7
mpq(3,49)
>>> mpq(45,3) * mpq(11,8)
mpq(165,8)

gmpy2 supports correctly rounded arbitrary precision real and complex arithmetic via the MPFR and MPC libraries. Floating point contexts are used to control precision, rounding modes, and exceptional conditions. For example, division by zero can either return an Infinity or raise an exception.

>>> gmpy2.set_context(gmpy2.context())
>>> mpfr(1)/7
mpfr('0.14285714285714285')
>>> gmpy2.get_context().precision=200
>>> mpfr(1)/7
mpfr('0.1428571428571428571428571428571428571428571428571428571428571',200)
>>> gmpy2.get_context()
context(precision=200, real_prec=Default, imag_prec=Default,
        round=RoundToNearest, real_round=Default, imag_round=Default,
        emax=1073741823, emin=-1073741823,
        subnormalize=False,
        trap_underflow=False, underflow=False,
        trap_overflow=False, overflow=False,
        trap_inexact=False, inexact=True,
        trap_invalid=False, invalid=False,
        trap_erange=False, erange=False,
        trap_divzero=False, divzero=False,
        allow_complex=False,
        rational_division=False,
        allow_release_gil=False)
>>> mpfr(1)/0
mpfr('inf')
>>> gmpy2.get_context().trap_divzero=True
>>> mpfr(1)/0  
Traceback (most recent call last):
...
gmpy2.DivisionByZeroError: division by zero
>>> gmpy2.get_context()
context(precision=200, real_prec=Default, imag_prec=Default,
        round=RoundToNearest, real_round=Default, imag_round=Default,
        emax=1073741823, emin=-1073741823,
        subnormalize=False,
        trap_underflow=False, underflow=False,
        trap_overflow=False, overflow=False,
        trap_inexact=False, inexact=True,
        trap_invalid=False, invalid=False,
        trap_erange=False, erange=False,
        trap_divzero=True, divzero=True,
        allow_complex=False,
        rational_division=False,
        allow_release_gil=False)
>>> gmpy2.sqrt(mpfr(-2))
mpfr('nan')
>>> gmpy2.get_context().allow_complex=True
>>> gmpy2.get_context().precision=53
>>> gmpy2.sqrt(mpfr(-2))
mpc('0.0+1.4142135623730951j')
>>>
>>> gmpy2.set_context(gmpy2.context())
>>> with gmpy2.local_context() as ctx:
...   print(gmpy2.const_pi())
...   ctx.precision+=20
...   print(gmpy2.const_pi())
...   ctx.precision+=20
...   print(gmpy2.const_pi())
...
3.1415926535897931
3.1415926535897932384628
3.1415926535897932384626433831
>>> print(gmpy2.const_pi())
3.1415926535897931

Miscellaneous gmpy2 Functions

gmpy2.digits(x, base=10, prec=0, /) str

Return string representing a number x.

gmpy2.from_binary(bytes, /) mpz | xmpz | mpq | mpfr | mpc

Return a Python object from a byte sequence created by to_binary().

gmpy2.license() str

Return string giving license information.

gmpy2.mp_limbsize() int

Return the number of bits per limb.

gmpy2.mp_version() str

Return string giving current GMP version.

gmpy2.mpc_version() str

Return string giving current MPC version.

gmpy2.mpfr_version() str

Return string giving current MPFR version.

gmpy2.random_state(seed=0, /) object

Return new object containing state information for the random number generator. An optional integer can be specified as the seed value.

gmpy2.to_binary(x, /) bytes

Return a Python byte sequence that is a portable binary representation of a gmpy2 object x. The byte sequence can be passed to from_binary() to obtain an exact copy of x’s value. Raises a TypeError if x is not a gmpy2 object.

gmpy2.version() str

Return string giving current GMPY2 version.

Generic gmpy2 Functions

gmpy2.add(x, y, /) mpz | mpq | mpfr | mpc

Return x + y.

gmpy2.div(x, y, /) mpz | mpq | mpfr | mpc

Return x / y; uses true division.

gmpy2.mul(x, y, /) mpz | mpq | mpfr | mpc

Return x * y.

gmpy2.sub(x, y, /) mpz | mpq | mpfr | mpc

Return x - y.

gmpy2.square(x, /) mpz | mpq | mpfr | mpc

Return x * x.

gmpy2.f2q(x, err=0, /) mpz | mpq

Return the ‘best’ mpq approximating x to within relative error err. Default is the precision of x. Uses Stern-Brocot tree to find the ‘best’ approximation. An mpz object is returned if the denominator is 1. If err<0, relative error is 2.0 ** err.

gmpy2.fma(x, y, z, /) mpz | mpq | mpfr | mpc

Return correctly rounded result of (x * y) + z.

gmpy2.fms(x, y, z, /) mpz | mpq | mpfr | mpc

Return correctly rounded result of (x * y) - z.

gmpy2.cmp_abs(x, y, /) int

Return -1 if abs(x) < abs(y); 0 if abs(x) = abs(y); or 1 else.

Exceptions

exception gmpy2.RangeError
exception gmpy2.InexactResultError
exception gmpy2.OverflowResultError
exception gmpy2.UnderflowResultError
exception gmpy2.InvalidOperationError
exception gmpy2.DivisionByZeroError