Tutorial

Start by importing the contents of the package with:

>>> from gmpy2 import *

Note

The use of from gmpy2 import * is not recommended in real code. The names in gmpy2 have been chosen to avoid conflict with Python’s builtin names but gmpy2 does use names that may conflict with other modules or variable names. In normal usage you’ll probably only want to import the classes and functions that you actually need.

Lets look first on some examples of arbitrary precision arithmetic with integer and rational types:

>>> mpz(99) * 43
mpz(4257)
>>> pow(mpz(99), 37, 59)
mpz(18)
>>> isqrt(99)
mpz(9)
>>> isqrt_rem(99)
(mpz(9), mpz(18))
>>> gcd(123, 27)
mpz(3)
>>> 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')
>>> mpz('123') + 1
mpz(124)
>>> 10 - mpz(1)
mpz(9)
>>> is_prime(17)
True
>>> mpz('1_000_000')
mpz(1000000)
>>> mpq(3, 7)/7
mpq(3,49)
>>> mpq(45, 3) * mpq(11, 8)
mpq(165,8)
>>> mpq(1, 7) * 11
mpq(11,7)

But gmpy2 also supports correctly rounded multiple precision real and complex arithmetic. The following example shows how to control precision settings and rounding modes:

>>> mpfr('1.2')
mpfr('1.2')
>>> mpfr(float('1.2'))
mpfr('1.2')
>>> ctx = get_context()
>>> ctx.precision
53
>>> ctx.precision = 100
>>> mpfr('1.2')
mpfr('1.2000000000000000000000000000006',100)
>>> mpfr(float('1.2'))
mpfr('1.1999999999999999555910790149937',100)
>>> ctx.precision = 53
>>> ctx.round = RoundUp
>>> const_pi()
mpfr('3.1415926535897936')
>>> ctx.round = RoundToNearest
>>> const_pi()
mpfr('3.1415926535897931')

You have seen, that if the precision is changed, then mpfr(float('1.2')) differs from mpfr('1.2'). To take advantage of the higher precision provided by the mpfr type, always pass constants as strings.

Floating point contexts also are used to control exceptional conditions. For example, division by zero can either return a floating-point positive infinity (default) or raise an exception.

>>> ctx.divzero
False
>>> mpfr(1)/0
mpfr('inf')
>>> ctx.trap_divzero = True
>>> mpfr(1)/0
Traceback (most recent call last):
...
gmpy2.DivisionByZeroError: division by zero
>>> ctx.divzero
True

Exceptions are normally raised in Python when the result of a real operation is not defined over the reals; for example, math.sqrt(-2) will raise a ValueError exception. The default context in gmpy2 implements similar behavior, but by setting allow_complex flag, complex results will be returned.

>>> sqrt(mpfr(-2))
mpfr('nan')
>>> ctx.allow_complex = True
>>> sqrt(mpfr(-2))
mpc('0.0+1.4142135623730951j')

Contexts can also be used in conjunction with Python’s with statement to temporarily change the context settings for a block of code.

>>> with local_context() as ctx:
...   print(const_pi())
...   ctx.precision += 20
...   print(const_pi())
...
3.1415926535897931
3.1415926535897932384628
>>> print(const_pi())
3.1415926535897931

It’s possible to set different precision settings for real and imaginary components.

>>> ctx = get_context()
>>> ctx.real_prec = 60
>>> ctx.imag_prec = 70
>>> sqrt(mpc('1+2j'))
mpc('1.272019649514068965+0.78615137775742328606947j',(60,70))

All gmpy2 numeric types support Python’s “new style” string formatting available in formatted string literals or with str.format(); see Format Specification Mini-Language for a description of the standard formatting syntax. The precision value optionally can be followed by the rounding mode type (‘U’ to round toward plus infinity, ‘D’ to round toward minus infinity, ‘Y’ to round away from zero, ‘Z’ to round toward zero and ‘N’ - round to the nearest value.

>>> a = mpfr("1.23456")
>>> "{0:15.3f}".format(a)
'          1.235'
>>> "{0:15.3Uf}".format(a)
'          1.235'
>>> "{0:15.3Df}".format(a)
'          1.234'
>>> "{0:.3Df}".format(a)
'1.234'
>>> "{0:+.3Df}".format(a)
'+1.234'