NAME
Math::FakeDD - DoubleDouble precision arithmetic for all architectures
DEPENDENCIES
This module needs Math::MPFR, which in turn requires the GMP and MPFR
C libraries.
The GMP library is available from : https://gmplib.org
The MPFR library is available from : https://www.mpfr.org
See the introductory explanation of "DoubleDouble" arithmetic in the
"Double-double arithmetic" section of:
https://en.wikipedia.org/wiki/Quadruple-precision_floating-point_format
DESCRIPTION
Perform DoubleDouble arithmetic operations on all architectures and
perl configurations.
See ARITMETIC IMPLEMENTATION section below.
SYNOPSIS
use Math::FakeDD qw(:all);
my $obj = Math::FakeDD->new('0.1');
print $obj; # Outputs [0.1 -5.551115123125783e-18] irrespective of
# perl's NV type. We see that the more significant double
# is 0.1, identical to the double precision representation
# of 0.1, and the less signficant double is
# -5.551115123125783e-18.
my $obj = Math::FakeDD->new(0.1);
print $obj; # Outputs [0.1 0.0] if NV type is 'double'.
# Outputs [0.1 -5.549759870410176e-18] if NV type is
# extended precision 80-bit long double.
# Otherwise outputs [0.1 -5.551115123125783e-18], same
# as for string arg of '0.1'.
Generally, providing a string argument will DWYW, whereas providing a
floating-point (NV) argument won't. (Of course, exceptions exist and
you should familiarise yourself with the difference if it is not
already clear to you.)
printx($obj); # Same as for print() execept that values are in hex.
print sprintx($obj); # Same as 'printx($obj)'.
print dd_repro($obj); # $obj in scientific notation (in decimal).
# Verify that the string returned by dd_repro($obj) is correct:
print "ok" if dd_repro_test(dd_repro($obj), $obj) == 15;
print dd_dec($obj); # Exact representation of the value held by $obj,
# in scientific notation .
NOTES: In the following documentation:
"$arg", "$arg1", "$arg2", etc. are arguments that can be either a
string (perl PV), a native perl numeric type (NV or IV or UV), or
a Math::FakeDD object.
"$obj" is a Math::FakeDD object.
"$mpfr" is a 2098-bit precision Math::MPFR object.
ASSIGNMENT FUNCTIONS
$obj = Math::FakeDD->new($arg); # $arg is optional here.
$obj = Math::FakeDD::new($arg); # $arg is optional here.
Returns a Math::FakeDD object with the value represented by $arg,
or zero if no argument is provided.
$arg must be one of PV (string), IV (integer), UV (unsigned integer),
or NV (perl floating point type).
dd_assign($obj, $arg);
Assigns the value represented by $arg, to the Math::FakeDD object.
$arg must be one of PV (string), IV (integer), UV (unsigned integer),
NV (perl floating point type) or Math::MPFR object.
$obj2 = dd_clone($obj1);
$obj2 = dd_copy ($obj1);
Both dd_clone() and dd_copy() return a copy of the Math::FakeDD
object that was given to them. dd_clone is an alias for dd_copy.
$obj = any2dd(@args);
Converts all of the arguments to Math::FakeDD objects and returns
the sum of all of those objects.
Each argument must be one of PV (string), IV (integer), UV (unsigned
integer), NV (perl floating point type) or Math::MPFR object, but
they don't all have to be of the same type.
Strings beginning with (+/-) '0x' or '0X' will be evaluated as hex
values. This is handy for re-creating values that have been displayed
using (s)printx.
Strings begining with '(+/-) '0b' will be evaluated as base 2 values.
ARITHMETIC FUNCTIONS
Use either the functions, or the overloaded
operations (that use these functions).
$obj = dd_add($arg1, $arg2);
$obj = dd_sub($arg1, $arg2);
$obj = dd_mul($arg1, $arg2);
$obj = dd_div($arg1, $arg2);
Returns a Math::FakeDD object with the value of $arg1
(respectively) plus, minus, multiplied by or divided by $arg2.
dd_add_eq($obj, $arg);
dd_sub_eq($obj, $arg);
dd_mul_eq($obj, $arg);
dd_div_eq($obj, $arg);
The value in $obj is (respectively) incremented, decremented,
multiplied or divided by $arg.
$obj = dd_pow($arg1, $arg2);
Return a Math::FakeDD object that contains $arg1 ** $arg2.
dd_pow_eq($obj, $arg);
The value held in $obj is raised to the power of $arg.
(That is, $obj = $obj ** $arg.)
$obj = dd_abs($arg);
Return a Math::FakeDD object containing the absolute value of $arg.
$obj = dd_int($arg);
Return a Math::FakeDD object containing the truncated
(integer) value of $arg.
EXPONENTIATION FUNCTIONS
$obj = dd_exp($arg);
$obj = dd_exp2($arg);
$obj = dd_exp10($arg);
Return a Math::FakeDD object that contains respectively
e ** $arg, 2 ** $arg, 10 ** $arg.
$obj = dd_log($arg);
$obj = dd_log2($arg);
$obj = dd_log10($arg);
Return a Math::FakeDD object that contains respectively
the natural log of $arg, the base 2 log of $arg, the
base 10 log of $arg.
TRANSCENDENTAL FUNCTIONS
$obj = dd_pi();
$obj = dd_euler();
$obj = dd_catalan();
Return (respectively) pi (3.141...), Euler's constant (0.577...)
and Catalan's constant (0.915...) .
TRIGONOMETRY FUNCTIONS
$obj = dd_cos($arg);
Return a Math::FakeDD object that contains cos($arg).
$obj = dd_sin($arg);
Return a Math::FakeDD object that contains sin($arg).
COMPARISON FUNCTIONS
$iv = dd_cmp($arg1, $arg2);
$iv = dd_spaceship($arg1, $arg2);
Return undef if at least one of $arg1
and $arg2 is NaN
$iv < 0 if $arg1 < $arg2.
$iv > 0 if $arg1 > $arg2.
$iv == 0 if $arg1 == $arg2.
$iv = dd_eq ($arg1, $arg2);
$iv = dd_neq($arg1, $arg2);
$iv = dd_gt($arg1, $arg2);
$iv = dd_gte($arg1, $arg2);
$iv = dd_lt($arg1, $arg2);
$iv = dd_lte($arg1, $arg2);
If (respectively) $arg1 == $arg2, $arg1 != $arg2,
$arg1 > $arg2, $arg1 >= $arg2, $arg1 < $arg2, $arg1 <= $arg2,
then $integer is set to 1.
Else $integer is set to 0.
$iv = dd_streq($obj, $arg);
We need this function only because Test::More can pull
in code that assumes 'eq' is overloaded. (And this is the
function that overloaded 'eq' calls.)
Return 1 if "$obj" eq "$arg".
Else return 0;
$iv = dd_strne($obj, $arg);
We provide this function only because dd_stre() is provided.
Return 1 if "$obj" ne "$arg".
Else return 0;
OUTPUT FUNCTIONS
$str = dd_dec($obj); # "dec" short for "decimalize"
Represent the *exact* value of $obj in scientific notation,
using as few digits as required to provide that exactness.
As with dd_repro(), if this $str is assigned to a new
Math::FakeDD object, then the new Math::FakeDD object will
be identical to the Math::FakeDD object from which this
$str was derived. However, the number of mantissa digits
returned by dd_dec() will be >= (usually greater than) the
number of mantissa digits returned by dd_repro().
$str = dd_hex($obj);
As for dd_dec(), except that the value placed in $str is in
hex ("%a") format.
$str = dd_repro($obj); # "repro" short for "reproducible"
#### NOTE: This function has turned into a much uglier hack
than I had envisaged. See the "TODO" section below
for elaboration.
Represent the value of $obj in decimal scientific notation,
using as few decimal mantissa digits as possible, such that if
this $str is assigned to a new Math::FakeDD object, then the
new Math::FakeDD object will be identical to (ie a reproduction
of) the Math::FakeDD object from which $str was derived.
Also set $Math::FakeDD::RETRO_PREC to the bit-precision value
that was used in determining $str.
If $Math::FakeDD::REPRO_PREC begins with ">", then the value that
dd_repro() returned was altered slightly (away from zero) from
the value that was calculated using the specified precision.
If $Math::FakeDD::REPRO_PREC begins with "<", then the value that
dd_repro() returned was altered slightly (toward zero) from the
value that was calculated using the specified precision.
Other possible $Math::FakeDD::REPRO_PREC values, all of which
indicate that no calcuation of precision has been made, are:
-1: the initial value, and dd_repro() has not been called at all;
0 : dd_repro returned an Inf, NaN or Zero;
undef: perl's nvtype is DoubleDouble, so dd_repro() simply used
Math::MPFR::nvtoa().
$iv = dd_repro_test(dd_repro($obj), $obj, $debug); # 3rd arg is optional
Check that the representation of dd_repro($obj) returned by
dd_repro() is accurate, and that it uses the fewest significant
decimal mantissa digits possible.
Some debugging output is provided if the third (optional) arg
is true.
The function assigns its first arg, dd_repro($obj), to a
string - let's call it $str.
4 tests are conducted:
1) that Math::FakeDD->new($str) == $obj.
$iv & 1 will be true if and only if this test passes.
2) that if we were to round $str *down* to 1 less significant decimal
digit then Math::FakeDD->new($str) < $obj.
$iv & 2 will be true if and only if this test passes.
3) that if we were round $str *up* to 1 less significant decimal
digit then Math::FakeDD->new($str) > $obj.
$iv & 4 will be true if and only if this test passes.
4) that there are no errant trailing zeroes in the mantissa portion
of $str.
$iv & 8 will be true if and only if this test passes.
If all four tests pass (in which case the returned $iv == 15) then
we know that dd_repro($obj) has functioned correctly and as intended.
Else, dd_repro() has not functioned correctly and we can determine
which test(s) failed by examining the 4 lowest bits of $iv.
$str = dd_stringify($obj);
Return a string that begins with "[" and ends with "]".
In between show, a space-delimited decimal string
representation of the more significant double followed by the
less significant double. Both doubles will be shown in as few
digits as possible, while not losing any information.
The overloading of interpolation uses this function.
$nv = dd_numify($obj); # Mainly for '0+' overloading.
Beginning in version 0.08, this function now converts $obj to a
2098-bit precision Math::MPFR object.
(Previously it converted $obj to an NV, as accurately as the
precision of the NV allowed.)
printx($obj);
Same as doing:
print(sprintx($obj)); # see below for sprintx documentation.
$str = sprintx($obj);
Same as dd_stringify($obj), except that the 2 doubles are
presented in hex ("%a") format, instead of decimal format.
$str = unpackx($obj);
Same as dd_stringify($obj), except that the 2 doubles have
each been unpacked into hex format by doing:
unpack "H*", pack "d>", $double;
OPERATOR OVERLOADING
The following operations are currently overloaded:
"", 0+, ==, !=, *, *=, **, **=, +, +=, -, -=, /, /=, <, <=, <=>, >, >=,
++, --,
bool, !,
atan2, cos, sin
eq, ne
=
Run
my %oloads = Math::FakeDD::oload();
The keys of %oloads are the overloaded operations, and their
respective values name the functions used in the respective operation.
These functions are documented above - except for dd_true(),
dd_false() overload_inc, overload_dec,and overload_copy(), which
are documented here:
$iv = dd_true($obj);
This function is not exported.
It is intended to be called only by overloading of 'bool'.
Returns 1 unless $obj is NaN or zero; else returns 0.
(This is the same criterion as used by Math::MPFR's overloading
of 'bool'.)
$iv = dd_false($obj);
This function is not exported.
It is intended to be called only by overloading of '!'.
Returns 1 if $obj is NaN or zero; else returns 0.
(This is the same criterion as used by Math::MPFR's overloading
of '!'.)
$obj2 = $obj1; # Utilizes overload_copy()
Use the unexported overload_copy() sub to copy $obj1 to $obj2.
$obj1++; # Utilizes overload_inc()
$obj1--; # Utilizes overload_dec()
Add or (respectively) subtract 1e0 to/from $obj1.
OTHER FUNCTIONS
$obj = dd_inf([$iv]); # $iv is an optional arg, which will be
# evaluated in (signed) numeric context
If the optional arg $iv, is less than 0 (in numeric context, then
a Math::FakeDD object with value -Inf is returned.
Else return a +Inf Math::FakeDD object.
$obj = dd_nan();
Return a NaN Math::FakeDD object.
$iv = dd_is_inf($obj);
Returns 1 if $obj is an infinity.
Else returns 0.
$iv = dd_is_nan($obj);
Returns 1 if $obj is a NaN.
Else returns 0.
$obj = mpfr2dd($mpfr); # Precision of $mpfr is 2098 bits.
$obj = mpfr_any_prec2dd($mpfr); # Precision of $mpfr is unrestricted.
Return the value held by the Math::MPFR object $mpfr as the
Math::FakeDD object $obj.
Precision can be (and often is) lost in this conversion if the
precision of $mpfr is greater than 107, or if $mpfr contains a
value outside of the double precision range.
$mpfr = dd2mpfr($obj);
Return the value held by the Math::FakeDD object $obj as a 2098-bit
precision Math::MPFR object $mpfr.
No precision is lost in this conversion.
$mpfr = mpfr2098($in);
Return the value held by $in as the 2098-bit precision Math::MPFR
object $mpfr.
$in can be a string (PV), an integer (IV), an unsigned integer (UV),
a perl floating point (NV) - but not a Math::FakeDD object.
To convert a Math::FakeDD object to a 2098-bit precision Math::MPFR
object, use dd2mpfr() instead.
$obj2 = dd_nextup($obj1);
$obj2 = dd_nextdown($obj1);
Return the value that is greater than, or (respectively) less than,
the given argument by the smallest amount possible.
Return dd_nan() if $obj1 is NaN.
If $obj1 is +Inf, dd_nextup() returns dd_inf(), dd_nextdown() returns
$Math::FakeDD::DD_MAX.
If $obj1 is -Inf, dd_nextup() returns -$Math::FakeDD::DD_MAX and
dd_nextdown() returns dd_inf(-1).
$iv = ulp_exponent($obj, [$bool]);
If no second argument, return the signed integer value ($iv) such that
2**$iv equates to the value of ULP of the given argument's less
significant double.
If a second argument is given, and it evaluates to TRUE, then the value
of the ULP of the given argument's more sigfificant double is returned.
NOTE:
ULP is aka "unit in last place" or, synonymously, "unit of least
precision".
$iv = is_subnormal($double);
$double is evaluated to double precision.
If that value is subnormal (abs($double) < 2**-1022) return 1.
Else 0 is returned.
NOTE:
This function returns 1 if $double is zero.
ARITHMETIC IMPLEMENTATION
Operands are first converted to a 2098-bit Math::MPFR object value.
If the operand is a Math::FakeDD object then the conversion is exact.
Else, the conversion might not be exact, depending upon the value.
The result of the operation on the 2098-bit operand(s) will also be
rounded to 2098 bits, and that value will then be rounded to its
DoubleDouble format and returned as a Math::FakeDD object.
DoubleDoubles with real values have precision of between 107 and
2098 bits (depending upon their value), except for subnormalized
double precision values where precision is in the range 1 to 52
bits (depending upon value).
All rounding is done to nearest, with ties to even.
TODO
Re-factor dd_repro(), which is currently just an awful hack.
Also, it's possible that dd_repro() doesn't work correctly for all
possible DoubleDouble values. It's recommended that, if this
matters, then dd_repro_test() should be run to check on the
correctness of the values that dd_repro() returns.
Please report any such errors, as that will be helpful with the
intended re-factoring.
LICENSE
This program is free software; you may redistribute it and/or
modify it under the same terms as Perl itself.
Copyright 2022-23, Sisyphus
AUTHOR
Sisyphus <sisyphus at(@) cpan dot (.) org>