1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Floating-Point Representation Distance (ULP), and Finding Adjacent Floating-Point Values</title> 5<link rel="stylesheet" href="../math.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../index.html" title="Math Toolkit 2.12.0"> 8<link rel="up" href="../utils.html" title="Chapter 2. Floating Point Utilities"> 9<link rel="prev" href="fp_facets/rationale.html" title="Design Rationale"> 10<link rel="next" href="next_float/nextafter.html" title="Finding the Next Representable Value in a Specific Direction (nextafter)"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr> 14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> 15<td align="center"><a href="../../../../../index.html">Home</a></td> 16<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> 17<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 18<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 19<td align="center"><a href="../../../../../more/index.htm">More</a></td> 20</tr></table> 21<hr> 22<div class="spirit-nav"> 23<a accesskey="p" href="fp_facets/rationale.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../utils.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="next_float/nextafter.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 27<a name="math_toolkit.next_float"></a><a class="link" href="next_float.html" title="Floating-Point Representation Distance (ULP), and Finding Adjacent Floating-Point Values">Floating-Point Representation 28 Distance (ULP), and Finding Adjacent Floating-Point Values</a> 29</h2></div></div></div> 30<div class="toc"><dl class="toc"> 31<dt><span class="section"><a href="next_float/nextafter.html">Finding the Next Representable 32 Value in a Specific Direction (nextafter)</a></span></dt> 33<dt><span class="section"><a href="next_float/float_next.html">Finding the Next 34 Greater Representable Value (float_next)</a></span></dt> 35<dt><span class="section"><a href="next_float/float_prior.html">Finding the Next 36 Smaller Representable Value (float_prior)</a></span></dt> 37<dt><span class="section"><a href="next_float/float_distance.html">Calculating the 38 Representation Distance Between Two floating-point Values (ULP) float_distance</a></span></dt> 39<dt><span class="section"><a href="next_float/float_advance.html">Advancing a floating-point 40 Value by a Specific Representation Distance (ULP) float_advance</a></span></dt> 41<dt><span class="section"><a href="next_float/ulp.html">Obtaining the Size of a 42 Unit In the Last Place - ULP</a></span></dt> 43</dl></div> 44<p> 45 <a href="http://en.wikipedia.org/wiki/Unit_in_the_last_place" target="_top">Unit of Least 46 Precision or Unit in the Last Place</a> is the gap between two different, 47 but as close as possible, floating-point numbers. 48 </p> 49<p> 50 Most decimal values, for example 0.1, cannot be exactly represented as floating-point 51 values, but will be stored as the <a href="http://en.wikipedia.org/wiki/Floating_point#Representable_numbers.2C_conversion_and_rounding" target="_top">closest 52 representable floating-point</a>. 53 </p> 54<p> 55 Functions are provided for finding adjacent greater and lesser floating-point 56 values, and estimating the number of gaps between any two floating-point values. 57 </p> 58<p> 59 The floating-point type (FPT) must have has a fixed number of bits in the representation. 60 The number of bits may set at runtime, but must be the same for all numbers. 61 For example, <a href="http://shoup.net/ntl/doc/quad_float.txt" target="_top">NTL::quad_float</a> 62 type (fixed 128-bit representation), <a href="http://shoup.net/ntl/doc/RR.txt" target="_top">NTL::RR</a> 63 type (arbitrary but fixed decimal digits, default 150) or <a href="../../../../../libs/multiprecision/doc/html/index.html" target="_top">Boost.Multiprecision</a> 64 <a href="../../../../../libs/multiprecision/doc/html/boost_multiprecision/tut/floats/cpp_dec_float.html" target="_top">cpp_dec_float</a> 65 and<a href="../../../../../libs/multiprecision/doc/html/boost_multiprecision/tut/floats/cpp_bin_float.html" target="_top">cpp_bin_float</a> 66 are fixed at runtime, but <span class="bold"><strong>not</strong></span> a type that 67 extends the representation to provide an exact representation for any number, 68 for example <a href="http://keithbriggs.info/xrc.html" target="_top">XRC eXact Real in 69 C</a>. 70 </p> 71<p> 72 The accuracy of mathematical functions can be assessed and displayed in terms 73 of <a href="https://en.wikipedia.org/wiki/Unit_in_the_last_place" target="_top">Unit in 74 the Last Place</a>, often as a ulps plot or by binning the differences 75 as a histogram. Samples are evaluated using the implementation under test and 76 compared with 'known good' representation obtained using a more accurate method. 77 Other implementations, often using arbitrary precision arithmetic, for example 78 <a href="http://www.wolframalpha.com/" target="_top">Wolfram Alpha</a> are one source 79 of references values. The other method, used widely in Boost.Math special functions, 80 it to carry out the same algorithm, but using a higher precision type, typically 81 using Boost.Multiprecision types like <code class="computeroutput"><span class="identifier">cpp_bin_float_quad</span></code> 82 for 128-bit (about 35 decimal digit precision), or <code class="computeroutput"><span class="identifier">cpp_bin_float_50</span></code> 83 (for 50 decimal digit precision). 84 </p> 85<p> 86 When converted to a particular machine representation, say <code class="computeroutput"><span class="keyword">double</span></code>, 87 say using a <code class="computeroutput"><span class="keyword">static_cast</span></code>, the value 88 is the nearest representation possible for the <code class="computeroutput"><span class="keyword">double</span></code> 89 type. This value cannot be 'wrong' by more than half a <a href="http://en.wikipedia.org/wiki/Unit_in_the_last_place" target="_top">Unit 90 in the last place (ULP)</a>, and can be obtained using the Boost.Math function 91 <code class="computeroutput"><span class="identifier">ulp</span></code>. (Unless the algorithm 92 is fundamentally flawed, something that should be revealed by 'sanity' checks 93 using some independent sources). 94 </p> 95<p> 96 See some discussion and example plots by Cleve Moler of Mathworks <a href="https://blogs.mathworks.com/cleve/2017/01/23/ulps-plots-reveal-math-function-accurary/" target="_top">ulps 97 plots reveal math-function accuracy</a>. 98 </p> 99</div> 100<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 101<td align="left"></td> 102<td align="right"><div class="copyright-footer">Copyright © 2006-2019 Nikhar 103 Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, 104 Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan 105 Råde, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg, 106 Daryle Walker and Xiaogang Zhang<p> 107 Distributed under the Boost Software License, Version 1.0. (See accompanying 108 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) 109 </p> 110</div></td> 111</tr></table> 112<hr> 113<div class="spirit-nav"> 114<a accesskey="p" href="fp_facets/rationale.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../utils.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="next_float/nextafter.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 115</div> 116</body> 117</html> 118
