1 files changed, 120 insertions, 0 deletions
diff --git a/Doc/library/fpectl.rst b/Doc/library/fpectl.rst
new file mode 100644
index 0000000..ef030f0
--- /dev/null
+++ b/Doc/library/fpectl.rst
@@ -0,0 +1,120 @@
+
+:mod:`fpectl` --- Floating point exception control
+==================================================
+
+.. module:: fpectl
+   :platform: Unix
+   :synopsis: Provide control for floating point exception handling.
+.. moduleauthor:: Lee Busby <busby1@llnl.gov>
+.. sectionauthor:: Lee Busby <busby1@llnl.gov>
+
+
+.. note::
+
+   The :mod:`fpectl` module is not built by default, and its usage is discouraged
+   and may be dangerous except in the hands of experts.  See also the section
+   :ref:`fpectl-limitations` on limitations for more details.
+
+.. index:: single: IEEE-754
+
+Most computers carry out floating point operations in conformance with the
+so-called IEEE-754 standard. On any real computer, some floating point
+operations produce results that cannot be expressed as a normal floating point
+value. For example, try ::
+
+   >>> import math
+   >>> math.exp(1000)
+   inf
+   >>> math.exp(1000) / math.exp(1000)
+   nan
+
+(The example above will work on many platforms. DEC Alpha may be one exception.)
+"Inf" is a special, non-numeric value in IEEE-754 that stands for "infinity",
+and "nan" means "not a number." Note that, other than the non-numeric results,
+nothing special happened when you asked Python to carry out those calculations.
+That is in fact the default behaviour prescribed in the IEEE-754 standard, and
+if it works for you, stop reading now.
+
+In some circumstances, it would be better to raise an exception and stop
+processing at the point where the faulty operation was attempted. The
+:mod:`fpectl` module is for use in that situation. It provides control over
+floating point units from several hardware manufacturers, allowing the user to
+turn on the generation of :const:`SIGFPE` whenever any of the IEEE-754
+exceptions Division by Zero, Overflow, or Invalid Operation occurs. In tandem
+with a pair of wrapper macros that are inserted into the C code comprising your
+python system, :const:`SIGFPE` is trapped and converted into the Python
+:exc:`FloatingPointError` exception.
+
+The :mod:`fpectl` module defines the following functions and may raise the given
+exception:
+
+
+.. function:: turnon_sigfpe()
+
+   Turn on the generation of :const:`SIGFPE`, and set up an appropriate signal
+   handler.
+
+
+.. function:: turnoff_sigfpe()
+
+   Reset default handling of floating point exceptions.
+
+
+.. exception:: FloatingPointError
+
+   After :func:`turnon_sigfpe` has been executed, a floating point operation that
+   raises one of the IEEE-754 exceptions Division by Zero, Overflow, or Invalid
+   operation will in turn raise this standard Python exception.
+
+
+.. _fpectl-example:
+
+Example
+-------
+
+The following example demonstrates how to start up and test operation of the
+:mod:`fpectl` module. ::
+
+   >>> import fpectl
+   >>> import fpetest
+   >>> fpectl.turnon_sigfpe()
+   >>> fpetest.test()
+   overflow        PASS
+   FloatingPointError: Overflow
+
+   div by 0        PASS
+   FloatingPointError: Division by zero
+     [ more output from test elided ]
+   >>> import math
+   >>> math.exp(1000)
+   Traceback (most recent call last):
+     File "<stdin>", line 1, in ?
+   FloatingPointError: in math_1
+
+
+.. _fpectl-limitations:
+
+Limitations and other considerations
+------------------------------------
+
+Setting up a given processor to trap IEEE-754 floating point errors currently
+requires custom code on a per-architecture basis. You may have to modify
+:mod:`fpectl` to control your particular hardware.
+
+Conversion of an IEEE-754 exception to a Python exception requires that the
+wrapper macros ``PyFPE_START_PROTECT`` and ``PyFPE_END_PROTECT`` be inserted
+into your code in an appropriate fashion.  Python itself has been modified to
+support the :mod:`fpectl` module, but many other codes of interest to numerical
+analysts have not.
+
+The :mod:`fpectl` module is not thread-safe.
+
+
+.. seealso::
+
+   Some files in the source distribution may be interesting in learning more about
+   how this module operates. The include file :file:`Include/pyfpe.h` discusses the
+   implementation of this module at some length. :file:`Modules/fpetestmodule.c`
+   gives several examples of use. Many additional examples can be found in
+   :file:`Objects/floatobject.c`.
+