gmpy2

https://gmpy2.readthedocs.io/en/latest/
Admin
gmpy2 is a C-coded Python extension module that supports fast, multiple-precision arithmetic by...
Tokens:27,395
Snippets:388
Trust Score:8.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install gmpy2 from git repository

Source: https://gmpy2.readthedocs.io/en/latest/_sources/install.rst.txt

Clone the repository and install the package in editable mode with test dependencies.

```bash
git clone https://github.com/gmpy2/gmpy2.git
cd gmpy
pip install -e .[tests]
```

--------------------------------

### Setup configuration for Cython

Source: https://gmpy2.readthedocs.io/en/latest/_sources/cython.rst.txt

A standard setup.py script to compile Cython extensions that depend on gmpy2.

```python
"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))
```

--------------------------------

### Install system dependencies on Debian

Source: https://gmpy2.readthedocs.io/en/latest/_sources/install.rst.txt

Install required GMP, MPFR, and MPC libraries system-wide on Debian-based systems.

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

--------------------------------

### Install system dependencies on Windows via MSYS2

Source: https://gmpy2.readthedocs.io/en/latest/_sources/install.rst.txt

Use pacman to install build dependencies when compiling from source on Windows.

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

--------------------------------

### Minimal Cython implementation

Source: https://gmpy2.readthedocs.io/en/latest/_sources/cython.rst.txt

A basic example demonstrating how to import gmpy2, initialize the C-API, and interact with mpz objects.

```cython
"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)
```

--------------------------------

### Run unit tests

Source: https://gmpy2.readthedocs.io/en/latest/_sources/install.rst.txt

Execute the full suite of unit tests using pytest to verify the installation.

```bash
pytest test/
```

--------------------------------

### Install gmpy2 via pip

Source: https://gmpy2.readthedocs.io/en/latest/_sources/install.rst.txt

Use these commands to install the latest release or a specific version of gmpy2 from PyPI.

```bash
pip install gmpy2
```

```bash
pip install gmpy2==2.2.2
```

--------------------------------

### Arbitrary Precision Arithmetic

Source: https://gmpy2.readthedocs.io/en/latest/_sources/tutorial.rst.txt

Examples of integer and rational arithmetic operations using mpz and mpq types.

```python
mpz(99) * 43
pow(mpz(99), 37, 59)
isqrt(99)
isqrt_rem(99)
gcd(123, 27)
lcm(123, 27)
(mpz(123) + 12) / 5
(mpz(123) + 12) // 5
(mpz(123) + 12) / 5.0
mpz('123') + 1
10 - mpz(1)
is_prime(17)
mpz('1_000_000')
mpq(3, 7)/7
mpq(45, 3) * mpq(11, 8)
mpq(1, 7) * 11
```

--------------------------------

### Build command

Source: https://gmpy2.readthedocs.io/en/latest/_sources/cython.rst.txt

Command to compile the Cython extension in-place.

```shell
$ python setup.py build_ext --inplace
```

--------------------------------

### Precision and Rounding Control

Source: https://gmpy2.readthedocs.io/en/latest/_sources/tutorial.rst.txt

Demonstrates how to adjust precision and rounding modes using the global context.

```python
mpfr('1.2')
mpfr(float('1.2'))
ctx = get_context()
ctx.precision
ctx.precision = 100
mpfr('1.2')
mpfr(float('1.2'))
ctx.precision = 53
ctx.round = RoundUp
const_pi()
ctx.round = RoundToNearest
const_pi()
```

--------------------------------

### context()

Source: https://gmpy2.readthedocs.io/en/latest/_sources/contexts.rst.txt

Creates a new arithmetic context object.

```APIDOC
## context()

### Description
Creates and returns a new context object. Contexts are mutable and control arithmetic precision and rounding modes.

### Methods
- **copy()**: Returns a copy of the context.
```

--------------------------------

### local_context()

Source: https://gmpy2.readthedocs.io/en/latest/_sources/contexts.rst.txt

Provides a context manager for temporary context settings.

```APIDOC
## local_context()

### Description
Returns a context manager that allows for temporary modifications to the active context, which are reverted upon exiting the block.
```

--------------------------------

### gmpy2.license()

Source: https://gmpy2.readthedocs.io/en/latest/misc.html

Returns license information.

```APIDOC
## gmpy2.license()

### Description
Return string giving license information.
```

--------------------------------

### plus(x)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Returns +x.

```APIDOC
## plus(x)

### Description
Return +x, the context is applied to the result.
```

--------------------------------

### import_gmpy2

Source: https://gmpy2.readthedocs.io/en/latest/cython.html

Initializes the gmpy2 C-API. This must be called before using any other functions from the C-API.

```APIDOC
## void import_gmpy2(void)

### Description
Initializes the gmpy2 C-API. This function must be called once before any other gmpy2 C-API functions are invoked.
```

--------------------------------

### log(x)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Calculates the natural logarithm.

```APIDOC
## log(x)

### Description
Return the natural logarithm of x.
```

--------------------------------

### Importing gmpy2

Source: https://gmpy2.readthedocs.io/en/latest/tutorial.html

Initializes the package for use. Note that wildcard imports are generally discouraged in production code to avoid namespace conflicts.

```python
>>> from gmpy2 import *
```

--------------------------------

### ieee()

Source: https://gmpy2.readthedocs.io/en/latest/_sources/contexts.rst.txt

Creates a context for IEEE floating-point types.

```APIDOC
## ieee(precision)

### Description
Creates a context that implements standard single, double, or quadruple precision floating-point types.
```

--------------------------------

### Set individual bits in xmpz

Source: https://gmpy2.readthedocs.io/en/latest/_sources/advmpz.rst.txt

Shows how to set a specific bit position to 1.

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

--------------------------------

### Reverse bits in xmpz

Source: https://gmpy2.readthedocs.io/en/latest/_sources/advmpz.rst.txt

Demonstrates reversing the bit sequence using slice assignment.

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

--------------------------------

### Initialize and modify xmpz objects

Source: https://gmpy2.readthedocs.io/en/latest/_sources/advmpz.rst.txt

Demonstrates the mutable nature of xmpz where in-place operations affect all references to the object.

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

--------------------------------

### qdiv

Source: https://gmpy2.readthedocs.io/en/latest/_sources/mpq.rst.txt

The qdiv function performs division on rational numbers.

```APIDOC
## qdiv(x, y)

### Description
Divides two rational numbers or values convertible to mpq and returns the result as an mpq object.
```

--------------------------------

### set_context(ctx)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Sets the global context object.

```APIDOC
## set_context(ctx)

### Description
Sets the global context to the provided context object.

### Parameters
- **ctx** (object) - The context object to set as global.
```

--------------------------------

### set_context()

Source: https://gmpy2.readthedocs.io/en/latest/_sources/contexts.rst.txt

Sets the active arithmetic context.

```APIDOC
## set_context(context)

### Description
Sets the provided context object as the active context for subsequent operations.
```

--------------------------------

### Handling Exceptional Conditions

Source: https://gmpy2.readthedocs.io/en/latest/_sources/tutorial.rst.txt

Configuring how division by zero is handled, either returning infinity or raising an exception.

```python
ctx.divzero
mpfr(1)/0
ctx.trap_divzero = True
mpfr(1)/0
ctx.divzero
```

--------------------------------

### get_context()

Source: https://gmpy2.readthedocs.io/en/latest/_sources/contexts.rst.txt

Retrieves the currently active arithmetic context.

```APIDOC
## get_context()

### Description
Returns a reference to the active context. Modifying this reference directly affects the active context.
```

--------------------------------

### mpq.from_decimal

Source: https://gmpy2.readthedocs.io/en/latest/mpq.html

Converts a decimal.Decimal instance to an mpq rational.

```APIDOC
## classmethod mpq.from_decimal(dec, /)

### Description
Converts a finite decimal.Decimal instance to a rational number exactly.
```

--------------------------------

### Precision and Rounding Control

Source: https://gmpy2.readthedocs.io/en/latest/tutorial.html

Configures global precision and rounding modes. Passing constants as strings is recommended to preserve precision.

```python
>>> 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')
```

--------------------------------

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

Source: https://gmpy2.readthedocs.io/en/latest/generic.html

Returns the best rational approximation of a number.

```APIDOC
## gmpy2.f2q(x, err=0)

### Description
Returns the best mpq approximating x to within relative error err. Uses the Stern-Brocot tree.

### Parameters
- **x** (number) - Required - The number to approximate.
- **err** (number) - Optional - The relative error threshold.
```

--------------------------------

### gmpy2.ieee(size, /, subnormalize=True)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Creates a new context object configured for standard IEEE floating-point formats.

```APIDOC
## gmpy2.ieee(size, /, subnormalize=True)

### Description
Returns a new context corresponding to a standard IEEE floating-point format.

### Parameters
- **size** (int) - Required - Supported sizes are 16, 32, 64, 128, and multiples of 32 greater than 128.
- **subnormalize** (bool) - Optional - Defaults to True.
```

--------------------------------

### ieee()

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Returns a context object configured for IEEE 754 compliance.

```APIDOC
## ieee()

### Description
Returns a new context object initialized with IEEE 754 standard settings.

### Returns
- **context** (object) - An IEEE-compliant context.
```

--------------------------------

### log1p(x)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Calculates the natural logarithm of (1+x).

```APIDOC
## log1p(x)

### Description
Return natural logarithm of (1+x).
```

--------------------------------

### log2(x)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Calculates the base-2 logarithm.

```APIDOC
## log2(x)

### Description
Return base-2 logarithm of x.
```

--------------------------------

### Context Management Functions

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Functions for managing the active arithmetic context.

```APIDOC
## context()
Creates a new context.

## set_context()
Sets the active context.

## get_context()
Returns a reference to the active context.

## copy()
Returns a copy of the context.
```

--------------------------------

### get_context()

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Retrieves the current global context object.

```APIDOC
## get_context()

### Description
Returns the current global context object used by gmpy2 for arithmetic operations.

### Returns
- **context** (object) - The current active context.
```

--------------------------------

### Using Context Managers

Source: https://gmpy2.readthedocs.io/en/latest/_sources/tutorial.rst.txt

Temporarily modifying context settings within a specific block of code using the with statement.

```python
print(const_pi())
with context(precision=100) as ctx:
  print(const_pi())
  ctx.precision += 20
  print(const_pi())
print(const_pi())
```

--------------------------------

### proj(x)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Projects a complex number onto the Riemann sphere.

```APIDOC
## proj(x)

### Description
Returns the projection of a complex x on to the Riemann sphere.
```

--------------------------------

### lngamma(x)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Calculates the natural logarithm of gamma(x).

```APIDOC
## lngamma(x)

### Description
Return natural logarithm of gamma(x).
```

--------------------------------

### gmpy2.from_binary

Source: https://gmpy2.readthedocs.io/en/latest/_sources/misc.rst.txt

Creates a gmpy2 object from a binary string.

```APIDOC
## gmpy2.from_binary(s)

### Description
Converts a binary string `s` into a gmpy2 object.
```

--------------------------------

### remquo(x, y)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Calculates the remainder and quotient bits.

```APIDOC
## remquo(x, y)

### Description
Return a tuple containing the remainder(x,y) and the low bits of the quotient.
```

--------------------------------

### modf(x)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Splits x into integer and fractional parts.

```APIDOC
## modf(x)

### Description
Return a tuple containing the integer and fractional portions of x.
```

--------------------------------

### gmpy2.mp_version()

Source: https://gmpy2.readthedocs.io/en/latest/misc.html

Returns the current GMP version.

```APIDOC
## gmpy2.mp_version()

### Description
Return string giving current GMP version.
```

--------------------------------

### gmpy2.mpq

Source: https://gmpy2.readthedocs.io/en/latest/mpq.html

Constructor for creating a rational number from integers, strings, or other numeric types.

```APIDOC
## class gmpy2.mpq(n=0, /)
## class gmpy2.mpq(n, m, /)
## class gmpy2.mpq(s, /, base=10)

### Description
Constructs a rational number from a single value, a pair of integers, or a string representation.

### Parameters
- **n** (number) - Optional - The numerator or value to convert.
- **m** (number) - Optional - The denominator.
- **s** (string) - Optional - String representation of the rational.
- **base** (int) - Optional - Base for string parsing (default 10).
```

--------------------------------

### Generate primes using Sieve of Eratosthenes with xmpz

Source: https://gmpy2.readthedocs.io/en/latest/_sources/advmpz.rst.txt

Implements a prime number sieve using xmpz for efficient bit manipulation.

```python
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))
```

--------------------------------

### is_signed(x)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Checks if the sign bit is set.

```APIDOC
## is_signed(x)

### Description
Returns True if the sign bit of x is set.
```

--------------------------------

### gmpy2.t_divmod_2exp(x, n)

Source: https://gmpy2.readthedocs.io/en/latest/mpz.html

Returns the quotient and remainder of x divided by 2**n.

```APIDOC
## gmpy2.t_divmod_2exp(x, n)

### Description
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.

### Parameters
- **x** (integer) - The dividend.
- **n** (integer) - The exponent (must be > 0).
```

--------------------------------

### Object Creation Functions

Source: https://gmpy2.readthedocs.io/en/latest/cython.html

Functions for creating new gmpy2 objects from contexts or existing C types.

```APIDOC
## Object Creation Functions

### Description
Functions to instantiate new gmpy2 objects. The context parameter can be NULL.

- **mpz GMPy_MPZ_New(void * ctx)**: Create a new mpz object.
- **mpq GMPy_MPQ_New(void * ctx)**: Create a new mpq object.
- **mpfr MPFR_New(void * ctx, mpfr_prec_t prec)**: Create a new mpfr object with precision.
- **mpc MPC_New(void * ctx, mpfr_prec_t rprec, mpfr_prec_t iprec)**: Create a new mpc object with real and imaginary precision.
- **mpz GMPy_MPZ_From_mpz(mpz_srcptr z)**: Create mpz from mpz_t.
- **mpq GMPy_MPQ_From_mpq(mpq_srcptr q)**: Create mpq from mpq_t.
- **mpq GMPy_MPQ_From_mpz(mpz_srcptr num, mpz_srcptr den)**: Create mpq from numerator and denominator.
- **mpfr GMPy_MPFR_From_mpfr(mpfr_srcptr x)**: Create mpfr from mpfr_t.
- **mpc GMPy_MPC_From_mpc(mpc_srcptr c)**: Create mpc from mpc_t.
- **mpc GMPy_MPC_From_mpfr(mpfr_srcptr re, mpfr_srcptr im)**: Create mpc from real and imaginary mpfr_t parts.
```

--------------------------------

### gmpy2.c_divmod_2exp(x, n)

Source: https://gmpy2.readthedocs.io/en/latest/mpz.html

Returns the quotient and remainder of x divided by 2**n, rounded towards +Inf.

```APIDOC
## gmpy2.c_divmod_2exp(x, n)

### Description
Return the quotient and remainder of x divided by 2**n. The quotient is rounded towards +Inf (ceiling rounding) and the remainder will be negative.

### Parameters
- **x** (int) - Required - Dividend.
- **n** (int) - Required - Exponent (must be > 0).
```

--------------------------------

### gmpy2.mpfr_from_old_binary(string)

Source: https://gmpy2.readthedocs.io/en/latest/mpfr.html

Creates an mpfr object from a legacy GMPY 1.x binary format.

```APIDOC
## gmpy2.mpfr_from_old_binary(string)

### Description
Return an `mpfr` from a GMPY 1.x binary mpf format.
```

--------------------------------

### log10(x)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Calculates the base-10 logarithm.

```APIDOC
## log10(x)

### Description
Return the base-10 logarithm of x.
```

--------------------------------

### Iterate over bits in xmpz

Source: https://gmpy2.readthedocs.io/en/latest/_sources/advmpz.rst.txt

Uses iteration methods to retrieve bit values or positions of set/cleared bits.

```python
>>> 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]
```

--------------------------------

### next_below(x)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Returns the next representable number below x.

```APIDOC
## next_below(x)

### Description
Return the next mpfr from x toward -Infinity.
```

--------------------------------

### gmpy2.set_emin(emin)

Source: https://gmpy2.readthedocs.io/en/latest/mpfr.html

Sets the minimum possible exponent for mpfr.

```APIDOC
## gmpy2.set_emin(emin)

### Description
Set the minimum possible exponent for mpfr.
```

--------------------------------

### Number Theory Functions

Source: https://gmpy2.readthedocs.io/en/latest/_sources/advmpz.rst.txt

Functions for primality testing and Lucas sequence calculations.

```APIDOC
## Number Theory Functions

### Functions
- **is_bpsw_prp(n)**
- **is_euler_prp(n, a)**
- **is_extra_strong_lucas_prp(n)**
- **is_fermat_prp(n, a)**
- **is_fibonacci_prp(n)**
- **is_lucas_prp(n)**
- **is_selfridge_prp(n)**
- **is_strong_bpsw_prp(n)**
- **is_strong_lucas_prp(n)**
- **is_strong_prp(n, a)**
- **is_strong_selfridge_prp(n)**
- **lucasu(P, Q, n)**
- **lucasu_mod(P, Q, n, m)**
- **lucasv(P, Q, n)**
- **lucasv_mod(P, Q, n, m)**
```

--------------------------------

### gmpy2.bincoef(n, k)

Source: https://gmpy2.readthedocs.io/en/latest/mpz.html

Calculates the binomial coefficient (n choose k).

```APIDOC
## gmpy2.bincoef(n, k)

### Description
Return the binomial coefficient ('n choose k'). Requires k >= 0.

### Parameters
- **n** (int) - Required - The total number of items.
- **k** (int) - Required - The number of items to choose.
```

--------------------------------

### gmpy2.f_divmod_2exp(x, n)

Source: https://gmpy2.readthedocs.io/en/latest/mpz.html

Returns the quotient and remainder of x divided by 2**n, rounded towards -Inf.

```APIDOC
## gmpy2.f_divmod_2exp(x, n)

### Description
Return quotient and remainder after dividing x by 2**n. The quotient is rounded towards -Inf (floor rounding) and the remainder will be positive.

### Parameters
- **x** (int) - Required - Dividend.
- **n** (int) - Required - Exponent (must be > 0).
```

--------------------------------

### root_of_unity(n, k)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Calculates the n-th root of unity raised to the k-th power.

```APIDOC
## root_of_unity(n, k)

### Description
Return the n-th root of mpc(1) raised to the k-th power.
```

--------------------------------

### System Information Functions

Source: https://gmpy2.readthedocs.io/en/latest/_sources/misc.rst.txt

Functions to retrieve system-specific information about the underlying libraries.

```APIDOC
## System Functions

- **gmpy2.mp_limbsize()**: Returns the size of a limb in the GMP library.
- **gmpy2.license()**: Returns the license information for the gmpy2 library.
```

--------------------------------

### gmpy2.local_context(**kwargs) / gmpy2.local_context(context, /, **kwargs)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Creates a new context for scoped arithmetic control, allowing overrides via keyword arguments.

```APIDOC
## gmpy2.local_context(context=None, /, **kwargs)

### Description
Returns a new context for controlling gmpy2 arithmetic, based either on the current context or a provided context object. Context options can be overridden by keyword arguments.
```

--------------------------------

### gmpy2.mpc_version()

Source: https://gmpy2.readthedocs.io/en/latest/misc.html

Returns the current MPC version.

```APIDOC
## gmpy2.mpc_version()

### Description
Return string giving current MPC version.
```

--------------------------------

### Implement custom object conversion to mpz

Source: https://gmpy2.readthedocs.io/en/latest/conversion.html

Define a class with an __mpz__ method to enable conversion to a gmpy2 mpz type.

```python
>>> 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'>
```

--------------------------------

### Arithmetic and Mathematical Operations

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

A selection of mathematical operations that apply the current context's settings.

```APIDOC
## add(x, y)
Return x + y.

## div(x, y)
Return x / y; uses true division.

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

## sqrt(x)
Return the square root of x.

## exp(x)
Return the exponential of x.
```

--------------------------------

### gmpy2.c_div_2exp(x, n)

Source: https://gmpy2.readthedocs.io/en/latest/mpz.html

Returns the quotient of x divided by 2**n, rounded towards +Inf.

```APIDOC
## gmpy2.c_div_2exp(x, n)

### Description
Returns the quotient of x divided by 2**n. The quotient is rounded towards +Inf (ceiling rounding).

### Parameters
- **x** (int) - Required - Dividend.
- **n** (int) - Required - Exponent (must be > 0).
```

--------------------------------

### mul_2exp(x, n)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Multiplies by 2 raised to the power of n.

```APIDOC
## mul_2exp(x, n)

### Description
Return mpfr or mpc multiplied by 2**n.
```

--------------------------------

### gmpy2.qdiv

Source: https://gmpy2.readthedocs.io/en/latest/mpq.html

Performs division returning an mpz or mpq.

```APIDOC
## gmpy2.qdiv(x, y=1, /)

### Description
Returns x/y as an mpz if the result is an integer, otherwise returns an mpq.
```

--------------------------------

### Setting Component-Specific Precision

Source: https://gmpy2.readthedocs.io/en/latest/_sources/tutorial.rst.txt

Configuring different precision settings for real and imaginary components of complex numbers.

```python
ctx = get_context()
ctx.real_prec = 60
ctx.imag_prec = 70
sqrt(mpc('1+2j'))
```

--------------------------------

### gmpy2.sec(x)

Source: https://gmpy2.readthedocs.io/en/latest/mpfr.html

Calculates the secant of x.

```APIDOC
## gmpy2.sec(x)

### Description
Return secant of x; x in radians.
```

--------------------------------

### root(x, n)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Calculates the n-th root of x.

```APIDOC
## root(x, n)

### Description
Return n-th root of x.
```

--------------------------------

### next_above(x)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Returns the next representable number above x.

```APIDOC
## next_above(x)

### Description
Return the next mpfr from x toward +Infinity.
```

--------------------------------

### gmpy2.unpack(x, n)

Source: https://gmpy2.readthedocs.io/en/latest/mpz.html

Unpacks an integer x into a list of n-bit values.

```APIDOC
## gmpy2.unpack(x, n)

### Description
Unpacks an integer x into a list of n-bit values. Equivalent to repeated division by 2**n. Raises an error if x is negative.

### Parameters
- **x** (integer) - The integer to unpack.
- **n** (integer) - The bit size.
```

--------------------------------

### gmpy2.rootn(x, n)

Source: https://gmpy2.readthedocs.io/en/latest/mpfr.html

Calculates the n-th root of x (IEEE 754-2008 compliant).

```APIDOC
## gmpy2.rootn(x, n)

### Description
Return n-th root of x. The result always an `mpfr`. Note: this is IEEE 754-2008 compliant version of `root()`.
```

--------------------------------

### Version Information Functions

Source: https://gmpy2.readthedocs.io/en/latest/_sources/misc.rst.txt

Functions to retrieve version information for the library and underlying GMP/MPFR/MPC libraries.

```APIDOC
## Version Functions

- **gmpy2.version()**: Returns the version of the gmpy2 library.
- **gmpy2.mp_version()**: Returns the version of the GMP library.
- **gmpy2.mpfr_version()**: Returns the version of the MPFR library.
- **gmpy2.mpc_version()**: Returns the version of the MPC library.
```

--------------------------------

### gmpy2.version()

Source: https://gmpy2.readthedocs.io/en/latest/misc.html

Returns the current gmpy2 version.

```APIDOC
## gmpy2.version()

### Description
Return string giving current GMPY2 version.
```

--------------------------------

### mpq.from_float

Source: https://gmpy2.readthedocs.io/en/latest/mpq.html

Converts a float to an mpq rational.

```APIDOC
## classmethod mpq.from_float(f, /)

### Description
Converts a finite float to a rational number exactly.
```

--------------------------------

### rootn(x, n)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Calculates the n-th root of x (IEEE 754-2008 compliant).

```APIDOC
## rootn(x, n)

### Description
Return n-th root of x. This is the IEEE 754-2008 compliant version of context.root().
```

--------------------------------

### Format MPFR numbers with precision and rounding

Source: https://gmpy2.readthedocs.io/en/latest/_sources/tutorial.rst.txt

Demonstrates standard and custom rounding modes (U for up, D for down) when formatting MPFR objects.

```python
>>> 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'
```

--------------------------------

### radians(x)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Converts degrees to radians.

```APIDOC
## radians(x)

### Description
Convert angle x from degrees to radians.
```

--------------------------------

### gmpy2.context

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Creates a new context for controlling gmpy2 arithmetic, optionally based on an existing context or overridden by keyword arguments.

```APIDOC
## class gmpy2.context(**kwargs)

### Description
Return a new context for controlling gmpy2 arithmetic, based either on the default context or on a given by ctx value. Context options additionally can be overridden by keyword arguments.

### Parameters
- **ctx** (context) - Optional - An existing context to base the new one on.
- **kwargs** (dict) - Optional - Keyword arguments to override context options.
```

--------------------------------

### gmpy2.zeta(x)

Source: https://gmpy2.readthedocs.io/en/latest/mpfr.html

Calculates the Riemann zeta function of x.

```APIDOC
## gmpy2.zeta(x)

### Description
Return Riemann zeta of x.
```

--------------------------------

### Context Attributes

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Configuration attributes for controlling precision, rounding, and behavior of mpfr and mpc types.

```APIDOC
## Context Attributes

- **allow_complex**: Controls whether an mpc result can be returned if an mpfr result is not possible.
- **allow_release_gil**: If True, many mpz and mpq computations will release the GIL.
- **emax**: Controls the maximum allowed exponent of an mpfr result.
- **emin**: Controls the minimum allowed exponent of an mpfr result.
- **imag_prec**: Controls the precision of the imaginary part of an mpc result.
- **imag_round**: Controls the rounding mode for the imaginary part of an mpc result.
- **precision**: Controls the precision of an mpfr result in bits.
- **rational_division**: If True, mpz / mpz returns an mpq instead of an mpfr.
- **real_prec**: Controls the precision of the real part of an mpc result.
- **real_round**: Controls the rounding mode for the real part of an mpc result.
- **round**: Sets the rounding mode (RoundAwayZero, RoundDown, RoundToNearest, RoundToZero, RoundUp).
- **subnormalize**: Enables gradual underflow to mimic IEEE-754 floating-point operations.
```

--------------------------------

### phase(x)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Calculates the phase angle of a complex number.

```APIDOC
## phase(x)

### Description
Return the phase angle, also known as argument, of a complex x.
```

--------------------------------

### gmpy2.f_div_2exp(x, n)

Source: https://gmpy2.readthedocs.io/en/latest/mpz.html

Returns the quotient of x divided by 2**n, rounded towards -Inf.

```APIDOC
## gmpy2.f_div_2exp(x, n)

### Description
Return the quotient of x divided by 2**n. The quotient is rounded towards -Inf (floor rounding).

### Parameters
- **x** (int) - Required - Dividend.
- **n** (int) - Required - Exponent (must be > 0).
```

--------------------------------

### rint_ceil(x)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Rounds to the nearest integer using ceiling.

```APIDOC
## rint_ceil(x)

### Description
Return 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.
```

--------------------------------

### gmpy2.comb(n, k)

Source: https://gmpy2.readthedocs.io/en/latest/mpz.html

Returns the number of combinations of n things, taking k at a time.

```APIDOC
## gmpy2.comb(n, k)

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

### Parameters
- **n** (int) - Required - Total items.
- **k** (int) - Required - Items to take.
```

--------------------------------

### gmpy2.sech(x)

Source: https://gmpy2.readthedocs.io/en/latest/mpfr.html

Calculates the hyperbolic secant of x.

```APIDOC
## gmpy2.sech(x)

### Description
Return hyperbolic secant of x.
```

--------------------------------

### Complex Results Configuration

Source: https://gmpy2.readthedocs.io/en/latest/_sources/tutorial.rst.txt

Enabling complex results for operations that are undefined over real numbers.

```python
sqrt(mpfr(-2))
ctx.allow_complex = True
sqrt(mpfr(-2))
```

--------------------------------

### gmpy2.t_div_2exp(x, n)

Source: https://gmpy2.readthedocs.io/en/latest/mpz.html

Returns the quotient of x divided by 2**n, rounded towards zero.

```APIDOC
## gmpy2.t_div_2exp(x, n)

### Description
Returns the quotient of x divided by 2**n. The quotient is rounded towards zero (truncation).

### Parameters
- **x** (integer) - The dividend.
- **n** (integer) - The exponent (must be > 0).
```

--------------------------------

### gmpy2.root(x, n)

Source: https://gmpy2.readthedocs.io/en/latest/mpfr.html

Calculates the n-th root of x.

```APIDOC
## gmpy2.root(x, n)

### Description
Return n-th root of x. The result always an `mpfr`. Note: not IEEE 754-2008 compliant; result differs when x = -0 and n is even. See `rootn()`.
```

--------------------------------

### is_zero(x)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Checks if a value is zero.

```APIDOC
## is_zero(x)

### Description
Returns True if x is equal to 0. If x is an mpc, returns True if both x.real and x.imag are equal to 0.
```

--------------------------------

### Perform slice assignments on xmpz

Source: https://gmpy2.readthedocs.io/en/latest/_sources/advmpz.rst.txt

Uses slice notation to set or clear ranges of bits. Note that ~0 or -1 can be used to set bits to 1.

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

--------------------------------

### remainder(x, y)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Calculates the remainder.

```APIDOC
## remainder(x, y)

### Description
Return x - n*y where n is the integer quotient of x/y, rounded to the nearest integer and ties rounded to even.
```

--------------------------------

### gmpy2.powmod(x, y, m)

Source: https://gmpy2.readthedocs.io/en/latest/mpz.html

Return (x**y) mod m using mpz conversion.

```APIDOC
## gmpy2.powmod(x, y, m)

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

--------------------------------

### gmpy2.get_emin()

Source: https://gmpy2.readthedocs.io/en/latest/mpfr.html

Returns the minimum possible exponent for mpfr.

```APIDOC
## gmpy2.get_emin()

### Description
Return the minimum possible exponent for mpfr.
```

--------------------------------

### gmpy2.mpc

Source: https://gmpy2.readthedocs.io/en/latest/mpc.html

Constructor for creating a complex floating-point number from various inputs including numeric values, pairs of real/imaginary components, or strings.

```APIDOC
## class gmpy2.mpc(c=0, precision=0)
## class gmpy2.mpc(real, imag=0, precision=0)
## class gmpy2.mpc(s, precision=0, base=10)

### Description
Constructs a complex floating-point number. Precision can be specified as a single value or a pair for real and imaginary components.

### Parameters
- **c** (numeric) - Optional - Numeric value to convert.
- **real** (numeric) - Optional - Real component.
- **imag** (numeric) - Optional - Imaginary component.
- **s** (string) - Optional - String representation of the complex number.
- **precision** (int/tuple) - Optional - Precision in bits.
- **base** (int) - Optional - Base for string parsing (up to 36).
```

--------------------------------

### gmpy2.remquo(x, y)

Source: https://gmpy2.readthedocs.io/en/latest/mpfr.html

Returns the remainder and quotient bits of x/y.

```APIDOC
## gmpy2.remquo(x, y)

### Description
Return a `tuple` containing the remainder(x,y) and the low bits of the quotient.
```

--------------------------------

### minus(x)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Returns the negation of x.

```APIDOC
## minus(x)

### Description
Return -x. The context is applied to the result.
```

--------------------------------

### gmpy2.get_emin_min()

Source: https://gmpy2.readthedocs.io/en/latest/mpfr.html

Returns the minimum possible exponent that can be set for mpfr.

```APIDOC
## gmpy2.get_emin_min()

### Description
Return the minimum possible exponent that can be set for mpfr.
```

--------------------------------

### gmpy2.sinh_cosh(x)

Source: https://gmpy2.readthedocs.io/en/latest/mpfr.html

Returns the hyperbolic sine and cosine of x.

```APIDOC
## gmpy2.sinh_cosh(x)

### Description
Return a `tuple` containing the hyperbolic sine and cosine of x.
```

--------------------------------

### gmpy2.mpfr_version()

Source: https://gmpy2.readthedocs.io/en/latest/misc.html

Returns the current MPFR version.

```APIDOC
## gmpy2.mpfr_version()

### Description
Return string giving current MPFR version.
```

--------------------------------

### pow(x, y)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Calculates x raised to the power of y.

```APIDOC
## pow(x, y)

### Description
Return x ** y.
```

--------------------------------

### Mathematical Functions

Source: https://gmpy2.readthedocs.io/en/latest/_sources/mpfr.rst.txt

A collection of functions for performing operations on mpfr objects.

```APIDOC
## Mathematical Functions

The following functions are available in the `gmpy2` module for `mpfr` objects:

- `agm`, `ai`, `atan2`, `cbrt`, `ceil`, `check_range`, `cmp`, `const_catalan`, `const_euler`, `const_log2`, `const_pi`, `cot`, `coth`, `csc`, `csch`, `degrees`, `digamma`, `eint`, `erf`, `erfc`, `exp10`, `exp2`, `expm1`, `factorial`, `floor`, `fmma`, `fmms`, `fmod`, `frac`, `frexp`, `fsum`, `gamma`, `gamma_inc`, `get_exp`, `hypot`, `inf`, `is_finite`, `is_infinite`, `is_regular`, `is_signed`, `is_unordered`, `j0`, `j1`, `jn`, `lgamma`, `li2`, `lngamma`, `log1p`, `log2`, `maxnum`, `minnum`, `modf`, `mpfr_from_old_binary`, `mpfr_grandom`, `mpfr_nrandom`, `mpfr_random`, `nan`, `next_above`, `next_below`, `radians`, `rec_sqrt`, `reldiff`, `remainder`, `remquo`, `rint`, `rint_ceil`, `rint_floor`, `rint_round`, `rint_trunc`, `root`, `rootn`, `round2`, `round_away`, `sec`, `sech`, `set_exp`, `set_sign`, `sign`, `sinh_cosh`, `trunc`, `y0`, `y1`, `yn`, `zero`, `zeta`, `get_max_precision`, `get_emax_max`, `get_emin_min`, `get_emax`, `get_emin`, `set_emax`, `set_emin`, `copy_sign`, `can_round`, `free_cache`
```

--------------------------------

### gmpy2.sign(x)

Source: https://gmpy2.readthedocs.io/en/latest/mpfr.html

Returns the sign of x.

```APIDOC
## gmpy2.sign(x)

### Description
Return -1 if x < 0, 0 if x == 0, or +1 if x >0.
```

--------------------------------

### gmpy2.fac(n)

Source: https://gmpy2.readthedocs.io/en/latest/mpz.html

Returns the exact factorial of n.

```APIDOC
## gmpy2.fac(n)

### Description
Return the exact factorial of n.

### Parameters
- **n** (int) - Required - The integer to calculate.
```

--------------------------------

### gmpy2.c_mod_2exp(x, n)

Source: https://gmpy2.readthedocs.io/en/latest/mpz.html

Returns the remainder of x divided by 2**n, which will be negative.

```APIDOC
## gmpy2.c_mod_2exp(x, n)

### Description
Return the remainder of x divided by 2**n. The remainder will be negative.

### Parameters
- **x** (int) - Required - Dividend.
- **n** (int) - Required - Exponent (must be > 0).
```

--------------------------------

### li2(x)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Calculates the real part of the dilogarithm of x.

```APIDOC
## li2(x)

### Description
Return real part of dilogarithm of x.
```

--------------------------------

### gmpy2.divm(a, b, m)

Source: https://gmpy2.readthedocs.io/en/latest/mpz.html

Returns x such that b*x == a mod m.

```APIDOC
## gmpy2.divm(a, b, m)

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

### Parameters
- **a** (int) - Required - Dividend.
- **b** (int) - Required - Multiplier.
- **m** (int) - Required - Modulus.
```

--------------------------------

### gmpy2.c_divmod(x, y)

Source: https://gmpy2.readthedocs.io/en/latest/mpz.html

Returns the quotient and remainder of x divided by y, rounded towards +Inf.

```APIDOC
## gmpy2.c_divmod(x, y)

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

### Parameters
- **x** (int) - Required - Dividend.
- **y** (int) - Required - Divisor.
```

--------------------------------

### gmpy2.t_divmod(x, y)

Source: https://gmpy2.readthedocs.io/en/latest/mpz.html

Returns the quotient and remainder of x divided by y.

```APIDOC
## gmpy2.t_divmod(x, y)

### Description
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.

### Parameters
- **x** (integer) - The dividend.
- **y** (integer) - The divisor.
```

--------------------------------

### lgamma(x)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Calculates the logarithm of the absolute value of gamma(x) and its sign.

```APIDOC
## lgamma(x)

### Description
Return a tuple containing the logarithm of the absolute value of gamma(x) and the sign of gamma(x).
```

--------------------------------

### rec_sqrt(x)

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Calculates the reciprocal of the square root.

```APIDOC
## rec_sqrt(x)

### Description
Return the reciprocal of the square root of x.
```

--------------------------------

### gmpy2.set_sign(x, s)

Source: https://gmpy2.readthedocs.io/en/latest/mpfr.html

Sets the sign bit of x.

```APIDOC
## gmpy2.set_sign(x, s)

### Description
If s is `True`, then return x with the sign bit set.
```

--------------------------------

### Importing gmpy2

Source: https://gmpy2.readthedocs.io/en/latest/_sources/tutorial.rst.txt

Importing all contents from the package. Note that this is generally discouraged in production code to avoid namespace conflicts.

```python
from gmpy2 import *
```

--------------------------------

### gmpy2.gcdext(a, b)

Source: https://gmpy2.readthedocs.io/en/latest/mpz.html

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

```APIDOC
## gmpy2.gcdext(a, b)

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

--------------------------------

### gmpy2.modf(x)

Source: https://gmpy2.readthedocs.io/en/latest/mpfr.html

Returns the integer and fractional parts of a number.

```APIDOC
## gmpy2.modf(x)

### Description
Return a `tuple` containing the integer and fractional portions of x.
```

--------------------------------

### gmpy2.get_context()

Source: https://gmpy2.readthedocs.io/en/latest/contexts.html

Retrieves a reference to the currently active arithmetic context.

```APIDOC
## gmpy2.get_context()

### Description
Returns a reference to the current context object used for gmpy2 arithmetic operations.
```

--------------------------------

### gmpy2.zero(n)

Source: https://gmpy2.readthedocs.io/en/latest/mpfr.html

Returns an mpfr initialized to 0.0.

```APIDOC
## gmpy2.zero(n)

### Description
Return an `mpfr` initialized to 0.0 with the same sign as n. If n is not given, +0.0 is returned.
```

--------------------------------

### gmpy2.to_binary

Source: https://gmpy2.readthedocs.io/en/latest/_sources/misc.rst.txt

Converts a gmpy2 object to a binary string.

```APIDOC
## gmpy2.to_binary(x)

### Description
Converts a gmpy2 object `x` into a binary string representation.
```

--------------------------------

### gmpy2.mpfr Constructor

Source: https://gmpy2.readthedocs.io/en/latest/mpfr.html

Creates a new mpfr instance from a numeric value or a string representation.

```APIDOC
## gmpy2.mpfr(n=0, precision=0)
## gmpy2.mpfr(n, precision, context)
## gmpy2.mpfr(s, precision=0, base=0)
## gmpy2.mpfr(s, precision, base, context)

### Description
Constructs a new multiple-precision real number. Inputs can be numeric types or strings representing numbers in various bases.

### Parameters
- **n** (numeric) - Optional - Numeric value to convert.
- **s** (string) - Optional - String representation of a number.
- **precision** (int) - Optional - Bit precision for the number.
- **base** (int) - Optional - Base of the input string (2-62).
- **context** (object) - Optional - Context object defining rounding and precision settings.
```

--------------------------------

### gmpy2.next_below(x)

Source: https://gmpy2.readthedocs.io/en/latest/mpfr.html

Returns the next representable mpfr value below x.

```APIDOC
## gmpy2.next_below(x)

### Description
Return the next `mpfr` from x toward -Infinity.
```

--------------------------------

### gmpy2.f_divmod(x, y)

Source: https://gmpy2.readthedocs.io/en/latest/mpz.html

Returns the quotient and remainder of x divided by y, rounded towards -Inf.

```APIDOC
## gmpy2.f_divmod(x, y)

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

### Parameters
- **x** (int) - Required - Dividend.
- **y** (int) - Required - Divisor.
```
Tokens:
Raw