math::machineparameters(3tcl)

NAME
math::machineparameters - Compute double precision machine parameters.

SYNOPSIS
package require Tcl 8.4

package require snit

package require math::machineparameters 0.1

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 :

•   t is the size of the mantissa

•   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

•   "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

•   "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.

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

    •   -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".

    •   -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...

    •   -mantissa : the number of bits in the mantissa

    •   -exponentmax : the largest positive exponent before overflow occurs

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

    •   -vmax : largest positive value before overflow occurs

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

objectname tostring
    Return a report for machine parameters.

objectname print
    Print machine parameters on standard output.

BUGS, IDEAS, FEEDBACK
This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category math of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for enhancements you may have for either package and/or documentation.

When proposing code changes, please provide unified diffs, i.e the output of diff -u.

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar.

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