diff options
Diffstat (limited to 'manual')
| -rw-r--r-- | manual/Makefile | 14 | ||||
| -rwxr-xr-x | manual/libm-err-tab.pl | 207 | ||||
| -rw-r--r-- | manual/math.texi | 42 |
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 |