Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

math::bigfloat(n)                             Tcl Math Library                             math::bigfloat(n)



____________________________________________________________________________________________________________

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 lan-guage. language.
       guage. 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 num-bers numbers
       bers 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,  rep-resenting representing
       resenting  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 repre-sented represented
       sented at Tcl lists: this package provides a set of procedures operating against the internal  repre-sentation representation
       sentation 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  argu-ment. argument.
              ment.  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, hyper-bolic hyperbolic
              bolic 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 uncer-tainties. uncertainties.
       tainties.

       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 sev-eral several
       eral 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://source -
       forge.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>




math                                                2.0.1                                  math::bigfloat(n)