Re: [boost] [math] Numeric constants docs out of date?

Subject: Re: [boost] [math] Numeric constants docs out of date?
From: Beman Dawes (bdawes_at_[hidden])
Date: 2012-04-08 15:27:31

On Sun, Apr 8, 2012 at 12:08 PM, John Maddock <boost.regex_at_[hidden]> wrote:
>> The docs for Numeric Constants seems out-of-date compared to the
>> <boost/math/constants/constants.hpp> header.
>>
>> See
>> http://www.boost.org/doc/libs/1_49_0/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals1/constants.html
>>
>> For example, the docs list 15 constants, but the header supplies 65 or
>> so constants.
>>
>> Beyond simply missing some functions, the description is so scanty it
>> looks like it may be for a much less capable older version of the
>> header.
>>
>> Am I missing something?
>
>
> I believe you're looking at the header in Trunk, and docs in the last
> release (in which the constants were a barely documented implementation
> detail).

Duh! Sorry for the noise.

The docs are quite nice. A couple of suggestions:

* In the Introduction's "Why use Boost.Math mathematical constants?"
section, consider adding a top level bullet calling out the supported
UDT types, rather than mentioning them in the "Accurate" bullet. See
attached. UDT support seems to me to be too interesting and important
to bury in a description of accuracy.

* Consider adding a historical note somewhere mentioning some of the
past math constant attempts and why they were considered insufficient.
Then add a FAQ entry "Why is the header done that way?" with an answer
that points to the historical note for the problems naive approaches
run into.

HTH,

--Beman


     Built-in and UDT types - including multiprecision user-defined type (UDT)
   floating-point types like NTL, MPFR/GMP, mp_float.

     Accurate - ensuring that the values are as accurate as possible for the
   chosen floating-point type.

     * No loss of accuracy from repeated rounding of intermediate computations.
     * Result is computed with higher precision and only rounded once.
     * Less risk of inaccurate result from functions pow, trig and log at
       [1]corner cases.
     * Less risk of [2]cancellation error.

References

   1. http://en.wikipedia.org/wiki/Corner_case
   2. http://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html