Complex arg-trig functions
Bruce Evans
brde at optusnet.com.au
Wed Aug 8 17:12:22 UTC 2012
On Wed, 8 Aug 2012, Peter Jeremy wrote:
> On 2012-Aug-05 12:19:54 -0700, Steve Kargl <sgk at troutmask.apl.washington.edu> wrote:
>> On Sun, Aug 05, 2012 at 01:48:53PM -0500, Stephen Montgomery-Smith wrote:
>>> I plan to respect your style (keep out very lengthy comments), but I
>>> hope whomever commits my code will respect my style and keep the lengthy
>>> comments.
>>
>> Essay long comments probably belong in the man page if the essay is
>> important to the details of implementation. Bruce may disagree with
>> me.
Of course only details visible to applications belong in the man page.
But I think many details belong in meta-comments in something more
like a readme than in every source file.
> I also believe that implementation details belong in the code and not
> the man page. The man page should contain information necessary to
> use the function: Domain, range, behaviour with exceptional inputs,
> accuracy and similar. Any "unexpected" behaviours as a side-effect of
> the implementation can be mentioned under BUGS.
Note that FreeBSD man pages mostly have less than this, and less than
even the non-Annex parts of C99, after removing some out-of date
meta-info from math.3.
> The user shouldn't
> need to know that it's implemented by range-reduction to [0 .. e/7]
> and then evaluated with an 11th order truncated Chebyshev polynomial
> that's had coefficients tweaked by a demon I summoned one evening.
Unless the implementation affects the user-visible behaviour. For
example, on i386 trig functions are still implemented using the i387
(except in my version), so applications are exposed to the huge errors
near multiples of pi/2 (starting at 1*pi/2) that are normal for the i387.
A note about this would point to the right place to blame :-).
> OTOH, the code itself should contain comments explaining what it is
> doing - particularly where it is relying on details of the floating
> point implementation or the difference between an operation on real
> (or complex) numbers and the same operation on float/double/...
> numbers.
That's too detailed. Almost every line depends on IEEE754 arithmetic
and on this not being too broken. Many depend on the arithmetic _not_
being the same as real arithmetic. An example is almost every line
in Dekker's algorithm.
> It's also useful to document why alternative (particularly
> "obviously better" alternative) approaches won't work.
Again too detailed. On most lines I consider a couple of routine
alternatives. For critical lines, I consider and try many more.
Bruce
More information about the freebsd-numerics
mailing list