ptweb/tmath.html at master · icyphy/ptweb · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
<html>
                                  <head><title>TMath</title></head>
<body><center><h1>
            TMath 0.2: A Tcl Interface to MATLAB and Mathematica
</h1><h2>
                Brian L. Evans (1) and Steve X. Gu (2)
</h2>
(1) Dept. of ECE, The University of Texas at Austin, Austin, TX 78712-1084
E-mail: bevans at ece utexas edu , Web: <a href="http://www.ece.utexas.edu/~bevans">http://www.ece.utexas.edu/~bevans</a>
<p>
(2) NORTEL, 2305 Mission College Blvd., Santa Clara, CA. 95052-8173
                      E-mail: stevegu at nt com

<p>
  with code from Joseph T. Buck, Wan-Teh Chang, Christopher X. Hylands,
 Edward A. Lee, David G. Messerschmitt, Jose Luis Pino, Kennard D. White.
<p>
           with help from Steven Eddins at The MathWorks, Inc.,
        John Novak and Todd Gayley at Wolfram Research, Inc., and
          Wade Schwartzkopf at The University of Texas at Austin
<p>

                               07/08/97

<p>
                      -- Table of Contents --
<pre>
           1.0 Introduction           5.0 Examples
           2.0 System Requirements    6.0 References
           3.0 Installation           7.0 Copyright
           4.0 New Tcl Commands       8.0 Acknowledgements
</pre></center>
<p>


<h1>
1.0 Introduction
</h1>
The TMath package is an extension to Tcl that allows Tcl to control
MATLAB [Han96] and Mathematica [Wol91] processes and to evaluate
MATLAB 5.0 and Mathematica 3.0 commands.  It provides
<p><ul>
    <li>two new Tcl commands matlab and mathematica,<br>
    <li>a framework for registering Tcl commands implemented as C++ methods,<br>
    <li>C++ interfaces for MATLAB and Mathematica, and<br>
    <li>C++ objects to control multiple MATLAB and Mathematica processes.<br>
</ul><p>
TMath does not use pipes to control MATLAB and Mathematica processes.
Instead, it uses the MATLAB Engine interface and the Mathematica
MathLink protocol.  The Engine interface is based on memory-to-memory
writes and reads.  MathLink is based on exchanging data packets.
<p>
TMath is based on an implementation [Eva95] developed for the Ptolemy
design environment [Pin95] for specifying, simulating, and synthesizing
signal processing and communications systems.
<p>
TMath source code and pre-built binaries are available from the FTP
site ptolemy.eecs.berkeley.edu in the directory pub/misc/tmath/tmath0.2,
i.e., <a href="http://ptolemy.eecs.berkeley.edu/other/tmath/tmath0.2">http://ptolemy.eecs.berkeley.edu/other/tmath/tmath0.2</a>.
<p>


<h1>
2.0 System Requirements
</h1><p>
TMath works with the following software:
<p><ul>
    <li>MATLAB 4 or 5<br>
    <li>Mathematica 2.2 or 3.0<br>
    <li>Tcl 7.4, 7.5, or 7.6<br>
</ul><p>
The pre-compiled binaries are compiled with
<p><ul>
    <li>MATLAB 5.0<br>
    <li>Mathematica 3.0<br>
    <li>Tcl 7.6
</ul><p>
under Solaris 2.5.1 and HP-UX 10.20 using version 2.7.2.2 of the GNU
C/C++ compiler.  For the pre-compiled binaries to run, Matlab 5.0 must
be installed on the local machine.
<p>
TMath includes dummy include files and libraries that allow TMath
to compile and run without Mathematica being installed locally.
If the code is compiled with Matlab 5.0, then Matlab must be
present for tmath to run.  During compilation, TMath requires include
files and libraries from either version 7.4, 7.5, or 7.6 of Tcl.
At startup, TMath sources the standard init.tcl Tcl script.
<p>
TMath will compile on the following Unix architectures:
<p><ul>
    <li>Sparc        Solaris 2.4, Solaris 2.5, and Sun OS 4.1.3<br>
    <li>SGI          Irix 5.3 and Irix 6.0<br>
    <li>HP           HP-UX 9 and HP-UX 10<br>
    <li>DEC Alpha    DEC Unix OSF 3.2<br>
    <li>IBM RS/6000  AIX 3.2.5 and AIX 4.1<br>
    <li>PC           Linux Slackware 3.0, NetBSD 1.0, and FreeBSD 2.1-Stable<br>
</ul><p>
The disk space requirements are
<p><ul>
    <li>compilation from sources: 1 Mb + 1.5 Mb/architecture installed<br>
    <li>installation of tmath binary: 50 Kb + 500 Kb/architecture installed<br>
    <li>shared libraries: 4.5 Mb/architecture
</ul><p>
To compile TMath, you will need the GNU make utility.  To check if GNU
make is on your path, type the following in Unix:
<pre>
    make -v
</pre>
This command should return
<pre>
    GNU Make version 3.74, by Richard Stallman and Roland McGrath....
</pre>
If you get something other than GNU make, e.g.
<pre>
    make: Fatal error: Unknown option `-v'
</pre>
then the default Unix make utility is the first 'make' to appear on
your Unix path.  Move the GNU directory before /bin/make (and before
/usr/ccs/bin if it is listed) in the path specification in your ~/.cshrc
file.  The GNU directory is sometimes called /usr/local/gnu/bin.  If GNU
make is not installed, then ask your system administrator to install it.
GNU tools are on the FTP site is prep.ai.mit.edu in /pub/gnu.
<p>
To compile TMath, you will need to have Tcl installed and know where
it is installed.  If you do not know where it has been installed, type
the following in Unix to see if tclsh exists on your path:
<pre>
    which tclsh
</pre>
You will also need a C++ compiler.  The makefiles will by default
expect version 2.7.2 of the GNU C/C++ compiler, g++.  You can find out
which version of g++ you have by typing
<pre>
    g++ --version
</pre>
If g++ does not recognize the --version option, then it is too
old to use.  If you are using the GNU C/C++ 2.6 compiler, then
edit the file 'tmath/settings.mk' and comment out the line
<pre>
    USE_GNU_COMPILER_272 = 1
</pre>
You can also use the standard C++ compilers on Sparc and HP workstations.
To do this, edit the 'tmath/settings.mk' and comment out the line
<pre>
    USE_GNU_COMPILER = 1
</pre>
In this case, the <em>arch</em> will be appended with the string
'cfront' signifying that it is a non-GNU compiler.  The C++ compiler
will be invoked by using the CC command.  Once the cfront version
has been built, set
<pre>
    setenv PTARCH `$TMATH_HOME/bin/ptarch`.cfront
</pre>
<p>
The release has been tested with the GNU C/C++ 2.7.2.2 compiler under
Solaris 2.5.1 and HP-UX 10.20.  It has also been tested using the CC
compiler under Solaris 2.5.1 and HP-UX 10.20.
<p>


<h1>
3.0 Installation
</h1><p>
Before proceeding, make sure that you have the proper system
requirements and settings, as described in Section 2.0.
<p>
<h2>
3.1 Installation of pre-compiled binaries
</h2>
Pre-compiled binaries of the tmath program and files it requires are
available for the Solaris 2.5.1 and HP-UX 10.20 architectures as the
compressed archived files
<p><ul>
    <li>tmath0.2.sol2.tar.Z<br>
    <li>tmath0.2.hppa.tar.Z<br>
</ul><p>
Installing them is simple.  First,
<pre>
    uncompress tmath0.2.sol2.tar.Z
    tar xf tmath0.2.sol2.tar
</pre>
Then, set the <code>TMATH_HOME</code> Unix environment variable to the full pathname
where you have installed tmath.  For example,
<pre>
    setenv TMATH_HOME /users/tmath
</pre>
Finally, run the tmath program:
<pre>
    $TMATH_HOME/bin/tmath
</pre>
where <em>arch</em> is the architecture you are on, e.g. sol2.5 or hppa.
If tmath complains about <code>TCL_LIBRARY</code>, then you can try the following:
<pre>
    setenv TCL_LIBRARY $TMATH_HOME/lib/tcl
    echo >$TCL_LIBRARY/init.tcl
</pre>
to create an empty init.tcl file on the Tcl library path.  Then, rerun
the tmath program.
<p>
<h2>
3.2 Installation from sources
</h2>
First, extract the contents of the TMath release:
<pre>
    uncompress tmath0.2.src.tar.Z
    tar xf tmath0.2.src.tar
</pre>
The 'tar xf' command will create a subdirectory called 'tmath'.
<p>
Second, set the <code>TMATH_HOME</code> Unix environment variable to the full pathname
where you have installed tmath.  For example,
<pre>
    setenv TMATH_HOME /users/tmath
</pre>
Third, edit 'tmath/override.mk', which will be included by other make
files, to set the TCL_ROOT and GNULIB variables.  TCL_ROOT should be
set to the directory that contains the tcl sub-directory (i.e., the
parent directory of where Tcl is installed).  For example, if Tcl is
installed in /usr/sww/lib, then
<pre>
    TCL_ROOT = /usr/sww
</pre>
GNULIB should be set to the directory in which the GNU C/C++ libraries
are installed, for example
<pre>
    GNULIB = /users/ptolemy/gnu/$(PTARCH)/lib
</pre>
Note that PTARCH is a make variable that is automatically set to the
machine architecture (sol2.5, hppa, etc.).  Its value is returned
by the 'bin/ptarch' script.
<p>
Fourth, build the tmath binary:
<pre>
    cd tmath
    make all
</pre>
The 'make all' command will first build the architecture-specific
directories (e.g. bin.sol2.5, lib.sol2.5, and obj.sol2.5 for Solaris 2.5
architectures), then compile tmath, and finally install it in the
bin.<em>arch</em> directory.  The tmath binary will be called by the tmath
script, which you can run by typing
<pre>
    bin/tmath
</pre>
After you have built tmath, only the bin, bin.<em>arch</em>, lib, and lib.<em>arch</em>
directories are required for tmath to run.  You may want to delete the
obj.<em>arch</em>, mk, and src directories if you do not plan to recompile
tmath in the future.  The bin directory holds several shell scripts, such
as ptarch which determines what the <em>arch</em> setting is.
<p>


<h1>
4.0 New Tcl Commands
</h1>
TMath introduces two new Tcl commands, matlab and mathematica.  They
are implemented as C++ methods.  The commands have a similar syntax:
<pre>
    matlab <em>command</em> <em>?arg1?</em> <em>?arg2?</em> ...
    mathematica <em>command</em> <em>?arg1?</em> <em>?arg2?</em> ...
</pre>
The matlab command controls the interaction with a shared MATLAB process.
The possible commands and arguments are:
<dl>
    <dt>matlab end
        <dd>terminate a session with MATLAB
<p>
    <dt>matlab eval <em>script</em>
        <dd>evaluate a MATLAB script and print the result
<p>
    <dt>matlab get <em>name</em> <em>?script?</em>
        <dd>evaluate a MATLAB script and get the named MATLAB matrix as
        Tcl lists of numbers
<p>
    <dt>matlab getpairs <em>name</em> <em>?script?</em>
        <dd>evaluate a MATLAB script and get the named MATLAB matrix as ordered
        pairs of numbers
<p>
    <dt>matlab send <em>script</em>
        <dd>evaluate a MATLAB script and suppress the output
<p>
    <dt>matlab set <em>name</em> <em>rows</em> <em>cols</em> <em>real</em> <em>?imag?</em>
        <dd>set the named MATLAB matrix with real and imaginary values
<p>
    <dt>matlab start
        <dd>start a new MATLAB session
<p>
    <dt>matlab status
        <dd>return the status of the Tcl/MATLAB connection (0 means connected,
        -1 means not initialized, and 1 means error)
<p>
    <dt>matlab unset <em>name</em>
        <dd>unset the named MATLAB matrix
</dl>
The mathematica command controls the interaction with a shared Mathematica
process. The possible commands and arguments are
<dl>
    <dt>mathematica end
        <dd>terminate a session with Mathematica
<p>
    <dt>mathematica eval <em>?script?</em>
        <dd>evaluate a Mathematica script and print the result
<p>
    <dt>mathematica get <em>name</em> <em>?script?</em>
        <dd>evaluate a Mathematica script and get the named Mathematica
        variable as a Tcl string
<p>
    <dt>mathematica send <em>script</em>
        <dd>evaluate a Mathematica script and suppress the output
<p>
    <dt>mathematica start
        <dd>start a new Mathematica session
<p>
    <dt>mathematica status
        <dd>return the status of the Tcl/Mathematica connection (0 means
        connected, -1 means not initialized, and 1 means error)
</dl>
Other Tcl commands are introduced by means of the lib/tcl/mathexpr.tcl
Tcl script.  They are listed below.
<dl>
    <dt>listApplyExpression <em>tclexpr</em> <em>list</em>
        <dd>Produces a new list by applying each item in list to the
        tclexpr by substituting for the variable i in tclexpr.  The
        tclexpr should be in an unevaluated form, e.g. { cos($i) }.
<p>
    <dt>makeOrderedPairs <em>x-values</em> ?<em>y-values</em>?
        <dd>Converts two lists, <em>x-values</em> and <em>y-values</em>, into ordered
        pairs; e.g., makeOrderedPairs "1 2 3" "3 2 1" returns
        "(1,3) (2,2) (3,1)".
<p>
    <dt>max <em>x1</em> <em>x2</em> ...
        <dd>Computes the maximum of the arguments according to the greater
        than operator, which also compares strings.
<p>
    <dt>min <em>x1</em> <em>x2</em> ...
        <dd>Computes the minimum of the arguments according to the less
        than operator, which also compares strings.
<p>
    <dt>range <em>min</em> <em>max</em> ?<em>increment</em>?
        <dd>Produces an ordered list of numbers running from min to max
        at increments of increment.  If the sequence of numbers will
        never reach max, then the routine will return an empty list.
<p>
    <dt>rangeApplyExpression <em>tclexpr</em> <em>min</em> <em>max</em> ?<em>increment</em>?
        <dd>Evaluate tclexpr at values of i running from min to max at
        increments of increment to produce a list.  If the sequence
        of numbers will never reach max, then the routine will return
        an empty list.  The tclexpr should be in an unevaluated form,
        e.g. { cos($i) }.
<p>
    <dt>sign <em>x</em>
        <dd>Returns 1 if x is greater than 0, -1 if x is less than 0, and
	0 otherwise.  Comparison is based on the Tcl operators less than
	and greater than, which also compare strings.
</dl>
Of these commands, only the makeOrderedPairs command is used to support
new matlab and mathematica Tcl commands.
<p>


<h1>
5.0 Examples
</h1>
This section presents examples of using the new matlab and mathematica
Tcl commands defined by TMath.  For an example of how we interfaced the
C++ simulation program Ptolemy to MATLAB, see the files "MatlabPtIfc.h"
and "MatlabPtIfc.cc" in the interfaces/ptolemy directory.  Note that
these files will not compile because we have not shipped the files
on which they depend.
<p>
Once TMath is running, you can start, interact with, and end MATLAB
and Mathematica processes.  To initiate a connection to a MATLAB and
Mathematica process, use
<pre>
    matlab start
    mathematica start
</pre>
Generate a simple plot of a straight line in MATLAB and Mathematica by
<pre>
    matlab send { plot( [0 1 2 3] ) }
    mathematica send { Plot[ x, {x, 0, 3} ] }
</pre>
Graphics are displayed in a separate window, just as the command line tty
interfaces to MATLAB and Mathematica display them.  The send command
suppresses the output normally returned by interacting with the program
using the command interface.  The eval command, on the other hand, returns
the dialog:
<pre>
    mathematica eval { Plot[x, {x, 0, 3}] }
    -Graphics-
</pre>
We can use MATLAB to compute eigenvalues of a matrix:
<pre>
    matlab getpairs c { c = eig( [1 2; 2 1] ) }
    -1.0 3.0
</pre>
Similarly, we can use Mathematica to derive formulas to be used as parameters:
<pre>
    mathematica get c {c=Integrate[A x, {x, 0, 1}]}
    A/2
</pre>
To terminate the connection, use
<pre>
    matlab end
    mathematica end
</pre>
<p>


<h1>
6.0 References
</h1><ul><li>
[Eva95] B. L. Evans, S. X. Gu, A. Kalavade, and E. A. Lee, "Symbolic
Computation in System Simulation and Design," Invited Paper, <em>Proc. of SPIE
Int. Sym. on Advanced Signal Processing Algorithms, Architectures, and
Implementations</em>, July 9-16, 1995, San Diego, CA, pp. 396-407.
<a href="http://ptolemy.eecs.berkeley.edu/publications/papers/95/spie95symcomp/">http://ptolemy.eecs.berkeley.edu/papers/95/spie95symcomp/</a><p>
<li>
[Han96] Duane Hanselman and Bruce Littlefield, <em>Mastering MATLAB</em>, Prentice
Hall, ISBN 0-13-191594-0, 542 pages, 1996.<p>
<li>
[Pin95] J. L. Pino, S. Ha, E. A. Lee, and J. T. Buck, ``Software Synthesis
for DSP Using Ptolemy,'' <em>Journal on VLSI Signal Processing</em>, vol. 9, no. 1,
pp. 7-21, Jan., 1995.  <a href="http://ptolemy.eecs.berkeley.edu/publications/papers/95/jvsp_codegen/">http://ptolemy.eecs.berkeley.edu/publications/papers/95/jvsp_codegen/</a><p>
<li>
[Wol91] Stephen Wolfram, <em>Mathematica: A System for Doing Mathematics by
Computer</em>, Addison-Wesley, ISBN 0-201-51502-4, 1991.
</ul>
<p>


<h1>
7.0 Copyright
</h1>
TMath is covered by the standard freely distributable U.C. Berkeley
copyright shown below.
<p>
Copyright (c) 1990-1997 The Regents of the University of California.
All rights reserved.
<p>
Permission is hereby granted, without written agreement and without
license or royalty fees, to use, copy, modify, and distribute this
software and its documentation for any purpose, provided that the above
copyright notice and the following two paragraphs appear in all copies
of this software.
<p>
IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
<p>
THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
ENHANCEMENTS, OR MODIFICATIONS.
<p>


<h1>
8.0  Acknowledgements
</h1>
TMath is based on code from the Ptolemy design environment.  The code
that was used was authored by Joseph T. Buck, Wan-Teh Chang, Christopher
X. Hylands, Edward A. Lee, David G. Messerschmitt, Jose Luis Pino, and
Kennard D. White.
<p>
The Ptolemy project is supported by the Advanced Research Projects Agency
and the U.S. Air Force (under the RASSP program, contract F33615-93-C-1317),
Semiconductor Research Corporation (project 95-DC-324), National Science
Foundation (MIP-9201605), the State of California MICRO program, and the
following companies:  Cadence, Dolby Laboratories, Hitachi, Lucky/Goldstar,
Mentor Graphics, Mitsubishi, Motorola, NEC, NORTEL (formerly Bell Northern
Research), Pacific Bell, Philips, and Rockwell.
<p>
In dealing with the finer points of interfacing to MATLAB, Steven Eddins
at The MathWorks, Inc., was very helpful.  For the interface to Mathematica,
the MathLink tutorial by Todd Gayley and proof-of-concept code by John
Novak were very helpful.  Todd Gayley and John Novak are at Wolfram
Research, Inc.
<p>
For more information, visit the following Web sites and news groups:
<ul>
<li>MATLAB: <a href="http://www.mathworks.com/">http://www.mathworks.com/</a>, comp.soft-sys.matlab
<li>Mathematica: <a href="http://www.wolfram.com/">http://www.wolfram.com/</a>, comp.soft-sys.math.mathematica
<li>Ptolemy: <a href="http://ptolemy.eecs.berkeley.edu/">http://ptolemy.eecs.berkeley.edu/</a>, comp.soft-sys.ptolemy
</ul><hr></body></html>