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'