/Doc/library/fpectl.rst

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