0
# gmpy2
1

2
gmpy2 is an optimized, C-coded Python extension module that provides fast multiple-precision arithmetic operations. It interfaces with the GNU Multiple Precision Arithmetic Library (GMP), the Multiple Precision Floating-Point Reliable Library (MPFR), and the Multiple Precision Complex Library (MPC) to deliver high-performance arbitrary-precision arithmetic for integers, rational numbers, real numbers, and complex numbers.
3

4
## Package Information
5

6
- **Package Name**: gmpy2
7
- **Language**: Python
8
- **Installation**: `pip install gmpy2`
9
- **Documentation**: https://gmpy2.readthedocs.io/en/latest/
10
- **Version**: 2.2.1
11

12
## Core Imports
13

14
```python
15
import gmpy2
16
```
17

18
Import specific data types and functions:
19

20
```python
21
from gmpy2 import mpz, mpq, mpfr, mpc, get_context, set_context
22
```
23

24
Import everything:
25

26
```python
27
from gmpy2 import *
28
```
29

30
## Basic Usage
31

32
```python
33
import gmpy2
34
from gmpy2 import mpz, mpq, mpfr, mpc
35

36
# Multiple-precision integers
37
big_int = mpz("123456789012345678901234567890")
38
print(big_int * 2)  # 246913578024691357802469135780
39

40
# Rational numbers with exact representation
41
rational = mpq(22, 7)  # Approximation of pi
42
print(rational)  # 22/7
43
print(float(rational))  # 3.142857142857143
44

45
# High-precision floating-point numbers
46
with gmpy2.local_context(precision=100):  # 100-bit precision
47
    x = mpfr("1.23456789012345678901234567890")
48
    y = gmpy2.sqrt(x)
49
    print(y)  # High-precision square root
50

51
# Complex numbers with arbitrary precision
52
z = mpc("3.14159+2.71828j")
53
print(gmpy2.phase(z))  # Complex phase/argument
54
```
55

56
## Architecture
57

58
gmpy2 provides a comprehensive multi-precision arithmetic system built on three main components:
59

60
- **GMP Integration**: Fast arbitrary-precision integers and rationals through mpz and mpq types
61
- **MPFR Integration**: Correctly rounded floating-point arithmetic with configurable precision via mpfr type  
62
- **MPC Integration**: Complex number arithmetic with independent real/imaginary precision control via mpc type
63
- **Context System**: Thread-safe precision, rounding mode, and exception control for all operations
64
- **Python Integration**: Seamless integration with Python's numeric protocols, operators, and built-in functions
65

66
This design enables gmpy2 to serve as the foundation for computational mathematics, scientific computing, and cryptographic applications requiring precision beyond Python's native numeric types.
67

68
## Capabilities
69

70
### Multiple-Precision Data Types
71

72
Core data types providing arbitrary-precision arithmetic: integers (mpz), mutable integers (xmpz), rationals (mpq), floating-point numbers (mpfr), and complex numbers (mpc).
73

74
```python { .api }
75
class mpz:
76
    def __init__(self, x=0, base=10): ...
77
    def bit_length(self) -> int: ...
78
    def is_prime(self, n=25) -> bool: ...
79

80
class mpq:
81
    def __init__(self, x=0, y=1): ...
82
    @property
83
    def numerator(self) -> mpz: ...
84
    @property
85
    def denominator(self) -> mpz: ...
86

87
class mpfr:
88
    def __init__(self, x=0.0, precision=None): ...
89
    @property
90
    def precision(self) -> int: ...
91
    def is_finite(self) -> bool: ...
92

93
class mpc:
94
    def __init__(self, real=0, imag=0, precision=None): ...
95
    @property
96
    def real(self) -> mpfr: ...
97
    @property
98
    def imag(self) -> mpfr: ...
99
```
100

101
[Data Types](./data-types.md)
102

103
### Arithmetic Operations
104

105
Basic and advanced arithmetic operations with context-aware precision and rounding control for all numeric types.
106

107
```python { .api }
108
def add(x, y): ...
109
def sub(x, y): ...
110
def mul(x, y): ...
111
def div(x, y): ...
112
def powmod(x, y, z): ...
113
def square(x): ...
114
```
115

116
[Arithmetic](./arithmetic.md)
117

118
### Number Theory
119

120
Comprehensive number theory functions including GCD/LCM, modular arithmetic, primality testing, factorization helpers, and integer sequences.
121

122
```python { .api }
123
def gcd(*args): ...
124
def lcm(*args): ...
125
def is_prime(x, n=25) -> bool: ...
126
def next_prime(x): ...
127
def invert(x, y): ...
128
def bincoef(n, k): ...
129
def fac(n): ...
130
def fib(n): ...
131
```
132

133
[Number Theory](./number-theory.md)
134

135
### Mathematical Functions
136

137
Extensive collection of mathematical functions including trigonometry, logarithms, exponentials, special functions, and constants with configurable precision.
138

139
```python { .api }
140
def sqrt(x): ...
141
def sin(x): ...
142
def cos(x): ...
143
def exp(x): ...
144
def log(x): ...
145
def gamma(x): ...
146
def const_pi(precision=None): ...
147
def const_euler(precision=None): ...
148
```
149

150
[Mathematical Functions](./math-functions.md)
151

152
### Bit Operations
153

154
Efficient bit manipulation operations for integer types including setting, clearing, testing bits, and bitwise logical operations.
155

156
```python { .api }
157
def bit_set(x, n): ...
158
def bit_clear(x, n): ...
159
def bit_test(x, n) -> bool: ...
160
def bit_count(x) -> int: ...
161
def bit_length(x) -> int: ...
162
def hamdist(x, y) -> int: ...
163
```
164

165
[Bit Operations](./bit-operations.md)
166

167
### Context Management
168

169
Precision and rounding control system providing thread-safe computation contexts with configurable precision, rounding modes, and exception handling.
170

171
```python { .api }
172
class context:
173
    def __init__(self, precision=53, round=RoundToNearest, **kwargs): ...
174
    def __enter__(self): ...
175
    def __exit__(self, *args): ...
176

177
def get_context() -> context: ...
178
def set_context(ctx: context): ...
179
def local_context(**kwargs): ...
180
```
181

182
[Context Management](./context.md)
183

184
### Random Numbers
185

186
Random number generation for all gmpy2 types with multiple algorithms and configurable random state management.
187

188
```python { .api }
189
class random_state:
190
    def __init__(self, seed=0): ...
191

192
def mpz_random(state, n): ...
193
def mpz_urandomb(state, n): ...  
194
def mpfr_random(state): ...
195
def mpc_random(state): ...
196
```
197

198
[Random Numbers](./random.md)
199

200
### Utility Functions
201

202
Version information, binary serialization, floating-point utilities, and system information functions.
203

204
```python { .api }
205
def version() -> str: ...
206
def mp_version() -> str: ...
207
def mpfr_version() -> str: ...
208
def mpc_version() -> str: ...
209
def mp_limbsize() -> int: ...
210
def license() -> str: ...
211

212
def to_binary(x): ...
213
def from_binary(s): ...
214
def pack(x, precision, emin, emax): ...
215
def unpack(s, precision, emin, emax): ...
216

217
def get_max_precision() -> int: ...
218
def get_emax_max() -> int: ...
219
def get_emin_min() -> int: ...
220
def free_cache(): ...
221
```
222

223
[Utility Functions](./utilities.md)
224

225
## Constants
226

227
```python { .api }
228
# Rounding modes
229
RoundToNearest: int
230
RoundToZero: int
231
RoundUp: int
232
RoundDown: int
233
RoundAwayZero: int
234
Default: int
235

236
# Version information
237
__version__: str
238
```
239

240
## Exceptions
241

242
```python { .api }
243
class DivisionByZeroError(ArithmeticError): ...
244
class InexactResultError(ArithmeticError): ...
245
class InvalidOperationError(ArithmeticError): ...
246
class OverflowResultError(ArithmeticError): ...
247
class UnderflowResultError(ArithmeticError): ...
248
class RangeError(ArithmeticError): ...
249
```