
Note: for information on this release of the CPML, such as new features,
      please check the Release_Notes file.



The Compaq Portable Math Library (CPML) is a library of math functions provided
for the Linux Operating System running on Alpha AXP platforms.  The entrypoints
and implementations in CPML are identical to those in Compaq's Tru64 UNIX libm.
CPML is a superset of the libm for Alpha Linux and consequently can be
considered a replacement library.

CPML is divided into two sets of routines - standard routines and "fast"
routines.  CPML standard routines are designed to support the C and Fortran
languages as defined by the X/Open, ANSI C and ANSI Fortran standards for IEEE
single, double and quad precision floating point formats.  CPML "fast" entry
points are a small set of single and double precision routines that gain some
increase in performance over the standard routines by relaxing some of the
exception handling and accuracy constraints of the standard routines.

CPML uses the ANSI C naming convention for the standard routines: single and
quad precision functions are suffixed with the characters 'f' and 'l'
respectively.  For example, the single precision sine function is named sinf
and the quad precision power function is named powl.

Other than the following two exceptions, CPML routines use C call-by-value
semantics:

	o The "call-by-reference" jacket routines for supporting Fortran
	  intrinsic functions.  The entry point names for these routines
	  are prefixed with "r_".

	o The quad precision format supported in CPML is the 128-bit IEEE
	  extended precision format (1 sign bit, 15 exponent bits and 113
	  fraction bits).  Since the alpha calling standard does not support
	  passing 128 bit data items in registers, CPML quad precision
	  routines use "pass-by-reference" semantics.

The standard CPML routines:

        o Never generate a floating point exception (i.e. all exceptional
          cases are screened out before the exception can occur)

        o Handle all IEEE Nan, Infinity and denormalized values

        o Return a zero result for invalid arguments and set errno to
          EDOM

        o Return the largest (signed) floating point value for overflow
          and set errno to ERANGE

        o Return a signed zero for underflow errors and set errno to
          ERANGE

        o Are thread safe

When called from a routine compiled by Compaq Fortran, C, or C++, the CPML
library functions adopt the exception behavior traditional for that language 
or the behavior specified by the choice of compilation option for the 
calling routine.   For example, CPML functions called by a routine compiled 
with Compaq Fortran will exhibit "typical Fortran" behavior when presented
with an exceptional case:  underflows are quietly flushed to zero, and signals
are raised when the result would overflow or would be invalid for some reason.
If the same routine is compiled with the option "-fpe3", the CPML library 
functions quietly return appropriate IEEE denormal, infinity, or NaN values.

In addition to being quite robust, the standard CPML routines are designed and
implemented to provide high accuracy and performance.   CPML standard routines
are significantly faster that the corresponding routines in the Linux libm and,
with a few exceptions, are also faster than the corresponding libffm routines.
In most cases, the error in CPML standard routines is bounded by .6 lsb as
compared to .8 lsb for the Linux libm or 3.0 lsb for libffm.  (See the table
below for more details.)

The "fast" entry points have the same names as the standard entry points except
that they are prefixed by "F_".  For example, the single precision fast sine
routine is named F_sinf and the fast double precision power routine is F_pow.
The fast entry points achieve increased performance by having slightly higher
error bounds, and not being as rigorous about about detecting and reporting
error conditions.  Specifically, the fast routines tend to generate floating
point exceptions for invalid arguments and overflow conditions rather than
setting errno.  Not all of the standard routines currently have fast
counterparts.  The following table is a partial list of the standard routines
in CPML and shows which routines have "by-reference" and "fast" implementations:


      Name       ref fast    Name       ref fast    Name       ref fast
      ------    ---- ----    ------    ---- ----    ------    ---- ----   
      acos       yes  no  |  expm1       no  no  |  nextafter  yes  no
      acosd      yes  no  |  fabs       yes  no  |  nint       yes  no
      acosh       no  no  |  finite     yes  no  |  pow         no yes
      asin       yes  no  |  floor      yes  no  |  remainder   no  no
      asind      yes  no  |  fp_class   yes  no  |  rint       yes  no
      asinh       no  no  |  frexp       no  no  |  scalb       no  no
      atan       yes yes  |  hypot       no yes  |  sin        yes yes
      atan2      yes yes  |  ilogb       no  no  |  sind       yes yes
      atand      yes  no  |  isnan      yes  no  |  sinh       yes  no
      atand2     yes  no  |  j0          no  no  |  sqrt       yes yes
      atanh      yes  no  |  j1          no  no  |  tan        yes yes
      ceil       yes  no  |  jn          no  no  |  tand       yes  no
      copysign   yes  no  |  ldexp       no  no  |  tanh       yes  no
      cos        yes yes  |  lgamma      no  no  |  trunc      yes  no
      cosd       yes yes  |  log        yes yes  |  unordered  yes  no
      cosh       yes  no  |  log10      yes yes  |  y0          no  no
      cot        yes  no  |  log1p       no  no  |  y1          no  no
      cotd       yes  no  |  log2       yes  no  |  yn          no  no
      erf         no  no  |  logb        no  no  |  __rsqrt     no  no
      erfc        no  no  |  modf        no  no  |
      exp        yes yes  |  nearest     no  no  |

Included with of CPML is the header file cpml.h.  This header file is intended
to aid C programmers to access the fast entry points.  By including cpml.h in
your C program, the standard libm entry point names will be redefined to access
CPML fast entry points.  Users should be aware, however, that the accuracy and
exception behavior differences between the standard and fast entry points may
cause problems for some applications.  While this is highly unlikely, it is
possible and users are encourage to use discretion when using cpml.h.

The following table gives accuracy and performance comparisons for CPML, the
standard Alpha Linux math library (libm), and version 0.28 of the freely
distributed fast math library (FFM). (See
http://people.frankfurt.netsurf.de/Joachim.Wesner/ )

The section of the table marked 'Accuracy', gives the maximum observed least
significant bit (lsb) error over the entire function domain.

The section headed 'Performance', gives the cycle counts for executing the
function at a particular input value on a Alpha 21164A cpu. Two sets of
performance numbers are given for CPML: one for Tru64 Unix and one for Linux.


              Accuracy                           Performance
        -----------------------   -----------------------------------------
                                               CPML            Fast CPML
                     Fast           Input   -----------       -----------
Func    CPML  libm   CPML  FFM      Value   Tru64 Linux libm  Tru64 Linux FFM
-----  ------------------------   --------------------------------------------

sqrt     .50   .50   1.90   .97       10.0    68   68   1017    41    44   75
sin      .54   .83   1.91  3.20       1.96    68   74    268    54    61   85
log10    .55  1.92   3.22  3.57        2.1    56   62    367    43    49  105
rsqrt   1.43     -      -  2.19       10.0    45   50      -     -     -   73
atan     .53   .76      -  1.86       200.    81   83    242     -     -   95
acos     .59   .88      -  1.44       -.99    89   95   1185     -     -  161
atan2   1.27  1.43      -  2.89    1.1,2.1   105  108    408     -     -  139
sinh     .51  1.78      -  2.43        2.1    78   83    535     -     -  122
log      .55   .85   3.45  3.78        2.1    56   62    299    43    49  104
tanh     .61  2.08      -  3.34        2.1   134  139    489     -     -  155
asin     .63   .85      -  2.50        .99    92   99   1193     -     -  162
tan      .54   .83   2.67  3.46       7.85    90  101    505    75    81   97
log2     .58     -      -  3.26       10.0    57   61      -     -     -  102
cosh     .51  1.31      -  2.51        2.1    79   82    440     -     -  122
cos      .53   .81   1.97  3.00       1.57    68   73    251    53    61   89
exp      .50   .85   3.53  2.14        2.1    62   67    376    47    52   87
pow      .51   .82   3.76  2706   1.1,10.1   113  118   1047    91    91  203
cot      .54     -      -  4.05        2.1    84   92      -     -     -   88


