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