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

optional leading sign code:

‘+’ -> 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, /) → int | None: 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, /) → int | None: 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) → bytes

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.

gmpy2.bit_mask(n, /) → mpz: Return an mpz exactly n bits in length with all bits set.

gmpy2.bit_scan0(x, n=0, /) → int | None: 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, /) → int | None: 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.