Class: QDouble

• Inheritance
• Description
• Related information
• Class protocol
  • coercing & converting
  • constants
  • instance creation
  • queries
• Instance protocol
  • arithmetic
  • coercing & converting
  • comparing
  • double dispatching
  • inspecting
  • mathematical functions
  • printing & storing
  • private accessing
  • testing
• Examples

Inheritance:

   Object
   |
   +--Magnitude
      |
      +--ArithmeticValue
         |
         +--Number
            |
            +--LimitedPrecisionReal
               |
               +--QDouble

Package:

stx:libbasic2

Category:

Magnitude-Numbers

Version:

rev: 1.45 date: 2019/07/19 15:29:05

user: cg

file: QDouble.st directory: libbasic2

module: stx stc-classLibrary: libbasic2

Author:

Claus Gittinger

Description:

ATTENTION: ongoing, unfinished work.
No warranty that this works correctly...

QDoubles represent rational numbers with extended, but still limited precision.

In contrast to Floats (which use the C-compiler's native 64bit 'double' format),
QDoubles give you roughly 200 bit or approx. 60 decimal digits of precision.

Representation:
    QDoubles use 4 IEEE doubles, each keeping 53 bits of precision.
    A qDouble's value is the sum of those 4 doubles,
    and a qDouble keeps this unevaluated sum as its state.
    (due to overlap, the final precision is less than 53*4)

Range and Precision of Storage Formats: see LimitedPrecisionReal >> documentation
the number of decmal digits:
    QDouble decimalPrecision
    LongFloat decimalPrecision
    Float decimalPrecision
    ShortFloat decimalPrecision

the number of bits:
    QDouble precision
    LongFloat precision
    Float precision
    ShortFloat precision

Notice:
    when assigning a converted double precision number as in:
        qd := 1.0 asQDouble.
    you still get only a regular double precision approximation to 0.1
    because the error is already inherit in the double.

    For a full precision constant, you (currently) need to convert from a string
    (because the compilers do not know about then, yet):
        qd := QDouble readFrom:'0.1'.

    To see the error of the double precision version, compute:
        (0.1 asQDouble) - (QDouble readFrom:'0.1')

Related information:

    Number
    Float
    ShortFloat
    LongFloat
    Fraction
    FixedPoint
    Integer
    Complex
    FloatArray
    DoubleArray

Class protocol:

 coerce: aNumber

convert the argument aNumber into an instance of the receiver's class and return it.

 NaN

return a QDouble which represents not-a-Number (i.e. an invalid number)

 e

return the constant e as quad precision double.
(returns approx. 200 bits of precision)

usage example(s):

self e

 fmax

return the constant e as quad precision double.
(returns approx. 200 bits of precision)

usage example(s):

Float fmax self fmax

 fmin

return the smallest representable instance of this class

usage example(s):

QDouble fmin Float fmin

 infinity

(comment from inherited method)
return an instance of myself which represents positive infinity (for my instances).
Warning: do not compare equal against infinities;
instead, check using isFinite or isInfinite

 invFact

table returning 1/n!
(for taylor series)

usage example(s):

1.0 / (3 factorial) 0.166666666666667 1 asQDouble / (3 factorial) - (self invFact at:1) 1 asQDouble / (4 factorial) - (self invFact at:2) 1 asQDouble / (5 factorial) - (self invFact at:3) 1 asQDouble / (6 factorial) - (self invFact at:4) 1 asQDouble / (7 factorial) - (self invFact at:5) 1 asQDouble / (8 factorial) - (self invFact at:6) 1 asQDouble / (9 factorial) - (self invFact at:7) 1 asQDouble / (10 factorial) - (self invFact at:8) 1 asQDouble / (11 factorial) - (self invFact at:9) 1 asQDouble / (12 factorial) - (self invFact at:10) 1 asQDouble / (13 factorial) - (self invFact at:11) 1 asQDouble / (14 factorial) - (self invFact at:12) 1 asQDouble / (15 factorial) - (self invFact at:13) 1 asQDouble / (16 factorial) - (self invFact at:14) 1 asQDouble / (17 factorial) - (self invFact at:15)

 ln10

return the constant e as quad precision double.
(returns approx. 200 bits of precision)

usage example(s):

self ln10

 ln2

return the constant e as quad precision double.
(returns approx. 200 bits of precision)

usage example(s):

self ln2

 negativeInfinity

(comment from inherited method)
return an instance of myself which represents negative infinity (for my instances).
Warning: do not compare equal against infinities;
instead, check using isFinite or isInfinite

 pi

return the constant pi as quad precision double.
(returns approx. 200 bits of precision)

usage example(s):

self pi

 unity

return the neutral element for multiplication (1.0) as QDouble

usage example(s):

self unity

 zero

return the neutral element for addition (0.0) as QDouble

usage example(s):

self zero

 basicNew

return a new quad-precision double - here we return 0.0
Notice that numbers are usually NOT created this way ...
It's implemented here to allow things like binary store & load
of floats. (but even this support will go away eventually, it's not
a good idea to store the bits of a float - the reader might have a
totally different representation - so floats should be
binary stored in a device independent format.

usage example(s):

self basicNew

 d0: d0 d1: d1 d2: d2 d3: d3

return a new quad-precision double from individual double components

usage example(s):

self d0: 3.141592653589793116e+00 d1: 1.224646799147353207e-16 d2: -2.994769809718339666e-33 d3: 1.112454220863365282e-49

 fromDoubleArray: aDoubleArray

return a new quad-precision double from coercing a double array

 fromFloat: aFloat

return a new quad-precision double from coercing aFloat

usage example(s):

self fromFloat:1.0

 fromInteger: anInteger

return a new quad-precision double from coercing anInteger

usage example(s):

self fromInteger:2 self fromInteger:16rFFFFFFFF -- 32bit 4294967295.0 self fromInteger:16rFFFFFFFFFFFF -- 48bit 281474976710655.0 self fromInteger:16rFFFFFFFFFFFFF -- 52bit 4503599627370495.0 self fromInteger:16rFFFFFFFFFFFFFF -- 56bit 72057594037927935.0 self fromInteger:16rFFFFFFFFFFFFFFF -- 60bit 1152921504606846975.0 self fromInteger:16r1FFFFFFFFFFFFFFF -- 61bit 2305843009213693951.0 self fromInteger:16r3FFFFFFFFFFFFFFF -- 62bit 4611686018427387903.0 self fromInteger:16r7FFFFFFFFFFFFFFF -- 63bit 9223372036854775807.0 self fromInteger:16rFFFFFFFFFFFFFFFF -- 64bit 18446744073709551615.0

 defaultPrintPrecision

return the number of decimal digits printed by default

usage example(s):

ShortFloat defaultPrintPrecision Float defaultPrintPrecision LongFloat defaultPrintPrecision QDouble defaultPrintPrecision

 epsilon

return the maximum relative spacing of instances of mySelf
(i.e. the value-delta of the least significant bit)

usage example(s):

Float epsilon -> 2.22044604925031E-16 ShortFloat epsilon -> 1.19209289550781E-07 LongFloat epsilon -> 1.0842021724855E-19 QDouble epsilon -> 1.21543267145725E-63

 numBitsInExponent

answer the number of bits in the exponent

usage example(s):

1.0 asQDouble numBitsInExponent

 numBitsInMantissa

answer the number of bits in the mantissa.
Here, a fake number is returned

usage example(s):

1.0 asFloat numBitsInMantissa 1.0 asShortFloat numBitsInMantissa 1.0 asLongFloat numBitsInMantissa 1.0 asQDouble numBitsInMantissa 1.0 asQDouble class numBitsInMantissa Float numBitsInMantissa ShortFloat numBitsInMantissa QDouble numBitsInMantissa

 precision

answer the number of bits in the mantissa

usage example(s):

1.0 class numBitsInMantissa 1.0 asShortFloat class numBitsInMantissa 1.0 asLongFloat class numBitsInMantissa 1.0 asQDouble class numBitsInMantissa Float numBitsInMantissa ShortFloat numBitsInMantissa QDouble numBitsInMantissa QDouble precision

 radix

answer the radix of a QDouble's exponent
This is an IEEE float, which is represented as binary

Instance protocol:

 * aNumber

return the product of the receiver and the argument, aNumber

usage example(s):

(((QDouble fromFloat:1e20) + (QDouble fromFloat:1.0)) * (QDouble fromFloat:2.0)) asDoubleArray

 + aNumber

return the sum of the receiver and the argument, aNumber

usage example(s):

((QDouble fromFloat:1e20) + (QDouble fromFloat:1.0)) asDoubleArray

 - aNumber

return the sum of the receiver and the argument, aNumber

usage example(s):

(QDouble fromFloat:1e20) asDoubleArray ((QDouble fromFloat:1e20) - (QDouble fromFloat:1.0)) asDoubleArray (QDouble fromFloat:1e-20) asDoubleArray ((QDouble fromFloat:1e-20) - (QDouble fromFloat:1.0)) asDoubleArray ((QDouble fromFloat:2.0) - (QDouble fromFloat:1.0)) asDoubleArray ((QDouble fromFloat:2.0) - (QDouble fromFloat:1.0) + (QDouble fromFloat:1.0)) asDoubleArray ((QDouble fromFloat:1e-20) - (QDouble fromFloat:1.0) + (QDouble fromFloat:1.0)) asDoubleArray

usage example(s):

Modified (comment): / 15-06-2017 / 00:34:41 / cg

 / aNumber

return the quotient of the receiver and the argument, aNumber

usage example(s):

((QDouble fromFloat:1e20) / (QDouble fromFloat:2.0)) asDoubleArray ((QDouble fromFloat:1.2345) / (QDouble fromFloat:10.0)) asDoubleArray ((QDouble fromFloat:1.2345) / 10.0) asDoubleArray

usage example(s):

Modified (comment): / 15-06-2017 / 00:14:26 / cg

 asDoubleArray

(QDouble fromFloat:1.0) asDoubleArray
(QDouble fromFloat:2.0) asDoubleArray

 asFloat

(QDouble fromFloat:1.0) asFloat
(QDouble fromFloat:2.0) asFloat

 asInteger

(comment from inherited method)
return an integer with same value - might truncate

 asQDouble

return a QDouble with same value as myself.

 asTrueFraction

1e10 asTrueFraction -> 10000000000
1e20 asTrueFraction -> 100000000000000000000
(1e20 + 1) asTrueFraction -> 100000000000000000000 ouch!

1e10 asQDouble asTrueFraction -> 10000000000
1e20 asQDouble asTrueFraction -> 100000000000000000000
(1e20 asQDouble + 1) asTrueFraction -> 100000000000000000001

(1e40 asQDouble + 1e20 + 1) asTrueFraction -> 10000000000000000303886028427003666890753
(1e40 asQDouble + 1e20) asTrueFraction

 coerce: aNumber

convert the argument aNumber into an instance of the receiver's class and return it.

 exponent

(comment from inherited method)
extract a normalized float's exponent.
This is a fallback for systems which do not provide frexp in their math lib,
als also for error reporting (NaN or Inf).
The returned value depends on the float-representation of
the underlying machine and is therefore highly unportable.
This is not for general use.
This assumes that the mantissa is normalized to
0.5 .. 1.0 and the float's value is mantissa * 2^exp

 generality

return the generality value - see ArithmeticValue>>retry:coercing:

 negative

(QDouble fromFloat:0.0) negative
(QDouble fromFloat:1.0) negative
(QDouble fromFloat:-1.0) negative

 positive

return true, if the receiver is greater or equal to zero (not negative)

usage example(s):

(QDouble fromFloat:1.0) positive (QDouble fromFloat:-1.0) positive

 < aNumber

return true, if the argument, aNumber is greater than the receiver

 = aNumber

return true, if the argument, aNumber has the same value as than the receiver

 differenceFromFloat: aFloat

aFloat - self

 differenceFromQDouble: aQDouble

aQDouble - self

 equalFromQDouble: aQDouble

(QDouble fromFloat:1.0) = (QDouble fromFloat:1.0)
(QDouble fromFloat:1.0) = 1.0
1.0 = (QDouble fromFloat:1.0)

 lessFromQDouble: aQDouble

sent when aQDouble does not know how to compare to the receiver..
Return true if aQDouble < self

 productFromFloat: aFloat

loosing bits here:

(1e20+1.0)*2.0
(1e20+1.0)*1e20
(1e40+1.0)*2.0

but not here:

(1.0 asQDouble) * 2.0
((1e20 asQDouble) + (1.0)) * 2.0
((1e20 asQDouble) + (1.0)) * 100.0 10000000000000000000100.0
((1e20 asQDouble) + (1.0)) * 1000.0
((1e40 asQDouble) + (1.0)) * 2.0

2.0 * (QDouble fromFloat:1.0)
2.0 * (QDouble fromFloat:3.0)
(QDouble fromFloat:2.0) * (QDouble fromFloat:3.0)

QDouble ln2 DoubleArray(0.693147180559945 2.3190468138463E-17 5.70770843841621E-34 -3.58243221060181E-50)
2.0 * QDouble ln2 DoubleArray(1.38629436111989 4.6380936276926E-17 1.14154168768324E-33 -7.16486442120362E-50)
QDouble ln2 * 2.0

2.0 * ((QDouble fromFloat:1e20) + (QDouble fromFloat:1.0)) DoubleArray(2E+20 2.0 0.0 0.0)
((QDouble fromFloat:1e20) + (QDouble fromFloat:1.0)) * 2.0 DoubleArray(2E+20 4E+20 0.0 0.0)
((QDouble fromFloat:1e20) + (QDouble fromFloat:1.0)) * (QDouble fromFloat:2.0) DoubleArray(2E+20 4E+20 0.0 0.0)
(QDouble fromFloat:2.0) * ((QDouble fromFloat:1e20) + (QDouble fromFloat:1.0)) DoubleArray(2E+20 4E+20 0.0 0.0)

(2.0 * ((QDouble fromFloat:1e20) + (QDouble fromFloat:1.0))) - (QDouble fromFloat:1e20) - (QDouble fromFloat:1e20)

(2.0 * (QDouble fromFloat:1.0)) asFloat
(1e20 * (QDouble fromFloat:1.0)) asFloat

(1e20 * (QDouble fromFloat:1.0) * 1e-20) asDoubleArray

 productFromQDouble: aQDouble

(QDouble fromFloat:1.0) * 2.0
2.0 * (QDouble fromFloat:1.0)
(QDouble fromFloat:1.0) * (QDouble fromFloat:2.0)

1e20 * (QDouble fromFloat:1.0)
(2.0 * (QDouble fromFloat:1.0)) asFloat
(1e20 * (QDouble fromFloat:1.0)) asFloat

(1e20 * (QDouble fromFloat:1.0) * 1e-20) asDoubleArray

( ((QDouble fromFloat:1.0) + (QDouble fromFloat:1e20)) * (QDouble fromFloat:2.0)) asDoubleArray

 quotientFromQDouble: aQDouble

sloppy

usage example(s):

2.0 / (QDouble fromFloat:2.0) 2.0 / (QDouble fromFloat:1.0) 1e20 / (QDouble fromFloat:1.0) (2.0 / (QDouble fromFloat:1.0)) asFloat (1e20 / (QDouble fromFloat:1.0)) asFloat (QDouble fromFloat:2.0) / 2.0 (QDouble fromFloat:1e20) / 2.0 ((QDouble fromFloat:1.0) / 2.0) asFloat ((QDouble fromFloat:1e20 / 2.0)) asFloat ((1e20 + (QDouble fromFloat:1.0) + 1e-20) / 2.0) asDoubleArray ((QDouble fromFloat:10.0) quotientFromQDouble: (QDouble fromFloat:1.234)) asDoubleArray ((QDouble fromFloat:1.234) / (QDouble fromFloat:10.0)) asDoubleArray q0: 1.234000e-01 (a[0]=1.234000e+00; b[0]=1.000000e+01) a: 1.234000e+00/0.000000e+00/0.000000e+00/0.000000e+00 b: 1.000000e+01/0.000000e+00/0.000000e+00/0.000000e+00 (b * q0): 1.234000e+00/-2.775558e-17/0.000000e+00/0.000000e+00 r: 2.775558e-17/0.000000e+00/0.000000e+00/0.000000e+00 q1: 2.775558e-18 (r[0]=2.775558e-17; b[0]=1.000000e+01) r: -1.540744e-33/0.000000e+00/0.000000e+00/0.000000e+00 q2: -1.540744e-34 (r[0]=-1.540744e-33; b[0]=1.000000e+01) r: 8.552847e-50/0.000000e+00/0.000000e+00/0.000000e+00 q3: 8.552847e-51 (r[0]=8.552847e-50; b[0]=1.000000e+01) before renorm: 1.234000e-01/2.775558e-18/-1.540744e-34/8.552847e-51 after renorm: 1.234000e-01/2.775558e-18/-1.540744e-34/8.552847e-51 1.234/10.0 is: 0.123400 / 0.000000 / -0.000000 / 0.000000

 sumFromFloat: aFloat

1.0 + (QDouble fromFloat:1.0)
1e20 + (QDouble fromFloat:1.0)
(1.0 + (QDouble fromFloat:1.0)) asFloat
(1e20 + (QDouble fromFloat:1.0)) asFloat

(1.0 + (QDouble fromFloat:1.0)) asDoubleArray
(1e20 + (QDouble fromFloat:1.0)) asDoubleArray
(1e20 + (QDouble fromFloat:1.0) + 1e-20) asDoubleArray

 sumFromInteger: anInteger

1 + (QDouble fromFloat:1.0)
1e20 asInteger + (QDouble fromFloat:1.0)
(1 + (QDouble fromFloat:1.0)) asFloat
(1e20 asInteger + (QDouble fromFloat:1.0)) asFloat

 sumFromQDouble: aQDouble

(QDouble fromFloat:1.0) + (QDouble fromFloat:1.0)
(QDouble fromFloat:1.0) + 1.0
1.0 + (QDouble fromFloat:1.0)

((QDouble fromFloat:1.0) + (QDouble fromFloat:1.0)) asDoubleArray
((QDouble fromFloat:1.0) + 1.0) asDoubleArray
(1.0 + (QDouble fromFloat:1.0)) asDoubleArray
(1e-20 + (QDouble fromFloat:1.0)) asDoubleArray
(1e20 + (QDouble fromFloat:1.0)) asDoubleArray

 inspectorExtraAttributes

extra (pseudo instvar) entries to be shown in an inspector.

 exp

the exp_sloppy code is the algorithm from the original C++ qd package;

usage example(s):

2.0 exp -> 7.38905609893065 2.0 asQDouble exp -> 7.38905609893065022723 2 asQDouble exp printfPrintString:'%70.68f' -> 7.389056098930650227230427460575007813180315570551847324087127822432669 actual result: -> 7.3890560989306502272304274605750078131803155705518473240871278225225737960790577633843124850791217947737531612654...

 exp_sloppy

this is the algorithm from the qd C++ package;

 exp_withAccuracy: epsilon

compute e^x of the receiver using a taylor series approximation.
This method is only invoked for limitedPrecisionReal classes, which do not compute
exp themself (i.e. QDouble)

 floor

return the receiver truncated towards negative infinity

usage example(s):

(QDouble fromFloat:4.0) floor (QDouble fromFloat:4.1) floor (QDouble fromFloat:0.1) floor (0.1 + (QDouble fromFloat:1.0)) floor (1e20 + (QDouble fromFloat:1.0)) floor (QDouble fromFloat:1.5) floor (QDouble fromFloat:0.5) floor (QDouble fromFloat:-0.5) floor (QDouble fromFloat:-1.5) floor

 floor2

return the receiver truncated towards negative infinity

 ln

return the natural logarithm of myself.
Raises an exception, if the receiver is less or equal to zero.

Not sure if this is really faster than using a taylor right away:
the three exp-computations at the end are done in qDouble and are tailors themself...

usage example(s):

-1 ln -1.0 asQDouble ln 0.0 asQDouble ln 1.0 asQDouble ln 3.0 ln printfPrintString:'%60.58lf' -> 1.0986122886681097821082175869378261268138885498046875000000' ^ 3.0 asQDouble ln printfPrintString:'%60.58f' -> 1.0986122886681096913952452369225257046474905578227494517347 3.0 asQDouble ln printfPrintString:'%70.68f' -> 1.09861228866810969139524523692252570464749055782274945173469433364779 (3.0 asQDouble ln_withAccuracy:1e-64) printfPrintString:'%70.68f' 1.09861228866810969139524523692252570464749055782274945173469433364475 (3.0 asQDouble ln_withAccuracy:1e-100) printfPrintString:'%70.68f' '1.098612288668109691395245236922525704647490557822749451734694333656909' actual result: -> 1.0986122886681096913952452369225257046474905578227494517346943336374942932186089668736157548137320887879700290659...

 negated

(QDouble fromFloat:1.0) negated
((QDouble fromFloat:1e20) + (QDouble fromFloat:1.0)) negated asDoubleArray

(((QDouble fromFloat:1e20) + (QDouble fromFloat:1.0))
+ ((QDouble fromFloat:1e20) + (QDouble fromFloat:1.0))) asDoubleArray

 sqrt

Return the square root of the receiver

usage example(s):

this computes a roughly 65 digits precision result, using sqrt from the double as an initial guess

usage example(s):

FloatD is only correct in roughly 17 digits 2 sqrt printfPrintString:'%50.48f' -> 1.414213562373095145474621858738828450441360473633 ^ QDouble gives you much more: 2 asQDouble sqrt printfPrintString:'%50.48f' -> 1.414213562373095048801688724209698078569671875377 2 asQDouble sqrt printfPrintString:'%60.58f' -> 1.4142135623730950488016887242096980785696718753769480731767' 2 asQDouble sqrt printfPrintString:'%70.68f' -> 1.41421356237309504880168872420969807856967187537694807317667973799602 actual digits: -> 1.4142135623730950488016887242096980785696718753769480731766797379907324784621070388503875343276415727350138462309...

 squared

return receiver * receiver

usage example(s):

(QDouble fromFloat:4.0) squared (1e20 + (QDouble fromFloat:1.0)) squared

 digitsWithPrecision: precision

generate digits and exponent.
if precision is >0, that many digits are generated.
If it is 0 the required number of digits is generated
(but never more than the decimalPrecision, which is 65)

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 printOn: aStream

return a printed representation of the receiver.

Notice:
this code was adapted from an ugly piece of c++ code,
which was obviously hacked.
It does need a rework.
As an alternative, use the printf functions, which should also deal wth QDoubles

usage example(s):

(1.2345 asQDouble) printOn:Transcript . Transcript cr. (1.2345 asFloat) printOn:Transcript . Transcript cr. (1.2345 asLongFloat) printOn:Transcript . Transcript cr. (1.2345 asShortFloat) printOn:Transcript . Transcript cr. ((QDouble fromFloat:1.2345) / 10.0) printOn:Transcript ((QDouble fromFloat:1.2345) / 10000.0) printOn:Transcript ((QDouble fromFloat:1.2345) / 1000000000.0) printOn:Transcript

 printOn: aStream precision: precisionIn width: width fixed: fixed showPositive: showPositive uppercase: uppercase fillChar: fillChar

return a printed representation of the receiver.
This is a parametrized entry, which can be used by printf-like functions.
Notice:
this code was adapted from an ugly piece of c++ code,
which was obviously hacked.
It does need a rework.
As an alternative, use the printf functions, which should also deal wth QDoubles


** This is an obsolete interface - do not use it (it may vanish in future versions) **

 round_string_qd: str at: precisionIn offset: offsetIn

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 d0

the most significant (and highest valued) 53 bits of precision

 d1

the next most significant (and next highest valued) 53 bits of precision

 d2

 d3

the least significant (and smallest valued) 53 bits of precision

 renorm

destructive renormalization

usage example(s):

(QDouble fromFloat:1.0) renorm

 isFinite

 isInfinite

(comment from inherited method)
return true, if the receiver is an infinite float (Inf).
These are not created by ST/X float operations (they raise an exception);
however, inline C-code could produce them ...

 isNaN

 isOne

 isZero

(comment from inherited method)
return true, if the receiver is zero

Examples: