[phobos] Proposed changes to std.math + introduce std.mathspecial

[Lars Tandle Kyllingstad]

On Wed, 2010-11-17 at 22:09 +0100, Don Clugston wrote:
> I have a pile of functions I wrote for Tango, most of which are part
> of C99. I'd like to move them into Phobos. In the process, I'd like to
> clean up a few things in std.math.
> 
> The main idea is that a new module, std.mathspecial, will contain
> mathematical Special Functions. In the long term, there could be quite
> a large number of these, but I think it will still be OK to have all
> of them declared in a single module.
> The implementations of these functions will mostly reside in
> std.internal.math.XXX. In many cases, the implementations are quite
> large.
> 
> std.math will be restricted to low-level operations and "high school"
> mathematics.

I think this is an excellent idea.


> (1) Add two necessary functions to std.math:
> 
> // Rounds x to the nearest int or long using the currently selected
> rounding mode
> // (MUCH faster than cast(int)).
> int rndint(real x)
> long rndlong(real x)

What would be the difference between these and rint() and lrint(), which
are already in std.math?


> (2) Delete etc.gamma

I didn't even know this module existed.  I recently implemented the
gamma function myself, based on the same source (Cephes).  If I'd known
about this it would have saved me quite a bit of time, so I say yes,
let's bring it out of hiding.


> (3) Create a new module std.mathspecial.
> 
> Move the following functions from std.math into std.mathspecial:
> erf()
> erfc()
> lgamma() -----> name changes to logGamma(real x)
> tgamma() ---> name changes to gamma(real x).
> BTW The 't' in the C name exists for extremely silly historical reasons.
> 
> std.math will retain alias for these functions, before they are
> eventually deprecated.

Absolutely.   Most people will never need these functions, but it's very
nice for scientific programmers to have them in the standard library.


> (4) Add implementations of those functions into std.internal.math.gammafunction
> Also add:
> real sgnGamma(real x);    // the sign of gamma(x), always used with logGamma.
> real digamma(x);   //  The digamma function
> real beta(real x, real y);    // the beta function
> 
> I'm not sure about the naming for the other functions. I will leave
> that for a later discussion.
> They include:
> * Distribution functions for the normal, F, chi-square, students-T, gamma, beta,
> poisson, binomial, and negative binomial distributions.
> * Cylindrical Bessel functions
> real cylBessel_j0(real x)  real cylBessel_y0(real x)
> real cylBessel_j1(real x)  real cylBessel_y1(real x)
> real cylBessel_jn(int n, real x )  real cylBessel_yn(int n, real x)

Regarding the Bessel functions, I suggest we use Mathematica's naming
scheme.  There, the (cylindrical) Bessel functions are called
BesselJ[n,z], BesselY[n,z], etc.  For D, that would be

  besselJ0(z)
  besselJ1(z)
  besselJ(n,z)

and so on.

I recently ported some of the modified Bessel functions (I_0, I_1, K_0,
and K_1) from Cephes.  I could polish the code a bit, add
implementations for general n, and submit that to std.mathspecial if
you're interested.

-Lars