document the partitions module

doc/source/credits.rst

@@ -58,6 +58,8 @@ Bibliography
 
 .. [Hoe2009] \J. van der Hoeven, "Ball arithmetic", Technical Report, HAL 00432152 (2009). http://www.texmacs.org/joris/ball/ball-abs.html
 
+.. [Joh2012] \F. Johansson, "Efficient implementation of the Hardy-Ramanujan-Rademacher formula", LMS Journal of Computation and Mathematics, Volume 15 (2012), 341-359, http://journals.cambridge.org/action/displayAbstract?fromPage=online&aid=8710297
+
 .. [Kar1998] \E. A. Karatsuba, "Fast evaluation of the Hurwitz zeta function and Dirichlet L-series", Problems of Information Transmission 34:4 (1998), 342-353. http://www.mathnet.ru/php/archive.phtml?wshow=paper&jrnid=ppi&paperid=425&option_lang=eng
 
 .. [Kob2010] \A. Kobel, "Certified Complex Numerical Root Finding", Seminar on Computational Geometry and Geometric Computing (2010), http://www.mpi-inf.mpg.de/departments/d1/teaching/ss10/Seminar_CGGC/Slides/02_Kobel_NRS.pdf

doc/source/index.rst

@@ -40,6 +40,7 @@ Module documentation
    gamma.rst
    zeta.rst
    hypgeom.rst
+   partitions.rst
    fmpz_holonomic.rst
 
 Credits and references

doc/source/partitions.rst

@@ -0,0 +1,44 @@
+**partitions.h** -- computation of the partition function
+===============================================================================
+
+This module implements the asymptotically fast algorithm
+for evaluating the integer partition function `p(n)`
+described in [Joh2012]_.
+The idea is to evaluate a truncation of the Hardy-Ramanujan-Rademacher series
+using tight precision estimates, and symbolically factoring the
+occurring exponential sums.
+
+An implementation based on floating-point arithmetic can
+also be found in FLINT. That version is significantly faster for
+small `n` (e.g. `n < 10^6`), but relies on some numerical subroutines
+that have not been proved correct.
+
+The implementation provided here uses ball arithmetic throughout to guarantee
+a correct error bound for the numerical approximation of `p(n)`.
+For large `n`, it is nearly as fast as the floating-point version in FLINT.
+
+.. function:: void partitions_rademacher_bound(fmpr_t b, ulong n, ulong N)
+
+    Sets `b` to an upper bound for
+
+    .. math ::
+
+        M(n,N) = \frac{44 \pi^2}{225 \sqrt 3} N^{-1/2}
+                  + \frac{\pi \sqrt{2}}{75} \left( \frac{N}{n-1} \right)^{1/2}
+                \sinh\left(\frac{\pi}{N} \sqrt{\frac{2n}{3}}\right).
+
+    This formula gives an upper bound for the truncation error in the
+    Hardy-Ramanujan-Rademacher formula when the series is taken up
+    to the term `t(n,N)` inclusive.
+
+.. function:: void partitions_hrr_sum_fmprb(fmprb_t x, ulong n, long N0, long N)
+
+    Evaluates the partial sum `\sum_{k=N_0}^N t(n,k)` of the
+    Hardy-Ramanujan-Rademacher series.
+
+.. function:: void partitions_fmpz_ui(fmpz_t p, ulong n)
+
+    Computes the partition function `p(n)` using the Hardy-Ramanujan-Rademacher
+    formula. This function computes a numerical ball containing `p(n)`
+    and verifies that the ball contains a unique integer.
+