bigfloat man page on MacOSX

Man page or keyword search:  
man Server   23457 pages
apropos Keyword Search (all sections)
Output format
MacOSX logo
[printable version]

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 :

       ·      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  man‐
       tissa  and  d the uncertainty, representing the limitation of that num‐
       ber's precision.	 This is why we call such mathematics interval	compu‐
       tations.	 Just take an example in physics : when you measure a tempera‐
       ture, not all digits you read are significant. Sometimes you just  can‐
       not  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 arbi‐
       trary precision.	 BigFloats are internally represented  at  Tcl	lists:
       this  package provides a set of procedures operating against the inter‐
       nal representation in order to :

       ·      perform math operations on BigFloats and (optionnaly) with inte‐
	      gers.

       ·      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  con‐
	      sidered  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 PRECI‐
	      SION.

	      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 exam‐
	      ple 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  con‐
	      verting 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	 argu‐
	      ment  (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 inte‐
	      ger.

PRECISION
       How do conversions work with precision ?

       ·      When a BigFloat is converted from string, the internal represen‐
	      tation  holds  its  uncertainty  as  1  at the level of the last
	      digit.

       ·      During computations, the uncertainty of each  result  is	inter‐
	      nally  computed the closest to the reality, thus saving the mem‐
	      ory 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 pack‐
       age  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 exam‐
       ple :

       # 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)
[top]

List of man pages available for MacOSX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
...................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net