/doc/index.html

http://gmpy.googlecode.com/ · HTML · 198 lines · 184 code · 9 blank · 5 comment · 0 complexity · d054b67f1de2efb8b6c4c0d6d43f58a8 MD5 · raw file 

    

  1. <HTML>
    2. 

  2. <HEAD>
    3. 

  3. <TITLE>Welcome to General Multiprecision PYthon
    4. 

  4. </TITLE>
    5. 

  5. 

  6. <!--
    7. 

  7. <LINK rel="stylesheet"
    8. 

  8.     href="http://sourceforge.net/sourceforge.css"
    9. 

  9.     type="text/css">
    10. 

  10. -->
    11. 

  11. 

  12. <STYLE>
    13. 

  13. body { margin-left: 30; margin-right: 30; }
    14. 

  14. </STYLE>
    15. 

  15. 

  16. </HEAD>
    17. 

  17. <BODY>
    18. 

  18. <FONT SIZE=-1>
    19. 

  19. Last updated on: 2008, June 22;
    20. 

  20. for GMPY release: 1.04
    21. 

  21. <A href="http://code.google.com/p/gmpy/">
    22. 

  22. <IMG src="http://code.google.com/images/code_sm.png"
    23. 

  23. width="88" height="31" border="0" alt="Go to Google Code gmpy page"></A>
    24. 

  24. <br>
    25. 

  25. </FONT>
    26. 

  26. <H1>GMPY Project goals and strategies</H1>
    27. 

  27. The General Multiprecision PYthon project (GMPY) focuses on
    28. 

  28. Python-usable modules providing multiprecision arithmetic
    29. 

  29. functionality to Python programmers.  The project mission
    30. 

  30. includes both C and C++ Python-modules (for speed) and pure
    31. 

  31. Python modules (for flexibility and convenience); it
    32. 

  32. potentially includes integral, rational and floating-point
    33. 

  33. arithmetic in any base.  Only cross-platform functionality
    34. 

  34. is of interest, at least for now.
    35. 

  35. <P>
    36. 

  36. As there are many good existing free C and C++ libraries
    37. 

  37. that address these issues, it is expected that most of the
    38. 

  38. work of the GMPY project will involve wrapping, and exposing
    39. 

  39. to Python, exactly these existing libraries (possibly with
    40. 

  40. additional "convenience" wrappers written in Python itself).
    41. 

  41. For starters, we've focused on the popular (and excellent)
    42. 

  42. GNU Multiple Precision library,
    43. 

  43. <A HREF="http://gmplib.org/">GMP</A>,
    44. 

  44. exposing its functionality through module <b>gmpy</b>.
    45. 

  45. 

  46. <H1>The GMPY Module</H1>
    47. 

  47. <P>
    48. 

  48. Python modules older than GMPY exposes a subset of the integral-MP
    49. 

  49. (MPZ) functionality of earlier releases of the GMP library.  The
    50. 

  50. first GMPY goal (currently nearly reached) was to develop the gmpy
    51. 

  51. module into a complete exposure of MPZ, MPF (floating-point), and
    52. 

  52. MPQ (rational) functionality of current GMP (release 4), as well
    53. 

  53. as auxiliary functionality such as random number generation, with
    54. 

  54. full support for current Python releases (2.3 and up) and the
    55. 

  55. Python 'distutils' (and also support for a "C API" allowing some
    56. 

  56. level of interoperation with other C-written extension modules for
    57. 

  57. Python).
    58. 

  58. 

  59. <p>
    60. 

  60. <b>Note</b>: the module's ability to be used as a "drop-in
    61. 

  61. replacement" for Python's own implementation of <i>long</i>s,
    62. 

  62. to rebuild Python from sources in a version using GMP, was a
    63. 

  63. characteristic of the gmp-module we started from, but is
    64. 

  64. <b>not</b> a target of the gmpy project, and we have no plans
    65. 

  65. to support it.
    66. 

  66. <P>
    67. 

  67. This first GMPY
    68. 

  68. module is called <b>gmpy</b>, just like the whole project.
    69. 

  69. <P>
    70. 

  70. The extended MP floating-point facilities of
    71. 

  71. <A HREF="http://www.loria.fr/projets/mpfr/">MPFR</A>
    72. 

  72. will later also be considered for inclusion in gmpy (either within
    73. 

  73. the same module, or as a further, separate add-on module).
    74. 

  74. [[ Rooting for MPFR to be merged with GMP so we can avoid some
    75. 

  75. awkwardness (but seeing no movement on this front so far) ]].
    76. 

  76. 

  77. <H2>Mutability... but <u>not</u> for now</H2>
    78. 

  78. Early tests have shown that supporting Python 2's "in-place
    79. 

  79. operation" functionality (by making MPZ, MPF and MPQ Python objects
    80. 

  80. <b>mutable</b>) would offer a substantial performance boost.
    81. 

  81. <p>
    82. 

  82. Despite this, widespread feeling among Python cognoscenti appears
    83. 

  83. to be against exposing such "mutable numbers".  As a consequence,
    84. 

  84. our current aim is for a first release of GMPY without mutability,
    85. 

  85. to be followed at some later time by one which will also fully
    86. 

  86. support in-place-mutable versions of number objects (as well as
    87. 

  87. the default immutable ones), but only when explicitly and
    88. 

  88. deliberately requested by a user (who can then be presumed to know
    89. 

  89. what he or she is doing).  Meanwhile, caching strategies are used
    90. 

  90. to ameliorate performance issues, and appear to be reasonably
    91. 

  91. worthwhile (so far, only MPZ and MPQ objects are subject to this
    92. 

  92. caching).
    93. 

  93. <p>
    94. 

  94. We've tended to solve other debatable design issues in a similar
    95. 

  95. vein, i.e., by trying to work "like Python's built-in numbers" when
    96. 

  96. there was a choice and two or more alternatives made sense.
    97. 

  97. 

  98. <H1>Project Status and near-future plans</H1>
    99. 

  99. The gmpy module's current release (latest current release
    100. 

  100. as of 2008/10/16: 1.04) is available for download in both
    101. 

  101. source and Windows-binary form, and Mac-binary form too.
    102. 

  102. 

  103. gmpy 1.04 exposes all of the mpz, mpq
    104. 

  104. and mpf functionality that was already available in GMP 3.1, and
    105. 

  105. most of the random-number generation functionality (there are no
    106. 

  106. current plans to extend gmpy to expose other such functionality,
    107. 

  107. although the currently experimental way in which it is architected
    108. 

  108. is subject to possible future changes).
    109. 

  109. <p>
    110. 

  110. On most platforms, you will need to separately procure and install
    111. 

  111. the GMP library itself to be able to build and use GMPY.  Note that
    112. 

  112. 4.0.1 or better is needed; take care: some Linux releases come bundled
    113. 

  113. with <strong>older</strong> GMP versions, such as GMP 3, and you may
    114. 

  114. have to install the latest GMP version instead -- beware also of
    115. 

  115. /usr/lib vs /usr/local/lib issues.
    116. 

  116. <p>
    117. 

  117. Please read the file "windows_build.txt" for detailed instructions on
    118. 

  118. compiling GMP and GMPY using the freely available MinGW tools.
    119. 

  119. <p>
    120. 

  120. [[ OLD: The exception to this need is under (32-bit) Windows, where
    121. 

  121. binary-accompanied releases are the norm, and builds of GMP usable
    122. 

  122. with MS VC++ 6 (the main C compiler used for Python on this platform)
    123. 

  123. are traditionally hard to come by.
    124. 

  124. <p>
    125. 

  125. We started the GMPY project using a VC++ port of GMP.LIB "just found on
    126. 

  126. the net", and later a port by Jorgen Lundman, but are currently relying
    127. 

  127. on other volunteers to build Windows binaries since we don't have any
    128. 

  128. Windows machine any more.  <a
    129. 

  129. href="http://www.cs.nyu.edu/exact/core/gmp/">This site</a> does appear
    130. 

  130. to offer all needed files and instructions for Windows developers who
    131. 

  131. want to re-build the gmpy module from sources; the gmpy project itself
    132. 

  132. just supplies a separate 'binary module' package is supplied, containing
    133. 

  133. only the pre-built GMPY.PYD, for those who do <b>not</b> want to
    134. 

  134. re-build from sources. ]]
    135. 

  135. <p>
    136. 

  136. <b>Do</b> note, however, that <b>all</b> gmpy users should download the
    137. 

  137. gmpy source-package as well, as currently that is the one including
    138. 

  138. <b>gmpy</b> documentation and unit-tests!
    139. 

  139. <H2>Currently-open issues</h2>
    140. 

  140. <p>
    141. 

  141. A still-weakish point is with the output-formatting of mpf numbers;
    142. 

  142. sometimes, this formatting ends up providing a few more digits than
    143. 

  143. a given number's accuracy would actually warrant (a few noise digits
    144. 

  144. after a long string of trailing '0' or '9' digits), particularly when
    145. 

  145. the mpf number is built from a Python float -- the accuracy situation
    146. 

  146. is quite a bit better when the mpf number is built from a <b>string</b>.
    147. 

  147. <p>
    148. 

  148. Because of this, since release 0.6, gmpy introduced an optional
    149. 

  149. 'floating-conversion format string' module-level setting: if present,
    150. 

  150. float-&gt;mpf conversion goes through an intermediate formatted
    151. 

  151. string (by default, it still proceeds directly, at least for now);
    152. 

  152. this does ameliorate things a bit, as does the better tracking done
    153. 

  153. (since 0.6, with further enhancements in 0.7) of the 'requested'
    154. 

  154. precision for an mpf (as opposed to the precision the underlying GMP
    155. 

  155. actually 'assigns' to it); but the issue cannot yet be considered fully
    156. 

  156. solved, and may well still need some design changes in the output
    157. 

  157. formatting functionality.
    158. 

  158. <p>
    159. 

  159. Unit tests are not considered a weak point any more; the over 1000
    160. 

  160. unit-tests now being run provide a decent cover of 93+% SLOC for gmpy.c,
    161. 

  161. up from 72% in 0.7.  The non-covered SLOCs (about 150 of gmpy.c's
    162. 

  162. current 2311 executable lines out of 6205 total)
    163. 

  163. are mostly disaster-tests to handle out-of-memory
    164. 

  164. situations, a smattering of 'defensive
    165. 

  165. programming' cases (to handle situations that 'should never happen,
    166. 

  166. but'...) and some cases of the new experimental 'callbacks' facility
    167. 

  167. (mostly provided for the specific use of PySymbolic, and intended to be
    168. 

  168. tested by that package).  We'll have to do better, eventually (presumably with
    169. 

  169. some mocking approach e.g. to simulate out-of-memory situations), but, for now,
    170. 

  170. this can be considered OK.
    171. 

  171. <p>
    172. 

  172. In the attempt to make gmpy as useful as can be for both stand-alone
    173. 

  173. use, and also in the context of PySymbolic, a tad too many design
    174. 

  174. decisions have been delayed/postponed by introducing module-level
    175. 

  175. flags, letting us 'have it both ways' in the current
    176. 

  176. gmpy 1.04; this has produced a somewhat unwieldy mix of module-level
    177. 

  177. flag-setting and call-back functions.  This whole area's architecture
    178. 

  178. will neet to be revisited, including other such design-decisions yet.
    179. 

  179. 

  180. <H2>Near-future plans</h2>
    181. 

  181. Future releases may have changes including: re-architecting the
    182. 

  182. module-level setting functions; more elegantly formatted documentation;
    183. 

  183. more timing-measurement scripts and usage-examples.  Some of the
    184. 

  184. currently experimental 'callbacks' will also be removed, having been
    185. 

  185. proven unnecessary.  All relevant GMP 4 functionality will be exposed.
    186. 

  186. <p>
    187. 

  187. No predictions on timing, though.  gmpy 1.04 meets all current needs
    188. 

  188. of the main author, so his motivation to work more on it is low:-).
    189. 

  189. So, don't hold your breath (pitching in and helping it happen, on the
    190. 

  190. other hand, _might_ be advisable, and will surely yield results:-).
    191. 

  191. <p>
    192. 

  192. <A HREF="http://code.google.com/p/gmpy/">Project page on
    193. 

  193. code.google.com</A>
    194. 

  194. <A href="http://code.google.com/p/gmpy/">
    195. 

  195. <IMG src="http://code.google.com/images/code_sm.png"
    196. 

  196. width="88" height="31" border="0" alt="Go to Google Code gmpy page"></A>
    197. 

  197. </BODY>
    198. 

  198. </HTML>
    199.