Unix/Linux Go Back    


SuSE 11.3 - man page for bigfloat (suse section n)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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 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 :

       o      BigFloat for floating-point numbers of arbitrary length.

       o      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 uncer-
       tainty, 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 :

       o      perform math operations on BigFloats and (optionnaly) with integers.

       o      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 num-
	      ber 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 com-
	      mand 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 deci-
	      mals 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 :

	      o      a BigFloat close enough to zero to raise "divide by zero".

	      o      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 ?

       o      When  a  BigFloat  is  converted from string, the internal representation holds its
	      uncertainty as 1 at the level of the last digit.

       o      During computations, the uncertainty of each  result  is	internally  computed  the
	      closest to the reality, thus saving the memory used.

       o      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  prob-
	      lems.

       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 repre-
       sentation.  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 respec-
       tive 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  uncer-
       tainty  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  quo-
       tient, 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 preci-
       sion  of the result is difficult.  It seems however that in many cases, the loss of preci-
       sion 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 pro-
       vided 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 inte-
       gers, 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 prob-
       lems.  Please report such in the category math :: bignum :: float of the Tcllib SF  Track-
       ers  [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

COPYRIGHT
       Copyright (c) 2004-2008, by Stephane Arnold <stephanearnold at yahoo dot fr>

math					      2.0.1				math::bigfloat(n)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 10:47 AM.