# 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, /)

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

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, /)

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, /)

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

Return x + y.

gmpy2.div(x, y, /)

Return x / y; uses true division.

gmpy2.mul(x, y, /)

Return x * y.

gmpy2.sub(x, y, /)

Return x - y.

gmpy2.square(x, /)

Return x * x.

gmpy2.f2q(x, err=0, /)

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, /)

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

gmpy2.fms(x, y, z, /)

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