#### /doc/gmpydoc.txt

Plain Text | 845 lines | 691 code | 154 blank | 0 comment | 0 complexity | 1bf1ed5a11f3a0367f2f3f82cecc6f38 MD5 | raw file

1gmpy module -- a complete Python 2.4+ and 3.x interface for GMP/MPIR. 2 3 4*Notes on history of file gmpydoc.txt* 5 6Notes for version 0.1 (pre-alpha), first one placed on sourceforge 7-- A. Martelli, aleaxit@yahoo.com, 00/11/06. 8 9Edited for version 0.2 (still pre-alpha), bugfixes & minor 10performance tweaks, 00/11/15 -- many thanks to Pearu Peterson for 11his contributions re 0.1 -> 0.2! 12 13Edited for version 0.3 (ditto) -- cleanup, exposing more mpz 14functions (almost all there...!), large performance-tweaks via 15caching (tx to PP for the inspiration!), some unit-tests -- **NEED 16MANY MORE TESTS FOR 0.4**!!! -- 00/11/18. 17 18Small edits for version 0.4 (ditto) -- just a couple more 19functions, and minor error-corrections -- 11/24. (Added 20docstrings in 0.4; would be nice to build a doc of some kind 21automatically from ONE place...). 22 23Edited for version 0.5 (ditto) -- documented the new functionality 24(mostly mpq; also: random, jacobi/legendre/ kronecker), minor 25cleanups & corrections -- 11/30. 26 27Editing for versions 0.6 (12/07), 0.7 (12/16), 0.8 (12/26): 28documented new functionalities, and performed minor cleanups 29& corrections, each time. 30 31Very minor editing for version 0.9 (2001/01/25). 32Minor editing for version 0.9b (2002/02/28). 33Minor editing for version 0.9c (2002/03/05). 34Minor editing for version 1.0 (2003/08/08). 35Minor editing for version 1.01 (2005/11/12); 36maintainer's preferred email changed to aleaxit@gmail.com . 37Minor editing for version 1.02 (2007/02/19). 38Minor editing for version 1.03 (2008/06/22). 39Minor editing for version 1.04 (2008/10/16). 40Minor editing for version 1.10 (2009/10/18) 41 42 43*Acknowledgments* 44 45gmpy 0.1 was based on previous versions of gmpmodule.c (for 46earlier Python and GMP releases) by AMK and Niels MÃ¶ller (only 47removed feature: conditional possibility to substitute this 48implementation in place of Python's built-in longs; lots and lots 49of added features). 50 51Special thanks are due to Pearu Peterson for his MANY important 52inputs on design aspects, performance tweak suggestions, and bug 53discoveries. 54 55Thanks also to Keith Briggs for his precious feedback, and to Tim 56Peters, Fredrik Lundh, "and a cast of thousands" (posters to 57c.l.py and, in some few cases, gmpy's sf discussion groups) for their 58suggestions. Furthermore, thanks to Case Van Horsen, who provided 59the Windows binary installers for gmpy 1.01. 60 61Chip Turner and Daniel Lord helped with the changes leading to version 621.02, so, thanks to them as well! 63 64Case Van Horsen has done almost all of the work leading to version 1.03, 65so, SUPER thanks!-) (He's also pointed out the issues requiring the 66enhancements in 1.04, mainly rich comparisons, and done other changes 67leading from 1.03 to 1.04). 68 69 70*Installation and testing* 71 72Pre-requisites: Python 2.4+ or 3.x, and recent versions of GMP 73(http://gmplib.org) or MPIR (http://www.mpir.org). gmpy has been tested 74with GMP version 4.2+ and MPIR 1.2+. 75 76To build gmpy from sources, get the sources from svn (or a sources 77zipfile, such as gmpy-1.10.zip) from http://code.google.com/p/gmpy/source. 78Place the source code into a new, dedicated directory, cd to that 79directory (from any shell on Unix/Linux, or from Terminal on Mac OS X), 80and run: 81 82 python setup.py install 83 84The DistUtils that come with Python take over and build and 85install the gmpy module for you (you may need to use 'sudo' or 86'su' appropriately to actually perform the installation, depending 87on the permissions you're using on Python's site-packages). 88 89Detailed instructions for building on Windows are included in 90"windows_build.txt" and "win_x64_sdk_build.txt". "windows_build.txt" 91describes the build process using Mingw32 and MSYS and was used to 92build the 32-bit Windows binaries. "win_x64_sdk_build.txt" describes 93the build process using the Microsoft Platform SDK and was used to 94build the 64-bit Windows binaries. The MPIR library offers better 95support for Windows and is recommended. 96 97The file "mac_build.txt" contains detailed instructions for compiling 98GMP and GMPY on MacOSX (or getting GMP via mactools/darwintools). 99 100The sources zipfile also contains this file (gmpydoc.txt), an 101example C source file for a separate module that uses the C-API of 102gmpy to interoperate with it, a copy of the index.html for the 103gmpy sourceforge site, and python scripts that exemplify, show the 104performance of, and test, some functionality of the gmpy module. 105 106To test the installation, cd to the directory where you unpacked 107the gmpy sources, and run, at the command prompt: 108 109 cd test 110 111(Note: use "cd test3" if you are using Python 3.x.) 112 113and then, at the next prompt: 114 115 python gmpy_test.py 116 117 118Expected output is something like (details may differ!): 119 120""" 121Unit tests for gmpy 1.02 release candidate 122 on Python 2.5 (r25:51918, Sep 19 2006, 08:49:13) 123[GCC 4.0.1 (Apple Computer, Inc. build 5341)] 124Testing gmpy 1.02 (GMP 4.2), default caching (20, 20, -2..11) 125gmpy_test_cvr 270 tests, 0 failures 126gmpy_test_rnd 26 tests, 0 failures 127gmpy_test_mpf 155 tests, 0 failures 128gmpy_test_mpq 264 tests, 0 failures 129gmpy_test_mpz 386 tests, 0 failures 130gmpy_test_dec 16 tests, 0 failures 1317 items had no tests: 132 [[ snip snip ]] 13331 items passed all tests: 134 [[ snip snip ]] 1351117 tests in 38 items. 1361117 passed and 0 failed. 137Test passed. 138""" 139 140Should you wish to test some specific portion, please note that 141each of the various modules listed at the start can also be run 142independently, if so desired: 143 python gmpy_test_mpq.py 144 python gmpy_test_mpz.py 145and so on, expecting output analogous to the above example. You 146may also run, for example, 147 python gmpy_test_mpq.py -v 148to get very verbose and detailed output. However, in any case, 149the key issue is the 'Test passed' line at the end of each run! 150 151*PLEASE* report any failures to gmpy's maintainers, with all details you 152can supply on your machine, on your OS, and on your installation of GMP 1534, gmpy 1.04, Python 2.3, 2.4, 2.5, or 2.6, and any other relevant issue 154(your C/C++ compiler & libraries, &c). *THANKS* in advance -- bug 155reporting and feedback is your key contribution to the gmpy project! 156(Reports of any _successful_ installations will also be welcome, if it's 157accompanied by enough details -- again, THANKS in advance!). The best 158way to report bugs (including unit-test failures) is via the Google Code 159issue tracker. 160 161 162*General notes on gmpy* 163 164Note that the mpfr() type from the MPFR library replaced GMP's mpf() 165type in gmpy2. 166 167gmpy exposes to Python three types of numbers that are implemented 168in GMP and MPIR: 169 mpz unlimited-precision integers 170 mpq unlimited-precision rationals 171 mpf extended-precision floats 172 173See GMP documentation for general descriptions of them! 174 GNU MP Home Page: http://gmplib.org 175 176The MPIR documentation is available from: 177 MPIR Home Page: http://www.mpir.org 178 179Licensing: gmpy is licensed under LGPL v2 or later. MPIR is also 180licensed under LGPL v2 or later. GMP converted to LGPL v3 beginning 181with version 4.2.2. IANAL, but, summarizing, this means: other 182_libraries_ that are derived from gmpy must also be distributed 183under the LPGL (or full-GPL), as must any modifications/additions to 184gmpy; but, no such restriction applies on code that just _uses_ these 185modules/libraries (such gmpy-using code may thus be licensed in whatever 186way is desired). 187 188Warranty: NONE -- as usual for open-source software (see the 189detailed disclaimers in GMP's license)! 190 191 192*gmpy.mpz -- unlimited-precision integral numbers* 193 194gmpy.mpz objects have the full arithmetic abilities of Python 195longs (in the future, there may also be mutable versions of them 196[for performance], but NOT yet). 197 198Specifically, arithmetic operators + and - (unary and binary), *, 199/ (truncating), %, **, bitwise operators such as &, |, ^, <<, >>, 200~, and builtin Python functions such as divmod and pow, all work 201as expected on mpz objects (basically, the same way as on builtin 202Python longs, except that the speed can be quite different -- from 203'a bit slower' for some things, up to much faster for others [such 204as multiplication of huge numbers]). 205 206Mixed-operand arithmetic is supported: the other operand (which 207must be a number of some kind) is coerced to a gmpy.mpz, unless 208it's of a floating type, in which case both operands are coerced into 209a gmpy.mpf object. Instances of the decimal.Decimal class are coerced 210into gmpy.mpf also. Instances of the fractions.Fraction class are 211coerced int gmpy.mpq. 212 213An mpz object can be built by passing to the gmpy.mpz constructor 214function any Python built-in, non-complex number, another mpz 215(this *shares* object identity, does *not* copy it -- which should 216be indifferent, since such objects are in any case immutable), a 217mpq or mpf (which gets truncated, as also a Python float does), or 218a string (representing the number in base 10). 219 220gmpy.mpz can also be called with TWO arguments: the first one a 221string representing the number in some base N, the second one, the 222integer N. N can be between 2 and 36, or it can be 256, which 223implies that the string is the _portable binary gmpy 224representation_ of the mpz (as produced by method .binary() of mpz 225objects, and function gmpy.binary() of the module). 226 227An N of 0 is also accepted, and means the string is interpreted as 228decimal, unless it starts with 0x (then, hexadecimal) or 0 (then, 229octal). When N=16 a starting a leading '0x' is also accepted, but 230not required; leading 0's are always accepted and ignored (they do 231NOT mean the rest is taken as octal!) if the base N is explicitly 232given as a Python int, or if it's omitted (and defaults to 10). 233 234*NOTE* that the trailing-L in a Python's "long" string 235representation is NOT accepted in the string argument to 236gmpy.mpz()! 237 238(Please note that all from-string transformations are performed by 239GMP or MPIR, and thus may follow slightly different conventions from 240normal Python ones). 241 242An mpz object can be transformed into a Python number by passing 243it as the argument of a call to Python's built-in number types 244(int, long, float, complex); it can also be formatted as an octal 245or hex string with Python built-in functions oct and hex. 246 247mpz objects also support the hash built-in function, and can thus 248be used as dictionary keys; for any Python int or long N, 249hash(mpz(n)) and hash(n) are equal. 250 251Other operations on mpz objects are all exposed as functions of 252module gmpy, and some, also, as methods of mpz objects. Unless 253otherwise noted, arguments to the following gmpy module functions 254are coerced to mpz (unless already of mpz type), and values 255returned from either functions or methods are also of mpz type. 256 257gmpy.binary(x) or x.binary(): returns a portable binary 258representation (base-256 little endian) of an mpz object, suitable 259for saving into a file (or db, whatever) -- this string can later 260be passed as the first argument to function gmpy.mpz (with a 261second argument with value 256) to reconstruct a copy of the 262original mpz object. *NOTE*: the binary format used by gmpy 263release 0.7 and later is not compatible with that of 0.6 and 264earlier, as the latter, as a design limitation, could not 265represent any mpz number that was < 0. 266 267gmpy.digits(x[,base]) or x.digits([base]): returns a string 268representing x in the given base (between 2 and 36, defaulting to 26910 if omitted or zero); a leading '-' will be present if x<0, but 270no leading '+' if x>=0. If base is 8 or 16, a decoration of a 271leading '0' (or, respectively, '0x') is present (after the '-' 272sign, if the number is negative). 273 274gmpy.numdigits(x[,base]) or x.numdigits([base]): returns an 275approximation to the number of digits for x in the given base 276(result is either exact [guaranteed if base is a power or 2] or 1 277more than actual length; space for a "sign", or leading 278decorations of '0' or '0x', is NOT considered). Base must be 279between 2 and 36, defaulting to 10 if omitted or zero. 280 281gmpy.sign(x) or x.sign(): -1, 0, or 1, depending on whether x is 282negative, zero, or positive. 283 284gmpy.divm(a, b, M): x such that b*x == a modulo M (will raise a 285ZeroDivisionError exception if no such x exists). 286 287gmpy.fac(x): factorial of x (takes O(x) time; x must be an 288ordinary Python non-negative integer!) 289 290gmpy.fib(x): x-th Fibonacci number (takes O(x) time; x must be an 291ordinary Python non-negative integer). 292 293gmpy.gcd(a,b): greatest common divisor of a and b (an mpz, >= 0). 294 295gmpy.gcdext(a, b): a tuple (g,s,t) such that 296 g==gmpy.gcd(a,b) and g == a*s + b*t 297(g, s and t are all mpz). 298 299gmpy.lcm(a,b): least common multiple of a and b (an mpz, >= 0). 300 301gmpy.is_square(x) or x.is_square(): 1 iff x is a perfect square, 302else 0 (returns Python int). 303 304gmpy.is_power(x) or x.is_power(): 1 iff x is a perfect power 305(i.e., there exist a, b such that a**b==x and b>1), else 0 306(returns Python int). 307 308gmpy.is_prime(x [, count]) or x.is_prime([count]): 2 if x is 309_certainly_ prime, 1 if x is _probably_ prime, 0 if x is 310_certainly_ composite; count defaults to 25 (probability of 311non-primality, if is_prime returns 1, is guaranteed to be no 312higher than 1 in 2**count). Returns Python int. 313NOTE: GMP believes negative numbers can be primes, and gmpy just 314reflects this stance (cfr discussion at 315http://www.utm.edu/research/primes/notes/faq/negative_primes.html) 316 317gmpy.next_prime(x) or x.next_prime(): returns mpz that is the 318lowest prime > x; *probabilistic* algorithm for 319prime-determination (see is_prime). 320 321gmpy.sqrt(x) or x.sqrt(): integer square-root of non negative 322number (truncating, unless is_square(x)). 323 324gmpy.sqrtrem(x) or x.sqrtrem(): tuple (s,t) such that 325s==gmpy.sqrt(x) and x==s*s+t. (s and t are mpz, >= 0). 326 327gmpy.root(x,n) or x.root(n): tuple (s,b) such that s is the 328truncated nth-root of x, b!=0 if s is the _exact_ root (i.e. 329x==s**n); n must be an ordinary Python int, >0. (s is an mpz, b a 330Python int). 331 332gmpy.bincoef(x, N) or x.bincoef(N): binomial coefficient "x over 333N"; N must be an ordinary Python int, >=0! (x may be < 0 , see 334Knuth vol 1, sect 1.2.6, part G). [Also known as: gmpy.comb(x, N) 335or x.comb(N), since the binomial coefficient is also the number of 336different combinations of x objects taken N at a time, with 337ordering ignored]. 338 339gmpy.remove(x, f) or x.remove(f): "remove factors": returns a 340two-element tuple (y,m), where y, an mpz, is x without any factor 341of f, and m (an ordinary Python int) is the multiplicity of f in x 342(e.g.: m==0 and y==x unless x%f==0; and in any case, it's ensured 343that x==y*(f**m) and that y%f!=0). 344 345gmpy.invert(x, m) or x.invert(m): modulo-inverse; returns an y 346such that x*y mod m = 1, if one exists, else 0 (returns an mpz in 347either case). 348 349 350gmpy.lowbits(x, n) or x.lowbits(n): returns the n lowest bits of x 351(n must be an ordinary Python int, >0; returns an mpz, >= 0). 352Note that x<0 is assumed to be in 2's complement notation (i.e., 353"extended on the left" with infinite 1-bits); so, for example, for 354any n>0, gmpy.lowbits(-1,n) returns an mpz>0 with the lowest n 355bits set to 1, i.e., (2**n)-1. 356 357gmpy.setbit(x, n, v) or x.setbit(n, v), n being a bitindex (0 and 358up, ordinary Python int) and v an int value (0 or 1, default 1): 359returns a copy of x with bit n set to v (mpz's are not mutable -- 360yet...!). [Any value v != 0 is equivalent to v=1, i.e., the bit 361is 'set'; so, for example, gmpy.setbit(0,n,-4) for any n>=0 362returns an mpz worth 2**n]. 363 364gmp.getbit(x, n) or x.getbit(n), n being a bitindex (0 and up, 365ordinary Python int): returns an int which is 0 or 1, same as the 366value of bit n of x. (See note on gmpy.lowbits for x<0). 367 368gmpy.scan0(x [, n]) or x.scan0([n]): returns the bit index of the 369next 0-bit starting at bit n (default 0); n must be an ordinary 370Python int, >=0; returns a Python int (-1 if there is no such 371bit-index, which can only happen for an x<0, which notionally is 372extended with infinite 1-bits). 373 374gmpy.scan1(x [, n]) or x.scan1([n]): returns the bit index of the 375next 1-bit starting at bit n (default 0); n must be an ordinary 376Python int, >=0; returns a Python int (-1 if there is no such 377bit-index, which can only happen for an x>=0, which notionally is 378extended with infinite 0-bits). 379 380gmpy.popcount(x) or x.popcount(): returns the "population count" 381(number of bits set to 1) of x; note that this is 'infinite' for 382x<0 (-1 is then returned). Returns a Python int. 383 384gmpy.hamdist(x,y) or x.hamdist(y): returns the Hamming-distance 385|x,y| if both >=0 or both < 0 (returns -1 if one but not both are 386<0) (the hamming distance is defined as: the number of 387bit-positions in which the two numbers differ). Returns a Python 388int. Same as gmpy.popcount(x^y). 389 390gmpy._copy(x) or x._copy(): provide a separate copy of x (only 391relevant for future mutability of mpz... currently useless!). 392 393gmpy.divexact(x,y): returns the quotient of x divided by y. It uses 394a faster division algorithm but requires that the remainder is 0. 395It will return garbage if the remainder is not 0! (New in 1.04.) 396 397*gmpy module-level setting functions* 398[NOTE: the overall architecture of these functions is due to be 399reworked sooner or later, NOT backwards-compatibly]. 400 401gmpy.set_debug(flag): turns on/off debugging output from the gmpy 402module (returns previous setting). [Only of interest to 403develop/debug gmpy itself!] Argument must be an ordinary Python 404int: debug is set on if flag!=0, off if flag==0. Returns a Python 405int (0 or 1, the _previous_ setting). 406 407gmpy.set_tagoff(flag): turns off/on the 'gmpy.' prefix to the 408"tag" that repr() places around the string-representation of gmpy 409objects (returns a Python int, 0 or 1, the previous setting). 410 411gmpy. get_zcache(), set_zcache(N), get_zconst(), set_zconst(N,M), 412get_qcache(), set_qcache(N)...: *internal tweaks/experimental 413stuff*, please don't use them unless you've read the C sources and 414understand what they do! Not further documented here (docstrings 415for these functions in gmpy may give a little more detail). 416 417 418*gmpy.mpq -- unlimited-precision rational numbers* 419 420gmpy.mpq objects have a subset of the arithmetic abilities of 421Python floats (in the future, mutable versions will also be 422supplied, but, NOT YET!), but represent arbitrary rational numbers 423with no loss of precision whatsoever. 424[Note, in particular, that raising-to-power works only without a 425modulo, and, if the exponent is a fraction with a denominator D 426(or gets converted to one), the base must be an exact D-th power, 427or the operation fails raising a ValueError exception]. 428 429Mixed-operand arithmetic is supported: the other operand is 430coerced to a gmpy.mpq. NOTE: the % operator and the divmod 431built-in function are NOT supported. mpq objects also support the 432hash built-in function, and can thus be used as dictionary keys; 433for any Python int or long N, hash(mpq(n)) and hash(n) are equal. 434 435A mpq object has a _numerator_ and a _denominator_; they can be 436obtained by calling on an mpq object the methods .numer() and 437.denom() -- each method has no arguments and returns an mpz (the 438denominator will always be >0; the numerator can be any; also, the 439numerator and denominator never have any common factors; mpq 440corresponding to integers, including 0, always have a denominator 441of exactly 1). 442 443 444An mpq is built by passing to the gmpy.mpq constructor function 445any Python number, another mpq (this *shares* object identity, 446does *not* copy it), a mpf or mpz, or a string (representing the 447number in base 10). [If an mpf or float argument is passed, the 448mpq is built from it with an 'optimal' approach based on a 449Stern-Brocot tree; see also the f2q method of mpf objects, and 450gmpy.f2q module-level function, which differ from explicit 451mpq-construction in that it can return an mpz if the mpq's 452denominator would be 1]. 453 454gmpy.mpq can also be called with TWO arguments: the first one a 455string representing the number in base N, the second one, the 456integer N. N can be between 2 and 36, or, it can be 256, which 457implies that the string is the _portable binary gmpy 458representation_ of the mpq (as produced by method .binary() of mpq 459objects, and function gmpy.qbinary() of the module). 460 461gmpy.mpq is typically called with a string that contains a '/' 462character: the digits before it will then be taken as the 463numerator, those after it, as the denominator (the resulting 464number is normalized: denominator>0, no common factors). A 465ZeroDivisionError is raised if the denominator thus supplied is 466zero; a ValueError, if the string is otherwise invalid (e.g., '/3' 467or '3/'). Hex and octal representations are supported if the base 468N is given as 0; see above gmpy.mpz; for example, 469mpq('0x13/011',0) is the same as mpq(19,9). 470 471gmpy.mpq can also be called with two number arguments: the first 472one is taken as the numerator, the second one as the denominator 473(the resulting number is normalized: denominator>0, no common 474factors). A ZeroDivisionError is raised if the denominator thus 475supplied is zero. 476 477 478Other operations on mpq objects are all exposed as functions of 479modules gmpy, and some, also, as methods of mpq objects: 480 481gmpy.qbinary(x) or x.binary(): returns a portable binary 482representation of any mpq object. 483 484gmpy.qsign(x) or x.sign(): -1, 0, or 1, depending on whether x is 485negative, zero, or positive. 486 487gmpy.qdiv(x[,y]) or x.qdiv([y]), which is _also_ supplied as a 488method on mpz and mpf objects (which are implicitly converted to 489mpq's in this case): return x/y (or just x, if y is absent), as an 490mpz if possible (==if a resulting mpq would have a denominator of 4911), else as an mpq (with a denominator > 1). The functions are 492optimized, so that, if x is an mpz and y is absent or 1, or if x 493is an mpq with a denom>1 and y is absent or 1, then the same 494object-identity as x is returned, so that the operation is very 495fast. In other words, gmpy.qdiv only ever takes substantial time 496if it DOES have an important job to perform, and can thus be 497called rather freely, even in loops, to 'normalize' numeric 498results. 499 500Specifically, please note that, for an x that is an mpq, x.qdiv() 501returns either x, if x.denom()==1, or else the same mpz as 502x.numer() would return; if x is an mpz, x.qdiv() returns x (so it 503can be used polymorphically on an x that can be either, without 504any performance hit). 505 506 507 508*gmpy.mpf -- variable-precision floating numbers* 509 510gmpy.mpf objects have a subset of the arithmetic abilities of 511Python floats (in the future, mutable versions will also be 512supplied, but, NOT YET!). 513 514Mixed-operand arithmetic is supported: the other operand is 515coerced to a gmpy.mpf, except that, if the other operand is an 516mpq, then both are coerced to mpq. NOTE: trigonometric and 517exponential functionalities on mpf objects are NOT currently 518supported [GMP 3.1.1 had none; waiting to expose the MPFR 519extensions to GMP.] mpf objects also support the hash built-in 520function, and can thus be used as dictionary keys; for any Python 521float X, hash(mpf(x)) and hash(x) are equal. 522 523Each mpf object has a _precision_ -- a number of bits of precision 524to which values are stored in it. The precision of all newly 525generated mpf's is at least that set at module level via module 526function gmpy.set_minprec(n); a specific mpf's precision can be 527set to >= n bits by x.setprec(n); it can be queried (the exact 528current number of bits of precision is returned) by x.getprec() or 529gmpy.getprec(x). The granularity of precision of current MPF's is 530rough; exact precision setting is one of MPFR's enhancements. To 531get the actual precision that was _requested_ for a given mpf 532object, x.getrprec() and gmpy.getrprec(x) are also supplied -- the 533value returned from getprec will always be greater than, or equal 534to, the one returned from getrprec. 535 536** The following behavior is in new in gmpy 1.04. ** 537 538GMP only guarantees that the precision of a result is greater than 539or equal to the requested precision. But comparisons would use all 540the bits computed, regardless of whether they are accurate. This 541leads to situations where mpf('1.1') * mpf('1') != mpf('1.1'). 542Beginning with gmpy 1.04, the results of all mpf calculations are 543rounded to the requested precision. 544 545Note: GMP uses radix 2**32 (or 2**64) arithmetic and rounding is 546done on those boundaries. Let's assume we request 53 bits of 547precision on a 32-bit system. GMP rounds the requested precision 548up to 64 bits and then allocates three 32-bit words to store the 549mantissa. GMP also allocates one additional 32-bit word to simplify 550their internal operations. The additional word may or may not be 551present on any particular result. So in our scenario, GMP can return 552a mantissa with anywhere between 65 and 128 bits. The presence of 553the additional word caused the strange behavior with comparisons. 554If the additional word is present, the mantissa is rounded and the 555additional word is set to 0 so the effective precision is between 55665 and 96 bits. 557 558** End new section. ** 559 560An mpf is built by passing to the gmpy.mpf constructor function 561any Python built-in number, another mpf (this *shares* object 562identity, does *not* copy it -- unless specific precision is 563requested for the resulting mpf, see later), a mpq or mpz, or a 564string (representing the number in base 10, possibly with decimal 565point and/or exponent). 566 567If gmpy.mpf is called with a float argument, the exact steps used 568in conversion depend on the setting of module level option fcoform 569(set by gmpy.set_fcoform()). 570 571If fcoform is None, the float number is converted 'exactly' to an 572mpf (which often leaves spurious trailing bits from literals). If 573fcoform is a string, it's used as the format (left operand of %) 574in a formatting operation (with the float being transformed as the 575right operand), and the resulting intermediate string is the one 576that actually gets transformed to mpf (this normally gives good 577results with formats somewhere between '%.12e' and '%.16e', 578depending on the actual precision of the float being transformed). 579 580fcoform also applies to _implicit_ conversions of float to mpf, as 581invoked for mixed-mode arithmetic or when gmpy functions expecting 582an mpf argument are called with a float argument (a string could 583not be passed _explicitly_ here -- an explicit mpz() around it 584would be needed -- but it's OK if a float gets _implicitly_ 585converted-to-mpf-via-string in these cases, through the fcoform 586mechanism). 587 588An optional second argument can always be supplied to gmpy.mpf, 589whether the first argument is a number or a string; if supplied, 590it must be a Python int, >=0. If absent or 0, the precision of 591the mpf that is generated is determined by default depending on 592the input argument (in many cases, it's the number of significant 593bits in machine-floats; e.g., 53 on machines using IEEE 64-bit 594floating point). If the second argument is supplied and > 0, it's 595used as the requested-precision for the resulting mpf, ignoring 596the bits-of-precision held or implied by the first argument. 597Note, that if x is an mpf with n bits of precision, gmpy.mpf(x,m) 598will be able to return the same object identity as x if, and only 599if, m==n; else, a new mpf object of the requested precision will 600be generated. 601 602Note that, in arithmetic operations, the bits of precision of the 603result are generally set to the _lowest_ number of 604bits-of-precision of all the operands involved. 605 606 607gmpy.mpf can also be called with *3* arguments: the first one a 608string representing the number in base N, the second one the bits 609of precision requested (or 0 to accept the default determination 610of the bits), the third one, the integer N. N can be between 2 611and 36, or, it can be 256, which implies that the string is the 612_portable binary gmpy representation_ of the mpf (as produced by 613method .binary() of mpf objects, and function gmpy.fbinary() of 614the module). (Hex and octal decorations are *not* supported here; 615an N of 0 is totally equivalent to one of 10). 616 617Note that therefore, if a reasonable fcoform is set, two 618constructor calls such as 619 gmpy.mpf(3.4) 620and 621 gmpy.mpf('3.4') 622will produce the same mpf object, although the second way is 623faster (and does not depend on the module-level fcoform setting) 624and recommended as preferable to the first one. 625 626 627Other operations on mpf objects are all exposed as functions of 628modules gmpy, and some, also, as methods of mpf objects: 629 630gmpy.fbinary(x) or x.binary(): returns a portable binary 631representation of any mpf object. 632 633gmpy.fdigits(x[,args...]) or x.digits([args]): returns a string 634representing x. Arguments (must currently be passed positionally, 635if at all -- keywords NOT accepted!) are...: 636 base: number-base (between 2 and 36), default 10 637 digits: how many digits are requested (default 0, 638 "all of them" within x's precision; fewer than 639 requested may be obtained, if fewer available) 640 minexp: minimum exponent for which the number is 641 still to be formatted in integer.fraction form 642 (it's formatted as fraction-exponent form if 643 exponent is lower than minexp), default 0 644 maxexp: maximum exponent for which the number is 645 still to be formatted in integer.fraction form 646 (it's formatted as fraction-exponent form if 647 exponent is higher than maxexp), default -1 648 option: bitmask argument, default 0 (no options) 649 650Note that, by default, the formatting is in fraction-and-exponent 651form: 652 [<sign>]<digit>.<digits><marker><signed exponent> 653sign is '-' if x is negative, omitted if x>=0 654<marker> is 'e' for base<=10, otherwise '@' 655the signed exponent (sign omitted if exponent>=0) is always 656expressed in base 10, whatever the base used for the significand's 657digits. 658 659If option's bit 1 is set, the whole result string is enclosed 660between "gmpy.mpf('" at the start and "')" at the end, so it can 661be subject to eval to recover an approximation of the original 662number (depending on the settings of gmpy.set_tagoff(), the 663starting tag may actually be shortened to just "mpf('"). The 664precision, in bits, is also output in this case, just before the 665')', separated from the "first argument to gmpy.mpf" by a comma 666character (it is the same number as returned by .getrprec). 667 668If option's bit 2 is set, then minexp, maxexp, and option's bit 1, 669are ignored: the result is a tuple of 2 objects: first, a string 670made up of all the digits (and maybe a leading - sign) and nothing 671else; second, an integer that is the exponent to use. This can be 672used by Python code that wants finer-grained control on resulting 673string format. 674 675 676gmp.reldiff(x,y) or x.reldiff(y): returns the relative difference 677between x and y, a non-negative mpf roughly equal to 678abs(x-y)/((abs(x)+abs(y))/2). 679 680gmpy._fcopy(x) or x._copy(): provide a separate copy of x (only 681relevant for future mutability of mpf..!). 682 683gmpy.fsign(x) or x.sign(): -1, 0, or 1, depending on whether x is 684negative, zero, or positive. 685 686gmpy.f2q(x) or x.f2q(): like gmpy.mpq(x), but, like qdiv, will 687return an mpz (instead of, as normally, an mpq), if the mpq's 688denominator would be 1. 689 690gmpy.fsqrt(x) or x.sqrt(): square-root of non negative number x. 691 692gmpy.set_fcoform([x]): sets or resets the format with which to 693build the intermediate-string to be used for float->mpf 694conversion. If x is None, or is absent, then the format is reset, 695and such conversions proceed 'directly'. If x is a Python int, it 696must be between 1 and 30, and is used as the number of digits in 697the format string '%.<x>e' (for example, set_fcoform(12) will set 698the format string for float-conversion to '%.12e'). Else, x must 699be a Python string usable as: 700 x%f 701to format a float object f in some suitable way. set_fcoform also 702returns the previous setting of this option, None or a string. 703(See also the paragraph above about the float->mpf conversion 704mechanics, which gives more details about the way in which this 705format string is used by gmpy). 706 707 708*Experimental: function gmpy.rand* 709 710Support for these random number generation functions was removed 711in gmpy2. A new API will be introduced. 712 713Since gmpy 0.5, the linear congruential random number generator of 714GMP is exposed via gmpy (with some modest added-value 715functionality) through function gmpy.rand. A couple of options were 716added in 0.6. This will be refactored into separate functions in 717some future release. 718 719Its first parameter is a string 'opt' (4-characters, lowercase) 720which determines the exact functionality; it normally has a second 721parameter 'arg' (which is optional for most values of 'opt') and 722may return either None or a significant value (an mpz, except for 723opt='floa', when an mpf is returned). 724 725gmpy.rand('init') 726 Initialize the random-generator state (this 727 is _implicitly_ called by other options of 728 gmpy.rand, if needed, but should be explicitly 729 called) to ensure 32 bits' randomness per 730 each generation ('throw'). Returns None. 731gmpy.rand('init', arg) 732 ditto, but ensure 'arg' bits of randomness 733 (arg being an int between 1 and 128). This 734 tweaks the linear congruential parameters 735 according to the number of needed bits (it 736 may be faster to generate just the needed 737 number of 'good' bits). Returns None. 738gmpy.rand('qual') 739 returns the current 'quality of random 740 numbers' (the arg value passed to 'init', 741 with a default of 32), or 0 if random 742 number generation is not initialized yet. 743 [ignores arg, if present] 744gmpy.rand('seed', arg) 745 set the current random-seed to 'arg', an 746 mpz (or coerced to mpz). Returns None. 747gmpy.rand('seed') 748 set the current random-seed 'randomly' in 749 its turn (uses C-level function 'rand()'). 750 Returns None. 751gmpy.rand('save') 752 returns the current random-seed (an mpz) 753 so that it can be saved (e.g. for program 754 checkpointing) and later restored via 755 a gmpy.rand('seed', x) call. 756 [ignores arg, if present] 757gmpy.rand('next') 758 returns a uniformly distributed random 759 number in the range 0:2**31 (note that 760 the UPPER end is EXCLUDED) and advances 761 the random-number generation by 1 step. 762 (Basically, returns '31 random bits', if 763 the current quality of the generator is 764 at least 31; for lower-quality generators, 765 upper bits tend to be "better" than less 766 significant ones). 767gmpy.rand('next',arg) 768 returns a uniformly distributed random 769 number in the range 0:arg (note that 770 the UPPER end is EXCLUDED) and advances 771 the random-number generation by 1 step. 772 Value returned is integral (mpz). 773gmpy.rand('floa',arg) 774 returns a uniformly distributed random 775 number in the range 0:1 (note that 776 the UPPER end is EXCLUDED), with arg 777 meaningful bits (default, if arg is 0, 778 is current 'quality'), and advances the 779 random-number generation by 1 step. 780 Value returned is floating-point (mpf). 781gmpy.rand('floa') 782 returns a uniformly distributed random 783 number in the range 0:1 (note that 784 the UPPER end is EXCLUDED), with as many 785 meaningful bits as the current 'quality', 786 and advances random-number generation by 1 787 step. Value returned is floating-point (mpf). 788gmpy.rand('shuf',arg) 789 randomly shuffles mutable-sequence 'arg' 790 (normally a list), in a way that ensures 791 all permutations are equally likely. It 792 advances random-number generation by 793 len(arg)-1 steps. Returns None. 794 795 796*Experimental: the callbacks-facility* 797 798The "callback" facilities were removed in gmpy 1.10. The documentation 799is left as-is for historical reference. 800 801Since gmpy 0.8, gmpy exposes 'callback' facilities to help 802client-code customize the handling of what, in pure-gmpy, would be 803error-cases. This is mostly intended for the use of Pearu 804Peterson's PySymbolic package, and is not currently documented 805(nor tested) in great detail for general use. You are welcome to 806contact gmpy's maintainer directly (and/or study gmpy's C 807sources:-) if you think you may have use for this facility, or are 808interested in doing something similar in other C modules for 809Python use -- it IS an interesting and reasonably novel approach. 810 811To summarize: with gmpy.set_callback(name, callable), client-code 812may set a Python callable as a callback for gmpy in a set of 813situations determined by the string 'name'. For example, 814 gmpy.set_callback('ZD', myfun) 815sets 'myfun' as the callback that gmpy is to use in 816'zero-division' situations. When gmpy is about to raise a 817ZeroDivision error, it checks if the 'ZD' callback is set; if so, 818then, instead of raising the exception itself, it delegates 819everything to the callback in question, passing it the name of the 820gmpy function involved, the arguments it was called with, and the 821error-string gmpy would use if it did raise the error. It's up to 822the callback to either raise a ZeroDivision itself, OR return some 823special object to map this situation -- for example, PySymbolic 824may return an 'infinity' object and suppress the error. 825 826Basically, this works around Python's (excellent!) choice to adopt 827the terminating-model rather than the restartable one for 828exception handling, in a few cases of specific interest to numeric 829computation that's being used in a symbolic setting. 830 831Most callbacks are module-global, with one specific exception. 832When any gmpy function or method is trying to convert arguments to 833gmpy objects (mpz, mpq, mpf), and a conversion fails, all argument 834objects are examined, looking for a method called '__gmpy__' in 835any of them. 836 837If one is found, then, rather than raising an error to indicate 838the conversion failure, that method is called as a 'localized 839callback' as above. This lets other, non-gmpy objects participate 840in gmpy computations (if they're willing to handle all cases 841involving them!): Python does much of this via __coerce__ etc, and 842this localized-callback facility does the rest for named 843module-functions and methods, where normal coercion would not 844apply. 845