aboutsummaryrefslogtreecommitdiff
path: root/manual
diff options
context:
space:
mode:
authorUlrich Drepper <drepper@redhat.com>1999-10-30 06:56:10 +0000
committerUlrich Drepper <drepper@redhat.com>1999-10-30 06:56:10 +0000
commitaaa1276ee31ca872190cd097c7b4d845996fed39 (patch)
treed14e77b1744c5713f4cfff6e86c9417d7ddd8ce8 /manual
parent6491b8094e929133e3eb8793bb6296f69fb54a78 (diff)
downloadglibc-aaa1276ee31ca872190cd097c7b4d845996fed39.tar
glibc-aaa1276ee31ca872190cd097c7b4d845996fed39.tar.gz
glibc-aaa1276ee31ca872190cd097c7b4d845996fed39.tar.bz2
glibc-aaa1276ee31ca872190cd097c7b4d845996fed39.zip
Update.
* manual/math.texi (Errors in Math Functions): New section. * math/libm-err-tab.pl: Moved to... * manual/libm-err-tab.pl: ...here. * manual/Makefile: Add rules for math function error table generation.
Diffstat (limited to 'manual')
-rw-r--r--manual/Makefile14
-rwxr-xr-xmanual/libm-err-tab.pl207
-rw-r--r--manual/math.texi42
3 files changed, 261 insertions, 2 deletions
diff --git a/manual/Makefile b/manual/Makefile
index 3c6640e8a7..4b88543129 100644
--- a/manual/Makefile
+++ b/manual/Makefile
@@ -69,7 +69,7 @@ examples = $(filter-out $(foreach d, $(add-ons), ../$d/%.c.texi), \
chapters.% top-menu.%: libc-texinfo.sh $(texis)
AWK=$(AWK) $(SHELL) $< '$(chapters)' '$(add-chapters)' '$(appendices)'
-libc.dvi libc.info: chapters.texi top-menu.texi
+libc.dvi libc.info: chapters.texi top-menu.texi libm-err.texi
libc.dvi: texinfo.tex
# Generate the summary from the Texinfo source files for each chapter.
@@ -89,6 +89,15 @@ dir-add.info: xtract-typefun.awk $(texis)
echo "END-INFO-DIR-ENTRY") > $@.new
mv -f $@.new $@
+# The table with the math errors is generated.
+libm-err.texi: stamp-libm-err
+stamp-libm-err: libm-err-tab.pl $(wildcard $(foreach dir,$(sysdirs),\
+ $(dir)/libm-test-ulps))
+ pwd=`pwd`; \
+ $(PERL) $< $$pwd/.. > libm-err-tmp
+ $(move-if-change) libm-err-tmp libm-err.texi
+ touch $@
+
# Generate Texinfo files from the C source for the example programs.
%.c.texi: examples/%.c
sed -e 's,[{}],@&,g' \
@@ -106,13 +115,14 @@ dir-add.info: xtract-typefun.awk $(texis)
# Distribution.
minimal-dist = summary.awk texis.awk tsort.awk libc-texinfo.sh libc.texinfo \
+ libm-err.texi stamp-libm-err \
$(filter-out summary.texi, $(nonexamples)) \
$(patsubst %.c.texi,examples/%.c, $(examples))
doc-only-dist = Makefile COPYING.LIB
distribute = $(minimal-dist) $(examples) stdio-fp.c \
libc.info* libc.?? libc.??s texinfo.tex \
- xtract-typefun.awk dir-add.info dir
+ xtract-typefun.awk dir-add.info dir libm-err-tab.pl
export distribute := $(distribute)
tar-it = tar chovf $@ $^
diff --git a/manual/libm-err-tab.pl b/manual/libm-err-tab.pl
new file mode 100755
index 0000000000..448bf801ab
--- /dev/null
+++ b/manual/libm-err-tab.pl
@@ -0,0 +1,207 @@
+#!/usr/bin/perl -w
+
+# Copyright (C) 1999 Free Software Foundation, Inc.
+# This file is part of the GNU C Library.
+# Contributed by Andreas Jaeger <aj@suse.de>, 1999.
+
+# The GNU C Library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Library General Public License as
+# published by the Free Software Foundation; either version 2 of the
+# License, or (at your option) any later version.
+
+# The GNU C Library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+# Library General Public License for more details.
+
+# You should have received a copy of the GNU Library General Public
+# License along with the GNU C Library; see the file COPYING.LIB. If not,
+# write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+# Boston, MA 02111-1307, USA.
+
+# Information about tests are stored in: %results
+# $results{$test}{"type"} is the result type, e.g. normal or complex.
+# In the following description $platform, $type and $float are:
+# - $platform is the used platform
+# - $type is either "normal", "real" (for the real part of a complex number)
+# or "imag" (for the imaginary part # of a complex number).
+# - $float is either of float, ifloat, double, idouble, ldouble, ildouble;
+# It represents the underlying floating point type (float, double or long
+# double) and if inline functions (the leading i stands for inline)
+# are used.
+# $results{$test}{$platform}{$type}{$float} is defined and has a delta
+# or 'fail' as value.
+
+use File::Find;
+
+use strict;
+
+use vars qw ($sources @platforms %pplatforms);
+use vars qw (%results @all_floats %suffices @all_functions);
+
+
+# all_floats is in output order and contains all recognised float types that
+# we're going to output
+@all_floats = ('float', 'double', 'ldouble');
+%suffices =
+ ( 'float' => 'f',
+ 'double' => '',
+ 'ldouble' => 'l'
+ );
+
+# Pretty description of platform
+%pplatforms =
+ ( "i386/fpu" => "ix86",
+ "generic" => "Generic",
+ "alpha" => "Alpha"
+ );
+
+@all_functions =
+ ( "acos", "acosh", "asin", "asinh", "atan", "atanh",
+ "atan2", "cabs", "cacos", "cacosh", "carg", "casin", "casinh",
+ "catan", "catanh", "cbrt", "ccos", "ccosh", "ceil", "cexp", "cimag",
+ "clog", "clog10", "conj", "copysign", "cos", "cosh", "cpow", "cproj",
+ "creal", "csin", "csinh", "csqrt", "ctan", "ctanh", "erf", "erfc",
+ "exp", "exp10", "exp2", "expm1", "fabs", "fdim", "floor", "fma",
+ "fmax", "fmin", "fmod", "frexp", "gamma", "hypot",
+ "ilogb", "j0", "j1", "jn", "lgamma", "lrint",
+ "llrint", "log", "log10", "log1p", "log2", "logb", "lround",
+ "llround", "modf", "nearbyint", "nextafter", "nexttoward", "pow",
+ "remainder", "remquo", "rint", "round", "scalb", "scalbn", "scalbln",
+ "sin", "sincos", "sinh", "sqrt", "tan", "tanh", "tgamma",
+ "trunc", "y0", "y1", "yn" );
+# "fpclassify", "isfinite", "isnormal", "signbit" are not tabulated
+
+if ($#ARGV == 0) {
+ $sources = $ARGV[0];
+} else {
+ $sources = '/usr/src/cvs/libc';
+}
+
+find (\&find_files, $sources);
+
+&print_all;
+
+sub find_files {
+ if ($_ eq 'libm-test-ulps') {
+ # print "Parsing $File::Find::name\n";
+ push @platforms, $File::Find::dir;
+ &parse_ulps ($File::Find::name, $File::Find::dir);
+ }
+}
+
+# Parse ulps file
+sub parse_ulps {
+ my ($file, $platform) = @_;
+ my ($test, $type, $float, $eps, $kind);
+
+ # $type has the following values:
+ # "normal": No complex variable
+ # "real": Real part of complex result
+ # "imag": Imaginary part of complex result
+ open ULP, $file or die ("Can't open $file: $!");
+ while (<ULP>) {
+ chop;
+ # ignore comments and empty lines
+ next if /^#/;
+ next if /^\s*$/;
+ if (/^Test/) {
+ $kind = 'test';
+ next;
+ }
+ if (/^Function: /) {
+ if (/\Real part of/) {
+ s/Real part of //;
+ $type = 'real';
+ } elsif (/Imaginary part of/) {
+ s/Imaginary part of //;
+ $type = 'imag';
+ } else {
+ $type = 'normal';
+ }
+ ($test) = ($_ =~ /^Function:\s*\"([a-zA-Z0-9_]+)\"/);
+ $kind = 'fct';
+ next;
+ }
+ # Only handle maximal errors of functions
+ next if ($kind eq 'test');
+ if (/^i?(float|double|ldouble):/) {
+ ($float, $eps) = split /\s*:\s*/,$_,2;
+ if ($eps eq 'fail') {
+ $results{$test}{$platform}{$type}{$float} = 'fail';
+ } elsif ($eps eq "0") {
+ # ignore
+ next;
+ } elsif (!exists $results{$test}{$platform}{$type}{$float}
+ || $results{$test}{$platform}{$type}{$float} ne 'fail') {
+ $results{$test}{$platform}{$type}{$float} = $eps;
+ }
+ if ($type =~ /^real|imag$/) {
+ $results{$test}{'type'} = 'complex';
+ } elsif ($type eq 'normal') {
+ $results{$test}{'type'} = 'normal';
+ }
+ next;
+ }
+ print "Skipping unknown entry: `$_'\n";
+ }
+ close ULP;
+}
+
+sub get_value {
+ my ($fct, $platform, $type, $float) = @_;
+
+ return (exists $results{$fct}{$platform}{$type}{$float}
+ ? $results{$fct}{$platform}{$type}{$float} : "0");
+}
+
+sub canonicalize_platform {
+ my ($platform) = @_;
+
+ $platform =~ s|^(.*/sysdeps/)||;
+
+
+ return exists $pplatforms{$platform} ? $pplatforms{$platform} : $platform;
+}
+
+sub print_all {
+ my ($fct, $platform, $float, $first, $i);
+
+ print '@multitable {nexttowardf} ';
+ foreach (@platforms) {
+ print ' {1000 + i 1000}';
+ }
+ print "\n";
+
+ print '@item Function ';
+ foreach (@platforms) {
+ print ' @tab ';
+ print &canonicalize_platform ($_);
+ }
+ print "\n";
+
+
+ foreach $fct (@all_functions) {
+ foreach $float (@all_floats) {
+ print "\@item $fct$suffices{$float} ";
+ foreach $platform (@platforms) {
+ print ' @tab ';
+ if (exists $results{$fct}{$platform}{'normal'}{$float}
+ || exists $results{$fct}{$platform}{'real'}{$float}
+ || exists $results{$fct}{$platform}{'imag'}{$float}) {
+ if ($results{$fct}{'type'} eq 'complex') {
+ print &get_value ($fct, $platform, 'real', $float),
+ ' + i ', &get_value ($fct, $platform, 'imag', $float);
+ } else {
+ print $results{$fct}{$platform}{'normal'}{$float};
+ }
+ } else {
+ print '-';
+ }
+ }
+ print "\n";
+ }
+ }
+
+ print "\@end multitable\n";
+}
diff --git a/manual/math.texi b/manual/math.texi
index f2736c2c45..c9a4c3a611 100644
--- a/manual/math.texi
+++ b/manual/math.texi
@@ -61,6 +61,7 @@ same as @code{double}.
* Exponents and Logarithms:: Also pow and sqrt.
* Hyperbolic Functions:: sinh, cosh, tanh, etc.
* Special Functions:: Bessel, gamma, erf.
+* Errors in Math Functions:: Known Maximum Errors in Math Functions.
* Pseudo-Random Numbers:: Functions for generating pseudo-random
numbers.
* FP Function Optimizations:: Fast code or small code.
@@ -1203,6 +1204,47 @@ is negative, @code{yn} signals a domain error; if it is zero,
@code{yn} signals overflow and returns @math{-@infinity}.
@end deftypefun
+@node Errors in Math Functions
+@section Known Maximum Errors in Math Functions
+@cindex math errors
+@cindex ulps
+
+This section lists the known errors of the functions in the math
+library. Errors are measured in ``units of the last place''. This is a
+measure for the relative error. For a number @math{z} with the
+representation @math{d.d@dots{}d@mul{}2^e} (we assume IEEE
+floating-point numbers with base 2) the ULP is represented by
+
+@tex
+$$\frac{|{\mathrm d.d\dots d - (z/2^e)|}{2^{p-1}}$$
+@end tex
+@ifnottex
+@smallexample
+|d.d...d - (z / 2^e)| / 2^(p - 1)
+@end smallexample
+@end ifnottex
+
+@noindent
+where @math{p} is the number of bits in the mantissa of the
+floating-point number representation. Ideally the error for all
+functions is always less than 0.5ulps. Using rounding bits this is also
+possible and normally implemented for the basic operations. To achieve
+the same for the complex math functions requires a lot more work and
+this was not spend so far.
+
+Therefore many of the functions in the math library have errors. The
+table lists the maximum error for each function which is exposed by one
+of the existing tests in the test suite. It is tried to cover as much
+as possible and really list the maximum error (or at least a ballpark
+figure) but this is often not achieved due to the large search space.
+
+The table lists the ULP values for different architectures. Different
+architectures have different results since their hardware support for
+floating-point operations varies and also the existing hardware support
+is different.
+
+@include libm-err.texi
+
@node Pseudo-Random Numbers
@section Pseudo-Random Numbers
@cindex random numbers