Markus Werle wrote:
John Maddock <john <at> johnmaddock.co.uk> writes:
The "Math Toolkit" has now matured to the point where Paul Bristow and I would like to ask for a formal review.
Some comments before the review begins (If you allow):
No problem at all: the more feedback the better.
In the docs sometimes you have formulations like e.g. "Returns the cubed root of x.". For native speakers this may be no problem, but sqrt(x)^3 may be easier to catch for the rest of us.
That would be x^(1/3) :-) I've just added that.
Also I dislike: "The definition used here is that used by Wolfram MathWorld" since by this the docs are neither self-contained nor robust against
Hmmm, that section could be better phrased, Looks like we need a concise definition of "kertosis", but there are limits to how much we can rewrite what's already very well explained elsewhere.
Citing papers is OK, but it takes a few thousand dollars to get them all I guess. So adding an outline of the algorithm would be nice for all functions (though saying what you use is GoodStuff(TM), too).
The special functions all have an "implementation" section that should provide that (or at least a formula). However, there are some papers that are just too complex to summarise (the methods used to obtain the initial approximations for the inverse incomplete gamma and beta functions are good examples of this). The aim is that someone should be able to get the jist of the code, by refering to the implementation section and the formulae. They may still need to do a bit of pencil and paper math to get their head round some of the formulae, but that's not necessarily a bad thing :-)
Since I got really excited about gamma functions (I need them and had hard times evaluating exact solutions from continuum mechanics): The Definition section needs some rework and the warnings about the different definitions will not help much in this form (at least for me, the stupid one)
I see no connection between \Int R(t, s) dt and the definitions F, E and \Pi so here again the docs are a little bit confusing and the information about gamma function definitions and what Legendre found out will not enter my brain without further information from other sources which I find odd.
Now I'm confused: the functions F, E and Pi relate to the exponential integrals, the incomplete gamma functions are traditionally denoted P and Q (for the regularized forms) and with upper and lower case gamma's for full-non-regularized versions. They are fully defined by the definitions given (the integrals), and those definitions are completely standard, so giving information beyond that is the job of the textbooks: like A&S etc. Which functions were you looking for?
OTOH given these function on a silver tablet I'd like to say: Thank You!
What I also dislike is the existence of default typedefs for double (students_t et al.). This is unnecessary and makes double a special type which it is not. I'd vote for removing those from the boost version of this due to the asymmetry it produces.
I'd be interested in other views on this: my gut feeling is that hardly any users of the statistics code will be using anything except double precision. The convenience of being able to write: quantile(students_t(10), .95); // 95% quantile for 10 degrees freedom is well worth it IMO. The alternative: quantile(students_t_distribution<double>(10), .95); is unnecessarily verbose in comparison. It's like writing: std::string rather than: std::basic_string<char> all the time. Thanks for the feedback, John.