TMath TMath 0.2: A Tcl Interface to MATLAB and Mathematica Brian L. Evans (1) and Steve X. Gu (2) (1) Dept. of ECE, The University of Texas at Austin, Austin, TX 78712-1084 E-mail: bevans@ece.utexas.edu, Web: http://www.ece.utexas.edu/~bevans (2) NORTEL, 2305 Mission College Blvd., Santa Clara, CA. 95052-8173 E-mail: stevegu@nt.com with code from Joseph T. Buck, Wan-Teh Chang, Christopher X. Hylands, Edward A. Lee, David G. Messerschmitt, Jose Luis Pino, Kennard D. White. 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 07/08/97 -- Table of Contents -- 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 1.0 Introduction 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 two new Tcl commands matlab and mathematica, a framework for registering Tcl commands implemented as C++ methods, C++ interfaces for MATLAB and Mathematica, and C++ objects to control multiple MATLAB and Mathematica processes. 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. TMath is based on an implementation [Eva95] developed for the Ptolemy design environment [Pin95] for specifying, simulating, and synthesizing signal processing and communications systems. 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., ftp://ptolemy.eecs.berkeley.edu/pub/misc/tmath/tmath0.2. 2.0 System Requirements TMath works with the following software: MATLAB 4 or 5 Mathematica 2.2 or 3.0 Tcl 7.4, 7.5, or 7.6 The pre-compiled binaries are compiled with MATLAB 5.0 Mathematica 3.0 Tcl 7.6 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. 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. TMath will compile on the following Unix architectures: Sparc Solaris 2.4, Solaris 2.5, and Sun OS 4.1.3 SGI Irix 5.3 and Irix 6.0 HP HP-UX 9 and HP-UX 10 DEC Alpha DEC Unix OSF 3.2 IBM RS/6000 AIX 3.2.5 and AIX 4.1 PC Linux Slackware 3.0, NetBSD 1.0, and FreeBSD 2.1-Stable The disk space requirements are compilation from sources: 1 Mb + 1.5 Mb/architecture installed installation of tmath binary: 50 Kb + 500 Kb/architecture installed shared libraries: 4.5 Mb/architecture To compile TMath, you will need the GNU make utility. To check if GNU make is on your path, type the following in Unix: make -v This command should return GNU Make version 3.74, by Richard Stallman and Roland McGrath.... If you get something other than GNU make, e.g. make: Fatal error: Unknown option `-v' 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. 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: which tclsh 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 g++ --version 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 USE_GNU_COMPILER_272 = 1 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 USE_GNU_COMPILER = 1 In this case, the arch 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 setenv PTARCH `$TMATH_HOME/bin/ptarch`.cfront 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. 3.0 Installation Before proceeding, make sure that you have the proper system requirements and settings, as described in Section 2.0. 3.1 Installation of pre-compiled binaries 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 tmath0.2.sol2.tar.Z tmath0.2.hppa.tar.Z Installing them is simple. First, uncompress tmath0.2.sol2.tar.Z tar xf tmath0.2.sol2.tar Then, set the TMATH_HOME Unix environment variable to the full pathname where you have installed tmath. For example, setenv TMATH_HOME /users/tmath Finally, run the tmath program: $TMATH_HOME/bin/tmath where arch is the architecture you are on, e.g. sol2.5 or hppa. If tmath complains about TCL_LIBRARY, then you can try the following: setenv TCL_LIBRARY $TMATH_HOME/lib/tcl echo >$TCL_LIBRARY/init.tcl to create an empty init.tcl file on the Tcl library path. Then, rerun the tmath program. 3.2 Installation from sources First, extract the contents of the TMath release: uncompress tmath0.2.src.tar.Z tar xf tmath0.2.src.tar The 'tar xf' command will create a subdirectory called 'tmath'. Second, set the TMATH_HOME Unix environment variable to the full pathname where you have installed tmath. For example, setenv TMATH_HOME /users/tmath 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 TCL_ROOT = /usr/sww GNULIB should be set to the directory in which the GNU C/C++ libraries are installed, for example GNULIB = /users/ptolemy/gnu/$(PTARCH)/lib 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. Fourth, build the tmath binary: cd tmath make all 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.arch directory. The tmath binary will be called by the tmath script, which you can run by typing bin/tmath After you have built tmath, only the bin, bin.arch, lib, and lib.arch directories are required for tmath to run. You may want to delete the obj.arch, 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 arch setting is. 4.0 New Tcl Commands TMath introduces two new Tcl commands, matlab and mathematica. They are implemented as C++ methods. The commands have a similar syntax: matlab command ?arg1? ?arg2? ... mathematica command ?arg1? ?arg2? ... The matlab command controls the interaction with a shared MATLAB process. The possible commands and arguments are: matlab end terminate a session with MATLAB matlab eval script evaluate a MATLAB script and print the result matlab get name ?script? evaluate a MATLAB script and get the named MATLAB matrix as Tcl lists of numbers matlab getpairs name ?script? evaluate a MATLAB script and get the named MATLAB matrix as ordered pairs of numbers matlab send script evaluate a MATLAB script and suppress the output matlab set name rows cols real ?imag? set the named MATLAB matrix with real and imaginary values matlab start start a new MATLAB session matlab status return the status of the Tcl/MATLAB connection (0 means connected, -1 means not initialized, and 1 means error) matlab unset name unset the named MATLAB matrix The mathematica command controls the interaction with a shared Mathematica process. The possible commands and arguments are mathematica end terminate a session with Mathematica mathematica eval ?script? evaluate a Mathematica script and print the result mathematica get name ?script? evaluate a Mathematica script and get the named Mathematica variable as a Tcl string mathematica send script evaluate a Mathematica script and suppress the output mathematica start start a new Mathematica session mathematica status return the status of the Tcl/Mathematica connection (0 means connected, -1 means not initialized, and 1 means error) Other Tcl commands are introduced by means of the lib/tcl/mathexpr.tcl Tcl script. They are listed below. listApplyExpression tclexpr list 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) }. makeOrderedPairs x-values ?y-values? Converts two lists, x-values and y-values, into ordered pairs; e.g., makeOrderedPairs "1 2 3" "3 2 1" returns "(1,3) (2,2) (3,1)". max x1 x2 ... Computes the maximum of the arguments according to the greater than operator, which also compares strings. min x1 x2 ... Computes the minimum of the arguments according to the less than operator, which also compares strings. range min max ?increment? 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. rangeApplyExpression tclexpr min max ?increment? 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) }. sign x 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. Of these commands, only the makeOrderedPairs command is used to support new matlab and mathematica Tcl commands. 5.0 Examples 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. 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 matlab start mathematica start Generate a simple plot of a straight line in MATLAB and Mathematica by matlab send { plot( [0 1 2 3] ) } mathematica send { Plot[ x, {x, 0, 3} ] } 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: mathematica eval { Plot[x, {x, 0, 3}] } -Graphics- We can use MATLAB to compute eigenvalues of a matrix: matlab getpairs c { c = eig( [1 2; 2 1] ) } -1.0 3.0 Similarly, we can use Mathematica to derive formulas to be used as parameters: mathematica get c {c=Integrate[A x, {x, 0, 1}]} A/2 To terminate the connection, use matlab end mathematica end 6.0 References [Eva95] B. L. Evans, S. X. Gu, A. Kalavade, and E. A. Lee, "Symbolic Computation in System Simulation and Design," Invited Paper, Proc. of SPIE Int. Sym. on Advanced Signal Processing Algorithms, Architectures, and Implementations, July 9-16, 1995, San Diego, CA, pp. 396-407. http://ptolemy.eecs.berkeley.edu/papers/spie95symcomp/ [Han96] Duane Hanselman and Bruce Littlefield, Mastering MATLAB, Prentice Hall, ISBN 0-13-191594-0, 542 pages, 1996. [Pin95] J. L. Pino, S. Ha, E. A. Lee, and J. T. Buck, ``Software Synthesis for DSP Using Ptolemy,'' Journal on VLSI Signal Processing, vol. 9, no. 1, pp. 7-21, Jan., 1995. http://ptolemy.eecs.berkeley.edu/papers/jvsp_codegen/ [Wol91] Stephen Wolfram, Mathematica: A System for Doing Mathematics by Computer, Addison-Wesley, ISBN 0-201-51502-4, 1991. 7.0 Copyright TMath is covered by the standard freely distributable U.C. Berkeley copyright shown below. Copyright (c) 1990-1997 The Regents of the University of California. All rights reserved. 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. 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. 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. 8.0 Acknowledgements 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. 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. 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. For more information, visit the following Web sites and news groups: MATLAB: http://www.mathworks.com/, comp.soft-sys.matlab Mathematica: http://www.wolfram.com/, comp.soft-sys.math.mathematica Ptolemy: http://ptolemy.eecs.berkeley.edu/, comp.soft-sys.ptolemy