documentation updates

doc/source/bernoulli.rst

@@ -1,6 +1,24 @@
+.. _bernoulli:
+
 **bernoulli.h** -- support for Bernoulli numbers
 ===============================================================================
 
+This module provides helper functions for exact or approximate calculation
+of the Bernoulli numbers, which are defined by the exponential
+generating function
+
+.. math ::
+
+    \frac{x}{e^x-1} = \sum_{n=0}^{\infty} B_n \frac{x^n}{n!}.
+
+Efficient algorithms are implemented for both multi-evaluation
+and calculation of isolated Bernoulli numbers.
+A global (or thread-local) cache is also provided,
+to support fast repeated evaluation of various special functions
+that depend on the Bernoulli numbers (including the gamma function
+and the Riemann zeta function).
+
+
 Generation of Bernoulli numbers
 --------------------------------------------------------------------------------
 
@@ -49,12 +67,13 @@ Caching
 
 .. var:: fmpq * bernoulli_cache
 
-    Global cache of Bernoulli numbers.
+    Cache of Bernoulli numbers. Uses thread-local storage if enabled
+    in FLINT.
 
 .. function:: void bernoulli_cache_compute(long n)
 
-    Makes sure that the Bernoulli numbers up to at least `B_{n-1}` are cached
-    globally. Warning: this function is not currently threadsafe.
+    Makes sure that the Bernoulli numbers up to at least `B_{n-1}` are cached.
+    Calling :func:`flint_cleanup()` frees the cache.
 
 
 Bounding

doc/source/credits.rst

@@ -1,3 +1,5 @@
+.. _credits:
+
 Credits and references
 ===============================================================================
 

doc/source/elefun.rst

@@ -1,6 +1,19 @@
+.. _elefun:
+
 **elefun.h** -- support for evaluation of elementary functions
 ===============================================================================
 
+This module implements algorithms used internally for evaluation
+of elementary functions (exp, log, sin, atan, ...).
+The functions provided here are mainly
+intended for internal use, though they may be useful to call directly in some
+applications where the default algorithm choices are suboptimal.
+Most applications should use the user-friendly functions
+in the :ref:`fmprb <fmprb>` and :ref:`fmpcb <fmpcb>` modules (or for
+power series, the functions in the
+:ref:`fmprb_poly <fmprb-poly>` and :ref:`fmpcb_poly <fmpcb-poly>`
+modules).
+
 The exponential function
 --------------------------------------------------------------------------------
 

doc/source/fmpcb.rst

@@ -1,6 +1,28 @@
+.. _fmpcb:
+
 **fmpcb.h** -- complex numbers
 ===============================================================================
 
+An :type:`fmpcb_t` represents a complex numbers with
+error bounds. An :type:`fmpcb_t` consists of a pair of real number
+balls of type :type:`fmprb_struct`, representing the real and
+imaginary part with separate error bounds.
+
+An :type:`fmpcb_t` thus represents a rectangle
+`[m_1-r_1, m_1+r_1] + [m_2-r_2, m_2+r_2] i` in the complex plane.
+This is used instead of a disk or square representation
+(consisting of a complex floating-point midpoint with a single radius),
+since it allows implementing many operations more conveniently by splitting
+into ball operations on the real and imaginary parts.
+It also allows tracking when complex numbers have an exact (for example
+exactly zero) real part and an inexact imaginary part, or vice versa.
+
+The interface for the :type:`fmpcb_t` type is slightly less developed
+than that for the :type:`fmprb_t` type. In many cases, the user can
+easily perform missing operations by directly manipulating the real and
+imaginary parts.
+
+
 Types, macros and constants
 -------------------------------------------------------------------------------
 
@@ -444,10 +466,14 @@ Special functions
 .. function:: void fmpcb_zeta(fmpcb_t z, const fmpcb_t s, long prec)
 
     Sets *z* to the value of the Riemann zeta function `\zeta(s)`.
+    Note: for computing derivatives with respect to `s`,
+    use :func:`fmpcb_poly_zeta_series` or the functions in the
+    :ref:`zeta <zeta>` module.
 
 .. function:: void fmpcb_hurwitz_zeta(fmpcb_t z, const fmpcb_t s, const fmpcb_t a, long prec)
 
     Sets *z* to the value of the Hurwitz zeta function `\zeta(s, a)`.
-    Note: for computing derivatives with respect to `s`, see the
-    functions in the *zeta* module.
+    Note: for computing derivatives with respect to `s`,
+    use :func:`fmpcb_poly_zeta_series` or the functions in the
+    :ref:`zeta <zeta>` module.
 

doc/source/fmpcb_mat.rst

@@ -1,8 +1,10 @@
+.. _fmpcb-mat:
+
 **fmpcb_mat.h** -- matrices over the complex numbers
 ===============================================================================
 
-An *fmpcb_mat_t* represents a dense matrix over the complex numbers,
-implemented as an array of entries of type *fmpcb_struct*.
+An :type:`fmpcb_mat_t` represents a dense matrix over the complex numbers,
+implemented as an array of entries of type :type:`fmpcb_struct`.
 
 The dimension (number of rows and columns) of a matrix is fixed at
 initialization, and the user must ensure that inputs and outputs to

doc/source/fmpcb_poly.rst

@@ -1,3 +1,5 @@
+.. _fmpcb-poly:
+
 **fmpcb_poly.h** -- polynomials over the complex numbers
 ===============================================================================
 

doc/source/fmpr.rst

@@ -1,3 +1,5 @@
+.. _fmpr:
+
 **fmpr.h** -- binary floating-point numbers
 ===============================================================================
 

doc/source/fmprb.rst

@@ -1,7 +1,9 @@
+.. _fmprb:
+
 **fmprb.h** -- real numbers represented as floating-point balls
 ===============================================================================
 
-An *fmprb_t* represents a ball over the real numbers,
+An :type:`fmprb_t` represents a ball over the real numbers,
 that is, an interval `[m-r, m+r]` where the midpoint `m` and the
 radius `r` are (extended) real numbers and `r` is nonnegative.
 The result of an (approximate) operation done on *fmprb_t* variables
@@ -849,8 +851,9 @@ Special functions
 
     Note: the Hurwitz zeta function is also available, but takes
     complex arguments (see :func:`fmpcb_hurwitz_zeta`).
-    For computation of the derivatives with respect to `s`, see the functions
-    in the *zeta* module.
+    For computing derivatives with respect to `s`,
+    use :func:`fmprb_poly_zeta_series` or the functions in the
+    :ref:`zeta <zeta>` module.
 
 .. function:: void fmprb_zeta_ui(fmprb_t b, ulong n, long prec)
 

doc/source/fmprb_mat.rst

@@ -1,8 +1,10 @@
+.. _fmprb-mat:
+
 **fmprb_mat.h** -- matrices over the real numbers
 ===============================================================================
 
-An *fmprb_mat_t* represents a dense matrix over the real numbers,
-implemented as an array of entries of type *fmprb_struct*.
+An :type:`fmprb_mat_t` represents a dense matrix over the real numbers,
+implemented as an array of entries of type :type:`fmprb_struct`.
 
 The dimension (number of rows and columns) of a matrix is fixed at
 initialization, and the user must ensure that inputs and outputs to

doc/source/fmprb_poly.rst

@@ -1,3 +1,5 @@
+.. _fmprb-poly:
+
 **fmprb_poly.h** -- polynomials over the real numbers
 ===============================================================================
 

doc/source/fmpz_holonomic.rst

@@ -1,3 +1,5 @@
+.. _fmpz-holonomic:
+
 **fmpz_holonomic.h** -- holonomic sequences and functions
 ===============================================================================
 

doc/source/gamma.rst

@@ -1,3 +1,5 @@
+.. _gamma:
+
 **gamma.h** -- support for the gamma function
 ===============================================================================
 
@@ -5,8 +7,11 @@ This module implements various algorithms for evaluating the
 gamma function and related functions. The functions provided here are mainly
 intended for internal use, though they may be useful to call directly in some
 applications where the default algorithm choices are suboptimal.
-Most applications should use the standard, user-friendly top-level functions
-in the *fmprb* and *fmpcb* modules.
+Most applications should use the user-friendly functions
+in the :ref:`fmprb <fmprb>` and :ref:`fmpcb <fmpcb>` modules (or for
+power series, the functions in the
+:ref:`fmprb_poly <fmprb-poly>` and :ref:`fmpcb_poly <fmpcb-poly>`
+modules).
 
 
 Evaluation using Taylor series
@@ -101,12 +106,13 @@ Evaluation using the Stirling series
     :func:`gamma_stirling_bound_fmprb` or
     :func:`gamma_stirling_bound_fmpcb`) is included in the output.
 
-.. function :: void gamma_stirling_eval_fmprb_series(fmprb_ptr res, const fmprb_t z, long n, long num, long prec)
+.. function :: void gamma_stirling_eval_fmprb_series(fmprb_ptr res, const fmprb_t z, long n, long len, long prec)
 
-.. function :: void gamma_stirling_eval_fmpcb_series(fmpcb_ptr res, const fmpcb_t z, long n, long num, long prec)
+.. function :: void gamma_stirling_eval_fmpcb_series(fmpcb_ptr res, const fmpcb_t z, long n, long len, long prec)
 
-    Evaluates the Stirling series of a power series `z + t`,
-    computing *num* coefficients. The error bound (computed via
+    Evaluates the Stirling series of a power series argument `z + t`,
+    writing a power series truncated to length *len* to the output *res*.
+    The error bound (computed via
     :func:`gamma_stirling_bound_fmprb` or
     :func:`gamma_stirling_bound_fmpcb`) is included in the output.
 

doc/source/history.rst

@@ -1,3 +1,5 @@
+.. _history:
+
 History and changes
 ===============================================================================
 

doc/source/hypgeom.rst

@@ -1,3 +1,5 @@
+.. _hypgeom:
+
 **hypgeom.h** -- support for hypergeometric series
 ===============================================================================
 

doc/source/index.rst

@@ -20,6 +20,7 @@ General information
 
    overview.rst
    setup.rst
+   issues.rst
    history.rst
 
 Module documentation

doc/source/issues.rst

@@ -0,0 +1,75 @@
+.. _issues:
+
+Potential issues
+===============================================================================
+
+Interface changes
+-------------------------------------------------------------------------------
+
+As this is an early version, note that any part of the interface is
+subject to change without warning! Most of the core interface should
+be stable at this point, but no guarantees are made.
+
+Correctness
+-------------------------------------------------------------------------------
+
+Except where otherwise specified, Arb is designed to produce
+provably correct error bounds. The code has been written carefully,
+and the library is extensively tested.
+However, like any complex mathematical software, Arb is virtually certain to
+contains bugs, so the usual precautions are advised:
+
+* Perform sanity checks on the output (check known mathematical relations; recompute to another precision and compare)
+* Compare against other mathematical software
+* Read the source code to verify that it does what it is supposed to do
+
+All bug reports are highly welcome!
+
+Integer overflow
+-------------------------------------------------------------------------------
+
+Machine-size integers are used for precisions, sizes of integers in
+bits, lengths of polynomials, and similar quantities that relate
+to sizes in memory. Very few checks are performed to verify that
+such quantities do not overflow.
+Precisions and lengths exceeding a small fraction
+of *LONG_MAX*, say `2^{24} \sim 10^7` on 32-bit systems,
+should be regarded as resulting in undefined behavior.
+On 64-bit systems this should generally not be an issue,
+since most calculations will exhaust the available memory
+(or the user's patience waiting for the computation to complete)
+long before running into integer overflows.
+However, the user needs to be wary of unintentionally passing input
+parameters of order *LONG_MAX* or negative parameters where
+positive parameters are expected, for example due to a runaway loop
+that repeatedly increases the precision.
+
+This caveat does not apply to exponents of floating-point numbers,
+which are represented as arbitrary-precision integers, nor to
+integers used as numerical scalars (e.g. :func:`fmprb_mul_si`).
+However, it still applies to conversions and operations where
+the result is requested exactly and sizes become an issue.
+For example, trying to convert
+the floating-point number `2^{2^{100}}` to an integer could
+result in anything from a silent wrong value to thrashing followed
+by a crash, and it is the user's responsibility not
+to attempt such a thing.
+
+Thread safety and caches
+-------------------------------------------------------------------------------
+
+Arb should be fully threadsafe, provided that both MPFR and FLINT have
+been built in threadsafe mode. Please note that thread safety is
+not currently tested, and extra caution when developing
+multithreaded code is therefore recommended.
+
+Arb may cache some data (such as the value of `\pi` and
+Bernoulli numbers) to speed up various computations. In threadsafe mode,
+caches use thread-local storage (there is currently no way to save memory
+and avoid recomputation by having several threads share the same cache).
+Caches can be freed by calling the ``flint_cleanup()`` function. To avoid
+memory leaks, the user should call ``flint_cleanup()`` when exiting a thread.
+It is also recommended to call ``flint_cleanup()`` when exiting the main
+program (this should result in a clean output when running
+`Valgrind <http://valgrind.org/>`_, and can help catching memory issues).
+

doc/source/overview.rst

@@ -1,3 +1,5 @@
+.. _overview:
+
 Feature overview
 ===============================================================================
 
@@ -12,25 +14,30 @@ standard floating-point arithmetic. (See for example [Hoe2009]_.)
 
 At the moment, Arb contains:
 
-* A module (fmpr) for correctly rounded arbitrary-precision
+* A module (:ref:`fmpr <fmpr>`) for correctly rounded arbitrary-precision
   floating-point arithmetic. Arb numbers have a few special features, such
   as arbitrary-size exponents (useful for combinatorics and asymptotics) and
   dynamic allocation (facilitating implementation of hybrid
   integer/floating-point and mixed-precision algorithms).
 
-* A module (fmprb) for real ball arithmetic, where a ball is
-  implemented as a pair of fmpr numbers, and a corresponding module (fmpcb) for
-  complex numbers in rectangular form.
+* A module (:ref:`fmprb <fmprb>`) for real ball arithmetic, where a ball is
+  implemented as a pair of fmpr numbers, and a corresponding module
+  (:ref:`fmpcb <fmpcb>`) for complex numbers in rectangular form.
 
-* Functions for fast high-precision computation of some mathematical constants,
-  based on ball arithmetic.
+* Functions for fast high-precision evaluation of various
+  mathematical constants and special functions, implemented using
+  ball arithmetic with rigorous error bounds.
 
-* Modules (fmprb_poly, fmpcb_poly) for polynomials or power series over the
-  real and complex numbers, implemented using balls as coefficients,
-  with fast polynomial multiplication.
+* Modules (:ref:`fmprb_poly <fmprb-poly>`, :ref:`fmpcb_poly <fmpcb-poly>`)
+  for polynomials or power series over the real and complex numbers,
+  implemented using balls as coefficients,
+  with asymptotically fast polynomial multiplication and
+  many other operations.
 
-* Modules (fmprb_mat, fmpcb_mat) for matrices over the real and complex
-  numbers, implemented using balls as coefficients.
+* Modules (:ref:`fmprb_mat <fmprb-mat>`, :ref:`fmpcb_mat <fmpcb-mat>`)
+  for matrices over the real and complex numbers,
+  implemented using balls as coefficients.
+  At the moment, only rudimentary linear algebra operations are provided.
 
 Planned features include more transcendental functions and more extensive
 polynomial and matrix functionality, as well as further optimizations.
@@ -47,7 +54,6 @@ The current version of Arb implements most of its floating-point arithmetic
 naively using high-level FLINT types. The speed at low precision is far from
 optimal, and the memory management can sometimes be wasteful. The internals
 will be rewritten in the future to fix the inefficiencies,
-which eventually should make Arb ball arithmetic about as fast as mpz or mpfr arithmetic at any precision.
+which eventually should make Arb ball arithmetic about as fast as
+mpz or mpfr arithmetic at any precision.
 
-**Warning**: as this is an early version, any part of the interface is
-subject to change! Also be aware that there are known and unknown bugs.

doc/source/partitions.rst

@@ -1,3 +1,5 @@
+.. _partitions:
+
 **partitions.h** -- computation of the partition function
 ===============================================================================
 

doc/source/setup.rst

@@ -1,3 +1,5 @@
+.. _setup:
+
 Setup
 ===============================================================================
 
@@ -93,19 +95,3 @@ The output of the example program should be something like the following::
     3.1415926535897932384626433832795028841971693993751 +/- 4.2764e-50
 
 
-Thread safety and caches
--------------------------------------------------------------------------------
-
-Arb should be fully threadsafe, provided that both MPFR and FLINT have
-been built in threadsafe mode. Please note that thread safety is
-not currently tested, and caution is therefore recommended.
-
-Arb may cache some data (such as the value of `\pi` and
-Bernoulli numbers) to speed up various computations. In threadsafe mode,
-caches use thread-local storage (there is currently no way to save memory
-and avoid recomputation by having several threads share the same cache).
-Caches can be freed by calling the ``flint_cleanup()`` function. To avoid
-memory leaks, the user should call ``flint_cleanup()`` when exiting a thread.
-It is also recommended to call ``flint_cleanup()`` when exiting the main
-program.
-

doc/source/zeta.rst

@@ -1,6 +1,18 @@
+.. _zeta:
+
 **zeta.h** -- support for the zeta function
 ===============================================================================
 
+This module implements various algorithms for evaluating the
+Riemann zeta function and related functions. The functions provided here are
+mainly intended for internal use, though they may be useful to call directly
+in some applications where the default algorithm choices are suboptimal.
+Most applications should use the user-friendly functions
+in the :ref:`fmprb <fmprb>` and :ref:`fmpcb <fmpcb>` modules (or for
+power series, the functions in the
+:ref:`fmprb_poly <fmprb-poly>` and :ref:`fmpcb_poly <fmpcb-poly>`
+modules).
+
 Integer zeta values
 -------------------------------------------------------------------------------