[boost] [math toolkit] Review results

From: Matthias Schabel (boost_at_[hidden])
Date: 2007-05-02 14:30:01

I'd like to congratulate John Maddock, Paul Bristow, and their  
contributors on putting together an outstanding submission to Boost.  
It is rare to have complete unanimity among votes, but in this case  
there were no dissenters to accepting either the special functions or  
the statistical distributions portions of the library, so I'm glad to  
announce that it has been accepted for inclusion in Boost. Thanks to  
the many participants in the review : Gottlob Frege, Guillaume  
Melquiond, Johan Råde, Arnaldur Gylfason, John Phillips, Mark Van De  
Vyver, Stephan Tolksdorf, Hubert Holin, Seweryn Habdank-Wojewodski,  
Kevin Lynch, Leonaldo Peralta, Jeff Garland, and Stefan Seefeld  
(apologies for anyone I might have missed in this list).

Here is a brief summary of the relatively few major issues that were  
raised during the course of the review :

1) Error handling is an issue that arises because this library is at  
the frontier between traditional numerical libraries and a  
(hopefully) new breed of such libraries that utilize modern  
programming techniques and facilities. Jeff Garland suggested that  
the default behavior should be to throw an exception, with errno  
being an option enabled by macro. It would also be nice to have more  
granular control over which instances throw exceptions and which do  
not (so, for example, a user could choose to ignore denormals). It  
was also suggested that additional, more transparent exceptions be  
provided for cases such as failure to converge rather than reusing  
tools::logic_error.

2) Jeff Garland also pointed out, rightly in my opinion, that  
attempts to use statistical functions that do not exist for a  
distribution should fail to compile rather than leading to a runtime  
error (e.g. mean of a Cauchy distribution). A reasonable method of  
implementing this should be devised or a strong argument for why it  
is not feasible/desirable provided.

3) Arnaldur Gylfason did some nice accuracy and performance testing  
vs. R. It was noted that the performance of quantile functions in  
this library was significantly worse than R, unlike non-quantile  
functions. He also pointed out that, for discrete distributions, the  
current behavior of returning fractional results for quantiles may  
not be the expected one. These issues should be addressed and  
documented.

4) Hubert Holin suggested the possibility of use of a policy  
parameter to choose between speed and accuracy. Another interesting  
possibility would be to allow the user to specify the desired  
precision either at compile or runtime.

5) It appears that this library will actually become two  
"sublibraries" within the Boost.Math library. Currently all code  
lives in the boost::math namespace; I would like to at least see a  
discussion of the possibility of having  
boost::math::special_functions, boost::math::statistics, and,  
perhaps, boost::math::statistics::distributions namespaces - as more  
functionality gets added to boost::math, collisions will become more  
likely, so some thought given now to logical partitioning may save  
pain later.

During the review a number of typos and minor issues of documentation  
were raised, which the authors will need to address if they haven't  
already. In particular, John Phillips noted that the rationale behind  
using rational (vs. polynomial) approximations be clarified, the  
derivation of coefficients be documented, and the list of special  
functions in the documentation be expanded to encompass all functions  
actually implemented in the library. Stephan Tolksdorf requested a  
table listing standard statistical tests and the corresponding  
library implementations and enumerated a number of other  
documentation issues.

Overall, the library was very well received, and the authors are to  
be commended on the tremendous amount of care and effort devoted to  
its preparation.

Matthias Schabel
Review Manager