1math::exact(n)                 Tcl Math Library                 math::exact(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       math::exact - Exact Real Arithmetic
9

SYNOPSIS

11       package require Tcl  8.6
12
13       package require grammar::aycock  1.0
14
15       package require math::exact  1.0.1
16
17       ::math::exact::exactexpr expr
18
19       number ref
20
21       number unref
22
23       number asPrint precision
24
25       number asFloat precision
26
27______________________________________________________________________________
28

DESCRIPTION

30       The  exactexpr command in the math::exact package allows for exact com‐
31       putations over the computable real numbers.  These are  not  arbitrary-
32       precision calculations; rather they are exact, with numbers represented
33       by algorithms that produce successive approximations. At the end  of  a
34       calculation,  the  caller can request a given precision for the end re‐
35       sult, and intermediate results are computed to  whatever  precision  is
36       necessary to satisfy the request.
37

PROCEDURES

39       The following procedure is the primary entry into the math::exact pack‐
40       age.
41
42       ::math::exact::exactexpr expr
43              Accepts a mathematical expression in Tcl syntax, and returns  an
44              object  that  represents the program to calculate successive ap‐
45              proximations to the expression's value. The result will  be  re‐
46              ferred to as an exact real number.
47
48       number ref
49              Increases the reference count of a given exact real number.
50
51       number unref
52              Decreases  the reference count of a given exact real number, and
53              destroys the number if the reference count is zero.
54
55       number asPrint precision
56              Formats the given number for printing, with the specified preci‐
57              sion.   (See  below  for  how precision is interpreted). Numbers
58              that are known to be rational are formatted as fractions.
59
60       number asFloat precision
61              Formats the given number for printing, with the specified preci‐
62              sion.  (See below for how precision is interpreted). All numbers
63              are formatted in floating-point E format.
64

PARAMETERS

66       expr   Expression to evaluate. The syntax for expressions is  the  same
67              as  it  is in Tcl, but the set of operations is smaller. See Ex‐
68              pressions below for details.
69
70       number The object returned by an earlier invocation of math::exact::ex‐
71              actexpr
72
73       precision
74              The  requested  'precision' of the result. The precision is (ap‐
75              proximately) the absolute value of the binary exponent plus  the
76              number  of  bits of the binary significand. For instance, to re‐
77              turn results to IEEE-754 double precision, 56 bits plus the  ex‐
78              ponent  are  required.  Numbers between 1/2 and 2 will require a
79              precision of 57; numbers between 1/4 and 1/2 or between 2 and  4
80              will  require 58; numbers between 1/8 and 1/4 or between 4 and 8
81              will require 59; and so on.
82

EXPRESSIONS

84       The math::exact::exactexpr command accepts expressions in a  subset  of
85       Tcl's syntax. The following components may be used in an expression.
86
87       •      Decimal integers.
88
89       •      Variable  references with the dollar sign ($).  The value of the
90              variable must be the result of another call to  math::exact::ex‐
91              actexpr.  The  reference count of the value will be increased by
92              one for each position at which it appears in the expression.
93
94       •      The exponentiation operator (**).
95
96       •      Unary plus (+) and minus (-) operators.
97
98       •      Multiplication (*) and division (/) operators.
99
100       •      Parentheses used for grouping.
101
102       •      Functions. See Functions below for the functions that are avail‐
103              able.
104

FUNCTIONS

106       The following functions are available for use within exact real expres‐
107       sions.
108
109       acos(x)
110              The inverse cosine of x. The result  is  expressed  in  radians.
111              The absolute value of x must be less than 1.
112
113       acosh(x)
114              The inverse hyperbolic cosine of x.  x must be greater than 1.
115
116       asin(x)
117              The  inverse sine of x. The result is expressed in radians.  The
118              absolute value of x must be less than 1.
119
120       asinh(x)
121              The inverse hyperbolic sine of x.
122
123       atan(x)
124              The inverse tangent of x. The result is expressed in radians.
125
126       atanh(x)
127              The inverse hyperbolic tangent of x.  The absolute  value  of  x
128              must be less than 1.
129
130       cos(x) The cosine of x. x is expressed in radians.
131
132       cosh(x)
133              The hyperbolic cosine of x.
134
135       e()    The base of the natural logarithms = 2.71828...
136
137       exp(x) The exponential function of x.
138
139       log(x) The natural logarithm of x. x must be positive.
140
141       pi()   The value of pi = 3.15159...
142
143       sin(x) The sine of x. x is expressed in radians.
144
145       sinh(x)
146              The hyperbolic sine of x.
147
148       sqrt(x)
149              The square root of x. x must be positive.
150
151       tan(x) The tangent of x. x is expressed in radians.
152
153       tanh(x)
154              The hyperbolic tangent of x.
155

SUMMARY

157       The  math::exact::exactexpr command provides a system that performs ex‐
158       act arithmetic over computable real numbers, representing  the  numbers
159       as  algorithms  for successive approximation.  An example, which imple‐
160       ments the high-school quadratic formula, is shown below.
161
162
163              namespace import math::exact::exactexpr
164              proc exactquad {a b c} {
165                  set d [[exactexpr {sqrt($b*$b - 4*$a*$c)}] ref]
166                  set r0 [[exactexpr {(-$b - $d) / (2 * $a)}] ref]
167                  set r1 [[exactexpr {(-$b + $d) / (2 * $a)}] ref]
168                  $d unref
169                  return [list $r0 $r1]
170              }
171
172              set a [[exactexpr 1] ref]
173              set b [[exactexpr 200] ref]
174              set c [[exactexpr {(-3/2) * 10**-12}] ref]
175              lassign [exactquad $a $b $c] r0 r1
176              $a unref; $b unref; $c unref
177              puts [list [$r0 asFloat 70] [$r1 asFloat 110]]
178              $r0 unref; $r1 unref
179
180       The program prints the result:
181
182
183              -2.000000000000000075e2 7.499999999999999719e-15
184
185       Note that if IEEE-754 floating point  had  been  used,  a  catastrophic
186       roundoff  error  would yield a smaller root that is a factor of two too
187       high:
188
189
190              -200.0 1.4210854715202004e-14
191
192       The invocations of exactexpr should be  fairly  self-explanatory.   The
193       other  commands  of  note  are  ref  and unref. It is necessary for the
194       caller to keep track of references to exact expressions - to  call  ref
195       every  time an exact expression is stored in a variable and unref every
196       time the variable goes out of scope or  is  overwritten.   The  asFloat
197       method emits decimal digits as long as the requested precision supports
198       them. It terminates when the requested precision yields an  uncertainty
199       of more than one unit in the least significant digit.
200

CATEGORY

202       Mathematics
203
205       Copyright (c) 2015 Kevin B. Kenny <kennykb@acm.org>
206       Redistribution permitted under the terms of the Open Publication License <http://www.opencontent.org/openpub/>
207
208
209
210
211tcllib                               1.0.1                      math::exact(n)
Impressum