[racket] Math library ready for testing

On 12/17/2012 04:06 AM, Pierpaolo Bernardi wrote:
> Some comments after scanning the manual.
>
> ====
> flulp-error
>
> "For non-rational arguments such as +nan.0, flulp-error returns 0.0 if
> (eqv? x r); otherwise it returns +inf.0."
>
> However one example is:
>
>> (flulp-error +inf.0 +nan.0)
> +nan.0
>
> Which does not agree with the doc.

Whoops! I'll fix this one.

> "2.3.2 Flonum Constants
>
> -max.0 : Flonum
> -min.0 : Flonum
> +min.0 : Flonum
> +max.0 : Flonum
>
> The rational flonums with maximum and minimum magnitude.
>
> Example:
>
>> (list -max.0 -min.0 +min.0 +max.0)
> '(-1.7976931348623157e+308
>    -4.9406564584125e-324
>    4.9406564584125e-324
>    1.7976931348623157e+308)"
>
> The minimum magnitude rational flonums are 0.0 and -0.0. Perhaps
> "minimum non-zero magnitude"?

Yes. Or "The nonzero, rational flonums with maximum and minimum 
magnitude." I'll fix it.

> gamma-inc
>
> "The following identities should hold:
>
> • (gamma-inc k x) = 0"
>
> I'm no expert, but this identity smells   8^)

Looks like another case of eyes just sliding over an obvious mistake 
because the brain thinks it already knows what's there. It should be 
(gamma-inc k 0) = 0. I'll fix it.

> multinomial
>
> "(multinomial n ks) → Natural
>     n : Integer
>    ks : (Listof Integer)
> ...
>> (multinomial 5 3 2)
> 10"
>
> The example does not agree with the spec.

I didn't update the docs after changing all the multinomial function 
argument types. I'll fix this.

> Unless I missed it, there's no evaluator of polynomials?  seems a
> useful and common operation, and surely there must be one or more
> implementations somewhere in the internals of the lib?

There are, for Chebyshev polynomials. When I considered making 
`math/polynomial', I discovered that I needed at least two kinds: 
Chebyshev basis and power basis (e.g. a + bx + cx^2 + ...). Not only 
that, but I needed functions for flonum, real, complex, and bigfloat 
polynomials, for both kinds.

I'd like to provide a general type for polynomials with any orthogonal 
basis, parameterized on type, with polymorphic operations that dispatch 
to flonum/real/complex/bigfloat implementations. (And more. For example, 
it's sensible to use polynomials as coefficients. Using n-dimensional 
monomial coefficients gives you supersparse n-dimensional polynomials.) 
That'll require support for generics in Typed Racket, which doesn't exist.

At very least, if `math/polynomial' doesn't have all that nifty 
parameterization, I'd like it to be designed to not break user programs 
when we upgrade it.

It's a lot of work either way, so I decided to hold back for Math v1.0.

> The prefix for bigfloat operations sometimes is "bigfloat-", sometimes
> "bf-", sometimes "bf", with no evident (to me) pattern.

Those that have "bigfloat" in the name are struct accessors, the 
bigfloat predicate, and conversion functions.

Values with the "bf-" prefix don't operate on bigfloats: they're 
parameters or constants.

The docs should explain this. Might be enough to group them better. Will 
fix.

> My two neurons protest vehemently.

Classic!

> Unless I missed it, there's no discussion of the result precision of
> mixed precision bf operations. Maybe it should be mentioned?

The docs for `bf-precision' cover it:

A parameter that determines the precision of new bigfloat values.

With a few noted exceptions, bigfloat functions conceptually compute in 
infinite precision, round the answers to (bf-precision) bits using 
(bf-rounding-mode), and return the rounded answers. (In practice, they 
employ finite algorithms that have been painstakingly proved to be 
equivalent to the aforementioned infinite process.)

**

It's been bugging me that this isn't discussed earlier in the docs. I'll 
try to do something about it. Advice welcome.

> bflog2, bflog10, bfexp2, bfexp10
>
> Unless I have missed them, there are no fl and generic equivalent of these.
> These are commonly used functions.  Maybe should be provided?

I'm not sure why MPFR provides these. (bfexp2 x) is equivalent to 
(bfexpt (bf 2) x), and similarly for `bfexp10'. If they had `bflogb' 
(log with base), the former two would be similarly redundant.

I'm planning `fllogb' instead of `fllog2' and `fllog10'. Just haven't 
gotten around to it.

> bfagm
>
> Wins the prize for the most fortranesque name.

Woo! Do I get a toaster? Luggage? An all-expenses-paid vacation to 
Wisconsin?

> why math/arrays and not data/arrays ?

Good question.

> diagonal-array
>
> "returns a square array..."
>
> hmmm... is 'square' appropriate for more than 2-dimensional arrays?

Nope. Will fix.

> Great work!

Thanks, and thanks for the feedback!

Neil ⊥