Doc/lib/libfpectl.tex

   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}