Return to READ_ME CVS log

Up to [local] / OpenXM_contrib / PHC / Ada / Math_Lib / Numbers

Annotation of OpenXM_contrib/PHC/Ada/Math_Lib/Numbers/READ_ME, Revision 1.1.1.1

1.1       maekawa     1: Basic number definitions, coefficient rings and fields for PHCv2.
                      2:
                      3: The definition of floating-point numbers is such that it is independent
                      4: of the pre-defined type "float".  New in the second version of PHC are
                      5: the multi-precision numbers.  This new feature is motivated by the demand
                      6: for robustness in semi-numerical computations, where we have to deal with
                      7: either badly-scaled input or singularities at the end of the computations.
                      8: The precision limits of the standard machine number do not always suffice.
                      9: However, software-driven arithmetic leads to a considerable loss in efficiency,
                     10: especially if we rely on the grammar school algorithms as the ones used here.
                     11:
                     12: The library is divided in three parts:
                     13: 1) encapsulation of standard machine types, packages group definitions
                     14: 2) implementation of the multi-precision arithmetic
                     15: 3) embedding : generics + instantiation, no implementation!
                     16: In addition we have random number generators and numbers_io,
                     17: besides the usual testing facilities.
                     18:
                     19: --------------------------------------------------------------------------------
                     20: file name                         : short description
                     21: --------------------------------------------------------------------------------
                     22: standard_natural_numbers          : defines the standard naturals
                     23: standard_natural_numbers_io       : input/output of standard naturals
                     24: standard_integer_numbers          : defines the standard integers
                     25: standard_integer_numbers_io       : input/output of standard integers
                     26: standard_floating_numbers         : defines single_float and double_float
                     27: standard_floating_numbers_io      : input/output of standard floating-point
                     28: standard_mathematical_functions   : defines math functions for standard floats
                     29: --------------------------------------------------------------------------------
                     30: characters_and_numbers            : utilities to input/output of numbers
                     31: multprec_natural_numbers          : natural numbers of arbitrary length
                     32: multprec_natural_numbers_io       : input/output routines of natural numbers
                     33: multprec_integer_numbers          : integer numbers of arbitrary length
                     34: multprec_integer_numbers_io       : input/output routines of integer numbers
                     35: multprec_floating_numbers         : multi-precision floating-point numbers
                     36: multprec_floating_numbers_io      : input/output routines of floating numbers
                     37: multprec_mathematical_functions   : defines math functions for multprec floats
                     38: generic_complex_numbers           : complex numbers over any real field
                     39: standard_complex_numbers          : implementation of complex numbers
                     40: standard_complex_numbers_io       : input/output of standard complex numbers
                     41: standard_complex_numbers_polar    : polar view on standard complex numbers
                     42: multprec_complex_numbers          : multi-precision complex numbers
                     43: multprec_complex_numbers_io       : input/output for multi-precision complex
                     44: multprec_complex_number_tools     : conversion/set_size operators
                     45: --------------------------------------------------------------------------------
                     46: abstract_ring                     : a ring has the operations +,- and *
                     47: abstract_ring_io                  : definition of input/output for a ring
                     48: abstract_ring-domain              : extension with order and division/remainder
                     49: abstract_ring-field               : extension with order and division
                     50: standard_natural_ring             : ring of standard natural numbers
                     51: standard_natural_ring_io          : abstract_ring_io(standard natural)
                     52: standard_integer_ring             : ring of standard integer numbers
                     53: standard_integer_ring_io          : abstract_ring_io(standard integer)
                     54: standard_integer_ring-domain      : domain of standard integer numbers
                     55: standard_floating_ring            : ring of standard floating-point numbers
                     56: standard_floating_ring_io         : abstract_ring_io(standard floating)
                     57: standard_floating_ring-ffield     : field of standard floating numbers
                     58: standard_complex_ring             : ring of standard complex numbers
                     59: standard_complex_ring_io          : abstract_ring_io(standard complex)
                     60: multprec_natural_ring             : ring of multi-precision natural numbers
                     61: multprec_natural_ring_io          : abstract_ring_io(multprec natural)
                     62: multprec_integer_ring             : ring of multi-precision integer numbers
                     63: multprec_integer_ring_io          : abstract_ring_io(multprec integer)
                     64: multprec_integer_ring-ddomain     : domain of multi-precision integer numbers
                     65: multprec_floating_ring            : ring of multi-precision floating numbers
                     66: multprec_floating_ring_io         : abstract_ring_io(multprec floating)
                     67: multprec_floating_ring-ffield     : field of multi-precision floating numbers
                     68: multprec_complex_ring             : ring of multi-precision complex numbers
                     69: multprec_complex_ring_io          : abstract_ring_io(multprec complex)
                     70: --------------------------------------------------------------------------------
                     71: numbers_io                        : user-friendly way of asking a number
                     72: standard_random_numbers           : generates random standard numbers
                     73: multprec_random_numbers           : generates random multi-precision numbers
                     74: --------------------------------------------------------------------------------
                     75: ts_natnum                         : test multi-precision natural numbers
                     76: ts_intnum                         : test multi-precision integer numbers
                     77: ts_fltnum                         : test multi-precision floating numbers
                     78: ts_cmpnum                         : test multi-precision complex numbers
                     79: ts_random                         : test random number generators
                     80: --------------------------------------------------------------------------------
                     81:
                     82: Natural numbers are seen as unsigned integer numbers and are also provided
                     83: with a "-" operation, although these operations do not always make sense.
                     84: The correct mathematically way is to define a monoid, but this would have
                     85: led to the definition of more vector packages.  Moreover, due to memory memory
                     86: limitations, rings do not exists in a computer, since it is always possible
                     87: to find two huge numbers for which the memory is insufficient to contain
                     88: their sum or product.  An Euclidean domain is defined as an extension of
                     89: the ring with order and division/remainder operations.  A field is a similar
                     90: extension of the ring with order and division operations.
                     91:
                     92: The multi-precision packages are at the next-lowest level.
                     93: We first focus on how to implement the operations.  Afterwards
                     94: and independently, the interpretations/encapsulations are set up.
                     95:
                     96: Single precision floating-point numbers are defined, but not elaborated
                     97: since they are not used anyway.  I recall that on an IBM RS/6000, adding
                     98: single precision floating-point numbers took longer than adding double
                     99: precision floating-point numbers.
                    100:
                    101: The encapsulation of standard numerical types into packages seems a lot
                    102: of overkill, especially with the dummy procedures.
                    103: However, PHC has a now a uniform and clear treatment of numbers.
                    104:
                    105: The standard complex numbers are somewhat hybrid: software-driven but still
                    106: constant cost.  Somehow this is an encouragement to use multi-precision,
                    107: but in a restricted fashion: with an extended, but limited fractional part.
                    108: In this new implementation, complex numbers are implemented by a generic
                    109: package, where the real number type has to be instantiated.
                    110: The complex numbers are first only presented in their Cartesian view
                    111: and adapted so that they fit in the generic_ring.field framework.
                    112:
                    113: The test facilities include interactive little programs that allow to
                    114: test for special cases and tests on randomly generated numbers.
                    115: The "little" is only relative: we have 2000 lines of testing software.
                    116:
                    117: The "abstract"-packages are new in Ada 95.  At a technical level, they are
                    118: used as formal parameters to shorten the list of generics to packages.
                    119: In the object-oriented methodology, they are abstract classes.
                    120:
                    121: This library contains 86 files:
                    122:   1 READ_ME file
                    123:  55 specifications (ads), 4 abstract classes, 3 generic packages
                    124:  30 implementations (adb), including 6 test programs
                    125: wc *adb counts 8274 lines of Ada code