GAP (ref) - Chapter 19: Floats

Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 Bib Ind
[Top of Book] [Contents] [Previous Chapter] [Next Chapter]

[MathJax off]

19 Floats
19.1 A sample run
19.2 Methods
19.2-1 Float creators
19.2-2 Rat
19.2-3 Cyc
19.2-4 SetFloats
19.2-5 FLOAT
19.2-6 EqFloat
19.2-7 PrecisionFloat
19.2-8 SignBit
19.2-9 SinCos
19.2-10 Atan2
19.2-11 Log1p
19.2-12 Erf
19.2-13 Infinity testers
19.2-14 Standard mathematical operations
19.3 High-precision-specific methods
19.4 Complex arithmetic
19.4-1 Argument
19.5 Interval-specific methods
19.5-1 Sup
19.5-2 Inf
19.5-3 Mid
19.5-4 AbsoluteDiameter
19.5-5 RelativeDiameter
19.5-6 IsDisjoint
19.5-7 IsSubset
19.5-8 IncreaseInterval
19.5-9 BlowupInterval
19.5-10 BisectInterval

### 19 Floats

Starting with version 4.5, GAP has built-in support for floating-point numbers in machine format, and allows package to implement arbitrary-precision floating-point arithmetic in a uniform manner. For now, one such package, Float exists, and is based on the arbitrary-precision routines in mpfr.

A word of caution: GAP deals primarily with algebraic objects, which can be represented exactly in a computer. Numerical imprecision means that floating-point numbers do not form a ring in the strict GAP sense, because addition is in general not associative (`(1.0e-100+1.0)-1.0` is not the same as `1.0e-100+(1.0-1.0)`, in the default precision setting).

Most algorithms in GAP which require ring elements will therefore not be applicable to floating-point elements. In some cases, such a notion would not even make any sense (what is the greatest common divisor of two floating-point numbers?)

#### 19.1 A sample run

Floating-point numbers can be input into GAP in the standard floating-point notation:

    gap> 3.14;
    3.14
    gap> last^2/6;
    1.64327
    gap> h := 6.62606896e-34;
    6.62607e-34
    gap> pi := 4*Atan(1.0);
    3.14159
    gap> hbar := h/(2*pi);
    1.05457e-34

Floating-point numbers can also be created using `Float`, from strings or rational numbers; and can be converted back using `String,Rat,Int`.

GAP allows rational and floating-point numbers to be mixed in the elementary operations `+,-,*,/`. However, floating-point numbers and rational numbers may not be compared. Conversions are performed using the creator `Float`:

    gap> Float("3.1416");
    3.1416
    gap> Float(355/113);
    3.14159
    gap> Rat(last);
    355/113
    gap> Rat(0.33333);
    1/3
    gap> Int(1.e10);
    10000000000
    gap> Int(1.e20);
    100000000000000000000
    gap> Int(1.e30);
    1000000000000000019884624838656

#### 19.2 Methods

Floating-point numbers may be directly input, as in any usual mathematical software or language; with the exception that every floating-point number must contain a decimal digit. Therefore `.1`, `.1e1`, `-.999` etc. are all valid GAP inputs.

Floating-point numbers so entered in GAP are stored as strings. They are converted to floating-point when they are first used. This means that, if the floating-point precision is increased, the constants are reevaluated to fit the new format.

Floating-point numbers may be followed by an underscore, as in `1._`. This means that they are to be immediately converted to the current floating-point format. The underscore may be followed by a single letter, which specifies which format/precision to use. By default, GAP has a single floating-point handler, with fixed (53 bits) precision, and its format specifier is `'l'` as in `1._l`. Higher-precision floating-point computations is available via external packages; float for example.

A record, `FLOAT` (19.2-5), contains all relevant constants for the current floating-point format; see its documentation for details. Typical fields are `FLOAT.MANT_DIG=53`, the constant `FLOAT.VIEW_DIG=6` specifying the number of digits to view, and `FLOAT.PI` for the constant \(\pi\). The constants have the same name as their C counterparts, except for the missing initial `DBL_` or `M_`.

Floating-point numbers may be created using the single function `Float` (19.2-1), which accepts as arguments rational, string, or floating-point numbers. Floating-point numbers may also be created, in any floating-point representation, using `NewFloat` (19.2-1) as in `NewFloat(IsIEEE754FloatRep,355/113)`, by supplying the category filter of the desired new floating-point number; or using `MakeFloat` (19.2-1) as in `MakeFloat(1.0,355/113)`, by supplying a sample floating-point number.

Floating-point numbers may also be converted to other GAP formats using the usual commands `Int` (14.2-3), `Rat` (17.2-6), `String` (27.7-6).

Exact conversion to and from floating-point format may be done using external representations. The "external representation" of a floating-point number `x` is a pair `[m,e]` of integers, such that `x=m*2^(-1+e-LogInt(AbsInt(m),2))`. Conversion to and from external representation is performed as usual using `ExtRepOfObj` (79.8-1) and `ObjByExtRep` (79.8-1):

    gap> ExtRepOfObj(3.14);
    [ 7070651414971679, 2 ]
    gap> ObjByExtRep(IEEE754FloatsFamily,last);
    3.14

Computations with floating-point numbers never raise any error. Division by zero is allowed, and produces a signed infinity. Illegal operations, such as `0./0.`, produce `NaN`'s (not-a-number); this is the only floating-point number `x` such that `not EqFloat(x+0.0,x)`.

The IEEE754 standard requires `NaN` to be non-equal to itself. On the other hand, GAP requires every object to be equal to itself. To respect the IEEE754 standard, the function `EqFloat` (19.2-6) should be used instead of `=`.

The category a floating-point belongs to can be checked using the filters `IsFinite` (30.4-2), `IsPInfinity` (19.2-13), `IsNInfinity` (19.2-13), `IsXInfinity` (19.2-13), `IsNaN` (19.2-13).

Comparisons between floating-point numbers and rationals are explicitly forbidden. The rationale is that objects belonging to different families should in general not be comparable in GAP. Floating-point numbers are also approximations of real numbers, and don't follow the same rules; consider for example, using the default GAP implementation of floating-point numbers,

    gap> 1.0/3.0 = Float(1/3);
    true
    gap> (1.0/3.0)^5 = Float((1/3)^5);
    false

##### 19.2-1 Float creators

`‣ Float`( obj ) | ( function )

`‣ NewFloat`( filter, obj ) | ( constructor )

`‣ MakeFloat`( sample, obj, obj ) | ( operation )

Returns: A new floating-point number, based on obj

This function creates a new floating-point number.

If obj is a rational number, the created number is created with sufficient precision so that the number can (usually) be converted back to the original number (see `Rat` (Reference: Rat) and `Rat` (17.2-6)). For an integer, the precision, if unspecified, is chosen sufficient so that `Int(Float(obj))=obj` always holds, but at least 64 bits.

obj may also be a string, which may be of the form `"3.14e0"` or `".314e1"` or `".314@1"` etc.

An option may be passed to specify, it bits, a desired precision. The format is `Float("3.14":PrecisionFloat:=1000)` to create a 1000-bit approximation of \(3.14\).

In particular, if obj is already a floating-point number, then `Float(obj:PrecisionFloat:=prec)` creates a copy of obj with a new precision. prec

##### 19.2-2 Rat

`‣ Rat`( f ) | ( attribute )

Returns: A rational approximation to f

This command constructs a rational approximation to the floating-point number f. Of course, it is not guaranteed to return the original rational number f was created from, though it returns the most `reasonable' one given the precision of f.

Two options control the precision of the rational approximation: In the form `Rat(f:maxdenom:=md,maxpartial:=mp)`, the rational returned is such that the denominator is at most md and the partials in its continued fraction expansion are at most mp. The default values are `maxpartial:=10000` and `maxdenom:=2^(precision/2)`.

##### 19.2-3 Cyc

`‣ Cyc`( f[, degree] ) | ( operation )

Returns: A cyclotomic approximation to f

This command constructs a cyclotomic approximation to the floating-point number f. Of course, it is not guaranteed to return the original rational number f was created from, though it returns the most `reasonable' one given the precision of f. An optional argument degree specifies the maximal degree of the cyclotomic to be constructed.

The method used is LLL lattice reduction.

##### 19.2-4 SetFloats

`‣ SetFloats`( rec[, bits][, install] ) | ( function )

Installs a new interface to floating-point numbers in GAP, optionally with a desired precision bits in binary digits. The last optional argument install is a boolean value; if false, it only installs the eager handler and the precision for the floateans, without making them the default.

##### 19.2-5 FLOAT

`‣ FLOAT` | ( global variable )

This record contains useful floating-point constants:

DECIMAL_DIG

  Maximal number of useful digits;

DIG

  Number of significant digits;

VIEW_DIG

  Number of digits to print in short view;

EPSILON

  Smallest number such that \(1\neq1+\epsilon\);

MANT_DIG

  Number of bits in the mantissa;

MAX

  Maximal representable number;

MAX_10_EXP

  Maximal decimal exponent;

MAX_EXP

  Maximal binary exponent;

MIN

  Minimal positive representable number;

MIN_10_EXP

  Minimal decimal exponent;

MIN_EXP

  Minimal exponent;

INFINITY

  Positive infinity;

NINFINITY

  Negative infinity;

NAN

  Not-a-number,

as well as mathematical constants `E`, `LOG2E`, `LOG10E`, `LN2`, `LN10`, `PI`, `PI_2`, `PI_4`, `1_PI`, `2_PI`, `2_SQRTPI`, `SQRT2`, `SQRT1_2`.

##### 19.2-6 EqFloat

`‣ EqFloat`( x, y ) | ( operation )

Returns: Whether the floateans x and y are equal

This function compares two floating-point numbers, and returns `true` if they are equal, and `false` otherwise; with the exception that `NaN` is always considered to be different from itself.

##### 19.2-7 PrecisionFloat

`‣ PrecisionFloat`( x ) | ( attribute )

Returns: The precision of x

This function returns the precision, counted in number of binary digits, of the floating-point number x.

##### 19.2-8 SignBit

`‣ SignBit`( x ) | ( attribute )

`‣ SignFloat`( x ) | ( attribute )

Returns: The sign of x.

The first function `SignBit` returns the sign bit of the floating-point number x: `true` if x is negative (including `-0.`) and `false` otherwise.

The second function `SignFloat` returns the integer `-1` if x<0, `0` if x=0 and `1` if x>0.

##### 19.2-9 SinCos

`‣ SinCos`( x ) | ( attribute )

Returns: The list `[sin(x), cos(x)]`.

The function returns a list with `sin` and `cos` of x.

##### 19.2-10 Atan2

`‣ Atan2`( y, x ) | ( operation )

Returns: The polar angle of (x, y) in the plane as float.

Returns the principal value of the argument (polar angle) of \((\textit{x}, \textit{y})\) in the plane. The returned value will always be in \((-\pi , \pi]\) and is not defined on \((0,0)\). This function is defined in accordance with IEEE 1788-2015 and imported from IEEE 754.

##### 19.2-11 Log1p

`‣ Log1p`( x ) | ( attribute )

`‣ Expm1`( x ) | ( attribute )

Returns: The natural logarithm of \(\textit{x}+1\) or exponential \(-1\) of x respectively.

The first function `Log1p` returns the natural logarithm \(log(\textit{x}+1)\).

The second function `Expm1` returns the exponential function \(exp(\textit{x})-1\)

These two functions are inverse to each other.

##### 19.2-12 Erf

`‣ Erf`( x ) | ( operation )

Returns: The error function given by the Gaussian integral

Returns the error function imported from IEEE 754 given by the formula:

\[ Erf(x) := \frac{2}{\sqrt{\pi}} \int_{0}^{x} exp(- t^2 ) dt \]

##### 19.2-13 Infinity testers

`‣ IsPInfinity`( x ) | ( property )

`‣ IsNInfinity`( x ) | ( property )

`‣ IsXInfinity`( x ) | ( property )

`‣ IsFinite`( x ) | ( property )

`‣ IsNaN`( x ) | ( property )

Returns `true` if the floating-point number x is respectively \(+\infty\), \(-\infty\), \(\pm\infty\), finite, or `not a number', such as the result of `0.0/0.0`.

##### 19.2-14 Standard mathematical operations

`‣ Sin`( f ) | ( attribute )

`‣ Cos`( f ) | ( attribute )

`‣ Tan`( f ) | ( attribute )

`‣ Sec`( f ) | ( attribute )

`‣ Csc`( f ) | ( attribute )

`‣ Cot`( f ) | ( attribute )

`‣ Asin`( f ) | ( attribute )

`‣ Acos`( f ) | ( attribute )

`‣ Atan`( f ) | ( attribute )

`‣ Sinh`( f ) | ( attribute )

`‣ Cosh`( f ) | ( attribute )

`‣ Tanh`( f ) | ( attribute )

`‣ Sech`( f ) | ( attribute )

`‣ Csch`( f ) | ( attribute )

`‣ Coth`( f ) | ( attribute )

`‣ Asinh`( f ) | ( attribute )

`‣ Acosh`( f ) | ( attribute )

`‣ Atanh`( f ) | ( attribute )

`‣ Log`( f ) | ( operation )

`‣ Log2`( f ) | ( attribute )

`‣ Log10`( f ) | ( attribute )

`‣ Exp`( f ) | ( attribute )

`‣ Exp2`( f ) | ( attribute )

`‣ Exp10`( f ) | ( attribute )

`‣ CubeRoot`( f ) | ( attribute )

`‣ Square`( f ) | ( attribute )

`‣ Hypothenuse`( x, y ) | ( operation )

`‣ Ceil`( f ) | ( attribute )

`‣ Floor`( f ) | ( attribute )

`‣ Round`( f ) | ( attribute )

`‣ Trunc`( f ) | ( attribute )

`‣ FrExp`( f ) | ( attribute )

`‣ LdExp`( f, exp ) | ( operation )

`‣ AbsoluteValue`( f ) | ( attribute )

`‣ Norm`( f ) | ( attribute )

`‣ Frac`( f ) | ( attribute )

`‣ Zeta`( f ) | ( attribute )

`‣ Gamma`( f ) | ( attribute )

Standard math functions. Functions ending in an integer like `Log2`, `Log10`, `Exp2` and `Exp10` indicate the base used, in `log` and `exp` the natural base is used, i.e. \(e\).

#### 19.3 High-precision-specific methods

GAP provides a mechanism for packages to implement new floating-point numerical interfaces. The following describes that mechanism, actual examples of packages are documented separately.

A package must create a record with fields (all optional)

creator

  a function converting strings to floating-point;

eager

  a character allowing immediate conversion to floating-point;

objbyextrep

  a function creating a floating-point number out of a list `[mantissa,exponent]`;

filter

  a filter for the new floating-point objects;

constants

  a record containing numerical constants, such as `MANT_DIG`, `MAX`, `MIN`, `NAN`.

The package must install methods `Int`, `Rat`, `String` for its objects, and creators `NewFloat(filter,IsRat)`, `NewFloat(IsString)`.

It must then install methods for all arithmetic and numerical operations: `SUM`, `Exp`, ...

The user chooses that implementation by calling `SetFloats` (19.2-4) with the record as argument, and with an optional second argument requesting a precision in binary digits.

#### 19.4 Complex arithmetic

Complex arithmetic may be implemented in packages, and is present in float. Complex numbers are treated as usual numbers; they may be input with an extra "i" as in `-0.5+0.866i`. They may also be created using `NewFloat` (19.2-1) with three arguments: the float filter, the real part, and the imaginary part.

Methods should then be implemented for `Norm`, `RealPart`, `ImaginaryPart`, `ComplexConjugate`, ...

##### 19.4-1 Argument

`‣ Argument`( z ) | ( attribute )

Returns the argument of the complex number z, namely the value `Atan2(ImaginaryPart(z),RealPart(z))`.

#### 19.5 Interval-specific methods

Interval arithmetic may also be implemented in packages. Intervals are in fact efficient implementations of sets of real numbers. The only non-trivial issue is how they should be compared. The standard `EQ` tests if the intervals are equal; however, it is usually more useful to know if intervals overlap, or are disjoint, or are contained in each other.

Note the usual convention that intervals are compared as in \([a,b]\leq[c,d]\) if and only if \(a\leq c\) and \(b\leq d\).

##### 19.5-1 Sup

`‣ Sup`( x ) | ( attribute )

Returns the supremum of the interval x.

##### 19.5-2 Inf

`‣ Inf`( x ) | ( attribute )

Returns the infimum of the interval x.

##### 19.5-3 Mid

`‣ Mid`( x ) | ( attribute )

Returns the midpoint of the interval x.

##### 19.5-4 AbsoluteDiameter

`‣ AbsoluteDiameter`( x ) | ( attribute )

`‣ Diameter`( x ) | ( operation )

Returns the absolute diameter of the interval x, namely the difference `Sup(x)-Inf(x)`.

##### 19.5-5 RelativeDiameter

`‣ RelativeDiameter`( x ) | ( attribute )

Returns the relative diameter of the interval x, namely `(Sup(x)-Inf(x))/AbsoluteValue(Min(x))`.

##### 19.5-6 IsDisjoint

`‣ IsDisjoint`( x1, x2 ) | ( operation )

Returns `true` if the two intervals x1, x2 are disjoint.

##### 19.5-7 IsSubset

`‣ IsSubset`( x1, x2 ) | ( operation )

Returns `true` if the interval x1 contains x2.

##### 19.5-8 IncreaseInterval

`‣ IncreaseInterval`( x, delta ) | ( operation )

Returns an interval with same midpoint as x but absolute diameter increased by delta.

##### 19.5-9 BlowupInterval

`‣ BlowupInterval`( x, ratio ) | ( operation )

Returns an interval with same midpoint as x but relative diameter increased by ratio.

##### 19.5-10 BisectInterval

`‣ BisectInterval`( x ) | ( operation )

Returns a list of two intervals whose union equals the interval x.

[Top of Book] [Contents] [Previous Chapter] [Next Chapter]
Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 Bib Ind

generated by GAPDoc2HTML