Basic number definitions, coefficient rings and fields for PHCv2.4.85

This directory was established in release 2 of PHCpack and was upgraded
for efficiency in later versions.  In v2.3, only the i/o of multiprecision
floating point numbers was extended for the interface with Maple.
In release 2.3.49 the type "integer64" was introduced.
Multiprecision arithmetic was substantially revised in v2.3.51.

The definition of floating-point numbers is such that it is independent
of the pre-defined type "float".  New in the second version of PHC are
the multiprecision numbers.  This new feature is motivated by the demand
for robustness in semi-numerical computations, where we have to deal with
either badly-scaled input or singularities at the end of the computations.
The precision limits of the standard machine number do not always suffice.
We are interested in increasing the precision by a linear factor, so the
algorithms from elementary school should suffice.  The crucial point is
the maximal exploitation of the existing standard arithmetic.

The library is divided in three parts:
1) encapsulation of standard machine types, packages group definitions
2) implementation of the multiprecision arithmetic
3) embedding : generics + instantiation, no implementation!
In addition we have random number generators and numbers_io,
besides the usual testing facilities.

In v2.4.80, code from test procedures was moved into separate test packages.

Run "gprbuild numbers.gpr" to make all test programs.
On windows, type "gprbuild numbers.gpr -Xos=windows"
at the PowerShell prompt.
The "gprclean numbers.gpr" removes all files created by gprbuild.

------------------------------------------------------------------------------
file name                        : short description
------------------------------------------------------------------------------
standard_natural_numbers         : defines the standard naturals
standard_natural_numbers_io      : input/output of standard naturals
standard_integer_numbers         : defines the standard integers
standard_integer_numbers_io      : input/output of standard integers
standard_floating_numbers        : defines single_float and double_float
standard_floating_numbers_io     : input/output of standard floating-point
standard_mathematical_functions  : defines math functions for standard floats
------------------------------------------------------------------------------
characters_and_numbers           : utilities to input/output of numbers
strings_and_numbers              : numbers <-> strings for interfaces
multprec_natural_coefficients    : coefficient vector representations
multprec_natural_coefficients_io : put for coefficient vector representations
multprec_natural_numbers         : natural numbers of arbitrary length
multprec_natural_numbers_io      : input/output routines of natural numbers
multprec_integer_numbers         : integer numbers of arbitrary length
multprec_integer_numbers_io      : input/output routines of integer numbers
multprec_floating_numbers        : multiprecision floating-point numbers
multprec_floating_numbers_io     : input/output routines of floating numbers
multprec_natural64_coefficients  : coefficient vector representations 64 bit
multprec_natural64_numbers       : natural numbers of arbitrary length
multprec_natural64_numbers_io    : input/output routines of natural numbers
multprec_integer64_numbers       : integer numbers of arbitrary length 64 bit
multprec_integer64_numbers_io    : input/output routines of integer numbers
multprec_floating64_numbers      : multiprecision floating-point numbers
multprec_floating64_numbers_io   : input/output routines of floating numbers
multprec_mathematical_functions  : defines math functions for multprec floats
generic_complex_numbers          : complex numbers over any real field
standard_complex_numbers         : implementation of complex numbers
standard_complex_numbers_io      : input/output of standard complex numbers
standard_complex_numbers_polar   : polar view on standard complex numbers
multprec_complex_numbers_polar   : multiprecision roots of unity
multprec_complex_numbers         : multiprecision complex numbers
multprec_complex_numbers_io      : input/output for multiprecision complex
multprec_complex_number_tools    : conversion/set_size operators
------------------------------------------------------------------------------
abstract_ring                    : a ring has the operations +,- and *
abstract_ring_io                 : definition of input/output for a ring
abstract_ring-domain             : extension with order and division/remainder
abstract_ring-field              : extension with order and division
boolean_numbers                  : definitions to instantiate a Boolean ring
boolean_numbers_io               : defines i/o of Boolean numbers
boolean_ring                     : definition of a Boolean ring
boolean_ring_io                  : a Boolean ring with input and output
standard_natural_ring            : ring of standard natural numbers
standard_natural_ring_io         : abstract_ring_io(standard natural)
standard_natural64_ring          : ring of standard long long natural numbers
standard_natural64_ring_io       : abstract_ring_io(standard natural64)
standard_integer_ring            : ring of standard integer numbers
standard_integer_ring_io         : abstract_ring_io(standard integer)
standard_integer_ring-domain     : domain of standard integer numbers
standard_integer64_ring          : ring of standard long long integer numbers
standard_integer64_ring_io       : abstract_ring_io(standard long long integer)
standard_integer64_ring-domain   : domain of standard long long integer numbers
standard_floating_ring           : ring of standard floating-point numbers
standard_floating_ring_io        : abstract_ring_io(standard floating)
standard_floating_ring-ffield    : field of standard floating numbers
standard_complex_ring            : ring of standard complex numbers
standard_complex_ring_io         : abstract_ring_io(standard complex)
multprec_natural_ring            : ring of multiprecision natural numbers
multprec_natural_ring_io         : abstract_ring_io(multprec natural)
multprec_integer_ring            : ring of multiprecision integer numbers
multprec_integer_ring_io         : abstract_ring_io(multprec integer)
multprec_integer_ring-ddomain    : domain of multiprecision integer numbers
multprec_integer64_ring          : ring of multiprecision integer64 numbers
multprec_integer64_ring_io       : abstract_ring_io(multprec integer)
multprec_integer64_ring-ddomain  : domain of multiprecision integer numbers
multprec_floating_ring           : ring of multiprecision floating numbers
multprec_floating_ring_io        : abstract_ring_io(multprec floating)
multprec_floating_ring-ffield    : field of multiprecision floating numbers
multprec_floating64_ring         : ring of multiprecision floating numbers
multprec_floating64_ring_io      : abstract_ring_io(multprec floating)
multprec_floating64_ring-ffield  : field of multiprecision floating numbers
multprec_complex_ring            : ring of multiprecision complex numbers
multprec_complex_ring_io         : abstract_ring_io(multprec complex)
multprec_complex64_ring          : ring of multiprecision complex numbers
multprec_complex64_ring_io       : abstract_ring_io(multprec complex)
------------------------------------------------------------------------------
standard_interval_numbers        : intervals of double_floats
standard_interval_numbers_io     : i/o for intervals of double_floats
standard_interval_ring           : ring of interval numbers
standard_interval_ring_io        : i/o ring of interval numbers
standard_interval_ring-ffield    : extension to field
------------------------------------------------------------------------------
numbers_io                       : user-friendly way of asking a number
standard_random_numbers          : generates random standard numbers
multprec_random_numbers          : generates random multiprecision numbers
standard_parse_numbers           : parsing characters on file into numbers
standard_write_numbers           : output of coefficients of polynomials
multprec_parse_numbers           : parsing into multiprecision numbers
multprec_write_numbers           : output of multiprecision coefficients
multprec_floating_constants      : multiprecision version of Pi
write_seed_number                : defines writing of the seed number
------------------------------------------------------------------------------
test_number_strings              : test parsing, writing number strings
test_natural_numbers             : test multiprecision natural numbers
test_integer_numbers             : test multiprecision integer numbers
test_floating_numbers            : test multiprecision floating numbers
test_complex_numbers             : test multiprecision complex numbers
test_random_numbers              : test random numbers
test_mathematical_functions      : test mathematical functions
------------------------------------------------------------------------------
ts_strnum                        : main test on number strings
ts_natnum                        : main test on multiprecision natural numbers
ts_intnum                        : main test on multiprecision integer numbers
ts_fltnum                        : main test on multiprecision floating numbers
ts_cmpnum                        : main test on multiprecision complex numbers
ts_plrexp                        : exponentiation via polar representation
ts_random                        : main test on random number generators
ts_matfun                        : main test on mathematical functions
ts_intval                        : test interval arithmetic
ts_mpcst                         : test multiprecision version of Pi
ts_numbio                        : reading of numbers with exception handling
ts_isnan                         : test how NaN is recognized
------------------------------------------------------------------------------

Natural numbers are seen as unsigned integer numbers and are also provided
with a "-" operation, although these operations do not always make sense.
The correct mathematically way is to define a monoid, but this would have
led to the definition of more vector packages.  Moreover, due to memory memory
limitations, rings do not exists in a computer, since it is always possible
to find two huge numbers for which the memory is insufficient to contain
their sum or product.  An Euclidean domain is defined as an extension of
the ring with order and division/remainder operations.  A field is a similar
extension of the ring with order and division operations.

The multiprecision packages are at the next-lowest level.
We first focus on how to implement the operations.  Afterwards
and independently, the interpretations/encapsulations are set up.

Single precision floating-point numbers are defined, but not elaborated
since they are not used anyway.  I recall that on an IBM RS/6000, adding
single precision floating-point numbers took longer than adding double
precision floating-point numbers.

The encapsulation of standard numerical types into packages seems a lot
of overkill, especially with the dummy procedures.
However, PHC has a now a uniform and clear treatment of numbers.

The standard complex numbers are somewhat hybrid: software-driven but still
constant cost.  Somehow this is an encouragement to use multiprecision,
but in a restricted fashion: with an extended, but limited fractional part.
In this new implementation, complex numbers are implemented by a generic
package, where the real number type has to be instantiated.
The complex numbers are first only presented in their Cartesian view
and adapted so that they fit in the generic_ring.field framework.

The test facilities include interactive little programs that allow to
test for special cases and tests on randomly generated numbers.
The "little" is only relative: we have 2000 lines of testing software.

The "abstract"-packages are new in Ada 95.  At a technical level, they are
used as formal parameters to shorten the list of generics to packages.
In the object-oriented methodology, they are abstract classes.
