
% Copyright (c) 1991-2002, The Numerical ALgorithms Group Ltd.
% All rights reserved.
%
% Redistribution and use in source and binary forms, with or without
% modification, are permitted provided that the following conditions are
% met:
%
%     - Redistributions of source code must retain the above copyright
%       notice, this list of conditions and the following disclaimer.
%
%     - Redistributions in binary form must reproduce the above copyright
%       notice, this list of conditions and the following disclaimer in
%       the documentation and/or other materials provided with the
%       distribution.
%
%     - Neither the name of The Numerical ALgorithms Group Ltd. nor the
%       names of its contributors may be used to endorse or promote products
%       derived from this software without specific prior written permission.
%
% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
% IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
% TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
% PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
% OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
% EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
% PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES-- LOSS OF USE, DATA, OR
% PROFITS-- OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
% LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
% NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
% SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


%
% FLOAT.htex

\Language{} provides two kinds of floating point numbers.
The domain \spadtype{Float} (abbreviation \spadtype{FLOAT})
implements a model of arbitrary
\index{floating point!arbitrary precision}
precision floating point numbers.
The domain \spadtype{DoubleFloat} (abbreviation \spadtype{DFLOAT})
is intended to make available
\index{floating point!hardware}
hardware floating point arithmetic in \Language{}.
\exptypeindex{DoubleFloat}
The actual model of floating point that \spadtype{DoubleFloat} provides is
system-dependent.
For example, on the IBM system 370 \Language{} 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.

For more information about \Language{}'s numeric and graphic
facilities,  see
\spadref{ugGraph},
\spadref{ugProblemNumeric}, and
\xmpref{DoubleFloat}.

% ********************************************************************
\head{subsection}{Introduction to Float}{ugxFloatIntro}
% ********************************************************************

Scientific notation is supported for input and output
\index{floating point!input}
of floating point numbers.
\index{scientific notation}
A floating point number is written as a string of digits containing a
decimal point optionally followed by the letter ``{\tt E}'', and then
the exponent.
\xtc{
We begin by doing some calculations using arbitrary precision floats.
The default precision is twenty decimal digits.
}{
\spadcommand{1.234}
}
\xtc{
A decimal base for the exponent is assumed, so the number
\spad{1.234E2}  denotes
\texht{$1.234 \cdot  10^2$}{\spad{1.234 * 10^2}}.
}{
\spadcommand{1.234E2}
}
\xtc{
The normal arithmetic operations are available for floating point
numbers.
}{
\spadcommand{sqrt(1.2 + 2.3 / 3.4 ^ 4.5)}
}

% ********************************************************************
\head{subsection}{Conversion Functions}{ugxFloatConvert}
% ********************************************************************

\xtc{
You can use conversion
(\spadref{ugTypesConvert})
to go back and forth between \spadtype{Integer}, \spadtype{Fraction Integer}
and \spadtype{Float}, as appropriate.
}{
\spadcommand{i := 3 :: Float \bound{i}}
}
\xtc{
}{
\spadcommand{i :: Integer \free{i}}
}
\xtc{
}{
\spadcommand{i :: Fraction Integer \free{i}}
}
\xtc{
Since you are explicitly asking for a conversion, you must take
responsibility for any loss of exactness.
}{
\spadcommand{r := 3/7 :: Float \bound{r}}
}
\xtc{
}{
\spadcommand{r :: Fraction Integer \free{r}}
}
\begin{inputonly}
)set message test off
\end{inputonly}
\xtc{
This conversion cannot be performed: use
\spadfunFrom{truncate}{Float} or \spadfunFrom{round}{Float} if that
is what you intend.
}{
\spadcommand{r :: Integer \free{r}}
}
\begin{inputonly}
)set message test on
\end{inputonly}

\xtc{
The operations \spadfunFrom{truncate}{Float} and \spadfunFrom{round}{Float}
truncate  \ldots
}{
\spadcommand{truncate 3.6}
}
\xtc{
and round
to the nearest integral \spadtype{Float} respectively.
}{
\spadcommand{round 3.6}
}
\xtc{
}{
\spadcommand{truncate(-3.6)}
}
\xtc{
}{
\spadcommand{round(-3.6)}
}
\xtc{
The operation \spadfunFrom{fractionPart}{Float} computes the fractional part of
\spad{x}, that is, \spad{x - truncate x}.
}{
\spadcommand{fractionPart 3.6}
}
\xtc{
The operation \spadfunFrom{digits}{Float} allows the user to set the
precision.
It returns the previous value it was using.
}{
\spadcommand{digits 40 \bound{d40}}
}
\xtc{
}{
\spadcommand{sqrt 0.2}
}
\xtc{
}{
\spadcommand{pi()\$Float \free{d40}}
}
\xtc{
The precision is only limited by the computer memory available.
Calculations at 500 or more digits of precision are not difficult.
}{
\spadcommand{digits 500 \bound{d1000}}
}
\xtc{
}{
\spadcommand{pi()\$Float \free{d1000}}
}
\xtc{
Reset \spadfunFrom{digits}{Float} to its default value.
}{
\spadcommand{digits 20}
}
Numbers of type \spadtype{Float} are represented as a record of two
integers, namely, the mantissa and the exponent where the base of the
exponent is binary.
That is, the floating point number \spad{(m,e)} represents the number
\texht{$m \cdot 2^e$}{\spad{m * 2^e}}.
A consequence of using a binary base is that decimal numbers can not, in
general, be represented exactly.

% ********************************************************************
\head{subsection}{Output Functions}{ugxFloatOutput}
% ********************************************************************

A number of operations exist for specifying how numbers of type \spadtype{Float} are to be
\index{floating point!output}
displayed.
By default, spaces are inserted every ten digits in the
output for readability.\footnote{Note that you cannot include spaces
in the input form of a floating point number, though you can use
underscores.}

\xtc{
Output spacing can be modified with the \spadfunFrom{outputSpacing}{Float}
operation.
This inserts no spaces and then displays the value of \spad{x}.
}{
\spadcommand{outputSpacing 0; x := sqrt 0.2 \bound{x}\bound{os0}}
}
\xtc{
Issue this to have the spaces inserted every \spad{5} digits.
}{
\spadcommand{outputSpacing 5; x \bound{os5}\free{x}}
}
\xtc{
By default, the system displays floats in either fixed format
or scientific format, depending on the magnitude of the number.
}{
\spadcommand{y := x/10^10 \bound{y}\free{x os5}}
}
\xtc{
A particular format may be requested with the operations
\spadfunFrom{outputFloating}{Float} and \spadfunFrom{outputFixed}{Float}.
}{
\spadcommand{outputFloating(); x \bound{of} \free{os5 x}}
}
\xtc{
}{
\spadcommand{outputFixed(); y \bound{ox} \free{os5 y}}
}
\xtc{
Additionally, you can ask for \spad{n} digits to be displayed after the
decimal point.
}{
\spadcommand{outputFloating 2; y \bound{of2} \free{os5 y}}
}
\xtc{
}{
\spadcommand{outputFixed 2; x \bound{ox2} \free{os5 x}}
}
\xtc{
This resets the output printing to the default behavior.
}{
\spadcommand{outputGeneral()}
}
%

% ********************************************************************
\head{subsection}{An Example: Determinant of a Hilbert Matrix}{ugxFloatHilbert}
% ********************************************************************

Consider the problem of computing the determinant of a \spad{10} by \spad{10}
\index{Hilbert matrix}
Hilbert matrix.
The \eth{(i,j)} entry of a Hilbert matrix is given by
\spad{1/(i+j+1)}.

\xtc{
First do the computation using rational numbers to obtain the
exact result.
}{
\spadcommand{a: Matrix Fraction Integer := matrix [[1/(i+j+1) for j in 0..9] for i in 0..9] \bound{a}}
}
\xtc{
This version of \spadfunFrom{determinant}{Matrix} uses Gaussian
elimination.
}{
\spadcommand{d:= determinant a \free{a}\bound{d}}
}
\xtc{
}{
\spadcommand{d :: Float \free{d}}
}
\xtc{
Now use hardware floats. Note that a semicolon (;) is used
to prevent the display of the matrix.
}{
\spadcommand{b: Matrix DoubleFloat := matrix [[1/(i+j+1\$DoubleFloat) for j in 0..9] for i in 0..9]; \bound{b}}
}
\xtc{
The result given by hardware floats is correct only to four significant
digits of precision.
In the jargon of numerical analysis, the Hilbert matrix is said to be
``ill-conditioned.''
\index{matrix!ill-conditioned}
}{
\spadcommand{determinant b \free{b}}
}
\xtc{
Now repeat the computation at a higher precision using \spadtype{Float}.
}{
\spadcommand{digits 40 \bound{d40}}
}
\xtc{
}{
\spadcommand{c: Matrix Float := matrix [[1/(i+j+1\$Float) for j in 0..9] for i in 0..9]; \free{d40} \bound{c}}
}
\xtc{
}{
\spadcommand{determinant c \free{c}}
}
\xtc{
Reset \spadfunFrom{digits}{Float} to its default value.
}{
\spadcommand{digits 20}
}
