NAME¶
math::bigfloat - Arbitrary precision floating-point numbers
SYNOPSIS¶
package require
Tcl 8.5
package require
math::bigfloat ?2.0.1?
fromstr number ?
trailingZeros?
tostr ?
-nosci?
number
fromdouble double ?
decimals?
todouble number
isInt number
isFloat number
int2float integer ?
decimals?
add x y
sub x y
mul x y
div x y
mod x y
abs x
opp x
pow x n
iszero x
equal x y
compare x y
sqrt x
log x
exp x
cos x
sin x
tan x
cotan x
acos x
asin x
atan x
cosh x
sinh x
tanh x
pi n
rad2deg radians
deg2rad degrees
round x
ceil x
floor x
DESCRIPTION¶
The bigfloat package provides arbitrary precision floating-point math
capabilities to the Tcl language. It is designed to work with Tcl 8.5, but for
Tcl 8.4 is provided an earlier version of this package. See
WHAT ABOUT TCL
8.4 ? for more explanations. By convention, we will talk about the numbers
treated in this library as :
- •
- BigFloat for floating-point numbers of arbitrary
length.
- •
- integers for arbitrary length signed integers, just as
basic integers since Tcl 8.5.
Each BigFloat is an interval, namely [
m-d, m+d], where
m is the
mantissa and
d the uncertainty, representing the limitation of that
number's precision. This is why we call such mathematics
interval
computations. Just take an example in physics : when you measure a
temperature, not all digits you read are
significant. Sometimes you
just cannot trust all digits - not to mention if doubles (f.p. numbers) can
handle all these digits. BigFloat can handle this problem - trusting the
digits you get - plus the ability to store numbers with an arbitrary
precision. BigFloats are internally represented at Tcl lists: this package
provides a set of procedures operating against the internal representation in
order to :
- •
- perform math operations on BigFloats and (optionnaly) with
integers.
- •
- convert BigFloats from their internal representations to
strings, and vice versa.
INTRODUCTION¶
- fromstr number ?trailingZeros?
- Converts number into a BigFloat. Its precision is at
least the number of digits provided by number. If the number
contains only digits and eventually a minus sign, it is considered as an
integer. Subsequently, no conversion is done at all.
trailingZeros - the number of zeros to append at the end of the
floating-point number to get more precision. It cannot be applied to an
integer.
# x and y are BigFloats : the first string contained a dot, and the second an e sign
set x [fromstr -1.000000]
set y [fromstr 2000e30]
# let's see how we get integers
set t 20000000000000
# the old way (package 1.2) is still supported for backwards compatibility :
set m [fromstr 10000000000]
# but we do not need fromstr for integers anymore
set n -39
# t, m and n are integers
The
number's last digit is considered by the procedure to be true at
+/-1, For example, 1.00 is the interval [0.99, 1.01], and 0.43 the interval
[0.42, 0.44]. The Pi constant may be approximated by the number
"3.1415". This string could be considered as the interval [3.1414 ,
3.1416] by
fromstr. So, when you mean 1.0 as a double, you may have to
write 1.000000 to get enough precision. To learn more about this subject, see
PRECISION.
For example :
set x [fromstr 1.0000000000]
# the next line does the same, but smarter
set y [fromstr 1. 10]
- tostr ?-nosci? number
- Returns a string form of a BigFloat, in which all digits
are exacts. All exact digits means a rounding may occur, for
example to zero, if the uncertainty interval does not clearly show the
true digits. number may be an integer, causing the command to
return exactly the input argument. With the -nosci option, the
number returned is never shown in scientific notation, i.e. not like
'3.4523e+5' but like '345230.'.
puts [tostr [fromstr 0.99999]] ;# 1.0000
puts [tostr [fromstr 1.00001]] ;# 1.0000
puts [tostr [fromstr 0.002]] ;# 0.e-2
- See PRECISION for that matter. See also
iszero for how to detect zeros, which is useful when performing a
division.
- fromdouble double ?decimals?
- Converts a double (a simple floating-point value) to a
BigFloat, with exactly decimals digits. Without the decimals
argument, it behaves like fromstr. Here, the only important feature
you might care of is the ability to create BigFloats with a fixed number
of decimals.
tostr [fromstr 1.111 4]
# returns : 1.111000 (3 zeros)
tostr [fromdouble 1.111 4]
# returns : 1.111
- todouble number
- Returns a double, that may be used in expr, from a
BigFloat.
- isInt number
- Returns 1 if number is an integer, 0 otherwise.
- isFloat number
- Returns 1 if number is a BigFloat, 0 otherwise.
- int2float integer ?decimals?
- Converts an integer to a BigFloat with decimals
trailing zeros. The default, and minimal, number of decimals is 1.
When converting back to string, one decimal is lost:
set n 10
set x [int2float $n]; # like fromstr 10.0
puts [tostr $x]; # prints "10."
set x [int2float $n 3]; # like fromstr 10.000
puts [tostr $x]; # prints "10.00"
ARITHMETICS¶
- add x y
- sub x y
- mul x y
- Return the sum, difference and product of x by
y. x - may be either a BigFloat or an integer y - may
be either a BigFloat or an integer When both are integers, these commands
behave like expr.
- div x y
- mod x y
- Return the quotient and the rest of x divided by
y. Each argument ( x and y) can be either a BigFloat
or an integer, but you cannot divide an integer by a BigFloat Divide by
zero throws an error.
- abs x
- Returns the absolute value of x
- opp x
- Returns the opposite of x
- pow x n
- Returns x taken to the nth power. It only
works if n is an integer. x might be a BigFloat or an
integer.
COMPARISONS¶
- iszero x
- Returns 1 if x is :
- •
- a BigFloat close enough to zero to raise "divide by
zero".
- •
- the integer 0.
- See here how numbers that are close to zero are converted
to strings:
tostr [fromstr 0.001] ; # -> 0.e-2
tostr [fromstr 0.000000] ; # -> 0.e-5
tostr [fromstr -0.000001] ; # -> 0.e-5
tostr [fromstr 0.0] ; # -> 0.
tostr [fromstr 0.002] ; # -> 0.e-2
set a [fromstr 0.002] ; # uncertainty interval : 0.001, 0.003
tostr $a ; # 0.e-2
iszero $a ; # false
set a [fromstr 0.001] ; # uncertainty interval : 0.000, 0.002
tostr $a ; # 0.e-2
iszero $a ; # true
- equal x y
- Returns 1 if x and y are equal, 0
elsewhere.
- compare x y
- Returns 0 if both BigFloat arguments are equal, 1 if
x is greater than y, and -1 if x is lower than
y. You would not be able to compare an integer to a BigFloat : the
operands should be both BigFloats, or both integers.
ANALYSIS¶
- sqrt x
- log x
- exp x
- cos x
- sin x
- tan x
- cotan x
- acos x
- asin x
- atan x
- cosh x
- sinh x
- tanh x
- The above functions return, respectively, the following :
square root, logarithm, exponential, cosine, sine, tangent, cotangent, arc
cosine, arc sine, arc tangent, hyperbolic cosine, hyperbolic sine,
hyperbolic tangent, of a BigFloat named x.
- pi n
- Returns a BigFloat representing the Pi constant with
n digits after the dot. n is a positive integer.
- rad2deg radians
- deg2rad degrees
- radians - angle expressed in radians (BigFloat)
degrees - angle expressed in degrees (BigFloat)
Convert an angle from radians to degrees, and vice versa.
ROUNDING¶
- round x
- ceil x
- floor x
- The above functions return the x BigFloat, rounded
like with the same mathematical function in expr, and returns it as
an integer.
PRECISION¶
How do conversions work with precision ?
- •
- When a BigFloat is converted from string, the internal
representation holds its uncertainty as 1 at the level of the last
digit.
- •
- During computations, the uncertainty of each result is
internally computed the closest to the reality, thus saving the memory
used.
- •
- When converting back to string, the digits that are printed
are not subject to uncertainty. However, some rounding is done, as not
doing so causes severe problems.
Uncertainties are kept in the internal representation of the number ; it is
recommended to use
tostr only for outputting data (on the screen or in
a file), and NEVER call
fromstr with the result of
tostr. It is
better to always keep operands in their internal representation. Due to the
internals of this library, the uncertainty interval may be slightly wider than
expected, but this should not cause false digits.
Now you may ask this question : What precision am I going to get after calling
add, sub, mul or div? First you set a number from the string representation
and, by the way, its uncertainty is set:
set a [fromstr 1.230]
# $a belongs to [1.229, 1.231]
set a [fromstr 1.000]
# $a belongs to [0.999, 1.001]
# $a has a relative uncertainty of 0.1% : 0.001(the uncertainty)/1.000(the medium value)
The uncertainty of the sum, or the difference, of two numbers, is the sum of
their respective uncertainties.
set a [fromstr 1.230]
set b [fromstr 2.340]
set sum [add $a $b]]
# the result is : [3.568, 3.572] (the last digit is known with an uncertainty of 2)
tostr $sum ; # 3.57
But when, for example, we add or substract an integer to a BigFloat, the
relative uncertainty of the result is unchanged. So it is desirable not to
convert integers to BigFloats:
set a [fromstr 0.999999999]
# now something dangerous
set b [fromstr 2.000]
# the result has only 3 digits
tostr [add $a $b]
# how to keep precision at its maximum
puts [tostr [add $a 2]]
For multiplication and division, the relative uncertainties of the product or
the quotient, is the sum of the relative uncertainties of the operands. Take
care of division by zero : check each divider with
iszero.
set num [fromstr 4.00]
set denom [fromstr 0.01]
puts [iszero $denom];# true
set quotient [div $num $denom];# error : divide by zero
# opposites of our operands
puts [compare $num [opp $num]]; # 1
puts [compare $denom [opp $denom]]; # 0 !!!
# No suprise ! 0 and its opposite are the same...
Effects of the precision of a number considered equal to zero to the cos
function:
puts [tostr [cos [fromstr 0. 10]]]; # -> 1.000000000
puts [tostr [cos [fromstr 0. 5]]]; # -> 1.0000
puts [tostr [cos [fromstr 0e-10]]]; # -> 1.000000000
puts [tostr [cos [fromstr 1e-10]]]; # -> 1.000000000
BigFloats with different internal representations may be converted to the same
string.
For most analysis functions (cosine, square root, logarithm, etc.), determining
the precision of the result is difficult. It seems however that in many cases,
the loss of precision in the result is of one or two digits. There are some
exceptions : for example,
tostr [exp [fromstr 100.0 10]]
# returns : 2.688117142e+43 which has only 10 digits of precision, although the entry
# has 14 digits of precision.
WHAT ABOUT TCL 8.4 ?¶
If your setup do not provide Tcl 8.5 but supports 8.4, the package can still be
loaded, switching back to
math::bigfloat 1.2. Indeed, an important
function introduced in Tcl 8.5 is required - the ability to handle bignums,
that we can do with
expr. Before 8.5, this ability was provided by
several packages, including the pure-Tcl
math::bignum package provided
by
tcllib. In this case, all you need to know, is that arguments to the
commands explained here, are expected to be in their internal representation.
So even with integers, you will need to call
fromstr and
tostr
in order to convert them between string and internal representations.
#
# with Tcl 8.5
# ============
set a [pi 20]
# round returns an integer and 'everything is a string' applies to integers
# whatever big they are
puts [round [mul $a 10000000000]]
#
# the same with Tcl 8.4
# =====================
set a [pi 20]
# bignums (arbitrary length integers) need a conversion hook
set b [fromstr 10000000000]
# round returns a bignum:
# before printing it, we need to convert it with 'tostr'
puts [tostr [round [mul $a $b]]]
NAMESPACES AND OTHER PACKAGES¶
We have not yet discussed about namespaces because we assumed that you had
imported public commands into the global namespace, like this:
namespace import ::math::bigfloat::*
If you matter much about avoiding names conflicts, I considere it should be
resolved by the following :
package require math::bigfloat
# beware: namespace ensembles are not available in Tcl 8.4
namespace eval ::math::bigfloat {namespace ensemble create -command ::bigfloat}
# from now, the bigfloat command takes as subcommands all original math::bigfloat::* commands
set a [bigfloat sub [bigfloat fromstr 2.000] [bigfloat fromstr 0.530]]
puts [bigfloat tostr $a]
EXAMPLES¶
Guess what happens when you are doing some astronomy. Here is an example :
# convert acurrate angles with a millisecond-rated accuracy
proc degree-angle {degrees minutes seconds milliseconds} {
set result 0
set div 1
foreach factor {1 1000 60 60} var [list $milliseconds $seconds $minutes $degrees] {
# we convert each entry var into milliseconds
set div [expr {$div*$factor}]
incr result [expr {$var*$div}]
}
return [div [int2float $result] $div]
}
# load the package
package require math::bigfloat
namespace import ::math::bigfloat::*
# work with angles : a standard formula for navigation (taking bearings)
set angle1 [deg2rad [degree-angle 20 30 40 0]]
set angle2 [deg2rad [degree-angle 21 0 50 500]]
set opposite3 [deg2rad [degree-angle 51 0 50 500]]
set sinProduct [mul [sin $angle1] [sin $angle2]]
set cosProduct [mul [cos $angle1] [cos $angle2]]
set angle3 [asin [add [mul $sinProduct [cos $opposite3]] $cosProduct]]
puts "angle3 : [tostr [rad2deg $angle3]]"
BUGS, IDEAS, FEEDBACK¶
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category
math :: bignum ::
float of the
Tcllib SF Trackers
[
http://sourceforge.net/tracker/?group_id=12883]. Please also report any ideas
for enhancements you may have for either package and/or documentation.
KEYWORDS¶
computations, floating-point, interval, math, multiprecision, tcl
CATEGORY¶
Mathematics
COPYRIGHT¶
Copyright (c) 2004-2008, by Stephane Arnold <stephanearnold at yahoo dot fr>