libs/math/doc/html/math_toolkit/next_float/ulp.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Obtaining the Size of a Unit In the Last Place - ULP</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.11.0">
   8 <link rel="up" href="../next_float.html" title="Floating-Point Representation Distance (ULP), and Finding Adjacent Floating-Point Values">
   9 <link rel="prev" href="float_advance.html" title="Advancing a floating-point Value by a Specific Representation Distance (ULP) float_advance">
  10 <link rel="next" href="../float_comparison.html" title="Floating-point Comparison">
  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="float_advance.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../next_float.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="../float_comparison.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h3 class="title">
  27 <a name="math_toolkit.next_float.ulp"></a><a class="link" href="ulp.html" title="Obtaining the Size of a Unit In the Last Place - ULP">Obtaining the Size of a
  28       Unit In the Last Place - ULP</a>
  29 </h3></div></div></div>
  30 <p>
  31         Function <code class="computeroutput"><span class="identifier">ulp</span></code> gives the size
  32         of a unit-in-the-last-place for a specified floating-point value.
  33       </p>
  34 <h5>
  35 <a name="math_toolkit.next_float.ulp.h0"></a>
  36         <span class="phrase"><a name="math_toolkit.next_float.ulp.synopsis"></a></span><a class="link" href="ulp.html#math_toolkit.next_float.ulp.synopsis">Synopsis</a>
  37       </h5>
  38 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">ulp</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  39 </pre>
  40 <pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
  41
  42 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">FPT</span><span class="special">&gt;</span>
  43 <span class="identifier">FPT</span> <span class="identifier">ulp</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">FPT</span><span class="special">&amp;</span> <span class="identifier">x</span><span class="special">);</span>
  44
  45 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">FPT</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policy</span><span class="special">&gt;</span>
  46 <span class="identifier">FPT</span> <span class="identifier">ulp</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">FPT</span><span class="special">&amp;</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Policy</span><span class="special">&amp;);</span>
  47
  48 <span class="special">}}</span> <span class="comment">// namespaces</span>
  49 </pre>
  50 <h5>
  51 <a name="math_toolkit.next_float.ulp.h1"></a>
  52         <span class="phrase"><a name="math_toolkit.next_float.ulp.description_ulp"></a></span><a class="link" href="ulp.html#math_toolkit.next_float.ulp.description_ulp">Description
  53         - ulp</a>
  54       </h5>
  55 <p>
  56         Returns one <a href="http://en.wikipedia.org/wiki/Unit_in_the_last_place" target="_top">unit
  57         in the last place</a> of <span class="emphasis"><em>x</em></span>.
  58       </p>
  59 <p>
  60         Corner cases are handled as follows:
  61       </p>
  62 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  63 <li class="listitem">
  64             If the argument is a NaN, then raises a <a class="link" href="../error_handling.html#math_toolkit.error_handling.domain_error">domain_error</a>.
  65           </li>
  66 <li class="listitem">
  67             If the argument is an infinity, then raises an <a class="link" href="../error_handling.html#math_toolkit.error_handling.overflow_error">overflow_error</a>.
  68           </li>
  69 <li class="listitem">
  70             If the argument is zero then returns the smallest representable value:
  71             for example for type <code class="computeroutput"><span class="keyword">double</span></code>
  72             this would be either <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;::</span><span class="identifier">min</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;::</span><span class="identifier">denorm_min</span><span class="special">()</span></code> depending whether denormals are supported
  73             (which have the values <code class="computeroutput"><span class="number">2.2250738585072014e-308</span></code>
  74             and <code class="computeroutput"><span class="number">4.9406564584124654e-324</span></code>
  75             respectively).
  76           </li>
  77 <li class="listitem">
  78             If the result is too small to represent, then returns the smallest representable
  79             value.
  80           </li>
  81 <li class="listitem">
  82             Always returns a positive value such that <code class="computeroutput"><span class="identifier">ulp</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">==</span> <span class="identifier">ulp</span><span class="special">(-</span><span class="identifier">x</span><span class="special">)</span></code>.
  83           </li>
  84 </ul></div>
  85 <p>
  86         <span class="bold"><strong>Important:</strong></span> The behavior of this function
  87         is aligned to that of <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Math.html#ulp%28double%29" target="_top">Java's
  88         ulp function</a>, please note however that this function should only
  89         ever be used for rough and ready calculations as there are enough corner
  90         cases to trap even careful programmers. In particular:
  91       </p>
  92 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  93 <li class="listitem">
  94             The function is asymetrical, which is to say, given <code class="computeroutput"><span class="identifier">u</span>
  95             <span class="special">=</span> <span class="identifier">ulp</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span></code> if <code class="computeroutput"><span class="identifier">x</span>
  96             <span class="special">&gt;</span> <span class="number">0</span></code>
  97             then <code class="computeroutput"><span class="identifier">x</span> <span class="special">+</span>
  98             <span class="identifier">u</span></code> is the next floating-point
  99             value, but <code class="computeroutput"><span class="identifier">x</span> <span class="special">-</span>
 100             <span class="identifier">u</span></code> is not necessarily the previous
 101             value. Similarly, if <code class="computeroutput"><span class="identifier">x</span> <span class="special">&lt;</span> <span class="number">0</span></code>
 102             then <code class="computeroutput"><span class="identifier">x</span> <span class="special">-</span>
 103             <span class="identifier">u</span></code> is the previous floating-point
 104             value, but <code class="computeroutput"><span class="identifier">x</span> <span class="special">+</span>
 105             <span class="identifier">u</span></code> is not necessarily the next
 106             value. The corner cases occur at power of 2 boundaries.
 107           </li>
 108 <li class="listitem">
 109             When the argument becomes very small, it may be that there is no floating-point
 110             value that represents one ULP. Whether this is the case or not depends
 111             not only on whether the hardware may <span class="emphasis"><em>sometimes</em></span> support
 112             denormals (as signalled by <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">FPT</span><span class="special">&gt;::</span><span class="identifier">has_denorm</span></code>),
 113             but also whether these are currently enabled at runtime (for example
 114             on SSE hardware, the DAZ or FTZ flags will disable denormal support).
 115             In this situation, the <code class="computeroutput"><span class="identifier">ulp</span></code>
 116             function may return a value that is many orders of magnitude too large.
 117           </li>
 118 </ul></div>
 119 <p>
 120         In light of the issues above, we recomend that:
 121       </p>
 122 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 123 <li class="listitem">
 124             To move between adjacent floating-point values always use <a class="link" href="float_next.html" title="Finding the Next Greater Representable Value (float_next)">float_next</a>,
 125             <a class="link" href="float_prior.html" title="Finding the Next Smaller Representable Value (float_prior)">float_prior</a>
 126             or <a class="link" href="nextafter.html" title="Finding the Next Representable Value in a Specific Direction (nextafter)">nextafter</a>
 127             (<code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">nextafter</span></code> is another candidate, but
 128             our experience is that this also often breaks depending which optimizations
 129             and hardware flags are in effect).
 130           </li>
 131 <li class="listitem">
 132             To move several floating-point values away use <a class="link" href="float_advance.html" title="Advancing a floating-point Value by a Specific Representation Distance (ULP) float_advance">float_advance</a>.
 133           </li>
 134 <li class="listitem">
 135             To calculate the edit distance between two floats use <a href="../../../../../../libs/math/doc/html/math_toolkit/next_float/float_distance.html" target="_top">Boost.Math
 136             float_distance</a>.
 137           </li>
 138 </ul></div>
 139 <p>
 140         There is none the less, one important use case for this function:
 141       </p>
 142 <p>
 143         If it is known that the true result of some function is x<sub>t</sub> and the calculated
 144         result is x<sub>c</sub>, then the error measured in ulp is simply <code class="literal">fabs(x<sub>t</sub> -
 145         x<sub>c</sub>) / ulp(x<sub>t</sub>)</code>.
 146       </p>
 147 </div>
 148 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 149 <td align="left"></td>
 150 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2019 Nikhar
 151       Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos,
 152       Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan
 153       R&#229;de, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg,
 154       Daryle Walker and Xiaogang Zhang<p>
 155         Distributed under the Boost Software License, Version 1.0. (See accompanying
 156         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>)
 157       </p>
 158 </div></td>
 159 </tr></table>
 160 <hr>
 161 <div class="spirit-nav">
 162 <a accesskey="p" href="float_advance.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../next_float.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="../float_comparison.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 163 </div>
 164 </body>
 165 </html>