1 <?xml version="1.0" encoding="iso-8859-1"?> 2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 3 4 <!-- 5 Copyright 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 Free Software Foundation, Inc. 6 Contributed by the AriC and Caramel projects, INRIA. 7 8 This file is part of the GNU MPFR Library. 9 10 The GNU MPFR Library is free software; you can redistribute it and/or modify 11 it under the terms of the GNU Lesser General Public License as published by 12 the Free Software Foundation; either version 3 of the License, or (at your 13 option) any later version. 14 15 The GNU MPFR Library is distributed in the hope that it will be useful, but 16 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 17 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 18 License for more details. 19 20 You should have received a copy of the GNU Lesser General Public License 21 along with the GNU MPFR Library; see the file COPYING.LESSER. If not, see 22 http://www.gnu.org/licenses/ or write to the Free Software Foundation, Inc., 23 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. 24 --> 25 26 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"> 27 28 <head><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> 29 <title>Frequently Asked Questions about GNU MPFR</title> 30 <style type="text/css">/*<![CDATA[*/ 31 /* Global stylesheet for visual media */ 32 33 html, body 34 { 35 background: white; 36 color: black; 37 } 38 39 div.logo { float: right } 40 div.logo img { border: 0 } 41 42 div.footer img { border: 0 } 43 44 dt 45 { 46 margin-top: 2ex; 47 margin-bottom: 1ex; 48 font-weight: bolder; 49 } 50 51 /* For testing: dd { background: #ddddff } */ 52 53 table { margin: 0.5ex auto } 54 55 li { margin-top: 0.5ex; margin-bottom: 0.5ex } 56 57 dd + dd 58 { 59 margin-top: 0; 60 margin-bottom: 0; 61 padding-top: 0.5ex; 62 padding-bottom: 0; 63 } 64 65 li > p, dd > p 66 { 67 margin-top: 0; 68 margin-bottom: 0; 69 padding-top: 0.5ex; 70 padding-bottom: 0.5ex; 71 } 72 73 .block-code code, code.block-code, 74 .block-code samp, samp.block-code 75 { 76 display: block; 77 padding: 0.5ex 0; 78 margin-left: 2em; 79 } 80 81 .nowrap { white-space: nowrap } 82 83 /* 84 dl.faq { counter-reset: faq } 85 86 dl.faq dt:before 87 { 88 counter-increment: faq; 89 content: counter(faq) ". "; 90 } 91 */ 92 93 dl.faq dt { background: #dddddd } 94 95 dl.faq dd 96 { 97 border-left: 4px solid; 98 border-color: transparent; 99 margin-left: 0em; 100 padding-left: 1.5em; 101 } 102 103 dl.faq dt:target + dd 104 { 105 border-left-color: #aaaaaa; 106 } 107 108 var.env { font-style: normal } 109 /*]]>*/</style> 110 </head> 111 112 <body> 113 114 <h1>Frequently Asked Questions about <cite><acronym>GNU</acronym> <acronym>MPFR</acronym></cite></h1> 115 116 <p><strong>Important notice: Problems with a particular version of 117 <cite><acronym>MPFR</acronym></cite> are discussed in the corresponding 118 bugs page.</strong></p> 119 120 <p>The latest version of this <acronym>FAQ</acronym> is available at 121 <a href="http://www.mpfr.org/faq.html">http://www.mpfr.org/faq.html</a>. 122 Please look at this version if possible.</p> 123 124 <ol> 125 <li><a href="#mpfr_vs_mpf">What are the differences between 126 <cite><acronym>MPF</acronym></cite> from <cite><acronym>GMP</acronym></cite> 127 and <cite><acronym>MPFR</acronym></cite>?</a></li> 128 <li><a href="#mpf2mpfr">How to convert my program written using 129 <cite><acronym>MPF</acronym></cite> to 130 <cite><acronym>MPFR</acronym></cite>?</a></li> 131 <li><a href="#no_libgmp">At configure time, I get the error: <q>libgmp not found or uses a different ABI.</q></a></li> 132 <li><a href="#undef_ref1">I get undefined reference to <code>__gmp_get_memory_functions</code>.</a></li> 133 <li><a href="#undef_ref2">When I link my program with 134 <cite><acronym>MPFR</acronym></cite>, I get undefined reference 135 to <code>__gmpXXXX</code>.</a></li> 136 <li><a href="#crash_high_prec">My program crashes with high precisions.</a></li> 137 <li><a href="#accuracy">Though I have increased the precision, the results 138 are not more accurate.</a></li> 139 <li><a href="#detect_mpfr">How can I detect <cite><acronym>MPFR</acronym></cite> 140 installation using <cite>autoconf</cite> or <cite>pkg-config</cite>?</a></li> 141 <li><a href="#cite">How to cite <cite><acronym>MPFR</acronym></cite> in a 142 scientific publication?</a></li> 143 <li><a href="#fpic">When I build <cite><acronym>MPFR</acronym></cite>, I get 144 an error asking me to recompile with <samp>-fPIC</samp>.</a></li> 145 </ol> 146 147 <dl class="faq"> 148 149 <dt id="mpfr_vs_mpf">1. What are the differences between 150 <cite><acronym>MPF</acronym></cite> from <cite><acronym>GMP</acronym></cite> 151 and <cite><acronym>MPFR</acronym></cite>?</dt> 152 153 <dd><p>The main differences are:</p> 154 <ul> 155 <li><p>The precision of a <cite><acronym>MPFR</acronym></cite> variable 156 is the <em>exact</em> number of bits used for its mantissa, whereas in 157 <cite><acronym>MPF</acronym></cite>, the precision requested by the user 158 is a minimum value (<cite><acronym>MPF</acronym></cite> generally uses a 159 higher precision). With the additional difference below, this implies that 160 the <cite><acronym>MPFR</acronym></cite> results do not depend on the 161 number of bits (16, 32, 64 or more) of the underlying architecture.</p></li> 162 <li><p>As a consequence, <cite><acronym>MPFR</acronym></cite> uses a 163 base-2 exponent, whereas in <cite><acronym>MPF</acronym></cite>, this 164 is a base-2<sup>32</sup> or base-2<sup>64</sup> exponent, depending on 165 the limb size. For this reason (and other internal ones), the maximum 166 exponent range in <cite><acronym>MPFR</acronym></cite> is different 167 (and smaller, if the exponent is represented by the same type as in 168 <cite><acronym>MPF</acronym></cite>).</p></li> 169 <li><p><cite><acronym>MPFR</acronym></cite> provides an additional rounding 170 mode argument to its functions; furthermore, it is guaranteed that the 171 result of any operation is the nearest possible floating-point value from 172 the exact result (considering the input variables as exact values), taking 173 into account the precision of the destination variable and the rounding 174 mode. <cite><acronym>MPFR</acronym></cite> also says whether the rounded 175 result is above or below the exact result.</p></li> 176 <li><p><cite><acronym>MPFR</acronym></cite> supports much more functions 177 (in particular transcendental functions such as exponentials, logarithms, 178 trigonometric functions and so on) and special values: signed zeros, 179 infinities, not-a-number (NaN).</p></li> 180 </ul></dd> 181 182 <dt id="mpf2mpfr">2. How to convert my program written using 183 <cite><acronym>MPF</acronym></cite> to 184 <cite><acronym>MPFR</acronym></cite>?</dt> 185 186 <dd><p>You need to add <q><code>r</code></q> to the function names, and to 187 specify the rounding mode (<code>MPFR_RNDN</code> for rounding to nearest, 188 <code>MPFR_RNDZ</code> for rounding towards zero, <code>MPFR_RNDU</code> 189 for rounding towards plus infinity, <code>MPFR_RNDD</code> for rounding 190 towards minus infinity). You can also define macros as follows: 191 <code class="block-code">#define mpf_add(a, b, c) mpfr_add(a, b, c, MPFR_RNDN)</code></p> 192 <p>The header file <samp>mpf2mpfr.h</samp> from the 193 <cite><acronym>MPFR</acronym></cite> distribution automatically 194 redefines all <cite><acronym>MPF</acronym></cite> functions in this 195 way, using the default <cite><acronym>MPFR</acronym></cite> rounding 196 mode. Thus you simply need to add the following line in all your files 197 using <cite><acronym>MPF</acronym></cite> functions: 198 <code class="block-code">#include <mpf2mpfr.h></code> 199 just after the <samp>gmp.h</samp> and <samp>mpfr.h</samp> 200 header files. If the program uses <cite><acronym>MPF</acronym></cite> 201 internals (such as direct access to <code>__mpf_struct</code> members), 202 additional changes will be needed.</p></dd> 203 204 <dt id="no_libgmp">3. At configure time, I get the error: <q>libgmp not found or uses a different ABI.</q></dt> 205 206 <dd><p>This test (<samp>checking for __gmpz_init in -lgmp</samp>) comes 207 after the <samp>gmp.h</samp> detection. The failure occurs either because 208 the <cite><acronym>GMP</acronym></cite> library could not be found 209 (as it is not in the provided library search paths) or because the 210 <cite><acronym>GMP</acronym></cite> library that was found does not have 211 the expected <acronym title="Application Binary Interface">ABI</acronym> 212 (<abbr>e.g.</abbr> 32-bit <abbr>vs</abbr> 64-bit). The former problem can be 213 due to the fact that a static build of <cite><acronym>MPFR</acronym></cite> 214 was requested while only a shared <cite><acronym>GMP</acronym></cite> library 215 is installed (or the opposite, but another error can also show up in this 216 case, see the <a href="#fpic">question about <samp>-fPIC</samp></a>). The 217 latter problem can have several causes:</p> 218 <ul> 219 <li>A wrong libgmp library has been picked up. This can occur if you have 220 several <cite><acronym>GMP</acronym></cite> versions installed on the 221 machine and something is wrong with the provided library search paths.</li> 222 <li>Wrong compiler options (<samp>CFLAGS</samp>) were given. In general, the 223 presence or absence of the <samp>-m64</samp> compiler option must match the 224 library <acronym title="Application Binary Interface">ABI</acronym>.</li> 225 <li>A wrong <samp>gmp.h</samp> file has been picked up (if you have several 226 <cite><acronym>GMP</acronym></cite> versions installed). Indeed, by default, 227 <cite><acronym>MPFR</acronym></cite> gets the compiler options from the 228 <samp>gmp.h</samp> file (with <cite><acronym>GMP</acronym></cite> 4.2.3 229 or later); this is needed because <cite><acronym>GMP</acronym></cite> does 230 not necessarily use the default <acronym>ABI</acronym>. The consequence is 231 that if the <samp>gmp.h</samp> file is associated with a library using a 232 different <acronym>ABI</acronym>, the <acronym>ABI</acronym>-related options 233 will be incorrect. Hence the failure.</li> 234 </ul> 235 <p>Note: The <samp>config.log</samp> output gives more information 236 than the error message. In particular, see the output of the test: 237 <samp>checking for CC and CFLAGS in gmp.h</samp>; it should give you 238 the default compiler options (from <samp>gmp.h</samp>).</p> 239 240 <p>See also the answer to the <a href="#undef_ref1">next question</a>.</p></dd> 241 242 <dt id="undef_ref1">4. I get undefined reference to <code>__gmp_get_memory_functions</code>.</dt> 243 244 <dd><p>Note: this was mainly a problem when upgrading from 245 <cite><acronym>GMP</acronym></cite> 4.1.4 to a later version, 246 but information given below may still be useful in other cases, 247 when several <cite><acronym>GMP</acronym></cite> libraries are 248 installed on the same machine.</p> 249 250 <p>If you get such an error, in particular when running 251 <samp>make check</samp>, then this probably means that you are using 252 the header file from <cite><acronym>GMP</acronym></cite> 4.2.x but the 253 <cite><acronym>GMP</acronym></cite> 4.1.4 library. This can happen if 254 several <cite><acronym>GMP</acronym></cite> versions are installed on 255 your machine (<abbr>e.g.</abbr>, one provided by the system in 256 <samp>/usr/{include,lib}</samp> and a new one installed by the owner or 257 administrator of the machine in <samp>/usr/local/{include,lib}</samp>) 258 and your include and library search paths are inconsistent. On various 259 <acronym>GNU</acronym>/Linux machines, this is unfortunately the case 260 by default (<samp>/usr/local/include</samp> is in the default include 261 search path, but <samp>/usr/local/lib</samp> is <em>not</em> in the 262 default library search path). Typical errors are: 263 <samp class="block-code">undefined reference to `__gmp_get_memory_functions'</samp> 264 in <samp>make check</samp>. The best solution is to add 265 <samp>/usr/local/include</samp> to your <var class="env">C_INCLUDE_PATH</var> 266 environment variable and to add <samp>/usr/local/lib</samp> to your 267 <var class="env">LIBRARY_PATH</var> and <var class="env">LD_LIBRARY_PATH</var> 268 environment variables (and/or <var class="env">LD_RUN_PATH</var>). 269 Alternatively, you can use <samp>--with-gmp*</samp> configure options, 270 <abbr>e.g.</abbr> <samp>--with-gmp=/usr/local</samp>, but <strong>this is 271 not guaranteed to work</strong> (in particular with <samp>gcc</samp> and 272 system directories such as <samp>/usr</samp> or <samp>/usr/local</samp>), 273 and other software that uses <cite><acronym>GMP</acronym></cite> and/or 274 <cite><acronym>MPFR</acronym></cite> will need correct paths too; 275 environment variables allow you to set them in a global way.</p> 276 <p>Other information can be given in the <samp>INSTALL</samp> file and 277 <samp>ld</samp> manual. Please look at them for more details. See also 278 the <a href="#undef_ref2">next question</a>.</p></dd> 279 280 <dt id="undef_ref2">5. When I link my program with 281 <cite><acronym>MPFR</acronym></cite>, I get undefined reference 282 to <code>__gmpXXXX</code>.</dt> 283 284 <dd><p>Link your program with <cite><acronym>GMP</acronym></cite>. Assuming 285 that your program is <samp>foo.c</samp>, you should link it using: 286 <samp class="block-code">cc link.c -lmpfr -lgmp</samp> 287 <cite><acronym>MPFR</acronym></cite> library reference (<samp>-lmpfr</samp>) 288 should be before <cite><acronym>GMP</acronym></cite>'s one 289 (<samp>-lgmp</samp>). Another solution is, with <acronym>GNU</acronym> 290 <samp>ld</samp>, to give all the libraries inside a group: 291 <samp class="block-code">gcc link.c -Wl,--start-group libgmp.a libmpfr.a -Wl,--end-group</samp> 292 See <samp>INSTALL</samp> file and <samp>ld</samp> manual for more 293 details.</p> 294 <p>If you used correct link options, but still get an error, this may mean 295 that your include and library search paths are inconsistent. Please see the 296 <a href="#undef_ref1">previous question</a>.</p></dd> 297 298 <dt id="crash_high_prec">6. My program crashes with high precisions.</dt> 299 300 <dd><p>Your stack size limit may be too small; indeed, by default, 301 <cite><acronym>GMP</acronym></cite> 4.1.4 and below allocates all 302 temporary results on the stack, and in very high precisions, this 303 limit may be reached. You can solve this problem in different ways:</p> 304 <ul> 305 <li><p>You can upgrade to <cite><acronym>GMP</acronym></cite> 4.2 (or above), 306 which now makes temporary allocations on the stack only when they are 307 small.</p></li> 308 <li><p>You can increase the stack size limit with the <samp>limit</samp>, 309 <samp>unlimit</samp> or <samp>ulimit</samp> command, depending on your 310 shell. This may fail on some systems, where the maximum stack size cannot 311 be increased above some value.</p></li> 312 <li><p>You can rebuild both <cite><acronym>GMP</acronym></cite> and 313 <cite><acronym>MPFR</acronym></cite> to use another allocation method.</p></li> 314 </ul></dd> 315 316 <dt id="accuracy">7. Though I have increased the precision, the results 317 are not more accurate.</dt> 318 319 <dd><p>The reason may be the use of C floating-point numbers. If you want 320 to store a floating-point constant to a <code>mpfr_t</code>, you should use 321 <code>mpfr_set_str</code> (or one of the <cite><acronym>MPFR</acronym></cite> 322 constant functions, such as <code>mpfr_const_pi</code> for π) instead 323 of <code>mpfr_set_d</code> or <code>mpfr_set_ld</code>. Otherwise the 324 floating-point constant will be first converted into a reduced-precision 325 (<abbr>e.g.</abbr>, 53-bit) binary number before 326 <cite><acronym>MPFR</acronym></cite> can work with it. This is the case 327 in particular for most exact decimal numbers, such as 0.17, which are 328 not exactly representable in binary.</p> 329 <p>Also remember that <cite><acronym>MPFR</acronym></cite> does not track 330 the accuracy of the results: copying a value <var>x</var> to <var>y</var> 331 with <code>mpfr_set (y, x, MPFR_RNDN)</code> where the variable <var>y</var> 332 is more precise than the variable <var>x</var> will not make it more 333 accurate; the (binary) value will remain unchanged.</p></dd> 334 335 <dt id="detect_mpfr">8. How can I detect <cite><acronym>MPFR</acronym></cite> 336 installation using <cite>autoconf</cite> or <cite>pkg-config</cite>?</dt> 337 338 <dd><p>The <cite><acronym>MPFR</acronym></cite> team does not currently 339 recommend any <cite>autoconf</cite> code, but a section will later 340 be added to the <cite><acronym>MPFR</acronym></cite> manual. The 341 <cite><acronym>MPFR</acronym></cite> team does not wish to support 342 <cite>pkg-config</cite> yet.</p></dd> 343 344 <dt id="cite">9. How to cite <cite><acronym>MPFR</acronym></cite> in a 345 scientific publication?</dt> 346 347 <dd><p>To properly cite <cite><acronym>MPFR</acronym></cite> in a scientific 348 publication, please cite the 349 <a href="http://doi.acm.org/10.1145/1236463.1236468"><acronym title="Association for Computing Machinery">ACM</acronym> 350 <acronym title="Transactions on Mathematical Software">TOMS</acronym> 351 paper</a> 352 (<a href="http://toms.acm.org/cgi/TOMSbibget.cgi?Fousse:2007:MMP">BibTeX</a>) 353 and/or the library web page 354 <a href="http://www.mpfr.org/">http://www.mpfr.org</a>. If your publication 355 is related to a particular release of <cite><acronym>MPFR</acronym></cite>, 356 for example if you report timings, please also indicate the release number 357 for future reference.</p></dd> 358 359 <dt id="fpic">10. When I build <cite><acronym>MPFR</acronym></cite>, I get 360 an error asking me to recompile with <samp>-fPIC</samp>.</dt> 361 362 <dd><p>A typical error looks like:</p> 363 <p><tt>/usr/bin/ld: <em>/path/to/</em>libgmp.a(realloc.o): relocation 364 R_X86_64_32 against `.rodata.str1.1' can not be used when making a 365 shared object; recompile with -fPIC<br /> 366 <em>/path/to/</em>libgmp.a: could not read symbols: Bad value<br /> 367 collect2: ld returned 1 exit status</tt></p> 368 <p>The probable reason is that you tried to build 369 <cite><acronym>MPFR</acronym></cite> with the shared library enabled (this 370 is the default), while only a static <cite><acronym>GMP</acronym></cite> 371 library could be found. To solve this problem, either rebuild and reinstall 372 <cite><acronym>GMP</acronym></cite> without the <samp>--disable-shared</samp> 373 configure option, or configure <cite><acronym>MPFR</acronym></cite> with 374 <samp>--disable-shared</samp>. If you did this and still get the above 375 error, the cause may be conflicting <cite><acronym>GMP</acronym></cite> 376 versions installed on your system; please check that your search path 377 settings are correct.</p> 378 <p>Additional note about the last sentence: Under <acronym>GNU</acronym>/Linux 379 (for instance), the linker takes the first library found in the library search 380 path, whether it is dynamic or static. The default behavior under darwin is 381 different, but <cite><acronym>MPFR</acronym></cite> will change it.</p></dd> 382 <!-- Reference concerning darwin: see MPFR_LD_SEARCH_PATHS_FIRST 383 in MPFR's configure.{ac,in} and acinclude.m4 --> 384 385 </dl> 386 387 </body> 388 389 </html> 390
