add arbitrary

arbitrary/README.arbitrary

@@ -0,0 +1,87 @@
+--
+-- directory Arbitrary contains
+--    A collection of arbitrary precision floating-point routines: 
+--    arithmetic, elementary functions, IO, and demos.
+--
+-- package Extended_Real provides:
+--    An arbitrary precision floating-point data type: e_Real.
+--
+--    Lower limit is 28 decimals, no upper limit is enforced.
+--
+--    All internal arithmetic is done on 64-bit Integers, so its most
+--    efficient on 64-bit CPU's.  The package is Pure. 
+--    Floating point attributes (Ada 95) are implemented as function calls.
+--    The package exports standard floating point operators:
+--    "*", "+", "/", "**", "Abs", "<", ">", "<=" , ">=", etc. 
+--    The standard operators make it easy to modify existing code to use
+--    extended precision arithmetic. Procedure calls Mult(X,Y) and Square(X)
+--    are also provided. They do multiplication "in-place", (overwrite
+--    X with the result) and are somewhat faster than the equivalent X := X*Y,
+--    and X := X*X.
+--
+-- package Extended_Real.Elementary_Functions provides:
+--    Sin, Cos, Sqrt, Arcsin, Arccos, Arctan, Log, Exp, Reciprocal (1/x),
+--    Reciprocal_Nth_Root (x to the power of -1/N), Divide, and "**" for
+--    extended arguments and exponents. Routines are Ada 95'ish.
+--
+-- package Extended_Real.IO provides:
+--    Text to extended-precision e_Real translation routines, and
+--    e_Real to Text translation routines.
+--
+-- package e_Derivs provides:
+--    Extended precision routines for taking high order derivatives of
+--    functions.  Functions constructed from  "*", "+", "/", "**", Sin,
+--    Cos, Sqrt, Arcsin, Arccos, Arctan, Log, Exp, Compose = f(g(x)),
+--    and Reciprocal can be differentiated to order specified by user.
+--
+-- package Extended_Real.Rand provides:
+--    a basic Random Number Generator.
+--
+-- procedure e_real_demo_1.adb is:
+--    an introductory routine that demonstrates use of Extended_Real.
+--
+-- procedure e_function_demo_1.adb is:
+--    an introductory routine that demonstrates use of 
+--    Extended_Real.Elementary_Functions.
+--
+-- procedure e_jacobi_eigen_demo_1.adb demonstrates:
+--    extended-precision eigen-decomposition on Hilbert's matrix using
+--    package e_Jacobi_Eigen.
+--
+-- package e_Jacobi_Eigen is:
+--    a Jabobi iterative eigen-decomposition routine.
+--    (Demonstrates how easy it is to upgrade a floating point routine
+--    to extended precision.)  e_Jacobi_Eigen uses Extended_Real.
+--
+-- A decent optimization on gcc/GNAT is usually provided by:
+--    gnatmake -gnatnp -O3 -march=native -funroll-loops xxx.adb
+--
+-- Always do a preliminary run which exercises Assertions, and other Checks:
+--    gnatmake -Wall -gnatwa -gnatVa -gnata -gnato -fstack-check -gnateE xxx.adb
+--
+-- Because precision is arbitrary, Extended_Real is not specially
+-- optimized for any particular precision. The present design works best
+-- in the limit of 100's of decimal digits.
+--
+-- Common applications:
+-- 0. Estimation of error in lower precision floating-point calculations.
+-- 1. Evaluation of constants for math routines and Table-driven algorithms.
+-- 2. Evaluation of series solutions of special function, especially when
+--    the terms are constructed of large factorials and exponentials.
+-- 3. Evaluation of recurrance relations for special functions.
+--
+-- Generics greatly reduce the work you have to do in modifying programs
+-- to use extended floating point:
+-- 
+-- 1. place generic formal declarations
+--    of the required extended arithmetic functions at the the top of the
+--    package or subprogram to be modified.
+--
+-- 2. use the unary "-" and "+" routines that convert Real to Extended:
+--
+--    so that declarations
+--      Number : Generic_Formal_Type := +1.234;
+--    and statements like
+--      Z  := (+4.567834E+012) * X;
+--    will be acceptible to both Real and Extended types.
+--