1======================================
2Python IEEE 754 floating point support
3======================================
4
5>>> from sys import float_info as FI
6>>> from math import *
7>>> PI = pi
8>>> E = e
9
10You must never compare two floats with == because you are not going to get
11what you expect. We treat two floats as equal if the difference between them
12is small than epsilon.
13>>> EPS = 1E-15
14>>> def equal(x, y):
15...     """Almost equal helper for floats"""
16...     return abs(x - y) < EPS
17
18
19NaNs and INFs
20=============
21
22In Python 2.6 and newer NaNs (not a number) and infinity can be constructed
23from the strings 'inf' and 'nan'.
24
25>>> INF = float('inf')
26>>> NINF = float('-inf')
27>>> NAN = float('nan')
28
29>>> INF
30inf
31>>> NINF
32-inf
33>>> NAN
34nan
35
36The math module's ``isnan`` and ``isinf`` functions can be used to detect INF
37and NAN:
38>>> isinf(INF), isinf(NINF), isnan(NAN)
39(True, True, True)
40>>> INF == -NINF
41True
42
43Infinity
44--------
45
46Ambiguous operations like ``0 * inf`` or ``inf - inf`` result in NaN.
47>>> INF * 0
48nan
49>>> INF - INF
50nan
51>>> INF / INF
52nan
53
54However unambigous operations with inf return inf:
55>>> INF * INF
56inf
57>>> 1.5 * INF
58inf
59>>> 0.5 * INF
60inf
61>>> INF / 1000
62inf
63
64Not a Number
65------------
66
67NaNs are never equal to another number, even itself
68>>> NAN == NAN
69False
70>>> NAN < 0
71False
72>>> NAN >= 0
73False
74
75All operations involving a NaN return a NaN except for nan**0 and 1**nan.
76>>> 1 + NAN
77nan
78>>> 1 * NAN
79nan
80>>> 0 * NAN
81nan
82>>> 1 ** NAN
831.0
84>>> NAN ** 0
851.0
86>>> 0 ** NAN
87nan
88>>> (1.0 + FI.epsilon) * NAN
89nan
90
91Misc Functions
92==============
93
94The power of 1 raised to x is always 1.0, even for special values like 0,
95infinity and NaN.
96
97>>> pow(1, 0)
981.0
99>>> pow(1, INF)
1001.0
101>>> pow(1, -INF)
1021.0
103>>> pow(1, NAN)
1041.0
105
106The power of 0 raised to x is defined as 0, if x is positive. Negative
107values are a domain error or zero division error and NaN result in a
108silent NaN.
109
110>>> pow(0, 0)
1111.0
112>>> pow(0, INF)
1130.0
114>>> pow(0, -INF)
115Traceback (most recent call last):
116...
117ValueError: math domain error
118>>> 0 ** -1
119Traceback (most recent call last):
120...
121ZeroDivisionError: 0.0 cannot be raised to a negative power
122>>> pow(0, NAN)
123nan
124
125
126Trigonometric Functions
127=======================
128
129>>> sin(INF)
130Traceback (most recent call last):
131...
132ValueError: math domain error
133>>> sin(NINF)
134Traceback (most recent call last):
135...
136ValueError: math domain error
137>>> sin(NAN)
138nan
139>>> cos(INF)
140Traceback (most recent call last):
141...
142ValueError: math domain error
143>>> cos(NINF)
144Traceback (most recent call last):
145...
146ValueError: math domain error
147>>> cos(NAN)
148nan
149>>> tan(INF)
150Traceback (most recent call last):
151...
152ValueError: math domain error
153>>> tan(NINF)
154Traceback (most recent call last):
155...
156ValueError: math domain error
157>>> tan(NAN)
158nan
159
160Neither pi nor tan are exact, but you can assume that tan(pi/2) is a large value
161and tan(pi) is a very small value:
162>>> tan(PI/2) > 1E10
163True
164>>> -tan(-PI/2) > 1E10
165True
166>>> tan(PI) < 1E-15
167True
168
169>>> asin(NAN), acos(NAN), atan(NAN)
170(nan, nan, nan)
171>>> asin(INF), asin(NINF)
172Traceback (most recent call last):
173...
174ValueError: math domain error
175>>> acos(INF), acos(NINF)
176Traceback (most recent call last):
177...
178ValueError: math domain error
179>>> equal(atan(INF), PI/2), equal(atan(NINF), -PI/2)
180(True, True)
181
182
183Hyberbolic Functions
184====================
185
186