PageRenderTime 39ms CodeModel.GetById 28ms app.highlight 4ms RepoModel.GetById 2ms app.codeStats 0ms

/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<HEAD>
  3<TITLE>Welcome to General Multiprecision PYthon
  4</TITLE>
  5
  6<!--
  7<LINK rel="stylesheet"
  8    href="http://sourceforge.net/sourceforge.css"
  9    type="text/css">
 10-->
 11
 12<STYLE>
 13body { margin-left: 30; margin-right: 30; }
 14</STYLE>
 15
 16</HEAD>
 17<BODY>
 18<FONT SIZE=-1>
 19Last updated on: 2008, June 22;
 20for GMPY release: 1.04
 21<A href="http://code.google.com/p/gmpy/">
 22<IMG src="http://code.google.com/images/code_sm.png"
 23width="88" height="31" border="0" alt="Go to Google Code gmpy page"></A>
 24<br>
 25</FONT>
 26<H1>GMPY Project goals and strategies</H1>
 27The General Multiprecision PYthon project (GMPY) focuses on
 28Python-usable modules providing multiprecision arithmetic
 29functionality to Python programmers.  The project mission
 30includes both C and C++ Python-modules (for speed) and pure
 31Python modules (for flexibility and convenience); it
 32potentially includes integral, rational and floating-point
 33arithmetic in any base.  Only cross-platform functionality
 34is of interest, at least for now.
 35<P>
 36As there are many good existing free C and C++ libraries
 37that address these issues, it is expected that most of the
 38work of the GMPY project will involve wrapping, and exposing
 39to Python, exactly these existing libraries (possibly with
 40additional "convenience" wrappers written in Python itself).
 41For starters, we've focused on the popular (and excellent)
 42GNU Multiple Precision library,
 43<A HREF="http://gmplib.org/">GMP</A>,
 44exposing its functionality through module <b>gmpy</b>.
 45
 46<H1>The GMPY Module</H1>
 47<P>
 48Python modules older than GMPY exposes a subset of the integral-MP
 49(MPZ) functionality of earlier releases of the GMP library.  The
 50first GMPY goal (currently nearly reached) was to develop the gmpy
 51module into a complete exposure of MPZ, MPF (floating-point), and
 52MPQ (rational) functionality of current GMP (release 4), as well
 53as auxiliary functionality such as random number generation, with
 54full support for current Python releases (2.3 and up) and the
 55Python 'distutils' (and also support for a "C API" allowing some
 56level of interoperation with other C-written extension modules for
 57Python).
 58
 59<p>
 60<b>Note</b>: the module's ability to be used as a "drop-in
 61replacement" for Python's own implementation of <i>long</i>s,
 62to rebuild Python from sources in a version using GMP, was a
 63characteristic of the gmp-module we started from, but is
 64<b>not</b> a target of the gmpy project, and we have no plans
 65to support it.
 66<P>
 67This first GMPY
 68module is called <b>gmpy</b>, just like the whole project.
 69<P>
 70The extended MP floating-point facilities of
 71<A HREF="http://www.loria.fr/projets/mpfr/">MPFR</A>
 72will later also be considered for inclusion in gmpy (either within
 73the same module, or as a further, separate add-on module).
 74[[ Rooting for MPFR to be merged with GMP so we can avoid some
 75awkwardness (but seeing no movement on this front so far) ]].
 76
 77<H2>Mutability... but <u>not</u> for now</H2>
 78Early tests have shown that supporting Python 2's "in-place
 79operation" functionality (by making MPZ, MPF and MPQ Python objects
 80<b>mutable</b>) would offer a substantial performance boost.
 81<p>
 82Despite this, widespread feeling among Python cognoscenti appears
 83to be against exposing such "mutable numbers".  As a consequence,
 84our current aim is for a first release of GMPY without mutability,
 85to be followed at some later time by one which will also fully
 86support in-place-mutable versions of number objects (as well as
 87the default immutable ones), but only when explicitly and
 88deliberately requested by a user (who can then be presumed to know
 89what he or she is doing).  Meanwhile, caching strategies are used
 90to ameliorate performance issues, and appear to be reasonably
 91worthwhile (so far, only MPZ and MPQ objects are subject to this
 92caching).
 93<p>
 94We've tended to solve other debatable design issues in a similar
 95vein, i.e., by trying to work "like Python's built-in numbers" when
 96there was a choice and two or more alternatives made sense.
 97
 98<H1>Project Status and near-future plans</H1>
 99The gmpy module's current release (latest current release
100as of 2008/10/16: 1.04) is available for download in both
101source and Windows-binary form, and Mac-binary form too.
102
103gmpy 1.04 exposes all of the mpz, mpq
104and mpf functionality that was already available in GMP 3.1, and
105most of the random-number generation functionality (there are no
106current plans to extend gmpy to expose other such functionality,
107although the currently experimental way in which it is architected
108is subject to possible future changes).
109<p>
110On most platforms, you will need to separately procure and install
111the GMP library itself to be able to build and use GMPY.  Note that
1124.0.1 or better is needed; take care: some Linux releases come bundled
113with <strong>older</strong> GMP versions, such as GMP 3, and you may
114have to install the latest GMP version instead -- beware also of
115/usr/lib vs /usr/local/lib issues.
116<p>
117Please read the file "windows_build.txt" for detailed instructions on
118compiling GMP and GMPY using the freely available MinGW tools.
119<p>
120[[ OLD: The exception to this need is under (32-bit) Windows, where
121binary-accompanied releases are the norm, and builds of GMP usable
122with MS VC++ 6 (the main C compiler used for Python on this platform)
123are traditionally hard to come by.
124<p>
125We started the GMPY project using a VC++ port of GMP.LIB "just found on
126the net", and later a port by Jorgen Lundman, but are currently relying
127on other volunteers to build Windows binaries since we don't have any
128Windows machine any more.  <a
129href="http://www.cs.nyu.edu/exact/core/gmp/">This site</a> does appear
130to offer all needed files and instructions for Windows developers who
131want to re-build the gmpy module from sources; the gmpy project itself
132just supplies a separate 'binary module' package is supplied, containing
133only the pre-built GMPY.PYD, for those who do <b>not</b> want to
134re-build from sources. ]]
135<p>
136<b>Do</b> note, however, that <b>all</b> gmpy users should download the
137gmpy source-package as well, as currently that is the one including
138<b>gmpy</b> documentation and unit-tests!
139<H2>Currently-open issues</h2>
140<p>
141A still-weakish point is with the output-formatting of mpf numbers;
142sometimes, this formatting ends up providing a few more digits than
143a given number's accuracy would actually warrant (a few noise digits
144after a long string of trailing '0' or '9' digits), particularly when
145the mpf number is built from a Python float -- the accuracy situation
146is quite a bit better when the mpf number is built from a <b>string</b>.
147<p>
148Because of this, since release 0.6, gmpy introduced an optional
149'floating-conversion format string' module-level setting: if present,
150float-&gt;mpf conversion goes through an intermediate formatted
151string (by default, it still proceeds directly, at least for now);
152this does ameliorate things a bit, as does the better tracking done
153(since 0.6, with further enhancements in 0.7) of the 'requested'
154precision for an mpf (as opposed to the precision the underlying GMP
155actually 'assigns' to it); but the issue cannot yet be considered fully
156solved, and may well still need some design changes in the output
157formatting functionality.
158<p>
159Unit tests are not considered a weak point any more; the over 1000
160unit-tests now being run provide a decent cover of 93+% SLOC for gmpy.c,
161up from 72% in 0.7.  The non-covered SLOCs (about 150 of gmpy.c's
162current 2311 executable lines out of 6205 total)
163are mostly disaster-tests to handle out-of-memory
164situations, a smattering of 'defensive
165programming' cases (to handle situations that 'should never happen,
166but'...) and some cases of the new experimental 'callbacks' facility
167(mostly provided for the specific use of PySymbolic, and intended to be
168tested by that package).  We'll have to do better, eventually (presumably with
169some mocking approach e.g. to simulate out-of-memory situations), but, for now,
170this can be considered OK.
171<p>
172In the attempt to make gmpy as useful as can be for both stand-alone
173use, and also in the context of PySymbolic, a tad too many design
174decisions have been delayed/postponed by introducing module-level
175flags, letting us 'have it both ways' in the current
176gmpy 1.04; this has produced a somewhat unwieldy mix of module-level
177flag-setting and call-back functions.  This whole area's architecture
178will neet to be revisited, including other such design-decisions yet.
179
180<H2>Near-future plans</h2>
181Future releases may have changes including: re-architecting the
182module-level setting functions; more elegantly formatted documentation;
183more timing-measurement scripts and usage-examples.  Some of the
184currently experimental 'callbacks' will also be removed, having been
185proven unnecessary.  All relevant GMP 4 functionality will be exposed.
186<p>
187No predictions on timing, though.  gmpy 1.04 meets all current needs
188of the main author, so his motivation to work more on it is low:-).
189So, don't hold your breath (pitching in and helping it happen, on the
190other hand, _might_ be advisable, and will surely yield results:-).
191<p>
192<A HREF="http://code.google.com/p/gmpy/">Project page on
193code.google.com</A>
194<A href="http://code.google.com/p/gmpy/">
195<IMG src="http://code.google.com/images/code_sm.png"
196width="88" height="31" border="0" alt="Go to Google Code gmpy page"></A>
197</BODY>
198</HTML>