1  Overview of gmpy2
  2  =================
  3  
  4  Tutorial
  5  --------
  6  
  7  The *mpz* type is compatible with Python's built-in int/long type but is
  8  significantly faster for large values. The cutover point for performance varies,
  9  but can be as low as 20 to 40 digits. A variety of additional integer functions
 10  are provided.
 11  ::
 12  
 13      >>> import gmpy2
 14      >>> from gmpy2 import mpz,mpq,mpfr,mpc
 15      >>> mpz(99) * 43
 16      mpz(4257)
 17      >>> pow(mpz(99), 37, 59)
 18      mpz(18)
 19      >>> gmpy2.isqrt(99)
 20      mpz(9)
 21      >>> gmpy2.isqrt_rem(99)
 22      (mpz(9), mpz(18))
 23      >>> gmpy2.gcd(123,27)
 24      mpz(3)
 25      >>> gmpy2.lcm(123,27)
 26      mpz(1107)
 27  
 28  The *mpq* type is compatible with the *fractions.Fraction* type included with
 29  Python.
 30  ::
 31  
 32      >>> mpq(3,7)/7
 33      mpq(3,49)
 34      >>> mpq(45,3) * mpq(11,8)
 35      mpq(165,8)
 36  
 37  The most significant new features in gmpy2 are support for correctly rounded
 38  arbitrary precision real and complex arithmetic based on the MPFR and MPC
 39  libraries. Floating point contexts are used to control exceptional conditions.
 40  For example, division by zero can either return an Infinity or raise an exception.
 41  ::
 42  
 43      >>> mpfr(1)/7
 44      mpfr('0.14285714285714285')
 45      >>> gmpy2.get_context().precision=200
 46      >>> mpfr(1)/7
 47      mpfr('0.1428571428571428571428571428571428571428571428571428571428571',200)
 48      >>> gmpy2.get_context()
 49      context(precision=200, real_prec=Default, imag_prec=Default,
 50              round=RoundToNearest, real_round=Default, imag_round=Default,
 51              emax=1073741823, emin=-1073741823,
 52              subnormalize=False,
 53              trap_underflow=False, underflow=False,
 54              trap_overflow=False, overflow=False,
 55              trap_inexact=False, inexact=True,
 56              trap_invalid=False, invalid=False,
 57              trap_erange=False, erange=False,
 58              trap_divzero=False, divzero=False,
 59              trap_expbound=False,
 60              allow_complex=False)
 61      >>> mpfr(1)/0
 62      mpfr('inf')
 63      >>> gmpy2.get_context().trap_divzero=True
 64      >>> mpfr(1)/0
 65      Traceback (most recent call last):
 66        File "<stdin>", line 1, in <module>
 67      gmpy2.DivisionByZeroError: 'mpfr' division by zero in division
 68      >>> gmpy2.get_context()
 69      context(precision=200, real_prec=Default, imag_prec=Default,
 70              round=RoundToNearest, real_round=Default, imag_round=Default,
 71              emax=1073741823, emin=-1073741823,
 72              subnormalize=False,
 73              trap_underflow=False, underflow=False,
 74              trap_overflow=False, overflow=False,
 75              trap_inexact=False, inexact=True,
 76              trap_invalid=False, invalid=False,
 77              trap_erange=False, erange=False,
 78              trap_divzero=True, divzero=True,
 79              trap_expbound=False,
 80              allow_complex=False)
 81      >>> gmpy2.sqrt(mpfr(-2))
 82      mpfr('nan')
 83      >>> gmpy2.get_context().allow_complex=True
 84      >>> gmpy2.get_context().precision=53
 85      >>> gmpy2.sqrt(mpfr(-2))
 86      mpc('0.0+1.4142135623730951j')
 87      >>>
 88      >>> gmpy2.set_context(gmpy2.context())
 89      >>> with gmpy2.local_context() as ctx:
 90      ...   print(gmpy2.const_pi())
 91      ...   ctx.precision+=20
 92      ...   print(gmpy2.const_pi())
 93      ...   ctx.precision+=20
 94      ...   print(gmpy2.const_pi())
 95      ...
 96      3.1415926535897931
 97      3.1415926535897932384628
 98      3.1415926535897932384626433831
 99      >>> print(gmpy2.const_pi())
100      3.1415926535897931
101      >>>
102  
103  
104  Miscellaneous gmpy2 Functions
105  -----------------------------
106  
107  **from_binary(...)**
108      from_binary(bytes) returns a gmpy2 object from a byte sequence created by
109      to_binary().
110  
111  **get_cache(...)**
112      get_cache() returns the current cache size (number of objects) and the
113      maximum size per object (number of limbs).
114  
115      gmpy2 maintains an internal list of freed *mpz*, *xmpz*, *mpq*, *mpfr*, and
116      *mpc* objects for reuse. The cache significantly improves performance but
117      also increases the memory footprint.
118  
119  **license(...)**
120      license() returns the gmpy2 license information.
121  
122  **mp_limbsize(...)**
123      mp_limbsize() returns the number of bits per limb used by the GMP or MPIR
124      library.
125  
126  **mp_version(...)**
127      mp_version() returns the version of the GMP or MPIR library.
128  
129  **mpc_version(...)**
130      mpc_version() returns the version of the MPC library.
131  
132  **mpfr_version(...)**
133      mpfr_version() returns the version of the MPFR library.
134  
135  **random_state(...)**
136      random_state([seed]) returns a new object containing state information for
137      the random number generator. An optional integer argument can be specified
138      as the seed value. Only the Mersenne Twister random number generator is
139      supported.
140  
141  **set_cache(...)**
142      set_cache(number, size) updates the maximum number of freed objects of each
143      type that are cached and the maximum size (in limbs) of each object. The
144      maximum number of objects of each type that can be cached is 1000. The
145      maximum size of an object is 16384. The maximum size of an object is
146      approximately 64K on 32-bit systems and 128K on 64-bit systems.
147  
148      .. note::
149          The caching options are global to gmpy2. Changes are not thread-safe. A
150          change in one thread will impact all threads.
151  
152  **to_binary(...)**
153      to_binary(x) returns a byte sequence from a gmpy2 object. All object types
154      are supported.
155  
156  **version(...)**
157      version() returns the version of gmpy2.