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_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.
- 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
andbytearray
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_power() bool
Return
True
if x is a perfect power (there exists a y and an n > 1, such that x=y**n), else returnFalse
.
- is_prime(n=25, /) bool
Return
True
if x is _probably_ prime, elseFalse
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.
- 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, anOverflowError
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.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_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.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.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 returnFalse
.
- 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 returnFalse
.
- gmpy2.is_prime(x, n=25, /) bool
Return
True
if x is _probably_ prime, elseFalse
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.isqrt_rem(x, /)
Return a 2-element tuple (s,t) such that s=isqrt(x) and t=x-s*s. x >=0.
- 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.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 tompz
.
- 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.