GMPY2(3)

📦

version 2.2.1 · 7 versions

okay bestie, you're reading the GMPY2(3) manual — that's gmpy2, the iconic C-coded Python extension module that does multiple-precision arithmetic 💅✨. Let's get into it.

✨ NAME ✨

gmpy2 — gmpy2 Documentation 📖

okay so gmpy2 is a C-coded Python extension module that supports multiple-precision arithmetic. It is the successor to the original gmpy module (which only supported the GMP library). gmpy2 adds support for the MPFR (correctly rounded real floating-point arithmetic) and MPC (correctly rounded complex floating-point arithmetic) libraries. 💖

The following libraries are supported:

GMP for integer and rational arithmetic (https://gmplib.org) 🧮
MPFR (https://www.mpfr.org) 🦋
MPC (https://www.multiprecision.org/mpc/) 🌈
Generalized Lucas sequences and primality tests are based on the following code:
- mpz_lucas: https://sourceforge.net/projects/mpzlucas/
- mpz_prp: https://sourceforge.net/projects/mpzprp/

📚 CONTENTS 📚

🌈 Overview 🌈

The mpz and mpq types support arbitrary precision integers and rationals via the GMP library. These types should be drop-in replacements for Python's ints and Fractions, but are significantly faster for large values. The cutover point for performance varies, but can be as low as 20 to 40 digits. All the special integer functions in the GMP are supported.

Warning: gmpy2 can crash the Python interpreter in case of memory allocation failure. To mitigate this feature of memory management in the GMP library, you should estimate the size of all results and prevent calculations that can exaust available memory. 💀

The mpfr and mpc types provide support for correctly rounded multiple precision real and complex arithmetic via the MPFR and MPC libraries. The context type is used to control precision, rounding modes, and exceptional conditions. For example, division by zero can either return an Infinity or raise an exception. It is possible to specify different precision and rounding modes for both the real and imaginary components of an mpc. The default precision is 53 bits --- just same as for Python's float and complex types.

Operator overloading is fully supported. Coversion from native Python types is optimized for performance.

🛠 Installation 🛠

gmpy2 requires CPython 3.7 or above. Pre-compiled binary wheels are available on PyPI. You can install latest release with pip:

pip install gmpy2

or some specific version with:

pip install gmpy2==2.1.5

🧚 From Sources 🧚

If pre-compiled binary wheels aren't available for your platform, the pip will fallback to installation from sources. In this case you will need to have required libraries (GMP, MPFR and MPC) already installed on your system, along with the include files for those libraries. On Debian you can install them systed-wide with:

sudo apt install libgmp-dev libmpfr-dev libmpc-dev

Tip: On Windows we recommend using MSYS2 (https://www.msys2.org/) to build the gmpy2 from sources. To install required dependencies before, run:

pacman -S gcc gmp-devel mpfr-devel mpc-devel python-setuptools python-pip

If you are a developer or like to get the latest updates as they come, be sure to install from the git repository and include required extra dependencies, for example the optional "tests" list, which include packages required for testing:

git clone git://github.com/aleaxit/gmpy.git
cd gmpy
pip install -e .[tests]

Next you may want to run full set of unit tests to make sure everything works:

pytest test/

🎓 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 as context managers in conjunction with Python's with statement to temporarily change the current context settings for a block of code.

>>> print(const_pi())
3.1415926535897931
>>> with context(precision=100) as ctx:
...   print(const_pi())
...   ctx.precision += 20
...   print(const_pi())
...
3.1415926535897932384626433832793
3.1415926535897932384626433832795028847
>>> 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 (https://docs.python.org/3/tutorial/inputoutput.html#tut-f-strings) or with str.format(); see Format Specification Mini-Language (https://docs.python.org/3/library/string.html#formatspec) 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'

🔢 Integers 🔢

🧮 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.

classmethod 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.

__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

okay so you're formatting a number and you want it just so. Here's everything you can stack into that format string 💅

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'. periodt. ✨

as_integer_ratio() -> tuple[mpz <#gmpy2.mpz>, mpz <#gmpy2.mpz>] — hands you back a pair of integers whose ratio is exactly equal to the original number. 🫶 the ratio is in lowest terms and the denominator is positive, no exceptions.
bit_clear(n, /) -> mpz <#gmpy2.mpz> — returns a copy of x with the n-th bit cleared. bye bit 👋
bit_count() -> int — returns how many 1-bits are set in abs(x). it's counting the ones bb 🧮
bit_flip(n, /) -> mpz <#gmpy2.mpz> — returns a copy of x with the n-th bit inverted. 0 becomes 1, 1 becomes 0, iconic behaviour honestly.
bit_length() -> int — returns 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 — returns the index of the first 0-bit of x with index >= n. and n >= 0, always. 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 — returns 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. no bit found, no vibes.
bit_set(n, /) -> mpz <#gmpy2.mpz> — returns a copy of x with the n-th bit set. ✨
bit_test(n, /) -> bool — returns the value of the n-th bit of x. is it 0 or is it 1, we must know 🕵️
conjugate() -> mpz <#gmpy2.mpz> — returns the conjugate of x. and like… it's literally just a new reference to x, bestie, because x is not a complex number. there was never anything to conjugate. 💀
digits(base=10, /) -> str — returns a 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 '+' shows up if x>=0.
is_congruent(y, m, /) -> bool — returns True if x is congruent to y modulo m, else it returns False. 🔁
is_divisible(d, /) -> bool — returns True if x is divisible by d, else False. clean division only 💅
is_even() -> bool — True if x is even, False otherwise. 2️⃣
is_odd() -> bool — True if x is odd, False otherwise. 3️⃣
is_power() -> bool — returns True if x is a perfect power (meaning there exists a y and an n > 1 such that x=y**n), else False. ✨
is_prime(n=25, /) -> bool — returns True if x is probably prime, else False if x is definitely composite. x gets checked for small divisors and up to n Miller-Rabin tests are performed.
is_probab_prime(n=25, /) -> int — returns 2 if x is definitely prime, 1 if x is probably prime, or 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. so like… 15 to 50, not 4, not 9000.
is_square() -> bool — returns True if x is a perfect square, else False. 🟪
num_digits(base=10, /) -> int — returns the length of the string representing the absolute value of x in the given base. values for base can range between 2 and 62. ⚠️ heads up: the value returned may be 1 too large.
to_bytes(length=1, byteorder='big', *, signed=False) -> bytes — returns an array of bytes representing an integer. 🧱
- length — length of the 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. yeah, it's giving imaginary bestie 🦋
numerator — the numerator of a rational number in lowest terms.
real — the real part of a complex number. the down-to-earth one 🌸

✨ mpz Functions ✨

these are the module-level baddies 💅 same energy as the methods up there, except you pass x in yourself.

gmpy2.bincoef(n, k, /) -> mpz <#gmpy2.mpz> — returns the binomial coefficient ("n choose k"). k >= 0.
gmpy2.bit_clear(x, n, /) -> mpz <#gmpy2.mpz> — returns a copy of x with the n-th bit cleared.
gmpy2.bit_count(x, /) -> int — returns the number of 1-bits set in abs(x).
gmpy2.bit_flip(x, n, /) -> mpz <#gmpy2.mpz> — returns a copy of x with the n-th bit inverted.
gmpy2.bit_length(x, /) -> int — returns the number of significant bits in the radix-2 representation of x. 📌 note: bit_length(0) returns 0.
gmpy2.bit_mask(n, /) -> mpz <#gmpy2.mpz> — returns an mpz exactly n bits in length with all bits set. every single bit is on, we love a full house 👑
gmpy2.bit_scan0(x, n=0, /) -> int | None — returns 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 — returns 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 <#gmpy2.mpz> — returns a copy of x with the n-th bit set.
gmpy2.bit_test(x, n, /) -> bool — returns the value of the n-th bit of x.
gmpy2.c_div(x, y, /) -> mpz <#gmpy2.mpz> — returns 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 <#gmpy2.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 <#gmpy2.mpz>, mpz <#gmpy2.mpz>] — returns 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 <#gmpy2.mpz>, mpz <#gmpy2.mpz>] — returns 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 <#gmpy2.mpz> — returns 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 <#gmpy2.mpz> — returns 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 <#gmpy2.mpz> — returns the number of combinations of "n things, taking k at a time". k >= 0. same as bincoef(n, k). twins fr fr 👯
gmpy2.divexact(x, y, /) -> mpz <#gmpy2.mpz> — returns the quotient of x divided by y. faster than standard division but requires the remainder is zero! do not play with this one unless you're sure 🔥
gmpy2.divm(a, b, m, /) -> mpz <#gmpy2.mpz> — returns x such that b*x == a mod m. raises a ZeroDivisionError exception if no such value x exists. 😭
gmpy2.double_fac(n, /) -> mpz <#gmpy2.mpz> — returns the exact double factorial (n!!) of n. the double factorial is defined as n*(n-2)*(n-4)... so yeah, it skips every other one 💫
gmpy2.f_div(x, y, /) -> mpz <#gmpy2.mpz> — returns 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 <#gmpy2.mpz> — returns 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 <#gmpy2.mpz>, mpz <#gmpy2.mpz>] — returns 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 <#gmpy2.mpz>, mpz <#gmpy2.mpz>] — returns 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 <#gmpy2.mpz> — returns 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 <#gmpy2.mpz> — returns 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 <#gmpy2.mpz> — returns the exact factorial of n. 🎀 see factorial(n) to get the floating-point approximation.
gmpy2.fib(n, /) -> mpz <#gmpy2.mpz> — returns the n-th Fibonacci number. 🌈
gmpy2.fib2(n, /) -> tuple[mpz <#gmpy2.mpz>, mpz <#gmpy2.mpz>] — returns a 2-tuple with the (n-1)-th and n-th Fibonacci numbers. two for the price of one 🫶
gmpy2.gcd(*integers, /) -> mpz <#gmpy2.mpz> — returns the greatest common divisor of integers. the biggest thing they all agree on 💖
gmpy2.gcdext(a, b, /) -> tuple[mpz <#gmpy2.mpz>, mpz <#gmpy2.mpz>, mpz <#gmpy2.mpz>] — bestie, it gives you a 3-element tuple (g,s,t) where g == gcd(a,b) and g == a*s + b*t. fr fr 💖
gmpy2.hamdist(x, y, /) -> int — returns the Hamming distance (the number of bit-positions where the bits differ) between integers x and y. lowkey useful for error correction vibes 😭
gmpy2.invert(x, m, /) -> mpz <#gmpy2.mpz> — returns y such that x*y == 1 modulo m. Raises ZeroDivisionError if no inverse exists. no inverse? tragic 💀
gmpy2.iroot(x, n, /) -> tuple[mpz <#gmpy2.mpz>, bool] — returns the integer n-th root of x and a boolean that is True iff the root is exact. x >= 0. n > 0. slay ✨
gmpy2.iroot_rem(x, n, /) -> tuple[mpz <#gmpy2.mpz>, mpz <#gmpy2.mpz>] — returns 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 returns False. 💅
gmpy2.is_divisible(x, d, /) -> bool — returns True if x is divisible by d, else returns False. 🫶
gmpy2.is_even(x, /) -> bool — returns True if x is even, False otherwise. even? periodt 🌸
gmpy2.is_odd(x, /) -> bool — returns True if x is odd, False otherwise. odd one out energy 👑
gmpy2.is_power(x, /) -> bool — returns True if x is a perfect power (there exists a y and an n > 1, such that x=y**n), else returns False. 🔥
gmpy2.is_prime(x, n=25, /) -> bool — returns 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. probably prime? iykyk 🌈
gmpy2.is_probab_prime(x, n=25, /) -> int — returns 2 if x is definitely prime, 1 if x is probably prime, or 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. iconic ⭐
gmpy2.is_square(x, /) -> bool — returns True if x is a perfect square, else returns False. 💖
gmpy2.isqrt(x, /) -> mpz <#gmpy2.mpz> — returns the integer square root of a non-negative integer x. 🎀
gmpy2.isqrt_rem(x, /) — returns a 2-element tuple (s,t) such that s=isqrt(x) and t=x-s*s. x >=0. 🦋
gmpy2.jacobi(x, y, /) -> mpz <#gmpy2.mpz> — returns the Jacobi symbol (x|y). y must be odd and >0. 💜
gmpy2.kronecker(x, y, /) -> mpz <#gmpy2.mpz> — returns the Kronecker-Jacobi symbol (x|y). ✨
gmpy2.lcm(*integers, /) -> mpz <#gmpy2.mpz> — returns the lowest common multiple of integers. 🧚
gmpy2.legendre(x, y, /) -> mpz <#gmpy2.mpz> — returns the Legendre symbol (x|y). y is assumed to be an odd prime. 💅
gmpy2.lucas(n, /) -> mpz <#gmpy2.mpz> — returns the n-th Lucas number. 🌸
gmpy2.lucas2(n, /) -> tuple[mpz <#gmpy2.mpz>, mpz <#gmpy2.mpz>] — returns a 2-tuple with the (n-1)-th and n-th Lucas numbers. 🫶
gmpy2.mpz_random(random_state, int, /) -> mpz <#gmpy2.mpz> — returns uniformly distributed random integer between 0 and n-1. 🎀
gmpy2.mpz_rrandomb(random_state, bit_count, /) -> mpz <#gmpy2.mpz> — returns 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 <#gmpy2.mpz> — returns uniformly distributed random integer between 0 and 2**bit_count-1. 🔥
gmpy2.multi_fac(n, m, /) -> mpz <#gmpy2.mpz> — returns the exact m-multi factorial of n. The m-multifactorial is defined as n*(n-m)*(n-2m)... slay ✨
gmpy2.next_prime(x, /) -> mpz <#gmpy2.mpz> — returns the next probable prime number > x. 👑
gmpy2.num_digits(x, base=10, /) -> int — returns the length of the 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.pack(lst, n, /) -> mpz <#gmpy2.mpz> — packs a list of integers lst into a single mpz by concatenating each integer element of lst after padding to length n bits. Raises an error if any integer is negative or greater than n bits in length. 🎀
gmpy2.popcount(x, /) -> int — returns 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 <#gmpy2.mpz> — returns (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 <#gmpy2.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 <#gmpy2.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 <#gmpy2.mpz> — returns (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.prev_prime(x, /) -> mpz <#gmpy2.mpz> — returns the previous probable prime number < x. Only present when compiled with GMP 6.3.0 or later. 🌈
gmpy2.primorial(n, /) -> mpz <#gmpy2.mpz> — returns the product of all positive prime numbers less than or equal to n. 💖
gmpy2.remove(x, f, /) -> tuple[mpz <#gmpy2.mpz>, mpz <#gmpy2.mpz>] — returns 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 <#gmpy2.mpz> — returns 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 <#gmpy2.mpz> — returns 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 <#gmpy2.mpz>, mpz <#gmpy2.mpz>] — returns 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 <#gmpy2.mpz>, mpz <#gmpy2.mpz>] — returns 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 <#gmpy2.mpz> — returns 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 <#gmpy2.mpz> — returns 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. 🌸
gmpy2.unpack(x, n, /) -> list — unpacks an integer x into a list of n-bit values. Equivalent to repeated division by 2**n. Raises error if x is negative. 🫶

💖 Integers (Advanced topics) 💖

gmpy2 gives you access to an experimental integer type called xmpz. The xmpz type is a mutable integer type. In-place operations (+=, //=, etc.) modify the original object and do not create a new object. Instances of xmpz cannot be used as dictionary keys. no cap 💀

>>> from gmpy2 import xmpz
>>> a = xmpz(123)
>>> b = a
>>> a += 1
>>> a
xmpz(124)
>>> b
xmpz(124)

The ability to change an xmpz object in-place allows for efficient and rapid bit manipulation. it's giving speed ✨

Individual bits can be set or cleared:

>>> a[10]=1
>>> a
xmpz(1148)

Slice notation is supported. The bits referenced by a slice can be either 'read from' or 'written to'. To clear a slice of bits, use a source value of 0. In 2s-complement format, 0 is represented by an arbitrary number of 0-bits. To set a slice of bits, use a source value of ~0. The tilde operator inverts, or complements the bits in an integer. (~0 is -1 so you can also use -1.) In 2s-complement format, -1 is represented by an arbitrary number of 1-bits. 💅

If a value for stop is specified in a slice assignment and the actual bit-length of the xmpz is less than stop, then the destination xmpz is logically padded with 0-bits to length stop. 🎀

>>> a=xmpz(0)
>>> a[8:16] = ~0
>>> bin(a)
'0b1111111100000000'
>>> a[4:12] = ~a[4:12]
>>> bin(a)
'0b1111000011110000'

Bits can be reversed:

>>> a = xmpz(1148)
>>> bin(a)
'0b10001111100'
>>> a[::] = a[::-1]
>>> bin(a)
'0b111110001'

The iter_bits() method returns a generator that returns True or False for each bit position. The methods iter_clear(), and iter_set() return generators that return the bit positions that are 1 or 0. The methods support arguments start and stop that define the beginning and ending bit positions that are used. To mimic the behavior of slices. the bit positions checked include start but the last position checked is stop - 1. 🌈

>>> a=xmpz(117)
>>> bin(a)
'0b1110101'
>>> list(a.iter_bits())
[True, False, True, False, True, True, True]
>>> list(a.iter_clear())
[1, 3]
>>> list(a.iter_set())
[0, 2, 4, 5, 6]
>>> list(a.iter_bits(stop=12))
[True, False, True, False, True, True, True, False, False, False, False, False]

The following program uses the Sieve of Eratosthenes to generate a list of prime numbers.

import time
import gmpy2

def sieve(limit=1000000):
    '''Returns a generator that yields the prime numbers up to limit.'''

    # Increment by 1 to account for the fact that slices  do not include
    # the last index value but we do want to include the last value for
    # calculating a list of primes.
    sieve_limit = gmpy2.isqrt(limit) + 1
    limit += 1

    # Mark bit positions 0 and 1 as not prime.
    bitmap = gmpy2.xmpz(3)

    # Process 2 separately. This allows us to use p+p for the step size
    # when sieving the remaining primes.
    bitmap[4 : limit : 2] = -1

    # Sieve the remaining primes.
    for p in bitmap.iter_clear(3, sieve_limit):
        bitmap[p*p : limit : p+p] = -1

    return bitmap.iter_clear(2, limit)

if __name__ == "__main__":
    start = time.time()
    result = list(sieve())
    print(time.time() - start)
    print(len(result))

✨ The xmpz type ✨

class gmpy2.xmpz(n=0, /)

💖 `class gmpy2.xmpz(s, /, base=0)` 💖

okay bestie, meet xmpz — the integer with main character energy that you're actually allowed to mutate. 🦋

You build one from a numeric value n, or from a string s made of digits in the given base. And literally every input that the mpz type constructor accepts? xmpz accepts it too. no notes. ✨

Note: this type can be faster when you're using it for augmented assignment (+=, -=, etc.), but — and this is the tradeoff, bestie — xmpz objects cannot be used as dictionary keys. 💀

💅 `format(fmt) -> str`

Hands you back a Python string by formatting mpz 'x' using the format string 'fmt'. A valid format string is a little build-your-own situation, and it goes like this:

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'. periodt. 💅

🌸 `bit_clear(n, /) -> mpz`

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

🌸 `bit_count() -> int`

Return the number of 1-bits set in abs(x). It's literally counting your blessings (the blessings are ones). ✨

🌸 `bit_flip(n, /) -> mpz`

Return a copy of x with the n-th bit inverted. glow-up for one single bit. 🦋

🌸 `bit_length() -> int`

Return the number of significant bits in the radix-2 representation of x.

Note: mpz(0).bit_length() returns 0. yes bestie, zero has zero bits of significance, it's giving humble. 😭

🌸 `bit_scan0(n=0, /) -> int | None`

Return the index of the first 0-bit of x with index >= n. And n >= 0, okay?

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. it's giving "nothing to see here". 🙈

🌸 `bit_scan1(n=0, /) -> int | None`

Return the index of the first 1-bit of x with index >= n. n >= 0, always.

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. same energy, different bit. 🫶

🌸 `bit_set(n, /) -> mpz`

Return a copy of x with the n-th bit set. slay, that bit is ON. 🔥

🌸 `bit_test(n, /) -> bool`

Return the value of the n-th bit of x. is it set or is it not, we simply must know. 👑

🌸 `conjugate() -> mpz`

Return the conjugate of x — which is just a new reference to x, because x is not a complex number, bestie. it's giving "I'm my own conjugate". 💜

🌸 `copy() -> xmpz`

Return a copy of a x. 💕

🌸 `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. it's giving minimal, it's giving clean. ✨

🦋 `iter_bits(start=0, stop=-1) -> collections.abc.Iterator`

Return True or False for each bit position in x beginning at start. If a positive value is specified for stop, iteration is continued until stop is reached. If a negative value is specified, iteration is continued until the last 1-bit.

Note: the value of the underlying xmpz object can change during iteration. yes this is unhinged, yes it's documented, we move. 💀

🦋 `iter_clear(start=0, stop=-1) -> collections.abc.Iterator`

Return every bit position that is clear in x, beginning at start. If a positive value is specified for stop, iteration is continued until stop is reached. If a negative value is specified, iteration is continued until the last 1-bit.

Note: the value of the underlying xmpz object can change during iteration. 🫶

🦋 `iter_set(start=0, stop=-1) -> collections.abc.Iterator`

Return an iterator yielding the bit position for every bit that is set in x, beginning at start. If a positive value is specified for stop, iteration is continued until stop is reached. To match the behavior of slicing, stop is not included. 🎀

If a negative value is specified, iteration is continued until the last 1-bit.

Note: the value of the underlying xmpz object can change during iteration. 💅

🧚 `limbs_finish(n, /) -> None`

Must be called after writing to the address returned by x.limbs_write(n) or x.limbs_modify(n) to update the limbs of x. it's the "and then you hit send" step, don't skip it. 🌸

🧚 `limbs_modify(n, /) -> int`

Returns the address of a mutable buffer representing the limbs of x, resized so that it may hold at least n limbs.

Must be followed by a call to x.limbs_finish(n) after writing to the returned address in order for the changes to take effect. fr fr, no limbs_finish, no effect. 💜

🧚 `limbs_read() -> int`

Returns the address of the immutable buffer representing the limbs of x. look but don't touch, bestie. 🙈

🧚 `limbs_write(n, /) -> int`

Returns the address of a mutable buffer representing the limbs of x, resized so that it may hold at least n limbs.

Must be followed by a call to x.limbs_finish(n) after writing to the returned address in order for the changes to take effect.

⚠️ WARNING: this operation is destructive and may destroy the old value of x. like, gone gone. your old x is not coming back. 💀

🧚 `make_mpz() -> mpz`

Return an mpz by converting x as quickly as possible. 🏎️

NOTE: optimized for speed — so the original xmpz value is set to 0! you heard me. it's a trade. 😭

⭐ `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. so like, an estimate with commitment issues. 💅

⭐ `num_limbs() -> int`

Return the number of limbs of x. simple. iconic. 🎀

⭐ `denominator`

the denominator of a rational number in lowest terms. 🦋

⭐ `numerator`

the numerator of a rational number in lowest terms. 🦋

⭐ `real`

the real part of a complex number. keeping it real, literally. 💜

🔥 Advanced Number Theory Functions 🔥

okay so this whole girlboss section is based on mpz_lucas.c and mpz_prp.c by David Cleaver. 👑

A good reference for probable prime testing is http://www.pseudoprime.com/pseudo.html

💖 `gmpy2.is_bpsw_prp(n, /) -> bool`

Return True if n is a Baillie-Pomerance-Selfridge-Wagstaff probable prime. A BPSW probable prime passes the is_strong_prp() test with base 2 and the is_selfridge_prp() test. two tests, one icon. ✨

💖 `gmpy2.is_euler_prp(n, a, /) -> bool`

Return True if n is an Euler probable prime to the base a (also known as Solovay-Strassen, iykyk).

Assuming:

gcd(n,a) == 1
n is odd

Then an Euler probable prime requires:

a**((n-1)/2) == (a/n) (mod n)

where (a/n) is the Jacobi symbol. math girlies rise 🎀

💖 `gmpy2.is_extra_strong_lucas_prp(n, p, /) -> bool`

Return True if n is an extra strong Lucas probable prime with parameters (p,1).

Assuming:

n is odd
D = p*p - 4, D != 0
gcd(n, 2*D) == 1
n = s*(2**r) + Jacobi(D,n), s odd

Then an extra strong Lucas probable prime requires:

lucasu(p,1,s) == 0 (mod n) and lucasv(p,1,s) == +/-2 (mod n)
or lucasv(p,1,s*(2**t)) == 0 (mod n) for some t, 0 <= t < r

"extra strong" is such a vibe, honestly. 🔥

💖 `gmpy2.is_fermat_prp(n, a, /) -> bool`

Return True if n is a Fermat probable prime to the base a.

Assuming:

gcd(n,a) == 1

Then a Fermat probable prime requires:

a**(n-1) == 1 (mod n)

the classic. the blueprint. the one everybody knows. 💅

💖 `gmpy2.is_fibonacci_prp(n, p, q, /) -> bool`

Return True if n is a Fibonacci probable prime with parameters (p,q).

Assuming:

n is odd
p > 0, q = +/-1
p*p - 4*q != 0

Then a Fibonacci probable prime requires:

lucasv(p,q,n) == p (mod n).

fibonacci girlies, this one's for you 🦋

💖 `gmpy2.is_lucas_prp(n, p, q, /) -> bool`

Return True if n is a Lucas probable prime with parameters (p,q).

Assuming:

n is odd
D = p*p - 4*q, D != 0
gcd(n, 2*q*D) == 1

Then a Lucas probable prime requires:

lucasu(p,q,n - Jacobi(D,n)) == 0 (mod n)

no cap. ✨

💖 `gmpy2.is_selfridge_prp(n, /) -> bool`

Return True if n is a Lucas probable prime with Selfridge parameters (p,q). (the manpage spells it "Selfidge" and honestly? we respect the typo era. 💀)

The Selfridge parameters are chosen by finding the first element D in the sequence {5, -7, 9, -11, 13, ...} such that Jacobi(D,n) == -1. Then let p=1 and q = (1-D)/4. Then perform a Lucas probable prime test.

it's giving "the algorithm picks its own outfit". 👑

💖 `gmpy2.is_strong_bpsw_prp(n, /) -> bool`

Return True if n is a strong Baillie-Pomerance-Selfridge-Wagstaff probable prime. A strong BPSW probable prime passes the is_strong_prp() test with base and the is_strong_selfridge_prp() test.

(yeah bestie the manpage really did leave the base blank right there. we are simply living with that. 😭)

💖 `gmpy2.is_strong_lucas_prp(n, p, q, /) -> bool`

Return True if n is a strong Lucas probable prime with parameters (p,q).

Assuming:

n is odd
D = p*p - 4*q, D != 0
gcd(n, 2*q*D) == 1
n = s*(2**r) + Jacobi(D,n), s odd

Then a strong Lucas probable prime requires:

lucasu(p,q,s) == 0 (mod n) or lucasv(p,q,s*(2**t)) == 0 (mod n) for some t, 0 <= t < r

strong AND lucas AND probable AND prime. the whole resume. 🔥

💖 `gmpy2.is_strong_prp(n, a, /) -> bool`

Return True if n is a strong probable prime to the base a — also known as Miller-Rabin, iykyk.

Assuming:

gcd(n,a) == 1
n is odd
n = s*(2**r) + 1, with s odd

Then a strong probable prime requires one of the following is true:

a**s == 1 (mod n) or a**(s*(2**t)) == -1 (mod n) for some t, 0 <= t < r.

one of those two hits, and she's a probable prime. that's it, that's the test. 💅

💖 `gmpy2.is_strong_selfridge_prp(n, /) -> bool`

Return True if n is a strong Lucas probable prime with Selfridge parameters (p,q).

same outfit-picking as before, but now she's strong. 💪✨

💖 `gmpy2.lucasu(p, q, k, /) -> mpz`

Return the k-th element of the Lucas U sequence defined by p,q.

p*p - 4*q must not equal 0; k must be greater than or equal to 0. those two rules? non-negotiable, bestie. 🎀

gmpy2.lucasu_mod(p, q, k, n, /) -> mpz — pulls the k-th element of the Lucas U sequence defined by p,q, but mod n. Ground rules bestie: p*p - 4*q must not equal 0, k must be >= 0, and n must be > 0. no exceptions 💅
gmpy2.lucasv(p, q, k, /) -> mpz — the k-th element of the Lucas V sequence defined by p,q. rules of the house: p*p - 4*q must not equal 0, and k must be >= 0.
gmpy2.lucasv_mod(p, q, k, n, /) -> mpz — k-th element of the Lucas V sequence defined by p,q, but (you guessed it) mod n. same vibes check: p*p - 4*q must not equal 0, k >= 0, and n > 0.

🍓 Rationals

the `mpq` type, she's giving fraction energy

class gmpy2.mpq(n=0, /)

class gmpy2.mpq(n, m, /)

class gmpy2.mpq(s, /, base=10)

okay so this makes you a rational number ✨ — either exactly from a non-complex number n, or from a pair of Rational values n and m, or from a string s built out of digits in whatever base you say. And honestly? every input that the Fraction type constructor accepts, this accepts too. periodt 🫶

Now about that string life: a string can be up to two integers in the same base, split by a / character, and both halves get parsed exactly the same way the mpz constructor does. If base is 0, the leading characters are used to sniff out the base — and this happens separately for the numerator and the denominator, fancy right? 💅 And if base=10, any string that represents a finite value and is accepted by the float constructor is also accepted. slay.

classmethod from_decimal(dec, /) -> mpq — converts a finite decimal.Decimal instance into a rational number, exactly. no rounding nonsense here.
classmethod from_float(f, /) -> mpq — converts a finite float to a rational number, exactly.
as_integer_ratio() -> tuple[mpz, mpz] — hands you a pair of integers whose ratio is exactly equal to the original number. The ratio is in lowest terms and the denominator is positive. math but make it clean 🌸
conjugate() -> mpz — returns the conjugate of x. and since x is not a complex number, this is literally just a new reference to x. iconic minimal effort 💀
digits(base=10, /) -> str — gives you a Python string of x in the given base. allowed bases are 2 to 62, default is 10. A leading '-' shows up if x<0, but there's no leading '+' if x>=0. she doesn't do extra.
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.

💜 mpq Functions

gmpy2.qdiv(x, y=1, /) -> mpz | mpq — returns x/y as an mpz if that's actually possible, otherwise as an mpq when x isn't exactly divisible by y. she adapts ✨

🌈 Contexts

so context() creates a brand new context. set_context() sets the active context. get_context() gives you a reference to that active context. and here's the tea bestie — contexts are mutable: modifying the reference you got back from get_context() will modify the active context until a new context gets enabled with set_context(). The context.copy() method will hand you a copy of the context. And if you want contexts that implement the standard single, double, and quadruple precision floating point types, that's what ieee() is for. 👑

🎀 Context Type

class gmpy2.context(**kwargs)

class gmpy2.context(ctx, /, **kwargs)

returns a fresh new context for controlling gmpy2 arithmetic — based either on the default context or on one given by the ctx value. and you can override context options on top of that with keyword arguments. very customizable, very demure.

abs(x, /) -> mpz | mpq | mpfr — returns abs(x), and the context gets applied to the result.
acos(x, /) -> mpfr | mpc — inverse cosine of x; result in radians.
acosh(x, /) -> mpfr | mpc — inverse hyperbolic cosine of x.
add(x, y, /) -> mpz | mpq | mpfr | mpc — returns x + y.
agm(x, y, /) -> mpfr — arithmetic-geometric mean of x and y.
ai(x, /) -> mpfr — Airy function of x.
asin(x, /) -> mpfr | mpc — inverse sine of x; result in radians.
asinh(x, /) -> mpfr | mpc — inverse hyperbolic sine of x.
atan(x, /) -> mpfr | mpc — inverse tangent of x; result in radians.
atan2(y, x, /) -> mpfr — arc-tangent of (y/x); result in radians.
atanh(x, /) -> mpfr | mpc — inverse hyperbolic tanget of x. (yes, "tanget" — we keep the lore exactly as written 🫶)
cbrt(x, /) -> mpfr — the cube root of x.
ceil(x, /) -> mpfr — returns an mpfr that is the smallest integer >= x.
check_range(x, /) -> mpfr — returns a new mpfr whose exponent lies within the range of emin and emax specified by the context.
clear_flags() -> None — clears all the MPFR exception flags. clean slate bestie ✨
const_catalan() -> mpfr — the catalan constant, at the context's precision.
const_euler() -> mpfr — the euler constant, at the context's precision.
const_log2() -> mpfr — the log2 constant, at the context's precision.
const_pi() -> mpfr — the constant pi, at the context's precision.
copy() -> context — a copy of a context.
cos(x, /) -> mpfr | mpc — cosine of x; x in radians.
cosh(x, /) -> mpfr | mpc — hyperbolic cosine of x.
cot(x, /) -> mpfr — cotangent of x; x in radians.
coth(x, /) -> mpfr — hyperbolic cotangent of x.
csc(x, /) -> mpfr — cosecant of x; x in radians.
csch(x, /) -> mpfr — hyperbolic cosecant of x.
degrees(x, /) -> mpfr — converts angle x from radians to degrees.

⚠️ heads up bestie: in rare cases the result may not be correctly rounded. not a drill.

digamma(x, /) -> mpfr — digamma of x.
div(x, y, /) -> mpz | mpq | mpfr | mpc — returns x / y; uses true division.
div_2exp(x, n, /) -> mpfr | mpc — returns mpfr or mpc divided by 2**n.
divmod(x, y, /) -> tuple[mpz | mpfr, mpz | mpq | mpfr] — returns divmod(x, y).

note: overflow, underflow, and inexact exceptions are not supported for mpfr arguments. so don't come for her about those 💀

eint(x, /) -> mpfr — exponential integral of x.
erf(x, /) -> mpfr — error function of x.
erfc(x, /) -> mpfr — complementary error function of x.
exp(x, /) -> mpfr | mpc — the exponential of x.
exp10(x, /) -> mpfr — returns 10**x.
exp2(x, /) -> mpfr — returns 2**x.
expm1(x, /) -> mpfr — returns exp(x) - 1.
factorial(n, /) -> mpfr — the floating-point approximation to the factorial of n.

if you want the exact integer result, go see fac() instead. this one's just the vibe approximation 🌸

floor(x, /) -> mpfr — returns an mpfr that is the largest integer <= x.
floor_div(x, y, /) -> mpz | mpfr — returns x // y; uses floor division.
fma(x, y, z, /) -> mpz | mpq | mpfr | mpc — the correctly rounded result of (x * y) + z. she does not cut corners ✨
fmma(x, y, z, t, /) -> mpfr — the correctly rounded result of (x * y) + (z * t).
fmms(x, y, z, t, /) -> mpfr — the correctly rounded result of (x * y) - (z * t).
fmod(x, y, /) -> mpfr — returns x - n*y where n is the integer quotient of x/y, rounded toward 0.
fms(x, y, z, /) -> mpz | mpq | mpfr | mpc — the correctly rounded result of (x * y) - z.
frac(x, /) -> mpfr — fractional part of x.
frexp(x, /) -> tuple[int, mpfr] — a tuple with the exponent and mantissa of x.
fsum(iterable, /) -> mpfr — an accurate sum of the values in the iterable. no floating point drama 💅
gamma(x, /) -> mpfr — gamma of x.
gamma_inc(a, x, /) -> mpfr — the (upper) incomplete gamma of a and x.
hypot(x, y, /) -> mpfr — the square root of (x**2 + y**2).
is_finite(x, /) -> bool — True if x is an actual number (i.e. non NaN or Infinity). If x is an mpc, returns True if both x.real and x.imag are finite.
is_infinite(x, /) -> bool — True if x is +Infinity or -Infinity. If x is an mpc, returns True if either x.real or x.imag is infinite. Otherwise it's False.
is_integer(x, /) -> bool — True if x is an integer; False otherwise.
is_nan(x, /) -> bool — True if x is NaN (Not-A-Number), else False.
is_regular(x, /) -> bool — True if x is not zero, NaN, or Infinity; False otherwise.
is_signed(x, /) -> bool — gives you True when the sign bit of x is set ✨
is_zero(x, /) -> bool — True if x is equal to 0. And if x is an mpc? Then it's True only when both x.real and x.imag are equal to 0 👑
j0(x, /) -> mpfr — first kind Bessel function of order 0 of x 💫
j1(x, /) -> mpfr — first kind Bessel function of order 1 of x
jn(n, x, /) -> mpfr — first kind Bessel function of order n of x. ⚠️ not me telling you this again but: the order of the arguments changed in gmpy2 2.2.0a2
lgamma(x, /) -> tuple[mpfr, int] — returns a tuple holding the logarithm of the absolute value of gamma(x), plus the sign of gamma(x) 🫶
li2(x, /) -> mpfr — real part of the dilogarithm of x
lngamma(x, /) -> mpfr — natural logarithm of gamma(x)
log(x, /) -> mpfr | mpc — the natural logarithm of x 🌸
log10(x, /) -> mpfr | mpc — the base-10 logarithm of x
log1p(x, /) -> mpfr — natural logarithm of (1+x)
log2(x, /) -> mpfr — base-2 logarithm of x
maxnum(x, y, /) -> mpfr — the max of x and y. If x and y aren't mpfr, they get converted to mpfr first. Then the result is rounded to match the specified context 🎀 Bonus: if only one of x or y is a number, then that number is what comes back.
minnum(x, y, /) -> mpfr — the min of x and y. Same deal as maxnum: not-mpfr inputs get converted to mpfr, the result gets rounded to match the specified context, and if only one of x or y is a number, that number is returned 💜
minus(x, /) -> mpz | mpq | mpfr | mpc — returns -x. The context is applied to the result.
mod(x, y, /) -> mpz | mpq | mpfr — returns mod(x, y). 🚨 real talk though: overflow, underflow, and inexact exceptions are not supported for mpfr arguments.
modf(x, /) -> tuple[mpfr, mpfr] — a tuple with the integer portion and the fractional portion of x 💅
mul(x, y, /) -> mpz | mpq | mpfr | mpc — returns x * y
mul_2exp(x, n, /) -> mpfr | mpc — an mpfr or mpc multiplied by 2**n
next_above(x, /) -> mpfr — the next mpfr from x toward +Infinity ⬆️
next_below(x, /) -> mpfr — the next mpfr from x toward -Infinity ⬇️
next_toward(x, y, /) -> mpfr — the next mpfr from x heading in the direction of y. Result keeps the same precision as x.
norm(x, /) -> mpfr — the norm of a complex x. norm(x) is defined as x.real**2 + x.imag**2, and abs(x) is the square root of norm(x) ✨
phase(x, /) -> mpfr — the phase angle (aka the argument) of a complex x 🌀
plus(x, /) -> mpz | mpq | mpfr | mpc — returns +x, and the context is applied to the result.
polar(x, /) -> tuple[mpfr, mpfr] — the polar coordinate form of a complex x that's in rectangular form
pow(x, y, /) -> mpz | mpq | mpfr | mpc — returns x ** y 🔥
proj(x, /) -> mpc — the projection of a complex x onto the Riemann sphere 🌐
radians(x, /) -> mpfr — converts angle x from degrees to radians. Small heads up: in rare cases the result may not be correctly rounded.
rec_sqrt(x, /) -> mpfr — the reciprocal of the square root of x
rect(r, phi, /) -> mpc — the rectangular coordinate form of a complex number that you gave in polar form
reldiff(x, y, /) -> mpfr — the relative difference between x and y. The result equals abs(x-y)/x.
remainder(x, y, /) -> mpfr — returns x - n*y where n is the integer quotient of x/y, rounded to the nearest integer, and ties rounded to even ⚖️
remquo(x, y, /) -> tuple[mpfr, int] — a tuple with remainder(x,y) and the low bits of the quotient
rint(x, /) -> mpfr — x rounded to the nearest integer using the context rounding mode
rint_ceil(x, /) -> mpfr — x rounded to the nearest integer, by first rounding to the next higher-or-equal integer and then, if needed, using the context rounding mode
rint_floor(x, /) -> mpfr — x rounded to the nearest integer, by first rounding to the next lower-or-equal integer and then, if needed, using the context rounding mode
rint_round(x, /) -> mpfr — x rounded to the nearest integer, by first rounding to the nearest integer (ties away from 0) and then, if needed, using the context rounding mode
rint_trunc(x, /) -> mpfr — x rounded to the nearest integer, by first rounding towards zero and then, if needed, using the context rounding mode
root(x, n, /) -> mpfr — the n-th root of x. The result is always an mpfr. 🚨 note: not IEEE 754-2008 compliant; the result differs when x = -0 and n is even. See context.rootn().
root_of_unity(n, k, /) -> mpc — the n-th root of mpc(1) raised to the k-th power 💫
rootn(x, n, /) -> mpfr — the n-th root of x. The result is always an mpfr. ✨ note: this is the IEEE 754-2008 compliant version of context.root().
round2(x, n=0, /) -> mpfr — x rounded to n bits. Uses the default precision if n isn't specified. See context.round_away() to access the mpfr_round() function of the MPFR.
round_away(x, /) -> mpfr — an mpfr that is x rounded to the nearest integer, with ties rounded away from 0 🫶
sec(x, /) -> mpfr — secant of x; x in radians
sech(x, /) -> mpfr — hyperbolic secant of x
sin(x, /) -> mpfr | mpc — sine of x; x in radians 🌊
sin_cos(x, /) -> tuple[mpfr | mpc, mpfr | mpc] — a tuple with the sine and the cosine of x; x in radians. Two for one, we love to see it 💅
sinh(x, /) -> mpfr | mpc — hyperbolic sine of x
sinh_cosh(x, /) -> tuple[mpfr, mpfr] — a tuple with the hyperbolic sine and cosine of x
sqrt(x, /) -> mpfr | mpc — the square root of x 🌱
square(x, /) -> mpz | mpq | mpfr | mpc — returns x * x
sub(x, y, /) -> mpz | mpq | mpfr | mpc — returns x - y
tan(x, /) -> mpfr | mpc — tangent of x; x in radians
tanh(x, /) -> mpfr | mpc — hyperbolic tangent of x
trunc(x, /) -> mpfr — an mpfr that is x truncated towards 0. Same as x.floor() if x>=0 or x.ceil() if x<0 ✂️
y0(x, /) -> mpfr — second kind Bessel function of order 0 of x
y1(x, /) -> mpfr — second kind Bessel function of order 1 of x
yn(n, x, /) -> mpfr — the second kind Bessel function of order n of x. ⚠️ once again for the people in the back: the order of the arguments changed in gmpy2 2.2.0a2
zeta(x, /) -> mpfr — Riemann zeta of x 🌀

🎀 attributes, aka the lil switches that run the whole vibe 🎀

allow_complex — this attribute controls whether or not an mpc result can be returned if an mpfr result would normally not be possible 💜
allow_release_gil — if you set it to True, lots of mpz and mpq computations will release the GIL.

🧪 This is considered an experimental feature. You've been warned, bestie.

divzero — this flag is not user controllable. It gets set automatically if a division by zero occurred and a NaN result was returned 🚨
emax — this attribute controls the maximum allowed exponent of an mpfr result. The maximum exponent is platform dependent and can be retrieved with get_emax_max() ⬆️
emin — this attribute controls the minimum allowed exponent of an mpfr result. The minimum exponent is platform dependent and can be retrieved with get_emin_min() ⬇️
erange — bestie this one is NOT yours to touch 🙅‍♀️ it flips itself on automatically whenever an erange error happens.
imag_prec — controls the precision of the imaginary part of an mpc result. If it's set to Default, then whatever real_prec is gets used instead. ✨
imag_round — controls the rounding mode for the imaginary part of an mpc result. If it's Default, then the real_round value is used. Heads up though: RoundAwayZero is not a valid rounding mode for mpc. 💀
inexact — not user controllable, sorry bestie. It just sets itself if an inexact result comes back.
invalid — also not user controllable. Auto-sets if an invalid (Not-A-Number) result is returned. 🚫
overflow — not user controllable either. Sets itself automatically if a result overflowed to +/-Infinity and trap_overflow is False.
precision — controls the precision of an mpfr result. It's measured in bits, not decimal digits, okay? The max precision you can ask for is platform dependent, and you can grab it with get_max_precision(). ⚠️ Also: if you set precision too close to the maximum, the MPFR library will literally fail. Don't do it.
rational_division — set this to True and mpz / mpz hands you back an mpq instead of an mpfr. It's giving "keep it exact" energy. 🎀
real_prec — controls the precision of the real part of an mpc result. If it's Default, then the precision attribute's value is used.
real_round — controls the rounding mode for the real part of an mpc result. If it's Default, then the round attribute's value is used. Same warning as before: RoundAwayZero is not a valid rounding mode for mpc.
round — the mpfr type has five rounding modes and here they all are:
- RoundAwayZero — the result is rounded away from 0.0.
- RoundDown — the result is rounded towards -Infinity.
- RoundToNearest — rounds to the nearest value; ties go to an even value.
- RoundToZero — the result is rounded towards 0.0.
- RoundUp — the result is rounded towards +Infinity.
subnormalize — so the usual IEEE-754 floating point representation supports gradual underflow when you hit the minimum exponent. The MPFR library does not enable gradual underflow by default, but you can turn it on to exactly mimic what IEEE-754 floating point operations do. Niche but iconic. 🦋
trap_divzero — controls whether a DivisionByZeroError gets raised when division by 0 happens. Fun fact: DivisionByZeroError is a sub-class of Python's ZeroDivisionError.
trap_erange — controls whether a RangeError is raised when certain operations get performed on NaN and/or Infinity values. Setting trap_erange to True is the move if you want an exception when comparisons get attempted against a NaN.
trap_inexact — controls whether an InexactResultError gets raised when an inexact result is returned. And if you want to know whether the result was greater or less than the exact result, go check the rc attribute of the mpfr result. 🕵️‍♀️
trap_invalid — controls whether an InvalidOperationError gets raised when a numerical result isn't defined. If no exception is raised, you get a special NaN (Not-A-Number) value instead. InvalidOperationError is a sub-class of Python's ValueError.

For example, gmpy2.sqrt(-2) will normally return mpfr('nan'). But if allow_complex is set to True, then you get an mpc result back instead. 🌈

trap_overflow — if set to False, a result bigger than the largest possible mpfr given the current exponent range gets replaced by +/-Infinity. If set to True, an OverflowResultError exception is raised instead.
trap_underflow — if set to False, a result smaller than the smallest possible mpfr given the current exponent range gets replaced by +/-0.0. If set to True, an UnderflowResultError exception gets raised.
underflow — not user controllable. Auto-sets if a result underflowed to +/-0.0 and trap_underflow is False.

💖 Context Functions 💖

gmpy2.get_context() -> context

Returns a reference to the current context. Easy.

gmpy2.ieee(size, /, subnormalize=True) -> context

Returns a brand new context matching a standard IEEE floating point format. The supported sizes are 16, 32, 64, 128, and multiples of 32 greater than 128. Slay. ✨

gmpy2.local_context(**kwargs) -> context

gmpy2.local_context(context, /, **kwargs) -> context

Returns a new context for controlling gmpy2 arithmetic, based either on the current context or on a ctx value. Context options can also be overridden with keyword arguments. iykyk 🫶

gmpy2.set_context(context, /) -> None

Activates a context object controlling gmpy2 arithmetic. That's it, that's the function.

😭 Exceptions 😭

exception gmpy2.RangeError

exception gmpy2.InexactResultError

exception gmpy2.OverflowResultError

exception gmpy2.UnderflowResultError

exception gmpy2.InvalidOperationError

exception gmpy2.DivisionByZeroError

There they all are, the whole squad. 💅

🌸 Multiple-precision Reals 🌸

`mpfr` Type — the main character 👑

class gmpy2.mpfr(n=0, /, precision=0)

class gmpy2.mpfr(n, /, precision, context)

class gmpy2.mpfr(s, /, precision=0, base=0)

class gmpy2.mpfr(s, /, precision, base, context)

Returns a floating-point number after converting either a numeric value n or a string s made of digits in the given base.

So for strings: they can have a fraction-part (period as the separator) and/or an exponent-part. The exponent marker is 'e' or 'E' for bases up to 10, and '@' in any base. In bases 2 and 16 the exponent prefix can also be 'p' or 'P' — and in that case the exponent means multiply by a power of 2 instead of the base. Note that the value of an exponent is always written in base 10. The fractional-part digits get parsed the same way the mpz type constructor does it, and both the whole number and the exponent-part can optionally be preceded by '+' or '-'. Every input that the float type constructor or the float.fromhex method accepts is also accepted here. 💖

Now for precision, listen up:

If a precision greater than or equal to 2 is specified, then it gets used.
A precision of 0 (which is the default) means the precision of either the specified context or the current context is used.
A precision of 1 minimizes the loss of precision by following these rules:
1. If n is a radix-2 floating point number, then the full precision of n is retained.
2. If n is an integer, then the precision is the bit length of the integer.

__format__(fmt) -> str

Returns a Python string by formatting '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 for negative values
- ' ' -> minus for negative values, space for positive values
optional width.precision
optional rounding mode:
- 'U' -> round toward plus Infinity
- 'D' -> round toward minus Infinity
- 'Y' -> round away from zero
- 'Z' -> round toward zero
- 'N' -> round to nearest
optional conversion code:
- 'a','A' -> hex format
- 'b' -> binary format
- 'e','E' -> scientific format
- 'f','F' -> fixed point format
- 'g','G' -> fixed or float format

The default format is '.6f'. 🌟

as_integer_ratio() -> tuple[mpz, mpz]

Returns the exact rational equivalent of an mpfr. The value is a tuple, purely for compatibility with Python's float.as_integer_ratio. 🎀

as_mantissa_exp() -> tuple[mpz, mpz]

Returns the mantissa and exponent of an mpfr. That's the whole thing.

as_simple_fraction(precision=0) -> mpq

Returns a simple rational approximation to x. The result is accurate to 'precision' bits. And if 'precision' is 0, then the precision of 'x' gets used instead.

conjugate() -> mpz

Returns the conjugate of x — which is literally just a new reference to x since x is not a complex number. Waste of effort? Maybe. Iconic? Absolutely. 💅

digits(base=10, prec=0, /) -> tuple[str, int, int] — bestie, this one gives you up to prec digits in whatever base you want. If prec is 0, it returns as many digits as are available, and it won't give you more digits than x's precision allows. base has to be between 2 and 62, inclusive. You get back a three-element tuple: the mantissa, the exponent, and the number of bits of precision. 💅
is_finite() -> bool — returns True if x is an actual number (so not NaN or Infinity, periodt). If x is an mpc <#gmpy2.mpc>, it returns True only if both x.real and x.imag are finite. 👑
is_infinite() -> bool — returns True if x is +Infinity or -Infinity. If x is an mpc <#gmpy2.mpc>, it returns True if either x.real or x.imag is infinite. Otherwise it's False.
is_integer() -> bool — returns True if x is an integer; False otherwise. no cap.
is_nan() -> bool — returns True if x is NaN (Not-A-Number), else False.
is_regular() -> bool — returns True if x is not zero, NaN, or Infinity; False otherwise.
is_signed() -> bool — returns True if the sign bit of x is set.
is_zero() -> bool — returns True if x is equal to 0. If x is an mpc <#gmpy2.mpc>, it returns True if both x.real and x.imag are equal to 0. 🫶
imag — imaginary component ✨
precision — precision in bits 🎀
rc — return code 💀
real — real component 🦋

✨ mpfr Functions ✨

gmpy2.agm(x, y, /) -> mpfr <#gmpy2.mpfr> — returns the arithmetic-geometric mean of x and y. slay ✨
gmpy2.ai(x, /) -> mpfr <#gmpy2.mpfr> — returns the Airy function of x.
gmpy2.atan2(y, x, /) -> mpfr <#gmpy2.mpfr> — returns arc-tangent of (y/x); the result is in radians.
gmpy2.cbrt(x, /) -> mpfr <#gmpy2.mpfr> — returns the cube root of x. periodt.
gmpy2.ceil(x, /) -> mpfr <#gmpy2.mpfr> — returns an mpfr that is the smallest integer >= x.
gmpy2.check_range(x, /) -> mpfr <#gmpy2.mpfr> — returns a new mpfr with an exponent that lies within the current range of emin and emax.
gmpy2.cmp(x, y, /) -> int — returns -1 if x < y; 0 if x = y; or 1 if x > y. Both x and y must be integer, rational or real. Note: 0 is returned (and the exception flag is set) if either argument is NaN. 💀
gmpy2.const_catalan(precision=0) -> mpfr <#gmpy2.mpfr> — returns the catalan constant using the specified precision. If no precision is specified, the default precision is used.
gmpy2.const_euler(precision=0) -> mpfr <#gmpy2.mpfr> — returns the euler constant using the specified precision. If no precision is specified, the default precision is used.
gmpy2.const_log2(precision=0) -> mpfr <#gmpy2.mpfr> — returns the log2 constant using the specified precision. If no precision is specified, the default precision is used.
gmpy2.const_pi(precision=0) -> mpfr <#gmpy2.mpfr> — returns the constant pi using the specified precision. If no precision is specified, the default precision is used.
gmpy2.cot(x, /) -> mpfr <#gmpy2.mpfr> — returns cotangent of x; x in radians.
gmpy2.coth(x, /) -> mpfr <#gmpy2.mpfr> — returns hyperbolic cotangent of x.
gmpy2.csc(x, /) -> mpfr <#gmpy2.mpfr> — returns cosecant of x; x in radians.
gmpy2.csch(x, /) -> mpfr <#gmpy2.mpfr> — returns hyperbolic cosecant of x.
gmpy2.degrees(x, /) -> mpfr <#gmpy2.mpfr> — converts angle x from radians to degrees. Note: in rare cases the result may not be correctly rounded. 🙈
gmpy2.digamma(x, /) -> mpfr <#gmpy2.mpfr> — returns digamma of x.
gmpy2.eint(x, /) -> mpfr <#gmpy2.mpfr> — returns exponential integral of x.
gmpy2.erf(x, /) -> mpfr <#gmpy2.mpfr> — returns error function of x.
gmpy2.erfc(x, /) -> mpfr <#gmpy2.mpfr> — returns complementary error function of x.
gmpy2.exp10(x, /) -> mpfr <#gmpy2.mpfr> — returns 10**x.
gmpy2.exp2(x, /) -> mpfr <#gmpy2.mpfr> — returns 2**x.
gmpy2.expm1(x, /) -> mpfr <#gmpy2.mpfr> — returns exp(x) - 1.
gmpy2.factorial(n, /) -> mpfr <#gmpy2.mpfr> — returns the floating-point approximation to the factorial of n. See fac() <#gmpy2.fac> to get the exact integer result. 💅
gmpy2.floor(x, /) -> mpfr <#gmpy2.mpfr> — returns an mpfr that is the largest integer <= x.
gmpy2.fmma(x, y, z, t, /) -> mpfr <#gmpy2.mpfr> — returns correctly rounded result of (x * y) + (z + t).
gmpy2.fmms(s, y, z, t, /) -> mpfr <#gmpy2.mpfr> — returns correctly rounded result of (x * y) - (z + t).
gmpy2.fmod(x, y, /) -> mpfr <#gmpy2.mpfr> — returns x - n*y where n is the integer quotient of x/y, rounded to 0.
gmpy2.frac(x, /) -> mpfr <#gmpy2.mpfr> — returns fractional part of x.
gmpy2.frexp(x, /) -> tuple[int, mpfr <#gmpy2.mpfr>] — returns a tuple containing the exponent and mantissa of x.
gmpy2.fsum(iterable, /) -> mpfr <#gmpy2.mpfr> — returns an accurate sum of the values in the iterable.
gmpy2.gamma(x, /) -> mpfr <#gmpy2.mpfr> — returns gamma of x.
gmpy2.gamma_inc(a, x, /) -> mpfr <#gmpy2.mpfr> — returns (upper) incomplete gamma of a and x.
gmpy2.get_exp(x, /) -> int — returns the exponent of x. It returns 0 for NaN or Infinity and sets the context.erange <#gmpy2.context.erange> flag of the current context, and it will raise an exception if context.trap_erange <#gmpy2.context.trap_erange> is set. 🚨
gmpy2.hypot(x, y, /) -> mpfr <#gmpy2.mpfr> — returns square root of (x**2 + y**2).
gmpy2.inf(n, /) -> mpfr <#gmpy2.mpfr> — returns an mpfr initialized to Infinity with the same sign as n. If n is not given, +Infinity is returned.
gmpy2.is_finite(x, /) -> bool — returns True if x is an actual number (i.e. non NaN or Infinity). If x is an mpc <#gmpy2.mpc>, it returns True if both x.real and x.imag are finite.
gmpy2.is_infinite(x, /) -> bool — returns True if x is +Infinity or -Infinity. If x is an mpc <#gmpy2.mpc>, it returns True if either x.real or x.imag is infinite. Otherwise it returns False.
gmpy2.is_regular(x, /) -> bool — returns True if x is not zero, NaN, or Infinity; False otherwise.
gmpy2.is_signed(x, /) -> bool — returns True if the sign bit of x is set.
gmpy2.is_unordered(x, y, /) -> bool — returns True if either x and/or y is NaN.
gmpy2.j0(x, /) -> mpfr <#gmpy2.mpfr> — returns first kind Bessel function of order 0 of x.
gmpy2.j1(x, /) -> mpfr <#gmpy2.mpfr> — returns first kind Bessel function of order 1 of x.
gmpy2.jn(n, x, /) -> mpfr <#gmpy2.mpfr> — returns the first kind Bessel function of order n of x. Note: the order of the arguments changed in gmpy2 2.2.0a2.
gmpy2.lgamma(x, /) -> tuple[mpfr <#gmpy2.mpfr>, int] — returns a tuple containing the logarithm of the absolute value of gamma(x) and the sign of gamma(x).
gmpy2.li2(x, /) -> mpfr <#gmpy2.mpfr> — returns real part of dilogarithm of x.
gmpy2.lngamma(x, /) -> mpfr <#gmpy2.mpfr> — returns natural logarithm of gamma(x).
gmpy2.log1p(x, /) -> mpfr <#gmpy2.mpfr> — returns natural logarithm of (1+x).
gmpy2.log2(x, /) -> mpfr <#gmpy2.mpfr> — returns base-2 logarithm of x.
gmpy2.maxnum(x, y, /) -> mpfr <#gmpy2.mpfr> — returns the maximum number of x and y. If x and y are not mpfr, they are converted to mpfr. The result is rounded to match the current context. If only one of x or y is a number, then that number is returned.
gmpy2.minnum(x, y, /) -> mpfr <#gmpy2.mpfr> — returns the minimum number of x and y. If x and y are not mpfr, they are converted to mpfr. The result is rounded to match the current context. If only one of x or y is a number, then that number is returned.
gmpy2.modf(x, /) -> tuple[mpfr <#gmpy2.mpfr>, mpfr <#gmpy2.mpfr>] — returns a tuple containing the integer and fractional portions of x.
gmpy2.mpfr_from_old_binary(string, /) -> mpfr <#gmpy2.mpfr> — returns an mpfr from a GMPY 1.x binary mpf format.
gmpy2.mpfr_grandom(random_state, /) -> tuple[mpfr <#gmpy2.mpfr>, mpfr <#gmpy2.mpfr>] — returns two random numbers with gaussian distribution.
gmpy2.mpfr_nrandom(random_state, /) — returns a random number with gaussian distribution.
gmpy2.mpfr_random(random_state, /) -> mpfr <#gmpy2.mpfr> — returns uniformly distributed number between [0,1].
gmpy2.nan() -> mpfr <#gmpy2.mpfr> — returns an mpfr initialized to NaN (Not-A-Number).
gmpy2.next_above(x, /) -> mpfr <#gmpy2.mpfr> — returns the next mpfr from x toward +Infinity.
gmpy2.next_below(x, /) -> mpfr <#gmpy2.mpfr> — returns the next mpfr from x toward -Infinity.
gmpy2.radians(x, /) -> mpfr <#gmpy2.mpfr> — converts angle x from degrees to radians. Note: in rare cases the result may not be correctly rounded. 🙈
gmpy2.rec_sqrt(x, /) -> mpfr <#gmpy2.mpfr> — returns the reciprocal of the square root of x.
gmpy2.reldiff(x, y, /) -> mpfr <#gmpy2.mpfr> — returns the relative difference between x and y. Result is equal to abs(x-y)/x.
gmpy2.remainder(x, y, /) -> mpfr <#gmpy2.mpfr> — returns x - n*y where n is the integer quotient of x/y, rounded to the nearest integer and ties rounded to even.
gmpy2.remquo(x, y, /) -> tuple[mpfr <#gmpy2.mpfr>, int] — returns a tuple containing the remainder(x,y) and the low bits of the quotient.
gmpy2.rint(x, /) -> mpfr <#gmpy2.mpfr> — returns x rounded to the nearest integer using the current rounding mode.
gmpy2.rint_ceil(x, /) -> mpfr <#gmpy2.mpfr> — returns x rounded to the nearest integer by first rounding to the next higher or equal integer and then, if needed, using the current rounding mode.
gmpy2.rint_floor(x, /) -> mpfr <#gmpy2.mpfr> — returns x rounded to the nearest integer by first rounding to the next lower or equal integer and then, if needed, using the current rounding mode.
gmpy2.rint_round(x, /) -> mpfr <#gmpy2.mpfr> — returns x rounded to the nearest integer by first rounding to the nearest integer (ties away from 0) and then, if needed, using the current rounding mode.
gmpy2.rint_trunc(x, /) -> mpfr <#gmpy2.mpfr> — returns x rounded to the nearest integer by first rounding towards zero and then, if needed, using the current rounding mode.
gmpy2.root(x, n, /) -> mpfr — okay so this gives you the n-th root of x, and the result is always an mpfr. ✨ ⚠️ bestie, heads up: this is not IEEE 754-2008 compliant — the result differs when x = -0 and n is even. peep rootn() if you need that. 👀
gmpy2.rootn(x, n, /) -> mpfr — same n-th root energy, but this is the IEEE 754-2008 compliant version of root(). slay. 💅
gmpy2.round2(x, n=0, /) -> mpfr — returns x rounded to n bits. if you don't pass n, it uses the default precision. check round_away() to access the mpfr_round() function of the MPFR. 🎀
gmpy2.round_away(x, /) -> mpfr — returns an mpfr that is x rounded to the nearest integer, with ties rounded away from 0. no cap. 🫶
gmpy2.sec(x, /) -> mpfr — returns the secant of x; x in radians. 🌸
gmpy2.sech(x, /) -> mpfr — returns the hyperbolic secant of x. 🦋
gmpy2.set_exp(x, n, /) -> mpfr — sets the exponent of x to n. if n is outside the range of valid exponents, set_exp() will set the context.erange flag of the current context and either return the original value or raise an exception if context.trap_erange is set. ⚠️
gmpy2.set_sign(x, s, /) -> mpfr — if s is True, returns x with the sign bit set. periodt. 💜
gmpy2.sign(x, /) -> int — returns -1 if x < 0, 0 if x == 0, or +1 if x >0. (yes, that's exactly how it's written, don't @ me.) 🙈
gmpy2.sinh_cosh(x, /) -> tuple[mpfr, mpfr] — returns a tuple containing the hyperbolic sine and cosine of x. 🍓
gmpy2.trunc(x, /) -> mpfr — returns an mpfr that is x truncated towards 0. same as x.floor() if x>=0 or x.ceil() if x<0. 🧚
gmpy2.y0(x, /) -> mpfr — returns the second kind Bessel function of order 0 of x. 🌈
gmpy2.y1(x, /) -> mpfr — returns the second kind Bessel function of order 1 of x. ⭐
gmpy2.yn(n, x, /) -> mpfr — returns the second kind Bessel function of order n of x. ⚠️ note: the order of the arguments changed in gmpy2 2.2.0a2. 👑
gmpy2.zero(n, /) -> mpfr — returns an mpfr initialized to 0.0 with the same sign as n. if n is not given, +0.0 is returned. 💖
gmpy2.zeta(x, /) -> mpfr — returns the Riemann zeta of x. 🔥
gmpy2.get_max_precision() -> int — returns the maximum bits of precision that can be used for calculations. ⚠️ note: to allow extra precision for intermediate calculations, avoid setting precision close to the maximum precision. 😭
gmpy2.get_emax_max() -> int — returns the maximum possible exponent that can be set for mpfr. 💅
gmpy2.get_emin_min() -> int — returns the minimum possible exponent that can be set for mpfr. 🎀
gmpy2.copy_sign(x, y, /) -> mpfr — returns an mpfr composed of x with the sign of y. 🫶
gmpy2.can_round(b, err, rnd1, rnd2, prec, /) -> bool — let b be an approximation to an unknown number x that is rounded according to rnd1. assume that b has an error at most two to the power of E(b)-err where E(b) is the exponent of b. then return True if x can be rounded correctly to prec bits with rounding mode rnd2. 🤓
gmpy2.free_cache() -> None — free the internal cache of constants maintained by MPFR. bye bestie 👋

🌈 Multiple-precision Complex 🌈

🎀 mpc Type 🎀

class gmpy2.mpc(c=0, /, precision=0)
class gmpy2.mpc(c=0, /, precision, context)
class gmpy2.mpc(real, /, imag=0, precision=0)
class gmpy2.mpc(real, /, imag, precision, context)
class gmpy2.mpc(s, /, precision=0, base=10)
class gmpy2.mpc(s, /, precision, base, context)

returns a complex floating-point number constructed from a numeric value c, or from a pair of two non-complex numbers real and imag, or from a string s made of digits in the given base. ✨

a string can have a real-part and/or an imaginary-part (with 'j' as a suffix), separated by '+', and it's parsed the same way the mpfr constructor does it (but base must be up to 36). 🦋

the precision can be specified by either a single number that is used for both the real and imaginary components, or as a pair of different precisions for the real and imaginary components. for every component, the meaning of its precision value is the same as in the mpfr type constructor. 🌸

methods:

__format__(fmt) -> str — returns a Python string by formatting '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 for negative values
  - ' ' -> minus for negative values, space for positive values
- optional width.real_precision.imag_precision
- optional rounding mode:
  - 'U' -> round toward plus infinity
  - 'D' -> round toward minus infinity
  - 'Z' -> round toward zero
  - 'N' -> round to nearest
- optional output style:
  - 'P' -> Python style, 1+2j, (default)
  - 'M' -> MPC style, (1 2)
- optional conversion code:
  - 'a','A' -> hex format
  - 'b' -> binary format
  - 'e','E' -> scientific format
  - 'f','F' -> fixed point format
  - 'g','G' -> fixed or scientific format
- the default format is 'f'.
conjugate() -> mpc — returns the conjugate of x. 💅
digits(base=10, prec=0, /) -> tuple[tuple[str, int, int], tuple[str, int, int]] — returns up to prec digits in the given base. if prec is 0, as many digits that are available given c's precision are returned. base must be between 2 and 62. the result consists of 2 three-element tuples that contain the mantissa, exponent, and number of bits of precision of the real and imaginary components. 🍓
is_finite() -> bool — return True if x is an actual number (i.e. non NaN or Infinity). if x is an mpc, return True if both x.real and x.imag are finite. 🌈
is_infinite() -> bool — return True if x is +Infinity or -Infinity. if x is an mpc, return True if either x.real or x.imag is infinite. otherwise return False. ⭐
is_nan() -> bool — return True if x is NaN (Not-A-Number) else False. 💀
is_zero() -> bool — return True if x is equal to 0. if x is an mpc, return True if both x.real and x.imag are equal to 0. 🙈
imag — imaginary component 👑
precision — precision in bits 🎀
rc — return code 💜
real — real component 🫶

✨ mpc Functions ✨

gmpy2.acos(x, /) -> mpfr | mpc — returns inverse cosine of x; result in radians. 🌸
gmpy2.acosh(x, /) -> mpfr | mpc — returns inverse hyperbolic cosine of x. 🦋
gmpy2.asin(x, /) -> mpfr | mpc — returns inverse sine of x; result in radians. 🍓
gmpy2.asinh(x, /) -> mpfr | mpc — returns inverse hyperbolic sine of x. 🧚
gmpy2.atan(x, /) -> mpfr | mpc — returns inverse tangent of x; result in radians. 🌈
gmpy2.atanh(x, /) -> mpfr | mpc — returns inverse hyperbolic tangent of x. ⭐
gmpy2.cos(x, /) -> mpfr | mpc — returns cosine of x; x in radians. 💖
gmpy2.cosh(x, /) -> mpfr | mpc — returns hyperbolic cosine of x. 🔥
gmpy2.div_2exp(x, n, /) -> mpfr | mpc — returns x divided by 2**n. 💅
gmpy2.exp(x, /) -> mpfr | mpc — returns the exponential of x. 🌟
gmpy2.is_nan(x, /) -> bool — return True if x is NaN (Not-A-Number) else False. 💀
gmpy2.is_zero(x, /) -> bool — return True if x is equal to 0. if x is an mpc, return True if both x.real and x.imag are equal to 0. 🙈
gmpy2.log(x, /) -> mpfr | mpc — returns the natural logarithm of x. 🎀
gmpy2.log10(x, /) -> mpfr | mpc — returns the base-10 logarithm of x. 🫶
gmpy2.mpc_random(random_state, /) -> mpc — returns a uniformly distributed number in the unit square [0,1]x[0,1]. 🎲
gmpy2.mul_2exp(x, n, /) -> mpfr | mpc — returns x multiplied by 2**n. ✨
gmpy2.norm(x, /) -> mpfr — returns the norm of a complex x. norm(x) is defined as x.real**2 + x.imag**2. abs(x) is the square root of norm(x). 🌈
gmpy2.phase(x, /) -> mpfr — returns the phase angle, also known as argument, of a complex x. ⭐
gmpy2.polar(x, /) -> tuple[mpfr, mpfr] — returns the polar coordinate form of a complex x that is in rectangular form. 🍓
gmpy2.proj(x, /) -> mpc — returns the projection of a complex x on to the Riemann sphere. 🌍
gmpy2.rect(r, phi, /) -> mpc — returns the rectangular coordinate form of a complex number that is given in polar form. 📐
gmpy2.root_of_unity(n, k, /) -> mpc — returns the n-th root of mpc(1) raised to the k-th power.. (yes, two dots, iconic) 👑
gmpy2.sin(x, /) -> mpfr | mpc — returns sine of x; x in radians. 💜
gmpy2.sin_cos(x, /) -> tuple[mpfr | mpc, mpfr | mpc] — returns a tuple containing the sine and cosine of x; x in radians. 🫶
gmpy2.sinh(x, /) -> mpfr | mpc — returns hyperbolic sine of x. 🦋
gmpy2.sqrt(x, /) -> mpfr | mpc — returns the square root of x. 🌸
gmpy2.tan(x, /) -> mpfr | mpc — returns tangent of x; x in radians. 🔥
gmpy2.tanh(x, /) -> mpfr | mpc — returns hyperbolic tangent of x. 🧚

🌟 Generic Functions 🌟

gmpy2.add(x, y, /) -> mpz | mpq | mpfr | mpc — returns x + y. 💖
gmpy2.div(x, y, /) -> mpz | mpq | mpfr | mpc — returns x / y; uses true division. periodt. 💅
gmpy2.mul(x, y, /) -> mpz | mpq | mpfr | mpc — bestie it literally returns x * y. that's it, that's the function 💖
gmpy2.sub(x, y, /) -> mpz | mpq | mpfr | mpc — returns x - y. subtraction nation rise 🫶
gmpy2.square(x, /) -> mpz | mpq | mpfr | mpc — returns x * x. the glow-up of multiplying by yourself ✨
gmpy2.f2q(x, err=0, /) -> mpz | mpq — returns the 'best' mpq that approximates x within a relative error of err. default is the precision of x. it uses a Stern-Brocot tree to hunt down that 'best' approximation (iykyk 🧚). if the denominator turns out to be 1, you get an mpz object back instead. and if err < 0, the relative error is 2.0 ** err. not me thinking that's kinda iconic
gmpy2.fma(x, y, z, /) -> mpz | mpq | mpfr | mpc — returns the correctly rounded result of (x * y) + z. fused multiply-add serving precision 💅
gmpy2.fms(x, y, z, /) -> mpz | mpq | mpfr | mpc — returns the correctly rounded result of (x * y) - z. yes it's fma's chaotic sibling 😌
gmpy2.cmp_abs(x, y, /) -> int — returns -1 if abs(x) < abs(y); 0 if abs(x) = abs(y); and 1 otherwise. comparing the vibes, ignoring the signs 🌈

🌸 Miscellaneous Functions 🌸

gmpy2.digits(x, base=10, prec=0, /) -> str — returns a string representing the number x. it's giving stringified 👑
gmpy2.from_binary(bytes, /) -> mpz | xmpz | mpq | mpfr | mpc — returns a Python object from a byte sequence that was created by to_binary(). the reunion arc 🥹
gmpy2.license() -> str — returns a string giving license information. read the fine print bestie, it's important 📜
gmpy2.mp_limbsize() -> int — returns the number of bits per limb. limbs!! like a body?? no it's just GMP internals 🦋
gmpy2.mp_version() -> str — returns a string giving the current GMP version.
gmpy2.mpc_version() -> str — returns a string giving the current MPC version.
gmpy2.mpfr_version() -> str — returns a string giving the current MPFR version.
gmpy2.random_state(seed=0, /) -> object — returns a brand new object holding state info for the random number generator. you can optionally pass an integer as the seed value 🎲
gmpy2.to_binary(x, /) -> bytes — returns a Python byte sequence that is a portable binary representation of a gmpy2 object x. you can hand that byte sequence to from_binary() and get an exact copy of x's value back. raises a TypeError if x isn't a gmpy2 object. no fakes allowed 🙅‍♀️
gmpy2.version() -> str — returns a string giving the current GMPY2 version. the origin story fr fr ⭐

🧚 Cython usage 🧚

the gmpy2 module provides a C-API that can be used conveniently from Cython. all the types and functions are declared in the header gmpy2.pxd, which gets installed automatically in your Python path right alongside the library. slay 💅

✨ Initialization ✨

to use the C-API you need to make one single call to the function void import_gmpy2(void). one call. that's the whole ritual 🕯️

🦋 Types 🦋

the types mpz, mpq, mpfr and mpc are declared as extension types in gmpy2.pxd. they correspond respectively to the C structures MPZ_Object, MPQ_Object, MPFR_Object and MPC_Object. they match, that's the whole point 💖

fast type checking can be done with the following C functions:

bint MPZ_Check(object) — equivalent to isinstance(obj, mpz)
bint MPQ_Check(object) — equivalent to isinstance(obj, mpq)
bint MPFR_Check(object) — equivalent to isinstance(obj, mpfr)
bint MPC_Check(object) — equivalent to isinstance(obj, mpc)

🌈 Object creation 🌈

to create a new gmpy2 type there are four basic functions:

mpz GMPy_MPZ_New(void * ctx) — create a new mpz object from a given context ctx
mpq GMPy_MPQ_New(void * ctx) — create a new mpq object from a given context ctx
mpfr MPFR_New(void * ctx, mpfr_prec_t prec) — create a new mpfr object with a given context ctx and precision prec
mpc MPC_New(void * ctx, mpfr_prec_t rprec, mpfr_prec_t iprec) — create a new mpc object with a given context ctx, and precisions rprec and iprec of respectively the real and imaginary parts

the context can be set to NULL and controls the default behavior (e.g. precision). setting it to NULL is like letting the algorithm pick your outfit for you, honestly relatable 🙈

the gmpy2.pxd header also provides a convenience macro to wrap a (copy of) an mpz_t, mpq_t, mpfr_t or mpc_t object into the corresponding gmpy2 type:

mpz GMPy_MPZ_From_mpz(mpz_srcptr z) — return a new mpz object with a given mpz_t value z
mpq GMPy_MPQ_From_mpq(mpq_srcptr q) — return a new mpq object from a given mpq_t value q
mpq GMPy_MPQ_From_mpz(mpz_srcptr num, mpz_srcptr den) — return a new mpq object with a given mpz_t numerator num and mpz_t denominator den
mpfr GMPy_MPFR_From_mpfr(mpfr_srcptr x) — return a new mpfr object with a given mpfr_t value x
mpc GMPy_MPC_From_mpc(mpc_srcptr c) — return a new mpc object with a given mpc_t value c
mpc GMPy_MPC_From_mpfr(mpfr_srcptr re, mpfr_srcptr im) — return a new mpc object with a given mpfr_t real part re and mpfr_t imaginary part im

👑 Access to the underlying C type 👑

each of the gmpy2 objects has a field corresponding to the underlying C type. the following functions give you access to that field:

mpz_t MPZ(mpz)
mpq_t MPQ(mpq)
mpfr_t MPFR(mpfr)
mpc_t MPC(mpc)

💜 Compilation 💜

the header gmpy2.pxd as well as the C header gmpy2.h that it depends on are installed in the Python path. to make Cython and the C compiler aware that these files exist, the Python path should be part of the include directories. manifesting ✨

quick reminder bestie: import_gmpy2() needs to be called before any other function of the C-API. do not skip this step, it WILL haunt you 💀

here's a minimal example of a Cython file test_gmpy2.pyx:

"A minimal cython file test_gmpy2.pyx"

from gmpy2 cimport *

cdef extern from "gmp.h":
    void mpz_set_si(mpz_t, long)

import_gmpy2()   # needed to initialize the C-API

cdef mpz z = GMPy_MPZ_New(NULL)
mpz_set_si(MPZ(z), -7)

print(z + 3)

the corresponding setup.py is given below:

"A minimal setup.py for compiling test_gmpy2.pyx"

import sys

from setuptools import Extension, setup
from Cython.Build import cythonize

ext = Extension("test_gmpy2", ["test_gmpy2.pyx"],
                include_dirs=sys.path, libraries=['gmp', 'mpfr', 'mpc'])

setup(name="cython_gmpy_test",
      ext_modules=cythonize([ext], include_path=sys.path))

with these two files in the same repository, you should be able to compile your module using:

$ python setup.py build_ext --inplace

for more about compilation and installation of cython files and extension modules, please refer to the official documentation of Cython and distutils. go read the docs, they ate 📚

🎀 Conversion Methods 🎀

a python object could interact with gmpy2 if it implements one of the following methods:

__mpz__ : return an object of type mpz.
__mpq__ : return an object of type mpq.
__mpfr__ : return an object of type mpfr.
__mpc__ : return an object of type mpc.

implementing one of these methods allows gmpy2 to convert a python object into a gmpy2 type. example:

>>> from gmpy2 import mpz
>>> class CustInt:
...     def __init__(self, x):
...             self.x = x
...     def __mpz__(self):
...             return mpz(self.x)
...
>>> ci = CustInt(5)
>>> z = mpz(ci); z
mpz(5)
>>> type(z)
<class 'gmpy2.mpz'>

look at that, your own little class getting adopted into the gmpy2 family 🥹

⭐ Arithmetic operations ⭐

gmpy2 allows arithmetic operations between gmpy2 numbers and objects with conversion methods. operations with objects that implement floating conversion and exact conversion methods are not supported. that means only the following cases are supported:

an integer type has to implement __mpz__
a rational type has to implement __mpq__ and can implement __mpz__
a real type has to implement __mpfr__
a complex type has to implement __mpc__ and can implement __mpfr__

examples:

>>> import gmpy2
>>> from gmpy2 import mpz, mpq, mpfr, mpc
>>> gmpy2.set_context(gmpy2.context())
>>> class Q:
...     def __mpz__(self): return mpz(1)
...     def __mpq__(self): return mpq(3,2)
>>> q = Q()
>>> mpz(2) + q
mpq(7,2)
>>> mpq(1,2) * q
mpq(3,4)
>>> mpfr(10) * q
mpfr('15.0')

the way that mpz(2) + q just becomes mpq(7,2)?? cheating but in a slay way 💅

💖 Release Notes 💖

🌟 Changes in gmpy2 2.2.1 🌟

fix internal use of char when int should be used. (jamesjer)
add xmpz.bit_count(). (skirpichev)

🌟 Changes in gmpy2 2.2.0 🌟

remove support for versions of Python < 3.7. (skirpichev)
support more modern build tools. (skirpichev)
use contextvars to manage gmpy2 contexts. (casevh)
_mpmath functions now use the vectorcall protocol. (casevh)
many documentation updates. (skirpichev)
add mpz.as_integer_ratio() / mpz.to_bytes() and mpz.from_bytes(). (skirpichev)
add is_probab_prime() to directly expose the GMP behavior. (skirpichev)
gcd() / lcm() now uses the vectorcall protocol. (skirpichev)
expose context type. (skirpichev)
correct error in is_strong_bpsw_prp(). (casevh)
added prev_prime() when GMP >= 6.3. (sethtroisi)
change argument order of jn() and yn() to match MPFR. (casevh)
fix documentation and code for is_extra_strong_lucas_prp(). (casevh)

🌟 Changes in gmpy2 2.1.5 🌟

version bump to fix wheel issues. no code changes. the most nothing-burger release, and honestly? respect 🙈

🌟 Changes in gmpy2 2.1.4 🌟

version bump to fix wheel issues. no code changes. again ✨

🌟 Changes in gmpy2 2.1.3 🌟

fix mpz(-3).is_prime().
add powmod_sec().
fix mpfr('inf') and mpfr('nan') if subnormalization is enabled.
powmod() and powmod_sec() release the GIL.
fix error messages for iroot(x,n) for large n.
add powmod_base_list() and powmod_exp_list() (experimental).
fix gmpy2.mpq(mpq, int).
fix issues with INF, NAN, and mpfr("-0") when subnormalization is True

🌟 Changes in gmpy2 2.1.2 🌟

code cleanup.
support Apple Silicon binary wheels.
is_prime(-2) now returns False. Issue #312.

🌟 Changes in gmpy2 2.1.1 🌟

code cleanup.
properly return NOTIMPLEMENTED for unsupported arguments in **. Issue #319.

🌟 Changes in gmpy2 2.1.0 🌟

improvements to setup.py.
add thread-safe contexts.
MPFR and MPC are now required.
Invalid Operation exception now raised for addition, etc.
inverse() now raises an exception if inverse does not exist.
add context methods.
Major code refactoring was literally required to properly support thread-safe contexts. it's giving surgery bestie 🔥
__str__ and __repr__ no longer tack an "L" onto the end on Python 2. the L era is over 💅
mpq(mpfr) now returns the exact result. no rounding drama ✨
Fixed repr(mpc) for precision >325 bits.
Intermediate conversions of Integer to mpfr are now done with the full precision of the Integer.
Support for interaction with the Decimal type? Removed. gone, bye 👋
No longer attempt to override the memory allocation functions. we said no thank you 🙈
gmpy2 types got registered into the numeric tower. iconic behavior honestly 👑
mpz(x) now calls int(x) if mpz() doesn't know how to convert x directly.
mpz got converted to an actual type using __new__ instead of being a factory function. glow up 🦋
Bug fix for small mpfr ** small Python integer. (the little guys matter too 😭)
Compiles with Python 3.11. periodt.

✨ Changes in gmpy2 2.1.0rc2

Documentation updates. (yes bestie, the docs got love too 📖)
Improvements to the build environment. 🛠️

✨ Changes in gmpy2 2.1.0rc1

Added support for embedded underscore characters in string literals. 1_000_000 core 🌸
GIL release now allowed for mpz/xmpz/mpq types only. nobody else, sorry 🚫

✨ Changes in gmpy2 2.1.0b6

Improved argument type processing by saving type information, which decreases the number of type check calls. Extra helpful for mpfr and mpc types. (Not complete, but the common operations are done.) 🏃‍♀️💨
Resolved a bug in mpfr → mpq conversion; issue #287.
Added limited support for releasing the GIL; disabled by default; see context.allow_release_gil.
Refactored how in-place operations are handled for mpz and xmpz types; in-place operations on xmpz will only return an xmpz result. no switching up on us 💀
Refactored conversion to C integer types. Some exception types changed to reflect Python types.
gcd() and lcm() now support more than two arguments, to align with the matching functions over in the math module. glow up for the gcd girlies 🫶

✨ Changes in gmpy2 2.1.0b5

Avoided an MPFR bug in mfr_fac_ui (factorial()) on platforms where long is 32-bits and the argument is >= 44787929. 🚧
Fixed testing bugs with Python 2.7.
Fixed mpz(0) to C long or long long.
Fixed incorrect results in f2q(). 😭
Adjusted the test suite to reflect output changes in MPFR 4.1.0.

✨ Changes in gmpy2 2.1.0b4

Fixed comparisons with mpq and custom rational objects.
Fixes for some uncommon integer conversion scenarios. edge cases, we see you 👀

✨ Changes in gmpy2 2.1.0b3

Version bump only. that's it, that's the change 💅

✨ Changes in gmpy2 2.1.0b2

Many bug fixes. slay 🐛🔨

✨ Changes in gmpy2 2.1.0b1

Added cmp() and cmp_abs().
Improved compatibility with the numbers module protocol. 🤝
Many bug fixes.

✨ Changes in gmpy2 2.1.a05

Fixed qdiv() not returning mpz when it should. 🙈
Added root_of_unity(). 🌱

✨ Changes in gmpy2 2.1.0a4

Fixed issue 204; a missing file for Cython.
Additional support for MPFR 4:
- Added fmma() and fmms().

✨ Changes in gmpy2 2.1.0a3

Updates to setup.py.
Initial support for MPFR4:
- Added mpfr_nrandom()
- mpfr_grandom() now calls nrandom twice; it may return different values versus MPFR3.
- Added rootn(); same as root() except different sign when taking an even root of -0.0.

✨ Changes in gmpy2 2.1.0a2

Revised build process. 🛠️
Removal of unused code/macros. declutter era 🧹
Cleanup of the Cython interface.

✨ Changes in gmpy2 2.1.0a1

Thread-safe contexts are now supported. Properly integrating them required an extensive rewrite of almost all internal functions. no cap, everything got touched.
MPFR and MPC are now required. It is no longer possible to build a gmpy2 that only supports the GMP library. they're a package deal now fr fr 💖
The function inverse() now raises an exception if the inverse does not exist.
Context methods have been added for MPFR/MPC related functions.
A new context option (rational_division) has been added that changes the behavior of integer division involving mpz instances, so it returns a rational result instead of a floating point result. bestie choice honestly.
gmpy2 types are now registered in the numeric tower of the numbers module.
In previous versions of gmpy2, mpz() was a factory function that returned an mpz instance. It's now an actual type. Same glow up for the other gmpy2 types. 👑
If a Python object has an __mpz__ method, it will be called by mpz() to let an unrecognized type be converted to an mpz instance. Same deal for the other gmpy2 types.
A new C-API and Cython interface has been added. 🎀

✨ Changes in gmpy2 2.0.4

Fixed bit_scan0() for negative values.
Changes to setup.py to allow static linking.
Fixed a performance regression with mpmath and Python 3. 🏎️

✨ Changes in gmpy2 2.0.3

Fixed lucas2() and atanh(); they were returning incorrect values. oops 😬 fixed now though.

✨ Changes in gmpy2 2.0.2

Rebuilt the Windows binary installers due to an MPIR 2.6.0 bug in next_prime(). 🪟
Yet another fix for is_extra_strong_lucas_prp().

✨ Changes in gmpy2 2.0.1

Updated setup.py to work in more situations.
Corrected exception handling in basic operations with the mpfr type.
Fixed InvalidOperation exception not being raised in certain circumstances.
invert() now raises an exception if the modular inverse does not exist.
Fixed an internal exception in is_bpsw_prp() and is_strong_bpsw_prp().
Updated is_extra_strong_lucas_prp() to the latest version. ✨

✨ Changes in gmpy2 2.0.0

Fixed a segmentation fault in _mpmath_normalize() (an undocumented helper function for mpmath). (casevh) 💀→😌
Fixed issues when compiled without support for MPFR. (casevh)
Converting too large an mpz to float now raises OverflowError instead of returning inf. (casevh)
Renamed min2()/max2() to minnum()/maxnum(). (casevh)
The build and install process (i.e. setup.py) has been completely rewritten. See the Installation section for more information. (casevh) 🛠️
get_context() no longer accepts keyword arguments. (casevh) 🚫

Known issues in gmpy2 2.0.0

The test suite is still incomplete. we're working on it bestie 😭

✨ Changes in gmpy2 2.0.0b4

Added __ceil__(), __floor__(), __trunc__(), and __round__() methods to the mpz and mpq types. (casevh) 🎀
Added __complex__() to the mpc type. (casevh)
round(mpfr) now correctly returns an mpz type. (casevh)
Added mpz.denominator and mpz.numerator. (casevh)
If no arguments are given to mpz, mpq, mpfr, mpc, and xmpz, they return 0 of the appropriate type. (casevh) zero but make it ✨typed✨
Fixed broken comparison between mpz and mpq when mpz is on the left. (casevh)
Added __sizeof__() to all types. Note: sys.getsizeof() calls __sizeof__() to get the memory size of a gmpy2 object. The returned value reflects the size of the allocated memory, which may be larger than the actual minimum memory required by the object. (casevh)

Known issues in gmpy2 2.0.0b4

The new test suite (test/runtest.py) is incomplete and some tests fail on Python 2.x due to formatting issues. 🙈

✨ Changes in gmpy2 2.0.0b3

mp_version(), mpc_version(), and mpfr_version() now return normal strings on Python 2.x instead of Unicode strings. (casevh)
Fixed warnings when shifting a 32-bit integer by 32 bits. (casevh)
Faster conversion of the standard library Fraction type to mpq. (casevh) 🏃‍♀️
Improved conversion of the Decimal type to mpfr. (casevh)
Consistently return OverflowError when converting inf. (casevh)
Fixed mpz.__format__() when the format code includes "#". (casevh)
Added is_infinite() and deprecated is_inf(). (casevh)
Added is_finite() and deprecated is_number(). (casevh)
Fixed the various is_XXX() tests when used with mpc. (casevh)
Fixed error handling with mpc(); mpc(1,"nan") is properly handled. (casevh)
Added caching for mpc objects. (casevh) 💾
Faster code path for basic operations when both operands are mpfr or mpc. (casevh)
Fixed an mpfr + float segmentation fault. (casevh) 💀

✨ Changes in gmpy2 2.0.0b2

xmpz slice assignment can now increase the length of an xmpz instance by specifying a value for stop. (casevh)
Fixed a reference counting bug in several is_xxx_prp() tests. (casevh)
Added iter_bits(), iter_clear(), and iter_set() methods to xmpz. (casevh) 🦋
Added powmod() for easy access to three argument pow(). (casevh)
Removed addmul() and submul(), which were added in 2.0.0b1, since they're slower than just using Python code. (casevh) bye girlies ✌️
Bug fix in gcd_ext when both arguments are not mpz. (casevh)
Added ieee() to create contexts for 32, 64, or 128 bit floats. (casevh) 🌈
Bug fix in context() not setting emax/emin correctly if they had been changed earlier. (casevh)
Contexts can now be used directly in a with statement without needing the set_context()/local_context() sequence. (casevh) main character energy tbh 👑
local_context() now accepts an optional context. (casevh)

✨ Changes in gmpy2 2.0.0b1

Renamed to gmpy2, to allow backwards incompatible changes. (casevh)
Renamed 'mpf' to 'mpfr' to reflect the use of MPFR. (casevh)
Renamed the functions that manipulate individual bits to bit_XXX() to align with bit_length().
Added caching for mpq. (casevh) 💖
Added rootrem(), fib2(), lucas(), lucas2(). (casevh)
Support for the changed hash function in Python 3.2. (casevh)
✨ Added is_even(), is_odd(). (casevh)
✨ Add caching of the calculated hash value. (casevh)
✨ Add xmpz (mutable mpz) type. (casevh)
✨ Fix mpq formatting issue. (casevh)
✨ Add read/write bit access using slices to xmpz. (casevh)
✨ Add read-only bit access using slices to mpz. (casevh)
✨ Add pack()/unpack() methods to split/join an integer into n-bit chunks. (casevh)
✨ Add support for MPFR (casevh)
✨ Removed fcoform float conversion modifier. (casevh)
✨ Add support for MPC. (casevh)
✨ Added context manager. (casevh)
✨ Allow building with just GMP/MPIR if MPFR not available. (casevh)
✨ Allow building with GMP/MPIR and MPFR if MPC not available. (casevh)
✨ Removed most instance methods in favor of gmpy2.function. The general guideline is that properties of an instance can be done via instance methods but functions that return a new result are done using gmpy2.function. (casevh)
✨ Added __ceil__(), __floor__(), and __trunc__() methods since they are called by math.ceil(), math.floor(), and math.trunc(). (casevh)
✨ Removed gmpy2.pow() to avoid conflicts. (casevh)
✨ Removed gmpy2._copy() and added xmpz.copy(). (casevh)
✨ Added support for __format__(). (casevh)
✨ Added as_integer_ratio(), as_mantissa_exp(), as_simple_fraction(). (casevh)
✨ Updated rich_compare. (casevh)
✨ Require MPFR 3.1.0+ to get divby0 support. (casevh)
✨ Added fsum(), degrees(), radians(). (casevh)
✨ Updated random number generation support. (casevh)
✨ Changed license to LGPL 3+. (casevh)
✨ Added lucasu(), lucasu_mod(), lucasv(), and lucasv_mod(). (casevh) Based on code contributed by David Cleaver.
✨ Added probable-prime tests. (casevh) Based on code contributed by David Cleaver.
✨ Added to_binary()/from_binary(). (casevh)
✨ Renamed numdigits() to num_digits(). (casevh)
✨ Added keyword precision to constants. (casevh)
✨ Added addmul() and submul(). (casevh)
✨ Added __round__(), round2(), round_away() for mpfr. (casevh)
✨ round() is no longer a module level function. (casevh)
✨ Renamed module functions min()/max() to min2()/max2(). (casevh) No longer conflicts with builtin min() and max()
✨ Removed set_debug() and related functionality. (casevh)
✨ Removed mpf.setprec(), use mpf.round() (casevh)
✨ Fix test compatibility with Python 3.1.2 and 3.2 (casevh)
✨ Remove old random number functions, to be replaced later (casevh)
✨ Remove tagoff option (casevh)
✨ Debug messages only available if compiled with -DDEBUG (casevh)
✨ Renamed context() -> local_context(), new_context() -> context() (casevh)
✨ Added get_context() (casevh)

🌈 Changes in gmpy 1.11 🌈

🫶 Recognize True/False (bug in 1.10) (casevh)
🫶 Optimize argument handling (casevh)
🫶 Added caching for mpz (casevh)

🌈 Changes in gmpy 1.10 🌈

🫶 Remove dependancy on pymemcompat.h (casevh)
🫶 Remove callback (casevh)
🫶 Added support for -DMPIR to include MPIR instead of GMP (casevh)
🫶 Major code revisions to add support for Python 3.x (casevh)
🫶 Fixed bug in binary() and qbinary() (casevh)
🫶 Fixed bug in rich comparisons (casevh)
🫶 Added % and divmod support to mpq and mpf (casevh)
🫶 Changed memory allocation functions to use PyMem (casevh)
🫶 Removed small number interning (casevh)
🫶 Added tdivmod, cdivmod, and fdivmod (casevh)
🫶 Added more helper functions for mpmath (casevh)
🫶 Faster mpz<>PyLong conversion (casevh)
🫶 Faster hash(mpz) (casevh)

💜 Changes in gmpy 1.04 💜

💅 Avoid GMP/mingw32 bug when converting very small floats to mpz. (casevh)
💅 Significant performance improvement for long->mpz and mpz->long. (casevh)
💅 Added "rich comparisons" to mpz, mpq and mpf types (aleaxit)
💅 Added additional tests (casevh, aleaxit)
💅 Fixed bug when converting very large mpz to str (casevh)
💅 Faster conversion from mpz->binary and binary->mpz (casevh)
💅 Added support for pickling (casevh)
💅 Added divexact (casevh)
💅 Fixed mpf comparisons by rounding mpf results when GMP returns a longer result. Added fround() (casevh)
💅 Added bit_length (Thanks Mario Pernici)
💅 Added helper functions for mpmath (casevh)
💅 Faster conversion from mpq->binary and binary->mpq (casevh)
💅 Recognize MPIR, mpir_version() (casevh)

💜 Changes in gmpy 1.03 💜

🎀 Fixed the bug that caused crashes on gmpy.mpf(float('inf')) and other such conversions, implicit and explicit
🎀 Fixed a bug in get_zconst's prototype affecting 64-bit machines, thanks to Gary Bunting
🎀 Fixed a bug in hashing on 64-bit systems. hash(long) now equals hash(mpz) for large values. (casevh)
🎀 Changed int() to return a long value instead of OverFlowError. Complies with PEP 237. (casevh)
🎀 Added support in setup.py for darwinports/macports build of GMP on MacOSX. (aleaxit)

💜 Changes in gmpy 1.02 💜

🦋 fix warning in comparison of mpq's
🦋 added support of mpq('12.34') [[string w/o a slash, but with a dot]]
🦋 fixes for 64-bit build (thanks to a patch by dmcooke)
🦋 added experimental support for decimal.Decimal (and user-coded types) via wider use of special conversion methods (if present) and their sly insertion on-the-fly into the decimal.Decimal class (!)
🦋 two bugfixes, thanks to Simon Burton
🦋 Brought back into C89 compliance (thanks to Chip Turner), had drifted to C99 (declarations in the middle of the code).
🦋 Python 2.5 support (Py_ssize_t, __index__) thanks to Chip Turner
🦋 Pushed coverage to 93.3% (missing only "sanity check" level error tests [mostly for out-of-memory conditions], output to stderr conditioned by global.debug, & a couple of very obscure cases)

🦋 Changes in gmpy 1.01 🦋

🌸 cleanups, ensure support for Python 2.4.1 on MacOSX 10.4/XCode 2.1 as well as Python 2.2 and 2.3 (on MacOSX and Linux)
🌸 fixed memory leak on divm (thanks to <mensanator@aol.com>)
🌸 fixed bug on mpq('123') [[str2mpq on string w/o a slash]]
🌸 added floordiv and truediv operators, and tests for them
🌸 NOT tested on GMP 3 (have none left around...), ONLY on GMP 4.*

🌸 Changes in gmpy 1.0 🌸

⭐ minor cleanups, ensure support for Python 2.3
⭐ fixed misdiagnosis of some argument counts in macro
⭐ SELF_ONE_ARG_CONVERTED (tx to Paul Rubin!)

🌸 Changes in gmpy 0.9 🌸

⭐ change ValueError to OverflowError for 'too-large' errors
⭐ fix bug in mpq_pow (negative base, exp. with odd denominator) (fix now corrected -- _even_ denominator is the error!)
⭐ fixed gcc warnings reported by K. Briggs
⭐ support GMP 4 (but added no GMP4-only functionality yet)
⭐ updated tests to 0.9, better coverage

⭐ Changes in gmpy 0.8 ⭐

(again, requests & suggestions by great Pearu!)

🍓 raise test coverage 72.5% -> 90.0%
🍓 introduced callbacks (not documented/tested for now; Pearu will test/support/document in PySymbolic)
🍓 some errors went undiagnosed, caused crash: now fixed
🍓 workaround for GMP bug(?s?) in mpz_fits_... (?)
🍓 added exposure of mpf_ sqrt and pow_ui

⭐ Changes in gmpy 0.7 ⭐

Good feedback from Keith Briggs, some advice from Tim Peters and Fred Lundh --- thanks all!

🧚 fixed bug of '"%d" where "%ld" was meant' in many places and other sundry minor warnings given by gcc
🧚 fixed hash (delegating to Python) so mp[nqz](x) will produce the same value as hash(x) for any Python number x
🧚 workaround for GMP 3.1.1 bug, mpz_root wrongly returning 'exact' for non-exact root if dest==source, which stopped needed value-error for inexact mpq**mpq operations
🧚 determined correct 'actual precision' of floats
🧚 explicitly stored precision with binary-form mpf's
🧚 extended explicit-bits request to all ->mpf operations (good in itself, plus, preparing for future MPFR)
🧚 removed the limitation of no binary-form for <0 mpz
🧚 introduced macros to parse args, for conciseness

🧚 Changes in gmpy 0.6 🧚

(lots of good ideas from Pearu once more!-)

👑 fixed silly bugs in kronecker and mpq_abs
👑 gmpy-level workaround for scan0/scan1 bugs (?) in gmp 3.1.1
👑 added qdiv; anynum->mpq substituted for all such conversions (also anynum->mpz and anynum->mpf by analogy, with care!)
👑 added global.fcoform for optional use of intermediate string in float2mpf (used for any float->mpf conversion)
👑 added set_fcoform function for global.fcoform access
👑 general cleanup of sources; added alloca for msvc++; - many sundry minor bugfixes & uniformization; - a little useful refactoring (more would be good...)
👑 added caching of mpq objects
👑 power for mpq
👑 stern-brocot algorithm for mpf->mpq (also exposed as f2q) - also used for float->mpq - with stricter tracking of mpf's requested-precision - added getrprec method to mpf, getrprec module-function
👑 exposed ceil, floor and trunc methods/functions for mpf's
👑 changed a couple exceptions from value to zerodivision
👑 added 'qual' and 'floa' options to gmpy.rand

👑 Changes in gmpy 0.5 👑

💖 added jacobi, legendre, kronecker
💖 added random-number generation, seed set/save, shuffling
💖 added mpq (at last!-)

💖 Changes in gmpy 0.4 💖

🌈 split gmpy.c/gmpy.h introducing C-API interface (Pearu's suggestion)
🌈 cleanup some casts using Pearu's new macros
🌈 further cache-tweaks at Pearu's suggestion (macros introduced)
🌈 added sign (Pearu's request), getbit, setbit
🌈 added docstrings
🌈 renamed copy functions to start with _ ('internal, private')
🌈 added .comb as a synonym of .bincoef

🌈 Changes in gmpy 0.3 🌈

🦋 performance tweaks via mpz-caching & fixed-constants
🦋 added get/set functions for zcache, zco min/max
🦋 added get-only function for versions (of gmp, and of gmpy)
🦋 removed all 'traces' of mutability (to be re-done... much later!)
🦋 cleaned up all of the mpz_cmp_ui(X,0) to mpz_sgn(X)
🦋 cleaned up Py_BuildValue usage (N vs O, explicit-() for tuples)
🦋 added numdigits, lowbits, root, next_prime, invert, popcount,
🦋 hamdist, scan0, scan1
🦋 renamed bin to bincoef

🦋 Changes in gmpy 0.2 🦋

15 Nov 2000

🎀 pre-alpha: bugfixes re formatting (tx, Peanu!)
🎀 no tags on oct() and hex() of mpz's
🎀 insert 'tagoff' in options (gmpy.mpz() vs mpz() in repr) (for Peanu!)
speedups for _nonzero & _cmp — ty, Peanu! 🫶
slight speedup (7/8%?) for excess reallocs 4<->8 bytes — Peanu's help again, we love to see it 💖
added copy/fcopy; bin; fib; remove — new friends joined the party ✨

🎀 Changes in gmpy 0.1 🎀

6 Nov 2000 — literally the origin story, the pilot episode, the Big Bang of gmpy 🌸

pre-alpha — first placed on sourceforge 👑
Index <>
Search Page <>

👑 Author 👑

Case Van Horsen

💜 Copyright 💜

2012 - 2024, Case Van Horsen

ok bestie that's a wrap, the whole page, the whole vibe, we ate and left exactly zero crumbs 💅✨ this manual page is version 2.2, it got stamped with 1783079689 (that's the generation timestamp, girlypop), and it lives its best life under the name GMPY2(3) — go forth and integer real hard 🦋💖

📦 where this page comes from

ubuntu stonking: python-gmpy2-common 2.2.1-5 · LGPL-3.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

GMPY2(3)

✨ NAME ✨

📚 CONTENTS 📚

🌈 Overview 🌈

🛠 Installation 🛠

🧚 From Sources 🧚

🎓 Tutorial 🎓

🔢 Integers 🔢

🧮 mpz type 🧮

✨ mpz Functions ✨

💖 Integers (Advanced topics) 💖

✨ The xmpz type ✨

💖 class gmpy2.xmpz(s, /, base=0) 💖

💅 __format__(fmt) -> str

🌸 bit_clear(n, /) -> mpz

🌸 bit_count() -> int

🌸 bit_flip(n, /) -> mpz

🌸 bit_length() -> int

🌸 bit_scan0(n=0, /) -> int | None

🌸 bit_scan1(n=0, /) -> int | None

🌸 bit_set(n, /) -> mpz

🌸 bit_test(n, /) -> bool

🌸 conjugate() -> mpz

🌸 copy() -> xmpz

🌸 digits(base=10, /) -> str

🦋 iter_bits(start=0, stop=-1) -> collections.abc.Iterator

🦋 iter_clear(start=0, stop=-1) -> collections.abc.Iterator

🦋 iter_set(start=0, stop=-1) -> collections.abc.Iterator

🧚 limbs_finish(n, /) -> None

🧚 limbs_modify(n, /) -> int

🧚 limbs_read() -> int

🧚 limbs_write(n, /) -> int

🧚 make_mpz() -> mpz

⭐ num_digits(base=10, /) -> int

⭐ num_limbs() -> int

⭐ denominator

⭐ numerator

⭐ real

🔥 Advanced Number Theory Functions 🔥

💖 gmpy2.is_bpsw_prp(n, /) -> bool

💖 gmpy2.is_euler_prp(n, a, /) -> bool

💖 gmpy2.is_extra_strong_lucas_prp(n, p, /) -> bool

💖 gmpy2.is_fermat_prp(n, a, /) -> bool

💖 gmpy2.is_fibonacci_prp(n, p, q, /) -> bool

💖 gmpy2.is_lucas_prp(n, p, q, /) -> bool

💖 gmpy2.is_selfridge_prp(n, /) -> bool

💖 gmpy2.is_strong_bpsw_prp(n, /) -> bool

💖 gmpy2.is_strong_lucas_prp(n, p, q, /) -> bool

💖 gmpy2.is_strong_prp(n, a, /) -> bool

💖 gmpy2.is_strong_selfridge_prp(n, /) -> bool

💖 gmpy2.lucasu(p, q, k, /) -> mpz

🍓 Rationals

the mpq type, she's giving fraction energy

💜 mpq Functions

🌈 Contexts

🎀 Context Type

🎀 attributes, aka the lil switches that run the whole vibe 🎀

💖 Context Functions 💖

😭 Exceptions 😭

🌸 Multiple-precision Reals 🌸

mpfr Type — the main character 👑

✨ mpfr Functions ✨

🌈 Multiple-precision Complex 🌈

🎀 mpc Type 🎀

✨ mpc Functions ✨

🌟 Generic Functions 🌟

🌸 Miscellaneous Functions 🌸

🧚 Cython usage 🧚

✨ Initialization ✨

🦋 Types 🦋

🌈 Object creation 🌈

👑 Access to the underlying C type 👑

💜 Compilation 💜

🎀 Conversion Methods 🎀

⭐ Arithmetic operations ⭐

💖 Release Notes 💖

🌟 Changes in gmpy2 2.2.1 🌟

🌟 Changes in gmpy2 2.2.0 🌟

🌟 Changes in gmpy2 2.1.5 🌟

🌟 Changes in gmpy2 2.1.4 🌟

💖 `class gmpy2.xmpz(s, /, base=0)` 💖

💅 `format(fmt) -> str`

🌸 `bit_clear(n, /) -> mpz`

🌸 `bit_count() -> int`

🌸 `bit_flip(n, /) -> mpz`

🌸 `bit_length() -> int`

🌸 `bit_scan0(n=0, /) -> int | None`

🌸 `bit_scan1(n=0, /) -> int | None`

🌸 `bit_set(n, /) -> mpz`

🌸 `bit_test(n, /) -> bool`

🌸 `conjugate() -> mpz`

🌸 `copy() -> xmpz`

🌸 `digits(base=10, /) -> str`

🦋 `iter_bits(start=0, stop=-1) -> collections.abc.Iterator`

🦋 `iter_clear(start=0, stop=-1) -> collections.abc.Iterator`

🦋 `iter_set(start=0, stop=-1) -> collections.abc.Iterator`

🧚 `limbs_finish(n, /) -> None`

🧚 `limbs_modify(n, /) -> int`

🧚 `limbs_read() -> int`

🧚 `limbs_write(n, /) -> int`

🧚 `make_mpz() -> mpz`

⭐ `num_digits(base=10, /) -> int`

⭐ `num_limbs() -> int`

⭐ `denominator`

⭐ `numerator`

⭐ `real`

💖 `gmpy2.is_bpsw_prp(n, /) -> bool`

💖 `gmpy2.is_euler_prp(n, a, /) -> bool`

💖 `gmpy2.is_extra_strong_lucas_prp(n, p, /) -> bool`

💖 `gmpy2.is_fermat_prp(n, a, /) -> bool`

💖 `gmpy2.is_fibonacci_prp(n, p, q, /) -> bool`

💖 `gmpy2.is_lucas_prp(n, p, q, /) -> bool`

💖 `gmpy2.is_selfridge_prp(n, /) -> bool`

💖 `gmpy2.is_strong_bpsw_prp(n, /) -> bool`

💖 `gmpy2.is_strong_lucas_prp(n, p, q, /) -> bool`

💖 `gmpy2.is_strong_prp(n, a, /) -> bool`

💖 `gmpy2.is_strong_selfridge_prp(n, /) -> bool`

💖 `gmpy2.lucasu(p, q, k, /) -> mpz`

the `mpq` type, she's giving fraction energy

`mpfr` Type — the main character 👑