How To Contribute to GNU MPFR?

There are several ways to contribute to MPFR:

• contribute a new mathematical function (see below);
• find, report and fix bugs;
• improve the code coverage and/or contribute new test cases;
• improve the documentation;
• measure and improve the efficiency of the code.

The Reporting Bugs section of the MPFR manual gives details on how to report new bugs.

How To Contribute a New Mathematical Function to MPFR?

Assume you want to write the code, say mpfr_foo, for a new mathematical function (say foo):

• You (or your employer, depending on your status or your country) first have to agree to donate your contribution to the MPFR project, more precisely to agree with the license used by MPFR, to agree to assign the copyright of your code to the FSF (this page explains why). In addition, if it applies, your employer has to agree to disclaim rights on your contribution.
• You need to define precisely the function you want to implement, in mathematical terms. For example, the dilogarithm function has different meanings in the literature. Use either a power series, an integral representation... If possible, give references to the literature.
• Then you need to choose an algorithm to evaluate the function foo. Write this algorithm, by detailing each atomic operation. Then you have to perform an error analysis of your algorithm (both the mathematical error, i.e., when neglecting terms of a Taylor series, and the roundoff error). See for example the algorithms.tex document (PDF version), which contains numerous examples of such algorithms and error analyses. In some cases, you will need different algorithms depending on the output precision and/or on the input range. Please write this description in LaTeX, so that it can easily be included in the algorithms.tex document.
• Implement in C the algorithm(s) described in the previous step. You have to follow the following guidelines:
  • conform to the ISO C90 and C99 standards;
  • conform to the GNU Coding Standards;
  • do not use machine floating-point types (float, double, etc.);
  • do not use functions defined in <math.h>, since they might give different results on different configurations;
  • further technical information is available in the README.dev file from the MPFR Git repository.
  For example, use the following to decide if the computed approximation enables one to deduce correct rounding:

      MPFR_CAN_ROUND (approx, approx_err, out_prec, rnd_mode)

• Implement a test program (say tfoo.c) that tests your implementation for correctness. This test program should:
  • test special values (±0, ±Inf, NaN);
  • test exact values, for example exp2(1) = 2, sqrt(25) = 5, etc.;
  • test hard-coded values that you have computed with another software tool, using a large precision. Please input those values in the same format as in the tests/data/exp file for example. Please indicate if those input/output pair were formally verified. See the data_check function in tests/tests.c;
  • test random values: generate a random number x, compute foo(x) with say p bits, then foo(x) with p+10 bits, and check that both results are compatible. A useful function that does that automatically is test_generic from tests/tgeneric.c;
  • test bad cases for the correct rounding. If the inverse function has been implemented, the bad_cases function from tests/tests.c can be used;
  • test in-place operations, i.e., with same input and output pointers, like mpfr_foo (a, a, ...). See the reuse.c test program.
• Write the documentation of the mpfr_foo function in the file mpfr.texi.
• (Optional) Test the efficiency of your implementation and compare it to other software tools.
• Send your contribution as a patch (obtained with git diff) with respect to the development version to the MPFR developers. They will review your contribution to decide if it will be included in MPFR. In that case, your contribution will be acknowledged in the corresponding source files and in the documentation.
• Here is an example of such a patch, which contributes the mpfr_add17 function to MPFR (note: this patch predates the source reorganization, so that some files should actually be in the doc or src directories; moreover, the new add17.c and tadd17.c files are not provided in this example).

Back to the MPFR page.