math::machineparameters(n)

📦
version 2.0 · 2 versions
, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

💖 math::machineparameters(n) 💖

okay bestie, welcome to the math::machineparameters page — yes that's the manual name, it lives in the tclrep corner of the world and it's genuinely such a niche little icon. sit down, grab a strawberry 🍓, and let's talk about how your computer's floating point numbers actually work. no cap.

✨ NAME ✨

math::machineparameters — bestie, it literally computes double precision machine parameters. that's the whole gig. that's it. and it does it flawlessly. 💅

🌸 SYNOPSIS 🌸

package require Tcl 8.5 9

package require snit

package require math::machineparameters 0.2

machineparameters create objectname ?options...?

objectname configure ?options...?

objectname cget opt

objectname destroy

objectname compute

objectname get key

objectname tostring

objectname print

look at that. snit is in the mix, Tcl 8.5 and 9 are required, and we're on version 0.2. it's giving very "small package, huge power" energy 👑

🦋 DESCRIPTION 🦋

okay so. the math::machineparameters package is the Tcl equivalent of the DLAMCH LAPACK function. that's the vibe. if you know LAPACK, you already get it. if you don't, we're about to have a moment.

in floating point systems, a floating point number is represented by:

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

and the digits have to satisfy:

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

with the convention that, and I quote the rules of the universe here:

  • t is the size of the mantissa
  • basis is the basis (the "radix")

so what do you actually do with this thing? okay so:

  • the compute method computes all machine parameters
  • then the get method lets you grab each parameter one by one
  • and the print method prints a whole report on standard output

literally the full pipeline. compute → get → print. main character energy from start to finish ✨

🎀 EXAMPLE 🎀

so in the following example, we compute the parameters of a desktop under Linux with these 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

and 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

and bestie, 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

like. the numbers line up. we ate. 🔥

and here's the second example — this one 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

three lines of actual work and you've got your machine's epsilon. iconic. no notes. 🫶

📚 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

academic besties were doing the work in 1972 so we could compute in 2024. respect 💜

👑 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. yes, the whole name. it's not shy.

  • -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 configures 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. bye bestie, it was real 😭

objectname compute

computes the machine parameters.

objectname get key

returns the value corresponding with the given key. here's the full list of available keys, no skips, no shortcuts:

  • -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. (yes, as a string. you get it.)

objectname print

print machine parameters on standard output.

💀 BUGS, IDEAS, FEEDBACK 💀

okay real talk time, and I need you to hear me on this one:

this document, and the package it describes, will undoubtedly contain bugs and other problems. 💀

not me being dramatic — that's literally what it says. so please report such in the category math of the Tcllib Trackers at [http://core.tcl.tk/tcllib/reportlist]. please also report any ideas for enhancements you may have for either the package and/or the documentation. we want the ideas. we need the ideas.

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. that's the whole procedure. it's giving "slightly extra" but it works, iykyk.

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

and that's the page, bestie!! 🎀 this was math::machineparameters(n) from tcllib, version 0.2, and the whole thing was shipped as tclrep's manual page. go compute your epsilon, you absolute queen 👑✨

📦 where this page comes from