[Python-checkins] CVS: python/dist/src/Doc/lib libfpectl.tex,NONE,1.1

[Fred L. Drake]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory usw-pr-cvs1:/tmp/cvs-serv8213/lib

Added Files:
	libfpectl.tex 
Log Message:

Documentation for the fpectl module, from Lee Busby.  (Thanks!)


--- NEW FILE: libfpectl.tex ---
\section{\module{fpectl} ---
         Floating point exception control}

\declaremodule{extension}{fpectl}
  \platform{Unix, Windows}
\moduleauthor{Lee Busby}{busby1@llnl.gov}
\sectionauthor{Lee Busby}{busby1@llnl.gov}
\modulesynopsis{Provide control for floating point exception handling.}

Most computers carry out floating point operations\index{IEEE-754}
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

\begin{verbatim}
>>> import math
>>> math.exp(1000)
inf
>>> math.exp(1000)/math.exp(1000)
nan
\end{verbatim}

(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 \module{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 \constant{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,
\constant{SIGFPE} is trapped and converted into the Python
\exception{FloatingPointError} exception.

The \module{fpectl} module defines the following functions and
may raise the given exception:

\begin{funcdesc}{turnon_sigfpe}{}
Turn on the generation of \constant{SIGFPE},
and set up an appropriate signal handler.
\end{funcdesc}

\begin{funcdesc}{turnoff_sigfpe}{}
Reset default handling of floating point exceptions.
\end{funcdesc}

\begin{excdesc}{FloatingPointError}
After \function{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.
\end{excdesc}


\subsection{Example \label{fpectl-example}}

The following example demonstrates how to start up and test operation of
the \module{fpectl} module.

\begin{verbatim}
>>> 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
\end{verbatim}


\subsection{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 \module{fpectl} to control your particular hardware.

Conversion of an IEEE-754 exception to a Python exception requires
that the wrapper macros \code{PyFPE_START_PROTECT} and
\code{PyFPE_END_PROTECT} be inserted into your code in an appropriate
fashion.  Python itself has been modified to support the
\module{fpectl} module, but many other codes of interest to numerical
analysts have not.

The \module{fpectl} module is not thread-safe.

\begin{seealso}
  \seetext{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}.}
\end{seealso}