====================================================================
DoubleFloat examples
====================================================================

Axiom provides two kinds of floating point numbers.  The domain Float
(abbreviation FLOAT) implements a model of arbitrary precision
floating point numbers.  The domain DoubleFloat (abbreviation DFLOAT)
is intended to make available hardware floating point arithmetic in
Axiom.  The actual model of floating point DoubleFloat that provides
is system-dependent.  For example, on the IBM system 370 Axiom uses
IBM double precision which has fourteen hexadecimal digits of
precision or roughly sixteen decimal digits.  Arbitrary precision
floats allow the user to specify the precision at which arithmetic
operations are computed.  Although this is an attractive facility, it
comes at a cost. Arbitrary-precision floating-point arithmetic
typically takes twenty to two hundred times more time than hardware
floating point.

The usual arithmetic and elementary functions are available for
DoubleFloat.  By default, floating point numbers that you enter into
Axiom are of type Float.

  2.71828
   2.71828 
                      Type: Float

You must therefore tell Axiom that you want to use DoubleFloat values
and operations.  The following are some conservative guidelines for
getting Axiom to use DoubleFloat.

To get a value of type DoubleFloat, use a target with @, ...

  2.71828@DoubleFloat
   2.71828 
                      Type: DoubleFloat

a conversion, ...

  2.71828 :: DoubleFloat
   2.71828 
                      Type: DoubleFloat

or an assignment to a declared variable.  It is more efficient if you
use a target rather than an explicit or implicit conversion.

  eApprox : DoubleFloat := 2.71828
   2.71828 
                      Type: DoubleFloat

You also need to declare functions that work with DoubleFloat.

  avg : List DoubleFloat -> DoubleFloat
                      Type: Void

  avg l ==
    empty? l => 0 :: DoubleFloat
    reduce(_+,l) / #l
                      Type: Void

  avg []
   0.
                      Type: DoubleFloat

  avg [3.4,9.7,-6.8]
   2.1000000000000001
                      Type: DoubleFloat

Use package-calling for operations from DoubleFloat unless the
arguments themselves are already of type DoubleFloat.

  cos(3.1415926)$DoubleFloat
   -0.99999999999999856
                      Type: DoubleFloat

  cos(3.1415926 :: DoubleFloat)
   -0.99999999999999856
                      Type: DoubleFloat

By far, the most common usage of DoubleFloat is for functions to be
graphed.

You can get the exact machine-specific bits of a DoubleFloat in two ways.
The first is to use the integerDecode function to break the DoubleFloat
into components.

  a := -1.0/3.0

    -0.33333333333333331

  integerDecode a

    [6004799503160661,- 54,- 1]

This is the mantissa, exact to 54 bits, the power of 2, and the sign.
Thus it is:

    6004799503160661 * 2^-54

You can get the same information as a fraction with 

   machineFraction a

     6004799503160661
  - -----------------
    18014398509481984

where the denominator 18014398509481984 is 2^54


See Also:
o )help Float
o )show DoubleFloat

