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

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:

The pre-compiled binaries are compiled with

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:

The disk space requirements are

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

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

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: