math::exact(3tcl) Tcl Math Library math::exact(3tcl)
______________________________________________________________________________
NAME
math::exact - Exact Real Arithmetic
SYNOPSIS
package require Tcl 8.6
package require grammar::aycock 1.0
package require math::exact 1.0.1
::math::exact::exactexpr expr
number ref
number unref
number asPrint precision
number asFloat precision
______________________________________________________________________________
DESCRIPTION
The exactexpr command in the math::exact package allows for exact com-
putations over the computable real numbers. These are not arbitrary-
precision calculations; rather they are exact, with numbers represented
by algorithms that produce successive approximations. At the end of a
calculation, the caller can request a given precision for the end re-
sult, and intermediate results are computed to whatever precision is
necessary to satisfy the request.
PROCEDURES
The following procedure is the primary entry into the math::exact pack-
age.
::math::exact::exactexpr expr
Accepts a mathematical expression in Tcl syntax, and returns an
object that represents the program to calculate successive ap-
proximations to the expression's value. The result will be re-
ferred to as an exact real number.
number ref
Increases the reference count of a given exact real number.
number unref
Decreases the reference count of a given exact real number, and
destroys the number if the reference count is zero.
number asPrint precision
Formats the given number for printing, with the specified preci-
sion. (See below for how precision is interpreted). Numbers
that are known to be rational are formatted as fractions.
number asFloat precision
Formats the given number for printing, with the specified preci-
sion. (See below for how precision is interpreted). All numbers
are formatted in floating-point E format.
PARAMETERS
expr Expression to evaluate. The syntax for expressions is the same
as it is in Tcl, but the set of operations is smaller. See Ex-
pressions below for details.
number The object returned by an earlier invocation of math::exact::ex-
actexpr
precision
The requested 'precision' of the result. The precision is (ap-
proximately) the absolute value of the binary exponent plus the
number of bits of the binary significand. For instance, to re-
turn results to IEEE-754 double precision, 56 bits plus the ex-
ponent are required. Numbers between 1/2 and 2 will require a
precision of 57; numbers between 1/4 and 1/2 or between 2 and 4
will require 58; numbers between 1/8 and 1/4 or between 4 and 8
will require 59; and so on.
EXPRESSIONS
The math::exact::exactexpr command accepts expressions in a subset of
Tcl's syntax. The following components may be used in an expression.
o Decimal integers.
o Variable references with the dollar sign ($). The value of the
variable must be the result of another call to math::exact::ex-
actexpr. The reference count of the value will be increased by
one for each position at which it appears in the expression.
o The exponentiation operator (**).
o Unary plus (+) and minus (-) operators.
o Multiplication (*) and division (/) operators.
o Parentheses used for grouping.
o Functions. See Functions below for the functions that are avail-
able.
FUNCTIONS
The following functions are available for use within exact real expres-
sions.
acos(x)
The inverse cosine of x. The result is expressed in radians.
The absolute value of x must be less than 1.
acosh(x)
The inverse hyperbolic cosine of x. x must be greater than 1.
asin(x)
The inverse sine of x. The result is expressed in radians. The
absolute value of x must be less than 1.
asinh(x)
The inverse hyperbolic sine of x.
atan(x)
The inverse tangent of x. The result is expressed in radians.
atanh(x)
The inverse hyperbolic tangent of x. The absolute value of x
must be less than 1.
cos(x) The cosine of x. x is expressed in radians.
cosh(x)
The hyperbolic cosine of x.
e() The base of the natural logarithms = 2.71828...
exp(x) The exponential function of x.
log(x) The natural logarithm of x. x must be positive.
pi() The value of pi = 3.15159...
sin(x) The sine of x. x is expressed in radians.
sinh(x)
The hyperbolic sine of x.
sqrt(x)
The square root of x. x must be positive.
tan(x) The tangent of x. x is expressed in radians.
tanh(x)
The hyperbolic tangent of x.
SUMMARY
The math::exact::exactexpr command provides a system that performs ex-
act arithmetic over computable real numbers, representing the numbers
as algorithms for successive approximation. An example, which imple-
ments the high-school quadratic formula, is shown below.
namespace import math::exact::exactexpr
proc exactquad {a b c} {
set d [[exactexpr {sqrt($b*$b - 4*$a*$c)}] ref]
set r0 [[exactexpr {(-$b - $d) / (2 * $a)}] ref]
set r1 [[exactexpr {(-$b + $d) / (2 * $a)}] ref]
$d unref
return [list $r0 $r1]
}
set a [[exactexpr 1] ref]
set b [[exactexpr 200] ref]
set c [[exactexpr {(-3/2) * 10**-12}] ref]
lassign [exactquad $a $b $c] r0 r1
$a unref; $b unref; $c unref
puts [list [$r0 asFloat 70] [$r1 asFloat 110]]
$r0 unref; $r1 unref
The program prints the result:
-2.000000000000000075e2 7.499999999999999719e-15
Note that if IEEE-754 floating point had been used, a catastrophic
roundoff error would yield a smaller root that is a factor of two too
high:
-200.0 1.4210854715202004e-14
The invocations of exactexpr should be fairly self-explanatory. The
other commands of note are ref and unref. It is necessary for the
caller to keep track of references to exact expressions - to call ref
every time an exact expression is stored in a variable and unref every
time the variable goes out of scope or is overwritten. The asFloat
method emits decimal digits as long as the requested precision supports
them. It terminates when the requested precision yields an uncertainty
of more than one unit in the least significant digit.
CATEGORY
Mathematics
COPYRIGHT
Copyright (c) 2015 Kevin B. Kenny <kennykb@acm.org>
Redistribution permitted under the terms of the Open Publication License <http://www.opencontent.org/openpub/>
tcllib 1.0.1 math::exact(3tcl)