Date: Sun, 05 Aug 2012 14:40:56 -0500 From: Stephen Montgomery-Smith <stephen@missouri.edu> To: Steve Kargl <sgk@troutmask.apl.washington.edu> Cc: freebsd-numerics@freebsd.org, Bruce Evans <brde@optusnet.com.au> Subject: Re: Complex arg-trig functions Message-ID: <501ECC48.40001@missouri.edu> In-Reply-To: <20120805191954.GA50379@troutmask.apl.washington.edu> References: <5017111E.6060003@missouri.edu> <501C361D.4010807@missouri.edu> <20120804165555.X1231@besplex.bde.org> <501D51D7.1020101@missouri.edu> <20120805030609.R3101@besplex.bde.org> <501D9C36.2040207@missouri.edu> <20120805175106.X3574@besplex.bde.org> <501EC015.3000808@missouri.edu> <20120805191954.GA50379@troutmask.apl.washington.edu>
next in thread | previous in thread | raw e-mail | index | archive | help
On 08/05/2012 02:19 PM, Steve Kargl wrote: > On Sun, Aug 05, 2012 at 01:48:53PM -0500, Stephen Montgomery-Smith wrote: >> Let me say that in my proposed code for casinh, etc, that I do have >> essay length comments. >> http://people.freebsd.org/~stephen/catrig.c > > Essay long comments probably belong in the man page if the essay is > important to the details of implementation. Bruce may disagree with > me. Except that the comments cannot really be understood without the code, and vice versa. For example, there are places where I compute things like X+Y, and computing Y would cause an underflow, but I happen to know that Y is so much smaller than X that I only need to compute X. But the reason why I can be sure that Y is so much smaller than X is quite subtle - you have to read the code that generates X and the parts that make up Y to see why this is true. Look in my code for the phrase "This cannot happen" and look at the comment this phrase appears in, and the comment below it. It simply doesn't belong in a man page. But the arguments are of the nature of a mathematical proof, and if the arguments aren't presented somewhere, in my opinion the code would be incomprehensible. You could argue that the reader of the code could simply read the paper (*) I got the algorithm from. But I made significant deviations from the algorithm, not least because that paper used exception handling to handle underflows and overflows, whereas I detect them before they happen. Also, I defined the function, which I called f(a,b) = 0.5 * (hypot(a,b) - b) = 0.5*a*a/(hypot(a,b) + b) which was implicitly used several times in that paper, but never presented as a single concept. In my opinion the algorithm is not obvious, but it is also necessary, because numeric instability can occur in rather awkward ways. It isn't immediately obvious how to work around them. I thought the ideas in the paper were brilliant. I feel very strongly that my essay long comments should stay inside the code. I think I do a good job explaining a rather subtle algorithm, and I would hope that a reader could completely understand the algorithm by reading my code + comments. (*) "Implementing the complex arcsine and arccosine functions using exception handling" by T. E. Hull, Thomas F. Fairgrieve, and Ping Tak Peter Tang, published in ACM Transactions on Mathematical Software, Volume 23 Issue 3, 1997, Pages 299-335, http://dl.acm.org/citation.cfm?id=275324
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?501ECC48.40001>