From owner-svn-src-all@FreeBSD.ORG Sat Oct 20 07:32:25 2012 Return-Path: Delivered-To: svn-src-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id D49CDA81; Sat, 20 Oct 2012 07:32:25 +0000 (UTC) (envelope-from brde@optusnet.com.au) Received: from mail04.syd.optusnet.com.au (mail04.syd.optusnet.com.au [211.29.132.185]) by mx1.freebsd.org (Postfix) with ESMTP id DA70E8FC0A; Sat, 20 Oct 2012 07:32:24 +0000 (UTC) Received: from c122-106-175-26.carlnfd1.nsw.optusnet.com.au (c122-106-175-26.carlnfd1.nsw.optusnet.com.au [122.106.175.26]) by mail04.syd.optusnet.com.au (8.13.1/8.13.1) with ESMTP id q9K7WEfu001705 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Sat, 20 Oct 2012 18:32:15 +1100 Date: Sat, 20 Oct 2012 18:32:14 +1100 (EST) From: Bruce Evans X-X-Sender: bde@besplex.bde.org To: Bruce Evans Subject: Re: svn commit: r241755 - head/lib/msun/src In-Reply-To: <20121020150917.I1095@besplex.bde.org> Message-ID: <20121020181443.X1561@besplex.bde.org> References: <201210192246.q9JMkm4R092929@svn.freebsd.org> <20121020150917.I1095@besplex.bde.org> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed X-Optus-Cloudmark-Score: 0 X-Optus-Cloudmark-Analysis: v=2.0 cv=eLtLFwV1 c=1 sm=1 a=xI64QrV9ptIA:10 a=kj9zAlcOel0A:10 a=PO7r1zJSAAAA:8 a=JzwRw_2MAAAA:8 a=Aet6fyW9sl8A:10 a=tlCQwBxB1yNg7U1qZQkA:9 a=CjuIK1q_8ugA:10 a=bxQHXO5Py4tHmhUgaywp5w==:117 Cc: svn-src-head@freebsd.org, svn-src-all@freebsd.org, src-committers@freebsd.org, Warner Losh X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 20 Oct 2012 07:32:26 -0000 On Sat, 20 Oct 2012, Bruce Evans wrote: > On Fri, 19 Oct 2012, Warner Losh wrote: > >> Log: >> Document the methods used to compute logf. Taken and edited from the >> double version, with adaptations for the differences between it and >> the float version. > > Please back this out. > > This was intentionally left out. It is painful to maintain large > comments that should be identical for all precisions. Double precision > is primary, and only comments that depend on the precision should be > given in other precisions, except for short comments to to right of > coulde whose non-duplication would just give larger diffs. If you > want to duplicate them, then they would often have to be quadruplicated > in 4 files for the 4 supported precisions: > - double precision > - float precision > - long double with MANT_DIG = 64 and 16 other bits > - long double with MANT_DIG = 113 and 15 other bits > Only 4 now, but there could easily be variations for long doubles. PS: in long double trig functions, I handle this carefully by giving references to the file containing the main description of the algorithm. Old Cygnus float functions are no so careful, and I didn't want to churn them for this. Example from k_cosl.c: % #include % __FBSDID("$FreeBSD: src/lib/msun/ld80/k_cosl.c,v 1.1 2008/02/17 07:32:14 das Exp $"); % % /* % * ld80 version of k_cos.c. See ../src/k_cos.c for most comments. % */ Most details are here. They are described in the same style as the e_log.c comments that you duplicated. Here they are in the kernel instead of in the main file. Another problem is that they really do belong in the kernel, but are harder to read there. We already have kernels for log and logf (k_log.h and k_logf.c). These unfortunately have to duplicate the code, but they are careful to not duplicate comments and carefully point to the main file for the comments. The kernels are only used for log10*() and log2*(), so strictly whatever the kernels do doesn't affect log() and logf(). You didn't duplicate the comments into these files. If you did, there would already be 4 or 6 copies of them without even long double precision: - e_log.c, e_logf.c - k_log.h, k_logf.c - e_log10.c, e_log10f.c, e_log2.c, e_log2f.c (if we don't use kernels and/or don't put the comments in the kernels). % % #include "math_private.h" % % /* % * Domain [-0.7854, 0.7854], range ~[-2.43e-23, 2.425e-23]: % * |cos(x) - c(x)| < 2**-75.1 % * % * The coefficients of c(x) were generated by a pari-gp script using % * a Remez algorithm that searches for the best higher coefficients % * after rounding leading coefficients to a specified precision. This documents some precision-dependent details too verbosely. It goes without saying that we generate minimax polynomials by some method. If we want to document the method(s), then it should be once per method and not placed in the source files whose polynomials happened to be generated using the methods. % * % * Simpler methods like Chebyshev or basic Remez barely suffice for % * cos() in 64-bit precision, because we want the coefficient of x^2 % * to be precisely -0.5 so that multiplying by it is exact, and plain % * rounding of the coefficients of a good polynomial approximation only % * gives this up to about 64-bit precision. Plain rounding also gives % * a mediocre approximation for the coefficient of x^4, but a rounding % * error of 0.5 ulps for this coefficient would only contribute ~0.01 % * ulps to the final error, so this is unimportant. Rounding errors in % * higher coefficients are even less important. % * % * In fact, coefficients above the x^4 one only need to have 53-bit % * precision, and this is more efficient. We get this optimization % * almost for free from the complications needed to search for the best % * higher coefficients. % */ This documents in excessive detail the limits of some methods. When it was written, I didn't know the limits very well. This is essentially a way of saying "don't document your methods here, else it would expand to be as verbose as this comment, if not to a book. I don't want to read this book in every source file". Bruce