Fred Drake | a5e7ad9 | 2001-01-09 20:38:54 +0000 | [diff] [blame] | 1 | \section{\module{fpectl} --- |
| 2 | Floating point exception control} |
| 3 | |
| 4 | \declaremodule{extension}{fpectl} |
| 5 | \platform{Unix, Windows} |
| 6 | \moduleauthor{Lee Busby}{busby1@llnl.gov} |
| 7 | \sectionauthor{Lee Busby}{busby1@llnl.gov} |
| 8 | \modulesynopsis{Provide control for floating point exception handling.} |
| 9 | |
| 10 | Most computers carry out floating point operations\index{IEEE-754} |
| 11 | in conformance with the so-called IEEE-754 standard. |
| 12 | On any real computer, |
| 13 | some floating point operations produce results that cannot |
| 14 | be expressed as a normal floating point value. |
| 15 | For example, try |
| 16 | |
| 17 | \begin{verbatim} |
| 18 | >>> import math |
| 19 | >>> math.exp(1000) |
| 20 | inf |
| 21 | >>> math.exp(1000)/math.exp(1000) |
| 22 | nan |
| 23 | \end{verbatim} |
| 24 | |
| 25 | (The example above will work on many platforms. |
| 26 | DEC Alpha may be one exception.) |
| 27 | "Inf" is a special, non-numeric value in IEEE-754 that |
| 28 | stands for "infinity", and "nan" means "not a number." |
| 29 | Note that, |
| 30 | other than the non-numeric results, |
| 31 | nothing special happened when you asked Python |
| 32 | to carry out those calculations. |
| 33 | That is in fact the default behaviour prescribed in the IEEE-754 standard, |
| 34 | and if it works for you, |
| 35 | stop reading now. |
| 36 | |
| 37 | In some circumstances, |
| 38 | it would be better to raise an exception and stop processing |
| 39 | at the point where the faulty operation was attempted. |
| 40 | The \module{fpectl} module |
| 41 | is for use in that situation. |
| 42 | It provides control over floating point |
| 43 | units from several hardware manufacturers, |
| 44 | allowing the user to turn on the generation |
| 45 | of \constant{SIGFPE} whenever any of the |
| 46 | IEEE-754 exceptions Division by Zero, Overflow, or |
| 47 | Invalid Operation occurs. |
| 48 | In tandem with a pair of wrapper macros that are inserted |
| 49 | into the C code comprising your python system, |
| 50 | \constant{SIGFPE} is trapped and converted into the Python |
| 51 | \exception{FloatingPointError} exception. |
| 52 | |
| 53 | The \module{fpectl} module defines the following functions and |
| 54 | may raise the given exception: |
| 55 | |
| 56 | \begin{funcdesc}{turnon_sigfpe}{} |
| 57 | Turn on the generation of \constant{SIGFPE}, |
| 58 | and set up an appropriate signal handler. |
| 59 | \end{funcdesc} |
| 60 | |
| 61 | \begin{funcdesc}{turnoff_sigfpe}{} |
| 62 | Reset default handling of floating point exceptions. |
| 63 | \end{funcdesc} |
| 64 | |
| 65 | \begin{excdesc}{FloatingPointError} |
| 66 | After \function{turnon_sigfpe()} has been executed, |
| 67 | a floating point operation that raises one of the |
| 68 | IEEE-754 exceptions |
| 69 | Division by Zero, Overflow, or Invalid operation |
| 70 | will in turn raise this standard Python exception. |
| 71 | \end{excdesc} |
| 72 | |
| 73 | |
| 74 | \subsection{Example \label{fpectl-example}} |
| 75 | |
| 76 | The following example demonstrates how to start up and test operation of |
| 77 | the \module{fpectl} module. |
| 78 | |
| 79 | \begin{verbatim} |
| 80 | >>> import fpectl |
| 81 | >>> import fpetest |
| 82 | >>> fpectl.turnon_sigfpe() |
| 83 | >>> fpetest.test() |
| 84 | overflow PASS |
| 85 | FloatingPointError: Overflow |
| 86 | |
| 87 | div by 0 PASS |
| 88 | FloatingPointError: Division by zero |
| 89 | [ more output from test elided ] |
| 90 | >>> import math |
| 91 | >>> math.exp(1000) |
| 92 | Traceback (most recent call last): |
| 93 | File "<stdin>", line 1, in ? |
| 94 | FloatingPointError: in math_1 |
| 95 | \end{verbatim} |
| 96 | |
| 97 | |
| 98 | \subsection{Limitations and other considerations} |
| 99 | |
| 100 | Setting up a given processor to trap IEEE-754 floating point |
| 101 | errors currently requires custom code on a per-architecture basis. |
| 102 | You may have to modify \module{fpectl} to control your particular hardware. |
| 103 | |
| 104 | Conversion of an IEEE-754 exception to a Python exception requires |
| 105 | that the wrapper macros \code{PyFPE_START_PROTECT} and |
| 106 | \code{PyFPE_END_PROTECT} be inserted into your code in an appropriate |
| 107 | fashion. Python itself has been modified to support the |
| 108 | \module{fpectl} module, but many other codes of interest to numerical |
| 109 | analysts have not. |
| 110 | |
| 111 | The \module{fpectl} module is not thread-safe. |
| 112 | |
| 113 | \begin{seealso} |
| 114 | \seetext{Some files in the source distribution may be interesting in |
| 115 | learning more about how this module operates. |
| 116 | The include file \file{Include/pyfpe.h} discusses the |
| 117 | implementation of this module at some length. |
| 118 | \file{Modules/fpetestmodule.c} gives several examples of |
| 119 | use. |
| 120 | Many additional examples can be found in |
| 121 | \file{Objects/floatobject.c}.} |
| 122 | \end{seealso} |