File: Setting-up-your-IEEE-environment.html

package info (click to toggle)
gsl-ref-html 2.3-1
  • links: PTS
  • area: non-free
  • in suites: bullseye, buster, sid
  • size: 6,876 kB
  • ctags: 4,574
  • sloc: makefile: 35
file content (280 lines) | stat: -rw-r--r-- 12,802 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016 The GSL Team.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "GNU General Public License" and "Free Software
Needs Free Documentation", the Front-Cover text being "A GNU Manual",
and with the Back-Cover Text being (a) (see below). A copy of the
license is included in the section entitled "GNU Free Documentation
License".

(a) The Back-Cover Text is: "You have the freedom to copy and modify this
GNU Manual." -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GNU Scientific Library &ndash; Reference Manual: Setting up your IEEE environment</title>

<meta name="description" content="GNU Scientific Library &ndash; Reference Manual: Setting up your IEEE environment">
<meta name="keywords" content="GNU Scientific Library &ndash; Reference Manual: Setting up your IEEE environment">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Function-Index.html#Function-Index" rel="index" title="Function Index">
<link href="IEEE-floating_002dpoint-arithmetic.html#IEEE-floating_002dpoint-arithmetic" rel="up" title="IEEE floating-point arithmetic">
<link href="IEEE-References-and-Further-Reading.html#IEEE-References-and-Further-Reading" rel="next" title="IEEE References and Further Reading">
<link href="Representation-of-floating-point-numbers.html#Representation-of-floating-point-numbers" rel="previous" title="Representation of floating point numbers">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Setting-up-your-IEEE-environment"></a>
<div class="header">
<p>
Next: <a href="IEEE-References-and-Further-Reading.html#IEEE-References-and-Further-Reading" accesskey="n" rel="next">IEEE References and Further Reading</a>, Previous: <a href="Representation-of-floating-point-numbers.html#Representation-of-floating-point-numbers" accesskey="p" rel="previous">Representation of floating point numbers</a>, Up: <a href="IEEE-floating_002dpoint-arithmetic.html#IEEE-floating_002dpoint-arithmetic" accesskey="u" rel="up">IEEE floating-point arithmetic</a> &nbsp; [<a href="Function-Index.html#Function-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Setting-up-your-IEEE-environment-1"></a>
<h3 class="section">45.2 Setting up your IEEE environment</h3>
<a name="index-IEEE-exceptions"></a>
<a name="index-precision_002c-IEEE-arithmetic"></a>
<a name="index-rounding-mode"></a>
<a name="index-arithmetic-exceptions"></a>
<a name="index-exceptions_002c-IEEE-arithmetic"></a>
<a name="index-division-by-zero_002c-IEEE-exceptions"></a>
<a name="index-underflow_002c-IEEE-exceptions"></a>
<a name="index-overflow_002c-IEEE-exceptions"></a>
<p>The IEEE standard defines several <em>modes</em> for controlling the
behavior of floating point operations.  These modes specify the important
properties of computer arithmetic: the direction used for rounding (e.g.
whether numbers should be rounded up, down or to the nearest number),
the rounding precision and how the program should handle arithmetic
exceptions, such as division by zero.
</p>
<p>Many of these features can now be controlled via standard functions such
as <code>fpsetround</code>, which should be used whenever they are available.
Unfortunately in the past there has been no universal API for
controlling their behavior&mdash;each system has had its own low-level way
of accessing them.  To help you write portable programs GSL allows you
to specify modes in a platform-independent way using the environment
variable <code>GSL_IEEE_MODE</code>.  The library then takes care of all the
necessary machine-specific initializations for you when you call the
function <code>gsl_ieee_env_setup</code>.
</p>
<dl>
<dt><a name="index-gsl_005fieee_005fenv_005fsetup"></a>Function: <em>void</em> <strong>gsl_ieee_env_setup</strong> <em>()</em></dt>
<dd><a name="index-GSL_005fIEEE_005fMODE"></a>
<p>This function reads the environment variable <code>GSL_IEEE_MODE</code> and
attempts to set up the corresponding specified IEEE modes.  The
environment variable should be a list of keywords, separated by
commas, like this,
</p>
<div class="display">
<pre class="display"><code>GSL_IEEE_MODE</code> = &quot;<var>keyword</var>,<var>keyword</var>,...&quot;
</pre></div>

<p>where <var>keyword</var> is one of the following mode-names,
</p>
<ul class="no-bullet">
<li><!-- /@w --> <code>single-precision</code>
</li><li><!-- /@w --> <code>double-precision</code>
</li><li><!-- /@w --> <code>extended-precision</code>
</li><li><!-- /@w --> <code>round-to-nearest</code>
</li><li><!-- /@w --> <code>round-down</code>
</li><li><!-- /@w --> <code>round-up</code>
</li><li><!-- /@w --> <code>round-to-zero</code>
</li><li><!-- /@w --> <code>mask-all</code>
</li><li><!-- /@w --> <code>mask-invalid</code>
</li><li><!-- /@w --> <code>mask-denormalized</code>
</li><li><!-- /@w --> <code>mask-division-by-zero</code>
</li><li><!-- /@w --> <code>mask-overflow</code>
</li><li><!-- /@w --> <code>mask-underflow</code>
</li><li><!-- /@w --> <code>trap-inexact</code>
</li><li><!-- /@w --> <code>trap-common</code>
</li></ul>

<p>If <code>GSL_IEEE_MODE</code> is empty or undefined then the function returns
immediately and no attempt is made to change the system&rsquo;s IEEE
mode.  When the modes from <code>GSL_IEEE_MODE</code> are turned on the
function prints a short message showing the new settings to remind you
that the results of the program will be affected.
</p>
<p>If the requested modes are not supported by the platform being used then
the function calls the error handler and returns an error code of
<code>GSL_EUNSUP</code>.  
</p>
<p>When options are specified using this method, the resulting mode is
based on a default setting of the highest available precision (double
precision or extended precision, depending on the platform) in
round-to-nearest mode, with all exceptions enabled apart from the
<small>INEXACT</small> exception.  The <small>INEXACT</small> exception is generated
whenever rounding occurs, so it must generally be disabled in typical
scientific calculations.  All other floating-point exceptions are
enabled by default, including underflows and the use of denormalized
numbers, for safety.  They can be disabled with the individual
<code>mask-</code> settings or together using <code>mask-all</code>.
</p>
<p>The following adjusted combination of modes is convenient for many
purposes,
</p>
<div class="example">
<pre class="example">GSL_IEEE_MODE=&quot;double-precision,&quot;\
                &quot;mask-underflow,&quot;\
                  &quot;mask-denormalized&quot;
</pre></div>

<p>This choice ignores any errors relating to small numbers (either
denormalized, or underflowing to zero) but traps overflows, division by
zero and invalid operations.
</p>
<p>Note that on the x86 series of processors this function sets both the
original x87 mode and the newer <small>MXCSR</small> mode, which controls SSE
floating-point operations.  The SSE floating-point units do not have a
precision-control bit, and always work in double-precision.  The
single-precision and extended-precision keywords have no effect in
this case.
</p></dd></dl>

<p>To demonstrate the effects of different rounding modes consider the
following program which computes <em>e</em>, the base of natural
logarithms, by summing a rapidly-decreasing series,
</p>
<div class="example">
<pre class="example">e = 1 + 1/2! + 1/3! + 1/4! + ... 
  = 2.71828182846...
</pre></div>

<div class="example">
<pre class="verbatim">#include &lt;stdio.h&gt;
#include &lt;gsl/gsl_math.h&gt;
#include &lt;gsl/gsl_ieee_utils.h&gt;

int
main (void)
{
  double x = 1, oldsum = 0, sum = 0; 
  int i = 0;

  gsl_ieee_env_setup (); /* read GSL_IEEE_MODE */

  do 
    {
      i++;
      
      oldsum = sum;
      sum += x;
      x = x / i;
      
      printf (&quot;i=%2d sum=%.18f error=%g\n&quot;,
              i, sum, sum - M_E);

      if (i &gt; 30)
         break;
    }  
  while (sum != oldsum);

  return 0;
}
</pre></div>

<p>Here are the results of running the program in <code>round-to-nearest</code>
mode.  This is the IEEE default so it isn&rsquo;t really necessary to specify
it here,
</p>
<div class="example">
<pre class="example">$ GSL_IEEE_MODE=&quot;round-to-nearest&quot; ./a.out 
i= 1 sum=1.000000000000000000 error=-1.71828
i= 2 sum=2.000000000000000000 error=-0.718282
....
i=18 sum=2.718281828459045535 error=4.44089e-16
i=19 sum=2.718281828459045535 error=4.44089e-16
</pre></div>

<p>After nineteen terms the sum converges to within <em>4 \times 10^-16</em> of the correct value.  
If we now change the rounding mode to
<code>round-down</code> the final result is less accurate,
</p>
<div class="example">
<pre class="example">$ GSL_IEEE_MODE=&quot;round-down&quot; ./a.out 
i= 1 sum=1.000000000000000000 error=-1.71828
....
i=19 sum=2.718281828459041094 error=-3.9968e-15
</pre></div>

<p>The result is about 
<em>4 \times 10^-15</em> 
below the correct value, an order of magnitude worse than the result
obtained in the <code>round-to-nearest</code> mode.
</p>
<p>If we change to rounding mode to <code>round-up</code> then the final result
is higher than the correct value (when we add each term to the sum the
final result is always rounded up, which increases the sum by at least
one tick until the added term underflows to zero).  To avoid this
problem we would need to use a safer converge criterion, such as
<code>while (fabs(sum - oldsum) &gt; epsilon)</code>, with a suitably chosen
value of epsilon.
</p>
<p>Finally we can see the effect of computing the sum using
single-precision rounding, in the default <code>round-to-nearest</code>
mode.  In this case the program thinks it is still using double precision
numbers but the CPU rounds the result of each floating point operation
to single-precision accuracy.  This simulates the effect of writing the
program using single-precision <code>float</code> variables instead of
<code>double</code> variables.  The iteration stops after about half the number
of iterations and the final result is much less accurate,
</p>
<div class="example">
<pre class="example">$ GSL_IEEE_MODE=&quot;single-precision&quot; ./a.out 
....
i=12 sum=2.718281984329223633 error=1.5587e-07
</pre></div>

<p>with an error of 
<em>O(10^-7)</em>, which corresponds to single
precision accuracy (about 1 part in <em>10^7</em>).  Continuing the
iterations further does not decrease the error because all the
subsequent results are rounded to the same value.
</p>
<hr>
<div class="header">
<p>
Next: <a href="IEEE-References-and-Further-Reading.html#IEEE-References-and-Further-Reading" accesskey="n" rel="next">IEEE References and Further Reading</a>, Previous: <a href="Representation-of-floating-point-numbers.html#Representation-of-floating-point-numbers" accesskey="p" rel="previous">Representation of floating point numbers</a>, Up: <a href="IEEE-floating_002dpoint-arithmetic.html#IEEE-floating_002dpoint-arithmetic" accesskey="u" rel="up">IEEE floating-point arithmetic</a> &nbsp; [<a href="Function-Index.html#Function-Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>