   Copyright (C)  2000    Daniel A. Atkinson  <DanAtk@aol.com>
   Copyright (C)  2004    Ivano Primi  <ivano.primi@tin.it>    

   Copying and distribution of this file, with or without modification,
   are permitted in any medium without royalty provided the copyright
   notice and this notice are preserved.

******************************************************************************

                   HIGH PRECISION ARITHMETIC (abbr. HPA) LIBRARY

                                    Summary

                 The extended precision library implements a high
                 precision floating point arithmetic together with a
                 comprehensive set of support functions. The general
                 areas covered by these functions include:

                     o Extended Precision Arithmetic   (both real and complex)
                     o Extended Precision Math Library (both real and complex)
                     o Applications of High Precision Computation

                 The math library support includes evaluation of
                 trigonometric, inverse trigonometric, hyperbolic,
                 logarithm, and exponential functions at the same
                 precision as the floating point math itself.


** History **

The HPA library comes from a branch of the source code of the CCMath library,
which is a work by Daniel A. Atkinson.
Actually, I just took the source code in the 'xarm' section
of the CCMath library, I modified a relevant part of it,
then I added the functions for complex arithmetic and
the makefiles to compile the library on a GNU/Linux(R) or Unix(R) system.
But the starting hard work was done by Daniel A. Atkinson, which was also very
kind to release the code of the CCMath Library under GNU Lesser 
General Public License. This made possible that I could modify and 
redistribute it under the same terms. So, a really big THANKS to Daniel !!
Unfortunately, I was not able to contact him personally, 
so if you know him and you can say him "Thanks" from me, please do it !


** License **

The HPA (abbreviation of HIGH PRECISION ARITHMETIC Library) is
copyrighted by Ivano Primi (ivprimi@libero.it) and
Daniel A. Atkinson (the author of the original code). 
As it is for the source code of the CCMath Library, the source code
of the HPA library is released under the terms of the GNU Lesser General 
Public License, as published by the Free Software Foundation; 
either version 2.1 of the License, or (at your option) any later version.

The HPA library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

You can contact me by paper mail writing to the next address

	Ivano Primi
	via Colle Cannetacce 50/A
	C.A.P. 00038 - Valmontone (ROMA)
	Italy                                                         .

If you prefer the electronic mail you can write to the address

	ivprimi@libero.it                                             .


** Installation instructions            **

Please read the file INSTALL to know how building and installing the
HPA library.


** Using HPA library in a C/C++ program **

The lists of the functions which compose the HPA library
are in the header files "xpre.h" and "cxpre.h".
So, to use them you have to add this line to the begin
of your source files:

	#include <xpre.h>

(or
	#include <cxpre.h>

 if you also need the functions of the complex math library).

The HPA library defines its own numeric types, called 'struct xpr'
and 'struct cxpr' respectively. 'struct xpr' can be used to declare and define
real variables, 'struct cxpr' for complex variables.
The size of a variable of 'struct xpr' type is given by  (2 x XDIM + 2) bytes,
where  XDIM is a constant defined in the file "xpre.h" (actually,
in the file "hpaconf.h" which is included by "xpre.h").
The size of a variable of 'struct cxpr' type is given by  (4 x XDIM + 4) bytes,
since 'struct cxpr' is actually a structure formed by two items of 'struct xpr'
type, used to store the real and the imaginary part of a complex number.
The HPA library provides several routines acting on 'struct xpr'
and 'struct cxpr' arguments.
I will not describe here what are the routines supplied by the library
and what they do. In fact, you can find their descriptions and
other useful information in the manual of the HPA library 
(look up the files "hpa.txt" or "hpa.html" inside the directory containing
all the HPA documentation).
Now I will only concentrate on how compiling and building a program
which makes use of the HPA library.
Together with the HPA library is installed a little and simple
program called 'hpaconf'. 
You can use it to quickly compile and build your programs.
If PREFIX is the root directory chosen to install the HPA library
(the default value for PREFIX is /usr/local), then 'hpaconf'
should be installed inside PREFIX/bin. You can know where 'hpaconf'
is by launching the command

	which hpaconf

on your console or terminal.
In the following I will suppose that the directory PREFIX/bin
is included in your PATH environment variable (This is surely
true if the command 'which' was able to find 'hpaconf').  

'hpaconf' recognizes four options:

	-v      to return the version of HPA installed on your system

	-c      to return the flags needed to compile using HPA

	-l	to return the flags to link  against HPA

	-n	to print a newline at the end of the output.

The option -v cannot be used together with the options -c and -l,
but it may be used together with -n:

	hpaconf -v 	prints onto the standard output (console) the version
			of HPA installed on your system

	hpaconf -v -n

	or

	hpaconf -n -v   (order does not matter) behaves exactly the same
			but also prints a newline to force the following
			output to be written on the next line.


The options -c and -l cannot be used together with -v, but they can be used
both at the same time and they can be accompanied by the option -n. Of course,
order does not matter.

	hpaconf -c	prints onto the standard output the flags
			needed to compile using HPA

	hpaconf -l	prints onto the standard output the flags
			needed to link  against HPA

	hpaconf -c -l	

	or

	hpaconf -l -c	prints both the flags to compile using HPA
			and the flags to link  against HPA.

If the -n option is added, then the information printed is followed
by a newline. Why 'hpaconf' is so useful ?
I will give you an example. To compile the source
file 'example.c' you should tell the compiler where looking for
the header files of HPA and for the library itself; to do this
it is sufficient to specify the related paths with the options
-I and -L (at least if you are using GCC/G++ as C/C++ compiler).
However, in this way you are constrained to remember the path
where HPA was installed and this is quite uncomfortable.
With 'hpaconf' you can simply use the command

	cc -c $(hpaconf -c) example.c 

or

	cc -c `hpaconf -c` example.c	.

to compile the file 'example.c' and obtain the object file 'example.o'.
Actually, the previous one is the right form of the command 
for a shell sh compatible, like ash, bash or ksh. 
If you are using another shell, probably the
right form to obtain the expansion of the command 'hpaconf -c'
will be another one (see the manual of your preferred shell for this).
On GNU/Linux bash is the default shell for all users. If this is
not true for your machine, then ask your system administrator :) 
Once you have obtained the object file 'example.o', you may do the linkage
by using the command (for a shell sh-compatible):

	cc example.o $(hpaconf -l) -o example

or

	cc example.o `hpaconf -l` -o example	.

If you want, you may also compile and build at the same time by using
(Do i need to repeat the next one is the right form only for
 a shell sh-compatible ?)

	cc example.c $(hpaconf -c -l) -o example

or

	cc example.c `hpaconf -c -l` -o example	.


which will compile 'example.c' and build the program 'example'.
Naturally, compiling and building at the same time is only
possible when the source code of your program is all contained in one
file.

The 'hpaconf' program may also be used to retrieve information
about the options used to compile the HPA library for the system
where you are working.
This information is displayed, together with hints about usage, when
'hpaconf' is called with no options. This is the output obtained
on my personal machine:

ivano@darkstar[~]$  hpaconf 
*** Usage:  hpaconf [-v] [-n] or
***         hpaconf [-c] [-l] [-n]

*** Meaning of the options:
    -v      return the current version of the HPA library
    -c      return flags to compile using HPA library
    -l      return flags to link  against HPA library
    -n      insert a newline at the end

----- Features of the HPA library (including build options) -----

Size of an extended precision floating point value (in bytes): 16
Number of bits available for the sign:     1
Number of bits available for the exponent: 15
Number of bits available for the mantissa: 112
Decimal digits of accuracy:               ~33
Dynamic range supported:          2^16384 > x > 2^(-16383)      i.e.
                             1.19*10^4932 > x > 1.68*10^-(4932)
In case of floating point error
the global (extern) variable 'xErrNo' is suitably set


The first value shown after the header "Features of the HPA library"
is the size of a variable of 'struct xpr' type. When I installed the
HPA library on my machine, i chose to compile it by setting XDIM
to 7. So, a variable of type 'struct xpr' turns out to have a size of
16 = 2 * 7 + 2  bytes.
Since XDIM could have been set to another value on the system
where you are working (actually, XDIM could also have the values
11, 15, 19, 23, 27 and 31), the first value shown by 'hpaconf'
could differ on your machine.
The next 2 values (bits available for sign and mantissa) are
the same for all the installations.
The decimal digits of accuracy depend on the value of XDIM,
namely they increase together with XDIM (till to a maximum of
149 when XDIM is 31). As you can see, the actual value of XDIM
determines the accuracy provided by the mathematical functions of 
the HPA library. Even if a larger value for XDIM implies 
a greater accuracy, together with XDIM increases the memory
(and the time !) requested by the routines of the HPA library
to perform their computations.
The dynamic range supported by the HPA library is always the same
(or almost).
At end, the HPA library can be compiled to deal differently with
the error conditions.
By default, whenever a runtime error occurs within a function of the HPA
library, this function sets an external error indicator to
a suitable value. This value can be looked up later
to know what exactly went wrong. 
The name of the variable of 'int' type used for this purpose
is 'xErrNo'. As you can see, the active behavior on my system
is the default one.
However, the HPA library could be compiled to deal
differently with runtime errors.
For instance, in case of error a suitable message could be
printed onto stderr and the library could also cause the
termination of the calling program via EXIT(1).
At last, the library could also be compiled to ignore
at all any runtime error (sigh !).
In the last line of the output of 'hpaconf', you can find
information about treatment of the errors.
This information can also be retrieved by looking up the file
"hpaconf.h" (automatically included by "xpre.h" and "cxpre.h"),
which defines the macro

XERR_DFL   to mean that, in case of error, 'xErrNo' is suitably set;
XERR_WARN  ..............................  a suitable message is printed
					   on stderr;
XERR_EXIT  ..............................  the calling program is terminated
					   through a call to exit(1) after
					   printing a message on stderr;
XERR_IGN   ..............................  nothing is done or signaled. 

This last way will turn out you very useful while writing your programs.
The file "hpaconf.h" also defines the macro HPA_VERSION as a string
containing the version number of the HPA library currently in use.





