# Multiple-precision Integers

The gmpy2 `mpz` type supports arbitrary precision integers. It should be a drop-in replacement for Python’s `int` type. Depending on the platform and the specific operation, an `mpz` will be faster than Python’s `int` once the precision exceeds 20 to 50 digits. All the special integer functions in GMP are supported.

## Examples

```>>> from gmpy2 import is_prime, mpz
>>> mpz('123') + 1
mpz(124)
>>> 10 - mpz(1)
mpz(9)
>>> is_prime(17)
True
>>> mpz('1_2')
mpz(12)
```

Note

The use of `from gmpy2 import *` is not recommended. 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.

Note

`mpz` ignores all embedded underscore characters. It does not attempt to be 100% compatible with all Python exceptions.

## mpz type

class gmpy2.mpz(n=0, /)
class gmpy2.mpz(s, /, base=0)

Return an immutable integer constructed from a numeric value n (truncating n to its integer part) or a string s made of digits in the given base. Every input, that is accepted by the `int` type constructor is also accepted.

The base may vary from 2 to 62, or if base is 0, then binary, octal, or hexadecimal strings are recognized by leading ‘0b’, ‘0o’, or ‘0x’ characters (case is ignored), otherwise the string is assumed to be decimal. For bases up to 36, digits case is ignored. For bases 37 to 62, upper-case letter represent the usual 10..35 range, while lower-case letter represent 36..61. Optionally the string can be preceded by ‘+’ or ‘-’. White space and underscore is simply ignored.

__format__(fmt) str

Return a Python string by formatting `mpz` ‘x’ using the format string ‘fmt’. A valid format string consists of:

optional alignment code:

‘<’ -> left shifted in field ‘>’ -> right shifted in field ‘^’ -> centered in field

‘+’ -> always display leading sign ‘-’ -> only display minus sign ‘ ‘ -> minus for negative values, space for positive values

optional base indicator

‘#’ -> precede binary, octal, or hex with 0b, 0o or 0x

optional width

optional conversion code:

‘d’ -> decimal format ‘b’ -> binary format ‘o’ -> octal format ‘x’ -> hex format ‘X’ -> upper-case hex format

The default format is ‘d’.

as_integer_ratio() tuple[mpz, mpz]

Return a pair of integers, whose ratio is exactly equal to the original number. The ratio is in lowest terms and has a positive denominator.

bit_clear(n, /) mpz

Return a copy of x with the n-th bit cleared.

bit_count() int

Return the number of 1-bits set in abs(x).

bit_flip(n, /) mpz

Return a copy of x with the n-th bit inverted.

bit_length() int

Return the number of significant bits in the radix-2 representation of x. Note: mpz(0).bit_length() returns 0.

bit_scan0(n=0, /)

Return the index of the first 0-bit of x with index >= n. n >= 0. If there are no more 0-bits in x at or above index n (which can only happen for x<0, assuming an infinitely long 2’s complement format), then `None` is returned.

bit_scan1(n=0, /)

Return the index of the first 1-bit of x with index >= n. n >= 0. If there are no more 1-bits in x at or above index n (which can only happen for x>=0, assuming an infinitely long 2’s complement format), then `None` is returned.

bit_set(n, /) mpz

Return a copy of x with the n-th bit set.

bit_test(n, /) bool

Return the value of the n-th bit of x.

conjugate() mpz

Return the conjugate of x (which is just a new reference to x since x is not a complex number).

digits(base=10, /) str

Return Python string representing x in the given base. Values for base can range between 2 to 62. A leading ‘-’ is present if x<0 but no leading ‘+’ is present if x>=0.

from_bytes(bytes, byteorder='big', *, signed=False) mpz

Return the integer represented by the given array of bytes.

bytes

Holds the array of bytes to convert. The argument must either support the buffer protocol or be an iterable object producing bytes. `bytes` and `bytearray` are examples of built-in objects that support the buffer protocol.

byteorder

The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder` as the byte order value.

signed

Indicates whether two’s complement is used to represent the integer.

is_congruent(y, m, /) bool

Returns `True` if x is congruent to y modulo m, else return `False`.

is_divisible(d, /) bool

Returns `True` if x is divisible by d, else return `False`.

is_even() bool

Return `True` if x is even, `False` otherwise.

is_odd() bool

Return `True` if x is odd, `False` otherwise.

is_power() bool

Return `True` if x is a perfect power (there exists a y and an n > 1, such that x=y**n), else return `False`.

is_prime(n=25, /) bool

Return `True` if x is _probably_ prime, else `False` if x is definitely composite. x is checked for small divisors and up to n Miller-Rabin tests are performed.

is_probab_prime(n=25, /) int

Return 2 if x is definitely prime, 1 if x is probably prime, or return 0 if x is definitely non-prime. x is checked for small divisors and up to n Miller-Rabin tests are performed. Reasonable values of n are between 15 and 50.

is_square() bool

Returns `True` if x is a perfect square, else return `False`.

num_digits(base=10, /) int

Return length of string representing the absolute value of x in the given base. Values for base can range between 2 and 62. The value returned may be 1 too large.

to_bytes(length=1, byteorder='big', *, signed=False)

Return an array of bytes representing an integer.

length

Length of bytes object to use. An `OverflowError` is raised if the integer is not representable with the given number of bytes.

byteorder

The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder` as the byte order value.

signed

Determines whether two’s complement is used to represent the integer. If signed is `False` and a negative integer is given, an `OverflowError` is raised.

denominator

the denominator of a rational number in lowest terms

imag

the imaginary part of a complex number

numerator

the numerator of a rational number in lowest terms

real

the real part of a complex number

## mpz Functions

gmpy2.bincoef(n, k, /) mpz

Return the binomial coefficient (‘n choose k’). k >= 0.

gmpy2.bit_clear(x, n, /) mpz

Return a copy of x with the n-th bit cleared.

gmpy2.bit_count(x, /) int

Return the number of 1-bits set in abs(x).

gmpy2.bit_flip(x, n, /) mpz

Return a copy of x with the n-th bit inverted.

gmpy2.bit_length(x, /) int

Return the number of significant bits in the radix-2 representation of x. Note: bit_length(0) returns 0.

Return an `mpz` exactly n bits in length with all bits set.

gmpy2.bit_scan0(x, n=0, /)

Return the index of the first 0-bit of x with index >= n. n >= 0. If there are no more 0-bits in x at or above index n (which can only happen for x<0, assuming an infinitely long 2’s complement format), then `None` is returned.

gmpy2.bit_scan1(x, n=0, /)

Return the index of the first 1-bit of x with index >= n. n >= 0. If there are no more 1-bits in x at or above index n (which can only happen for x>=0, assuming an infinitely long 2’s complement format), then `None` is returned.

gmpy2.bit_set(x, n, /) mpz

Return a copy of x with the n-th bit set.

gmpy2.bit_test(x, n, /) bool

Return the value of the n-th bit of x.

gmpy2.c_div(x, y, /) mpz

Return the quotient of x divided by y. The quotient is rounded towards +Inf (ceiling rounding). x and y must be integers.

gmpy2.c_div_2exp(x, n, /) mpz

Returns the quotient of x divided by 2**n. The quotient is rounded towards +Inf (ceiling rounding). x must be an integer. n must be >0.

gmpy2.c_divmod(x, y, /) tuple[mpz, mpz]

Return the quotient and remainder of x divided by y. The quotient is rounded towards +Inf (ceiling rounding) and the remainder will have the opposite sign of y. x and y must be integers.

gmpy2.c_divmod_2exp(x, n, /) tuple[mpz, mpz]

Return the quotient and remainder of x divided by 2**n. The quotient is rounded towards +Inf (ceiling rounding) and the remainder will be negative. x must be an integer. n must be >0.

gmpy2.c_mod(x, y, /) mpz

Return the remainder of x divided by y. The remainder will have the opposite sign of y. x and y must be integers.

gmpy2.c_mod_2exp(x, n, /) mpz

Return the remainder of x divided by 2**n. The remainder will be negative. x must be an integer. n must be >0.

gmpy2.comb(n, k, /) mpz

Return the number of combinations of ‘n things, taking k at a time’. k >= 0. Same as bincoef(n, k)

gmpy2.divexact(x, y, /) mpz

Return the quotient of x divided by y. Faster than standard division but requires the remainder is zero!

gmpy2.divm(a, b, m, /) mpz

Return x such that b*x == a mod m. Raises a `ZeroDivisionError` exception if no such value x exists.

gmpy2.double_fac(n, /) mpz

Return the exact double factorial (n!!) of n. The double factorial is defined as n*(n-2)*(n-4)…

gmpy2.f_div(x, y, /) mpz

Return the quotient of x divided by y. The quotient is rounded towards -Inf (floor rounding). x and y must be integers.

gmpy2.f_div_2exp(x, n, /) mpz

Return the quotient of x divided by 2**n. The quotient is rounded towards -Inf (floor rounding). x must be an integer. n must be >0.

gmpy2.f_divmod(x, y, /) tuple[mpz, mpz]

Return the quotient and remainder of x divided by y. The quotient is rounded towards -Inf (floor rounding) and the remainder will have the same sign as y. x and y must be integers.

gmpy2.f_divmod_2exp(x, n, /) tuple[mpz, mpz]

Return quotient and remainder after dividing x by 2**n. The quotient is rounded towards -Inf (floor rounding) and the remainder will be positive. x must be an integer. n must be >0.

gmpy2.f_mod(x, y, /) mpz

Return the remainder of x divided by y. The remainder will have the same sign as y. x and y must be integers.

gmpy2.f_mod_2exp(x, n, /) mpz

Return remainder of x divided by 2**n. The remainder will be positive. x must be an integer. n must be >0.

gmpy2.fac(n, /) mpz

Return the exact factorial of n.

See factorial(n) to get the floating-point approximation.

gmpy2.fib(n, /) mpz

Return the n-th Fibonacci number.

gmpy2.fib2(n, /) tuple[mpz, mpz]

Return a 2-tuple with the (n-1)-th and n-th Fibonacci numbers.

gmpy2.gcd(*integers, /) mpz

Return the greatest common divisor of integers.

gmpy2.gcdext(a, b, /) tuple[mpz, mpz, mpz]

Return a 3-element tuple (g,s,t) such that g == gcd(a,b) and g == a*s + b*t.

gmpy2.hamdist(x, y, /) int

Return the Hamming distance (number of bit-positions where the bits differ) between integers x and y.

gmpy2.invert(x, m, /) mpz

Return y such that x*y == 1 modulo m. Raises `ZeroDivisionError` if no inverse exists.

gmpy2.iroot(x, n, /) tuple[mpz, bool]

Return the integer n-th root of x and boolean value that is `True` iff the root is exact. x >= 0. n > 0.

gmpy2.iroot_rem(x, n, /) tuple[mpz, mpz]

Return a 2-element tuple (y,r), such that y is the integer n-th root of x and x=y**n + r. x >= 0. n > 0.

gmpy2.is_congruent(x, y, m, /) bool

Returns `True` if x is congruent to y modulo m, else return `False`.

gmpy2.is_divisible(x, d, /) bool

Returns `True` if x is divisible by d, else return `False`.

gmpy2.is_even(x, /) bool

Return `True` if x is even, `False` otherwise.

gmpy2.is_odd(x, /) bool

Return `True` if x is odd, `False` otherwise.

gmpy2.is_power(x, /) bool

Return `True` if x is a perfect power (there exists a y and an n > 1, such that x=y**n), else return `False`.

gmpy2.is_prime(x, n=25, /) bool

Return `True` if x is _probably_ prime, else `False` if x is definitely composite. x is checked for small divisors and up to n Miller-Rabin tests are performed.

gmpy2.is_probab_prime(x, n=25, /) int

Return 2 if x is definitely prime, 1 if x is probably prime, or return 0 if x is definitely non-prime. x is checked for small divisors and up to n Miller-Rabin tests are performed. Reasonable values of n are between 15 and 50.

gmpy2.is_square(x, /) bool

Returns `True` if x is a perfect square, else return `False`.

gmpy2.isqrt(x, /) mpz

Return the integer square root of a non-negative integer x.

gmpy2.isqrt_rem(x, /)

Return a 2-element tuple (s,t) such that s=isqrt(x) and t=x-s*s. x >=0.

gmpy2.jacobi(x, y, /) mpz

Return the Jacobi symbol (x|y). y must be odd and >0.

gmpy2.kronecker(x, y, /) mpz

Return the Kronecker-Jacobi symbol (x|y).

gmpy2.lcm(*integers, /) mpz

Return the lowest common multiple of integers.

gmpy2.legendre(x, y, /) mpz

Return the Legendre symbol (x|y). y is assumed to be an odd prime.

gmpy2.lucas(n, /) mpz

Return the n-th Lucas number.

gmpy2.lucas2(n, /) tuple[mpz, mpz]

Return a 2-tuple with the (n-1)-th and n-th Lucas numbers.

gmpy2.mpz_random(random_state, int, /) mpz

Return uniformly distributed random integer between 0 and n-1.

gmpy2.mpz_rrandomb(random_state, bit_count, /) mpz

Return a random integer between 0 and 2**bit_count-1 with long sequences of zeros and one in its binary representation.

gmpy2.mpz_urandomb(random_state, bit_count, /) mpz

Return uniformly distributed random integer between 0 and 2**bit_count-1.

gmpy2.multi_fac(n, m, /) mpz

Return the exact m-multi factorial of n. The m-multifactorial is defined as n*(n-m)*(n-2m)…

gmpy2.next_prime(x, /) mpz

Return the next probable prime number > x.

gmpy2.num_digits(x, base=10, /) int

Return length of string representing the absolute value of x in the given base. Values for base can range between 2 and 62. The value returned may be 1 too large.

gmpy2.popcount(x, /) int

Return the number of 1-bits set in x. If x<0, the number of 1-bits is infinite so -1 is returned in that case.

gmpy2.powmod(x, y, m, /) mpz

Return (x**y) mod m. Same as the three argument version of Python’s built-in `pow`, but converts all three arguments to `mpz`.

gmpy2.powmod_exp_list(base, exp_lst, mod, /) list[mpz, ...]

Returns list(powmod(base, i, mod) for i in exp_lst). Will always release the GIL. (Experimental in gmpy2 2.1.x).

gmpy2.powmod_base_list(base_lst, exp, mod, /) list[mpz, ...]

Returns list(powmod(i, exp, mod) for i in base_lst). Will always release the GIL. (Experimental in gmpy2 2.1.x).

gmpy2.powmod_sec(x, y, m, /) mpz

Return (x**y) mod m. Calculates x ** y (mod m) but using a constant time algorithm to reduce the risk of side channel attacks. y must be an integer >0. m must be an odd integer.

gmpy2.primorial(n, /) mpz

Return the product of all positive prime numbers less than or equal to n.

gmpy2.remove(x, f, /) tuple[mpz, mpz]

Return a 2-element tuple (y,m) such that x=y*(f**m) and f does not divide y. Remove the factor f from x as many times as possible. m is the multiplicity f in x. f > 1.

gmpy2.t_div(x, y, /) mpz

Return the quotient of x divided by y. The quotient is rounded towards 0. x and y must be integers.

gmpy2.t_div_2exp(x, n, /) mpz

Return the quotient of x divided by 2**n. The quotient is rounded towards zero (truncation). n must be >0.

gmpy2.t_divmod(x, y, /) tuple[mpz, mpz]

Return the quotient and remainder of x divided by y. The quotient is rounded towards zero (truncation) and the remainder will have the same sign as x. x and y must be integers.

gmpy2.t_divmod_2exp(x, n, /) tuple[mpz, mpz]

Return the quotient and remainder of x divided by 2**n. The quotient is rounded towards zero (truncation) and the remainder will have the same sign as x. x must be an integer. n must be >0.

gmpy2.t_mod(x, y, /) mpz

Return the remainder of x divided by y. The remainder will have the same sign as x. x and y must be integers.

gmpy2.t_mod_2exp(x, n, /) mpz

Return the remainder of x divided by 2**n. The remainder will have the same sign as x. x must be an integer. n must be >0.