tclrep/machineparameters(n)         tclrep         tclrep/machineparameters(n)



______________________________________________________________________________

NAME
       tclrep/machineparameters - Compute double precision machine parameters.

SYNOPSIS
       package require snit

       machineparameters create objectname ?options...?

       objectname configure ?options...?

       objectname cget opt

       objectname destroy

       objectname compute

       objectname get key

       objectname tostring

       objectname print

_________________________________________________________________

DESCRIPTION
       The math::machineparameters package is the Tcl equivalent of the DLAMCH
       LAPACK function.  In floating point systems, a floating point number is
       represented by

              x = +/- d1 d2 ... dt basis^e

       where digits satisfy

              0 <= di <= basis - 1, i = 1, t

       with the convention :

       o      t is the size of the mantissa

       o      basis is the basis (the "radix")

       The compute method computes all machine parameters.  Then, the get
       method can be used to get each parameter.  The print method prints a
       report on standard output.

EXAMPLE
       In the following example, one compute the parameters of a desktop under
       Linux with the following Tcl 8.4.19 properties :

              % parray tcl_platform
              tcl_platform(byteOrder) = littleEndian
              tcl_platform(machine)   = i686
              tcl_platform(os)        = Linux
              tcl_platform(osVersion) = 2.6.24-19-generic
              tcl_platform(platform)  = unix
              tcl_platform(tip,268)   = 1
              tcl_platform(tip,280)   = 1
              tcl_platform(user)      = <username>
              tcl_platform(wordSize)  = 4

       The following example creates a machineparameters object, computes the
       properties and displays it.

                   set pp [machineparameters create %AUTO%]
                   $pp compute
                   $pp print
                   $pp destroy

       This prints out :

                   Machine parameters
                   Epsilon : 1.11022302463e-16
                   Beta : 2
                   Rounding : proper
                   Mantissa : 53
                   Maximum exponent : 1024
                   Minimum exponent : -1021
                   Overflow threshold : 8.98846567431e+307
                   Underflow threshold : 2.22507385851e-308

       That compares well with the results produced by Lapack 3.1.1 :

                   Epsilon                      =   1.11022302462515654E-016
                   Safe minimum                 =   2.22507385850720138E-308
                   Base                         =    2.0000000000000000
                   Precision                    =   2.22044604925031308E-016
                   Number of digits in mantissa =    53.000000000000000
                   Rounding mode                =   1.00000000000000000
                   Minimum exponent             =   -1021.0000000000000
                   Underflow threshold          =   2.22507385850720138E-308
                   Largest exponent             =    1024.0000000000000
                   Overflow threshold           =   1.79769313486231571E+308
                   Reciprocal of safe minimum   =   4.49423283715578977E+307

       The following example creates a machineparameters object, computes the
       properties and gets the epsilon for the machine.

                   set pp [machineparameters create %AUTO%]
                   $pp compute
                   set eps [$pp get -epsilon]
                   $pp destroy


REFERENCES
       o      "Algorithms to Reveal Properties of Floating-Point Arithmetic",
              Michael A. Malcolm, Stanford University, Communications of the
              ACM, Volume 15 ,  Issue 11  (November 1972), Pages: 949 - 951

       o      "More on Algorithms that Reveal Properties of Floating, Point
              Arithmetic Units", W. Morven Gentleman, University of Waterloo,
              Scott B. Marovich, Purdue University, Communications of the ACM,
              Volume 17 ,  Issue 5  (May 1974), Pages: 276 - 277

CLASS API
       machineparameters create objectname ?options...?
              The command creates a new machineparameters object and returns
              the fully qualified name of the object command as its result.

              -verbose verbose
                     Set this option to 1 to enable verbose logging.  This
                     option is mainly for debug purposes.  The default value
                     of verbose is 0.

OBJECT API
       objectname configure ?options...?
              The command configure the options of the object objectname. The
              options are the same as the static method create.

       objectname cget opt
              Returns the value of the option which name is opt. The options
              are the same as the method create and configure.

       objectname destroy
              Destroys the object objectname.

       objectname compute
              Computes the machine parameters.

       objectname get key
              Returns the value corresponding with given key.  The following
              is the list of available keys.

              o      -epsilon : smallest value so that 1+epsilon>1 is false

              o      -rounding : The rounding mode used on the machine.  The
                     rounding occurs when more than t digits would be required
                     to represent the number.  Two modes can be determined
                     with the current system : "chop" means than only t digits
                     are kept, no matter the value of the number "proper"
                     means that another rounding mode is used, be it "round to
                     nearest", "round up", "round down".

              o      -basis : the basis of the floating-point representation.
                     The basis is usually 2, i.e. binary representation (for
                     example IEEE 754 machines), but some machines (like HP
                     calculators for example) uses 10, or 16, etc...

              o      -mantissa : the number of bits in the mantissa

              o      -exponentmax :  the largest positive exponent before
                     overflow occurs

              o      -exponentmin : the largest negative exponent before
                     (gradual) underflow occurs

              o      -vmax : largest positive value before overflow occurs

              o      -vmin : largest negative value before (gradual) underflow
                     occurs

       objectname tostring
              Return a report for machine parameters.

       objectname print
              Print machine parameters on standard output.

COPYRIGHT
       Copyright (c) 2008 Michael Baudin <michael.baudin@sourceforge.net>




math                                  1.0          tclrep/machineparameters(n)
