Contents






3 Where to Find Information
5 Running Mathematica
10 Textual Output in Mathematica
11 Editing Input for Mathematica
14 Using Mathematica from a Terminal
14 Using Mathematica in Batch Mode
15 Using Mathematica Remotely
18 Special Topic: Very Large Calculations
19 Interfacing with Other Programs
31 Using Mathematica's Ancillary Files










Mathematica:
Running the Kernel under Unix Systems





Mathematica® is a system for doing mathematical computation that runs on many kinds of computer.  The basic functionality of Mathematica is the same on all computers, but the way that the user, and external programs, interact with Mathematica can be different.  On the NeXT Computer, Mathematica can be run using the sophisticated NeXT Front End for Mathematica, which lets you create and save your text, computations and graphics in Notebook form.  You can also use Mathematica from a terminal window or shell, by typing the math command at any prompt.  In addition to this, Mathematica can be run remotely from another computer, and can be used in connection with independent programs.  This manual is for those want to know more about  Mathematica's behavior in the UNIX environment, and who want to use Mathematica on the NeXT without the Front End.




Where to Find Information



What This Manual Covers

This manual explains how to interact directly with Mathematica: how to start Mathematica, how to prepare input for it, how to format its output, how it displays graphics, and how to make other programs communicate with it.

This manual describes how to use Mathematica under the UNIX operating system.  Explanations and examples are given to show how to take advantage of the features offered by UNIX, notably the ability to communicate between simultaneously running processes.

This manual does not describe how to use Mathematica with the NeXT Front End for Mathematica, which you start up by double-clicking the Mathematica icon in the dock, and by opening the application named Mathematica.app in /NextApps.  For information on the use of the Mathematica Front End on the NeXT Computer, see /NextLibrary/Documentation/Mathematica/FrontEndSummary.

Mathematica can perform symbolic, numerical, and graphical computations. Symbolic and numerical results are displayed as sequences of characters, and look the same on any screen or terminal type.  Graphical results on the other hand are displayed differently on different kinds of terminal, in order to take advantage of the best resolution that each display device can achieve. Displaying and manipulating graphics are much easier when Mathematica is run under a graphical interface or ``windowing system''.  If you are using Mathematica to produce graphics on the NeXT Computer, you will probably want to do this with the Front End.



Other Sources of Information

The complete documentation kit for Mathematica on the NeXT Computer is available from Wolfram Research, Inc., P.O. Box 6059, Champaign, IL 61826-6059, USA (telephone: 217-398-0700).  This documentation kit may also be available from NeXT.

The general documentation for Mathematica is the book Mathematica: A System for Doing Mathematics by Computer, by Stephen Wolfram, published by Addison-Wesley in 1988 (paperback: ISBN 0-201-19330-2; hardback: ISBN 0-201-19334-5). This book comprises both a tutorial and an encyclopedic reference for Mathematica, and covers all those features of Mathematica that are the same from one version to another. You can obtain copies from your local bookstore, or directly from Addison-Wesley (1-800-447-2226).

At first, you will probably use Mathematica as a super-calculator, and the only Mathematica programs that you will use will be the ones that are distributed with Mathematica. At the point when you find yourself doing certain kinds of computation over and over, you will probably want to start writing Mathematica programs of your own. An excellent reference for Mathematica programming techniques is the book  Programming in Mathematica, written by Roman Maeder, and published by Addison-Wesley in 1989 (ISBN 0-201-51002-2).  This book begins with basic examples and progresses gradually to sophisticated techniques for writing efficient Mathematica code.



Elements of Mathematica documentation

General documentation Mathematica: A System for Doing
Mathematics by Computer (referred to as "The Mathematica Book")
UNIX-specific documentation Mathematica: Running the Kernel under the UNIX System (this manual)

Techniques for programming in Mathematica Programming in Mathematica

Front End documentation Mathematica: Summary of the Front End



Using Mathematica through Another Program

Note:  If you use Mathematica with a Front End, or as part of another program, some or all of this manual may be irrelevant to you.

This manual describes how to run Mathematica directly.  You can also run Mathematica indirectly as a subprogram embedded in another program. If this is how you are using Mathematica, then much of what is in this manual is irrelevant to you. Instead of reading this manual, you should look at the documentation that came with the program in which Mathematica is embedded.

Another common arrangement is to have Mathematica connected, as it is on the NeXT Computer, to a ``Front End'' that provides a sophisticated user interface, perhaps specific to a particular application area. While the computational aspects of Mathematica, as described in The Mathematica Book, are unaffected by the presence of the Front End, almost all the details of usage described in this manual may be changed.



Because versions of Mathematica running on different types of computer are all compatible, you can run Mathematica on one computer, with a Front End running on a separate computer, connected, for example, by a network.  The later section "Using Mathematica Remotely" describes how to connect Mathematica to a remote Front End; if you are using Mathematica this way you may need to read this section even if the other parts of this manual are irrelevant.




Running Mathematica


Summary

Running Mathematica

Starting Mathematica type math at a UNIX prompt
Terminating an input expression press Return
Interrupting Mathematica type the Intr character (probably Control-C)
Exiting Mathematica type Quit (note capitalization) at a Mathematica prompt


Setting Up the Environment

Tip:  If you run Mathematica by connecting to your computer from a remote computer, you should follow the instructions in the section "Using Mathematica Remotely", below.

Setting Terminal Parameters

You may need to reset certain terminal parameters in order to use Mathematica.  You can use the stty command to display the current settings of these parameters, and to reset them to new values.

stty all Command to display terminal parameter settings

This manual assumes that you are using the following settings:

Erase Del or Control-H

Kill Control-X

Intr Control-C

Quit Control-\

EOF Control-D



To set these terminal parameters to these values, you would use the following command.

stty erase '^?' kill '^X' intr '^C' quit '^\' eof '^D'

It is especially important to check the Erase and Kill settings, as the defaults for those parameters are respectively # and @, both of which characters are used by Mathematica. You will not be able to use Mathematica, even remotely through a Front End, if these characters are not set properly.

Starting Mathematica

To start Mathematica, simply type math. Mathematica will first give a message giving the Mathematica version number and copyright information, and then print out In[1]:=  to prompt you for your first line of input. Type Return at the end of your input. Mathematica will then process your input and give you a result.  If this does not work, ask your system administrator for help.

You type 2 + 2, followed by Return. In[1]:= 2 + 2
Mathematica works out the answer
and gives you the result. Out[1]= 4

Note: This section assumes that you are running Mathematica directly and interactively. If you use Mathematica through a Front End or as part of another program, what is described in this section, and in much of this manual, is probably irrelevant to you.



Possible Problems

Here are some problems you may encounter when you first try to run Mathematica. In this and subsequent problem sections, likely solutions are given after the description of each problem.

UNIX tells you that math is not found.

The Mathematica executable is probably not on your UNIX search path, or has not been correctly installed.



Input to Mathematica

When you have finished giving your input to Mathematica, you need simply press Return to have Mathematica start computing.

You may want to give Mathematica a command too long to fit on one line. This presents no difficulty.  Mathematica waits to start its computation until it sees a complete input expression.  If it sees the end of a line before it encounters the end of an expression, it simply waits for you to type more.

Mathematica continues to read lines of In[2]:= 2 + 3 +
input until it gets a complete expression. 4 + 5 +
6 + 7
Out[2]= 27

If you want to abandon a piece of input before it is complete, perhaps after you have typed several lines, you can do so by entering a single blank line (in other words, by typing Return twice in succession).

If Mathematica cannot understand a line of input that you give, it prints <retype line>.  You can then re-enter the line of input.  If you want to abandon your input, simply enter a blank line.

Mathematica prints <retype line> if it finds a syntactic error in your input (such as unbalanced parentheses).  It prints a ^ under the place at which it first detected the error.

You can always correct errors in your input to Mathematica by explicitly retyping your input, possibly with help from various graphical tools built into the display manager you are using.  The section "Editing Input for Mathematica" describes, however, how you can use your standard text editor to edit your input to Mathematica.



Recording Your Input

Specify that your input to Mathematica should be recorded

<<Utilities/Record.m append each line of input to the file math.record in the current directory

To be sure that none of your work is lost, you may want to keep a copy of each line of input you type to Mathematica.  The package Record.m appends each of your input lines to a file called math.record in your current directory.  This package is located in the Utilities subdirectory of the Mathematica Packages directory.

If you always want to keep a record of your Mathematica input, you should put <<Utilities/Record.m in your init.m initialization file.  (See ``Initialization Files'' in Section B.6 of The Mathematica Book.

Many versions of UNIX support the script command.  If the script command is available to you, you can use it to keep a complete copy of your Mathematica session, including both input and output.



Possible Problems

Here are some problems you may encounter in recording your input to Mathematica.

Input lines from different Mathematica jobs appear jumbled in the record file.

Each line of input is written to the record file as soon as you complete it.  If you have several Mathematica jobs running at once, then lines of input from different ones appear in exactly the order you typed them.

Mathematica prints Cannot open math.record.

You probably do not have write permission in your current directory.  In this case, Mathematica does not keep the math.record file.  Change to a directory where you do have write permission, and restart Mathematica.



Interrupting Mathematica

If you need to stop Mathematica in the middle of a calculation, you can type Control-C, the UNIX character.  Mathematica will print a list of options and prompt you for input.  If you then type the letter a, for ``abort'', Mathematica will try to abort your current calculation.  If you instead type exit, Mathematica will quit completely from the current session.

Interrupting Mathematica

Control-C stop a particular Mathematica calculation
Kill your window, or log out emergency exit
Control-\ kill Mathematica with core dump

It is sometimes difficult for Mathematica to stop when it is in the middle of a calculation.  There will often be a delay after you type Control-C before the menu appears.  Even if you then ask Mathematica to abort your calculation, there may be a long delay before Mathematica actually stops.

If all else fails, you can kill Mathematica by quitting the window that it is running in, or, in the very worst case, by logging out entirely.  If you know how, you can also kill Mathematica using the UNIX kill command from another window or another terminal.  You will have to kill not only the math process, but also mathexe, which is called from math.

Another way to kill your Mathematica job is to type Control-\ , the UNIX Quit character.  Under all normal circumstances, this should kill Mathematica immediately.  However, unless you have set up your environment so as not to allow core dumps, typing Control-\ will give a core dump. The core file for Mathematica can be many megabytes in size.  It may take a long time to dump, particularly over a network.  The core file will be named core.  You should remember to delete it.



A Possible Problem

Mathematica does not stop when you type Control-C

First, leave it for a minute or so.  If it still does not stop, you may have to kill your whole Mathematica job.



Exiting Mathematica

The command for exiting from Mathematica

Type Quit from within Mathematica

Make sure you have the correct capitalization of the word Quit, and press Return after it.

You cannot use Quit to kill Mathematica if it is in the middle of a calculation. See the previous section for information on how to kill Mathematica in this case.

You can also exit from Mathematica by pressing Control-D, the UNIX EOF character, unless this has specifically been disabled by setting $IgnoreEOF=True, as discussed in Section B.6 of The Mathematica Book.




Textual Output in Mathematica

Mathematica outputs mathematical expressions as text.  When Mathematica outputs a long expression, it must break the expression into several lines.  To do this, Mathematica must know how wide your screen or window is.

Unless your initialization file specifies otherwise, Mathematica starts by assuming a width of 78 characters.  You can find out how wide your screen or window actually is by executing the UNIX command stty all.  (When you are running over a network using rsh or rlogin, this command may sometimes give you incorrect results.)

Setting your line width

ResetMedium[PageWidth->n] assume a screen or window width of n characters

Mathematica continues to read lines of In[2]:= 2 + 3 +
input until it gets a complete expression. 4 + 5 +
6 + 7
Out[2]= 27


With this line width, the expression is In[3]:= t = Expand[ (1 + x) ^ 10 ]
broken onto two lines. 2        3        4
5 Out[3]= 1 + 10 x + 45 x  + 120 x  + 210 x  + 252 x  +
6        7       8       9    10
210 x  + 120 x  + 45 x  + 10 x  + x
This tells Mathematica that the page is 90 In[4]:= ResetMedium[PageWidth->90]
characters wide.
If the width you tell Mathematica to use is In[5]:= t
greater than the actual width of your 2        3        4
5
screen or window, output will wrap around 6        7       8       9    10
and be illegible. Out[3]= 1 + 10 x + 45 x + 120 x  + 210 x + 252 x + 210
x  + 120 x  + 45 x  + 10 x  +
10
x
This specifies a width of 40 characters. In[6]:= ResetMedium[PageWidth->40]
Now the output lines are shorter. In[7]:= t
2        3

Out[3]= 1 + 10 x + 45 x  + 120 x  +
4        5         6        7
210 x  + 252 x  +  210 x  + 120 x  +
8       9    10
45 x  + 10 x  + x




Editing Input for Mathematica


Introduction

There is no text editor built into Mathematica.  Different people like to use different editors, and we do not force everyone to learn and use a new editor.  Instead, Mathematica allows you to hook into the editor you already use.

Two ways to edit input for Mathematica

Maintain two windows: one for running your editor, and one for Mathematica.

Run your editor from inside Mathematica.



Editing in a Separate Window

When you are setting up complicated Mathematica definitions, you will often find it convenient to build up the definitions in a file, reading in each revision of the definitions as you produce it.

A convenient way to do this is to maintain two windows: one to edit your file, and one to run Mathematica.  Each time you get your definitions to a stage where you want to try them out, you can write out the file using your editor, and then read the latest version of the file into Mathematica.

Reading a file of definitions into Mathematica.

<<filename read a file into Mathematica


A Possible Problem

Revised definitions do not overwrite older ones.

In certain complicated cases, described in Section 2.2 of The Mathematica Book, Mathematica may not be able to tell whether a new definition for a function (named f, for example) should overwrite an older one you gave.  In such cases, Mathematica keeps both definitions, putting the newer one later.  If you want to make sure that Mathematica removes the old definitions, you can put Clear[f] at the top of your file.



Editing from Within Mathematica

Calling your editor from within Mathematica

Edit[ ] start your editor with an empty buffer; read in the expression you write out from your editor
Edit[expr] start your editor, with the input form of expr in the buffer
Edit[expr1, expr2, ...] start your editor, with the input form for a sequence of expressions in the buffer
EditIn[ ] start your editor, with the text of your latest input line in the buffer
EditIn[n] start your editor, with the text of In[n] in the buffer
EditIn[-n] start your editor, with the text of the input line n back in the buffer
EditDef[f1, f2, ...] start your editor, with the definitions of symbols f1, f2 , ... in the buffer
Recall[ ] display the input form of your last input line
Recall[n1, n2, ...] display the input expressions In[n1], In[n2], ...

When you evaluate the Mathematica function Edit[expr], Mathematica will start up your editor, placing the input form of expr in the edit buffer.  (Mathematica uses the shell environment variable EDITOR to tell which editor to call.  The default is vi.)

You can now use your editor to edit what is in the buffer.  When you have finished, you should exit your editor, saving what you have done.  (If you use vi, for example, you should use :wq to exit.)

Mathematica then reads back the contents of your editor buffer to use as input.  Note that Mathematica assigns each separate expression in the buffer to a different Mathematica input line In[n].  The results generated from these input lines are assigned to the corresponding Out[n].

Edit works by using a temporary file, with a name of the form /tmp/uniquename.  You may see this filename if your editor shows you what file it is editing.

Note that if you enter a line containing a syntax error directly into Mathematica, without using Edit, you will not be able to recover your input.  If you are trying to enter a long expression, it is therefore often a good idea to use Edit[ ].  If you make a mistake, you can then simply use your editor to correct it.  Edit will let you re-edit a particular line of input as many times as needed to get a correct form.

Note that if you call EditDef on a Protected symbol (such as a built-in function, as described in Section 2.2.18 of The Mathematica Book), then Mathematica puts the definition into your edit buffer, enclosing it in a comment.  You can make a new definition take effect by removing the (* and *), which delimit the comment, and then exiting your editor.  Of course, you can never modify the value of a Locked symbol.



Possible Problems

Here are some problems you may encounter when you edit from within Mathematica.

Your editor behaves strangely when called from Edit.

This is probably not the fault of Edit.  Try exiting from Mathematica and seeing whether your editor works as you expect in the window you are using to run Mathematica.

Your editor clears the screen when called from Edit.

If you use an editor that clears the screen on startup, such as vi, this will always happen.




Using Mathematica from a Terminal

You do not need to be using the main display of a NeXT Computer in order to run Mathematica. A standard character terminal will suffice.

Using the Mathematica command Edit, you can edit your Mathematica input as you would ordinary text.

You can use ResetMedium[PageWidth->n] to set the number of characters that Mathematica should generate on each output line, as discussed later in this manual in the section "Textual Output in Mathematica".  The default is 78 characters.

Even if your terminal has no graphics capabilities, you can still get some idea of what Mathematica graphics look like.  If you have a pure character display terminal, you can execute the command <<Terminal.m when you start Mathematica.  Then graphics output from Mathematica will be given as an array of characters.

You can also get Mathematica to produce Tektronix-emulation vector graphics output.  If you work at a terminal with Tektronix 4010 compatible vector graphics capabilities, execute the command <<Tek.m when you start Mathematica.  This will direct Mathematica to send vector graphics commands to your terminal when it produces graphics output.

Initializing graphics for terminal output

<<Terminal.m set up graphics output for a character display
<<Tek.m set up graphics output for a Tektronix 4010 emulation display




Using Mathematica in Batch Mode

Particularly when you are doing very large calculations, you may find it convenient to run Mathematica in batch mode.  You prepare a file with many lines of Mathematica input, then run it through Mathematica to produce output, which you store in another file.

The command to run in batch mode

math < infile > outfile run Mathematica in batch mode

Tip: A good alternative to batch mode in many situations is to set up an input file, then read the file into an interactive Mathematica session using <<filename.  One disadvantage of this is that you do not record the output from each of your input lines.

Some Mathematica functions that are useful in batch mode operation

AppendTo[$Echo, "stdout"] include input lines in output file

AppendTo[$Messages, "stderr"] print messages on standard error

AppendTo[$Urgent, "stderr"] see each input prompt as it is issued, together with any syntax error reports that are generated
Write["stderr", text] write text onto standard error
<<PSDirect.m write PostScript for graphics onto standard output

If you want to make sure that a batch calculation you run in Mathematica does not ``go out of control'' while you are not watching it, you can use the Mathematica functions TimeConstrained and MemoryConstrained, as discussed in Section 2.8 of The Mathematica Book.

Warning: Operations that require immediate user input do not work in batch mode.  Thus, for example,
Input and Debug do not work.  Control-C causes a batch mode Mathematica job to exit.


A Possible Problem

Multiple copies of In[n]:= are included in the output file.

This will happen whenever you have blank lines in your input file.




Using Mathematica Remotely


Main Program Running Remotely

If your computer is connected to a remote computer, you may want to run the main part of Mathematica on the remote computer, but still get graphics and other output on your computer. You can do this whether or not the remote computer is the same make and model or even from the same manufacturer as yours.

The details of using Mathematica remotely depend on the precise nature of the connection between the computers.  The basic idea, however, is to have output sent from the remote computer to your local computer for display.  Non-graphical output will appear on your screen in the usual way, as a sequence of characters.  To have graphics appear at your terminal, you will have to feed the PostScript form of the graphics into Mathematica's PostScript interpreter, which you must run as a local process on your workstation.  If your remote computer also supports the X Window System, you can have this done automatically by using the DISPLAY environment variable, as described in the Mathematica manual for the system you are using remotely.  As an alternative, you can designate an output file for the Mathematica Display function, then manually run the PostScript interpreter on that file.  (Be sure to use the appropriate version of the PostScript interpreter for the terminal type you are using; Mathematica's PostScript interpreters are discussed in the Section "Graphics Interpreters".)  See Section B.7.8 of The Mathematica Book for more information about the use of the Display function.

Another point to remember is that if you issue a command to the remote Mathematica process that would cause it to read or write a file, the file will be read or written on the remote computer's file system, which will often not be the same as the local computer's file system.



Running Remotely from a Front End

You can also use Mathematica on your computer through a Front End running on another computer, such as a Macintosh.  In this case you are working at the Macintosh, and your UNIX computer is the ``remote'' computer.  The computers may be connected by a serial connection (such as a modem) or through a network.

Here are the basic steps you need to go through to run Mathematica on a remote computer with a Front End on a local machine:

Establish a login connection.

The Mathematica Front End will provide a mechanism for logging on to your computer.  (In the Macintosh version of Mathematica this takes the form of a terminal window, which you must configure either for dialup or else TCP/IP network connection.)  In order to successfully log on, you must ensure that all the physical parameters (for example, baud rate and parity in a modem connection) are properly set.  You may need to use the UNIX stty command, as described previously, to determine the correct values of such parameters for the login port you are using.

Start Mathematica in remote mode on the remote computer.

Once you have logged in, issue the command mathremote, possibly with an error-checking option enabled, as explained below.  This starts Mathematica on the remote computer in remote mode, in which Mathematica does all input and output through the MathTalkTM communication protocol.

Tell the Front End to attach itself to the remote Mathematica.

Once you have done this, all your interactions with Mathematica, including, for example, interrupts, will thenceforth be made through the Front End using MathTalk.  In the Macintosh Front End you do this simply by closing the terminal window.

Use Mathematica.

In most respects you will use the remote Mathematica just as if it were running locally.  One point to remember is that file-reading commands, such as Mathematica's << operator, will attempt to read the files from the remote computer's file system.

Tell the Front End to shut down the remote Mathematica and log off.
How to do this will vary from one Front End to another, but each Front End will provide some way of terminating Mathematica on the remote machine.  This should not be confused with logging off the remote machine; you will usually have to re-open the terminal window and log off manually.  Consult the documentation that came with your Front End for details. See below for information about the possible consequences of catastrophic disconnections.

Remote access to Mathematica

mathremote run Mathematica in a mode appropriate for use with a remote Front End
mathremote -crc run Mathematica in remote mode, using additional error-correction checks in its communication


The basic command to start Mathematica in remote mode is mathremote.  In situations where the communication line between the local and remote computers is of poor quality, for example if you are using a modem to dial in over a noisy telephone line, you may wish to tell Mathematica and the Front End to perform extra checks to ensure the correctness of the packets of information they exchange.  On the remote computer you would use the command mathremote -crc to do this.  You will also have to tell the Front End to communicate in this mode.  How this is done will vary from one Front End to another; in the Macintosh Front End you would check an option in a dialog box.  Consult the documentation that came with your Front End for more details.

Warning: Check that your Front End supports the appropriate Mathematica version.
Mathematica version numbers below 1.1 are not compatible with 1.1 and above.

The version of MathTalk that was included in Mathematica versions below 1.1 is not compatible with the version of MathTalk in Mathematica versions 1.1 and above.  Make sure that the Front End you are using is compatible with the version of Mathematica you are trying to connect it to.

The Front End will provide some orderly way of terminating Mathematica and closing its connection to the remote computer.  But if the connection is broken catastrophically, say for example by someone unplugging your modem, then one, some, or all of the processes that are invoked when Mathematica runs in remote mode may fail to terminate properly.  For this reason, if you suffer a catastrophic disconnection when using Mathematica remotely on your computer through a Front End, you should reestablish the connection, log back in, and use the UNIX ps command to check for processes with the following names.  Use the kill command to terminate any of these processes that may be lingering.

Subprocesses used when Mathematica runs in remote mode

contr.r mathremote
control righte.r
leftc.r rightend
leftcrc twoway

mathexe




Special Topic: Very Large Calculations


Memory

When you do very large calculations in Mathematica, the most common problem is that you run out of memory.  Mathematica goes to considerable effort to minimize the amount of memory it uses, and to free any memory it no longer needs.  Nevertheless, it is inevitable that sufficiently large computations, particularly symbolic ones, can overrun any available amount of memory.

UNIX supports virtual memory, which automatically allows disk space to be used to supplement the physical RAM (random-access memory) in your computer.  Nevertheless, there are limits even to virtual memory.  If your Mathematica job becomes too large to fit in the available memory, given the other programs that are running, Mathematica has no choice but to quit.  In such a case, Mathematica simply prints Out of memory, then stops.  You cannot resume the aborted job.

You should realize that even though virtual memory in principle allows you access to larger memory space, access can be very slow when you go beyond what is available in RAM.  This means that Mathematica may run extremely slowly when it starts to use a larger amount of memory than you have physically available in RAM.

You can use the UNIX command ps to monitor how large your Mathematica job is getting, and to try to catch it before it runs out of memory.



Stack Space

Particularly when you use recursive algorithms, Mathematica may use up large amounts of stack space.  UNIX imposes strict limits on the stack space that can be used by any one program.  If Mathematica exceeds this stack space, it will crash.

The Mathematica variable $RecursionLimit specifies the maximum number of levels of recursion that Mathematica should use.  The default value for $RecursionLimit is 256. With this value, Mathematica should very rarely end up using so much stack space that it crashes. If you increase $RecursionLimit, or use parts of Mathematica whose internal algorithms are highly recursive, you may nevertheless cause Mathematica to run out of stack space.




Interfacing with Other Programs

One of the most powerful features of Mathematica is its ability to interact and communicate with other programs.

When you interface Mathematica with other programs, you can use it either in master mode or in slave mode.  In master mode, you can use Mathematica as a control program that sends data to a variety of external subprograms.  In slave mode, you can call Mathematica from within an external program to perform computations.

Warning: The discussions in this section assume the reader's complete understanding of UNIX, the
Bourne and C shells, and the C programming language.



Running Mathematica as a Subprogram

You can call Mathematica from a shell script, from within a C program, or from some other kind of program.  There are several ways to make the output you get from Mathematica easier to use within your program.

When you run Mathematica directly in its standard interactive mode, you get labels for all the input and output lines.  You can suppress these labels by calling math with the -noprompt option.

In order to use output from Mathematica inside your own programs, you will often need to parse the output into an internal form.  Parsing will be much easier if you output all expressions from Mathematica using FullForm[expr], as discussed in Section 2.6.3 of The Mathematica Book. A simple way to arrange this is to use the Mathematica variable $PrePrint, which specifies processing that is to be applied to every output expression before it is printed (this affects only the print form, not the value of the expression).  Making the assignment $PrePrint=FullForm thus causes all expressions to be printed in FullForm.

Convenient ways to run Mathematica as a subprogram

math -noprompt -run "$PrePrint=FullForm" run Mathematica without generating input or output labels, and with all output printed in an easy-to-parse form

math -noprompt -run "Print[FullForm[expr]]" < /dev/null evaluate a single expression and print the result in an easy-to-parse form on standard output

Here is a sample C program that calls Mathematica to perform computations.  The program opens two pipes, one to send input to Mathematica and one to receive results back from it, then forks a child process.  The child overlays its standard input with the receiving end of the first pipe and its standard output with the sending end of the second pipe, then overlays itself with Mathematica. The parent is then free to send computation commands down the first pipe and receive results from the second.

Note that Mathematica is invoked in -noprompt mode, to suppress the printing of the startup banner and input and output prompts.  Also the commands ResetMedium["stdout", PageWidth->Infinity] and $PrePrint=FullForm are used, ensuring that the output of each computation will be printed in linear format on a single line.  This allows the calling program to assume that the appearance of a newline character in the output from Mathematica signals the end of the result.  Finally, note that the program makes two calls to fetchresult() before sending any computation commands to Mathematica.  This absorbs messages which are printed by the standard version of the Mathematica initialization file init.m.  If you use a customized version of init.m, you may need a different number of initial calls to fetchresult().

Note: This program is only a sample, intended to illustrate possibilities.  For example, it ignores the possibility that a command might result in an error message (which would confuse the simple-minded scheme used here for detecting the end of a result).  A serious application would require the use of the MathTalk protocol, described below, to permit a more sophisticated interaction including error checking and interrupt handling.

A sample C program that calls Mathematica to perform computations.

#include     <stdio.h>

int     rdchnr, rdchnw, wrtchnr, wrtchnw;
char    buf[80];

main()
{
int     pid;
char    *mmapath, *args[5];

/*
**   Open pipes for Mathematica to read and write.
**   The parent process writes to the pipe that Mathematica reads,
**   and vice versa.
*/
if (makepipe(&rdchnr,&rdchnw)) exit();
if (makepipe(&wrtchnr,&wrtchnw)) exit();

/*
**   Split off the child process.
*/
pid = fork();

if (pid == 0)
{
/*
**       *************************************************
**       This is the code for the child process,
**       which sets up for, and then becomes, Mathematica.
**       *************************************************
*/
/* close the unneeded ends of the pipes */
close(rdchnw);
close(wrtchnr);

/* set up the arguments for, and the full path name of, Mathematica */
mmapath = "/usr/local/bin/math";
args[0] = mmapath;
args[1] = "-noprompt";
args[2] = "-run";
args[3] = "ResetMedium[\\"stdout\\", PageWidth->Infinity];$PrePrint=FullForm";
args[4] = (char *) 0;

/* install the pipes as Mathematica's standard input and output */
if ( dup2(rdchnr,0) == -1 )
{ perror("Error establishing read channel: "); exit(); }
if ( dup2(wrtchnw,1) == -1 )
{ perror("Error establishing write channel: "); exit(); }

/* start Mathematica */
execvp(mmapath,args);
perror("Error attempting to run Mathematica: ");
}
else
{
/*
**       ****************************************
**       This is the code for the parent process.
**       ****************************************
*/
/* close the unneeded ends of the pipes */
close(rdchnr);
close(wrtchnw);

/* absorb initialization messages harmlessly */
fetchresult();
fetchresult();

/* give Mathematica some commands, and get their results */
givecmd("1+2+3");
givecmd("+4+5\\n");
fetchresult();

givecmd("Expand[(1+x+y)^5]\\n");
fetchresult();

givecmd("N[Pi,200]\\n");
fetchresult();

/* tell Mathematica to shut down */
givecmd("Quit[]\\n");
}
}

int makepipe(rd,wrt)
int     *rd,*wrt;
{
int     piperesult, fildes[2];

piperesult = pipe(fildes);
if (piperesult) perror("Pipe creation failed:");

*rd = fildes[0];
*wrt = fildes[1];

return(piperesult);
}

givecmd(cmd)
char    *cmd;
{
strcpy(buf,cmd);
write(rdchnw,buf,strlen(buf));
}

fetchresult()
{
int     count, i, ch;

/*
**   Read buffer after buffer of output from Mathematica,
**   until a NEWLINE is seen.  Because Mathematica is printing
**   everything in FullForm, all output is linear, and because
**   PageWidth was set to Infinity, no line breaking happens, so
**   a NEWLINE means the end of a complete output expression.
*/
do {
count = read(wrtchnr,buf,80);
for ( i=0 ; i<count ; printf("%c", ch = buf[i++]) ) ;
} while (ch != '\\n');
}

A Possible Problem

Mathematica does unnecessary initialization.


Mathematica always reads the initialization file init.m.  If you do not want Mathematica to do any initialization, then create an empty init.m file in your current directory.



Running Programs from Within Mathematica

You can substantially extend the capabilities of Mathematica by running external programs from within it.  In almost all cases, Mathematica uses pipes to communicate with external programs. Sections 1.9, 2.6 and B.7 of The Mathematica Book discuss more details.

Sometimes no communication is needed between Mathematica and the external process.  In this case, you can use Mathematica's Run command to run the process.  Run["command"] runs the command, returning as its result the command's exit status code.



Ways to run external programs from within Mathematica

!command shell escape: run an external command immediately from within Mathematica
Run["command"] run an external command from within Mathematica, returning its exit status code as result

Most often, only one-way communication is needed between Mathematica and a process it launches.  For example, you might want to use Mathematica to analyze data from a laboratory experiment that is being monitored by apparatus that periodically sends numbers to the computer. Mathematica needs to be able to receive the data from the process that monitors the apparatus, but does not need to send anything to it.  The command ReadList["!program", Number] runs a program and returns a list of numbers obtained as the output of that program.

Conversely, you might want to use a \TeX\ previewer to see typeset forms of Mathematica output on your screen.  Mathematica must be able to send the TeXForm of expressions to the previewer, but does not need to receive any responses.  A suitable command for this would be TeXForm[expr] >> "!command".  If you use OpenWrite["!command"], then you can run many expressions through the same pipe instead of restarting the previewer for each expression.

You might also need to send graphics output to a special device.  You can use Display["!command", graphics] to send PostScript graphics to a program that controls the device.  By setting $Display or $DisplayFunction, you can arrange to have all graphics sent to the special device.

In cases like these, the basic idea is that since UNIX treats a pipe to a process as a file, any of the Mathematica commands (such as ReadList and Display) that can read or write data files can also be used to communicate with external processes.  To open a pipe to a process for one-way communication, simply give the name of the process, preceded by an exclamation mark, in place of the filename argument of the appropriate Mathematica file-manipulation command.  Done this way, launching a process from within Mathematica for one-way communication is similar to the use of the popen() system call in the C programming language.

As a simple example, the commands

f = OpenRead["!date"];
d = Read[f,String];
Close[f];

cause the UNIX command date to be run, and its output, which is the system date, to be stored as a string in the Mathematica variable d.

Additional ways to run external programs from within Mathematica

<< "!command" run an external command, and read the result into Mathematica

ReadList["!command", Number] run an external command, and read in the list of numbers it produces

expr >> "!command" send the printed form of expr as input to an external command
RunThrough["command", expr] feed the printed form of expr to a command, and read in the result
Splice["file"] scan an external file, running Mathematica on pieces of text enclosed between <* and *>
Display["!command", graphics] send PostScript graphics to an external command



Extending Mathematica by Installing C Procedures

An alternative to running external programs to do computations outside Mathematica is to write procedures in C and link them into Mathematica, which can then evaluate them as if they were built-in functions.

Source code files for writing programs that link C-language procedures into Mathematica

mathlink.c source code for linking procedures
mathlink.h header file containing declarations for procedures in mathlink.c

User-written programs can link procedures into Mathematica by calling the special Mathematica interface procedures defined in the file mathlink.c, which is stored in the Sources subdirectory of the main Mathematica directory.  Also in this directory is a C header file mathlink.h.  Programs containing procedures intended to be accessed by Mathematica should include mathlink.h and be linked to the object code compiled from mathlink.c.

Mathematica operators for starting, invoking, and terminating processes

StartProcess["command"] start an external process compiled with mathlink.c, and set up Mathematica functions to access functions inside the external process

CallProcess["command",f,{x1,x2,...}] call the function f within the process command with arguments x1, x2,...

EndProcess["command"] terminate an external process started by StartProcess

Once a program that contains procedures intended to be called by Mathematica has been properly compiled and linked, it can be launched from within Mathematica by executing StartProcess["command"], where command is the name of the executable version of the program.  The program performs initialization steps (described below) to install its procedures into Mathematica, then returns control to Mathematica.  The procedures can thereafter be called from within Mathematica by executing CallProcess[] with appropriate arguments.  If the procedures in the process are no longer needed, then the process can be halted from within Mathematica by executing EndProcess["command"].

The result of a call to StartProcess[] is a list of the names of the functions that were installed into Mathematica by that call.  The result of CallProcess[] is the value that was returned by the procedure it invoked.  Calling EndProcess[string] returns the expression EndProcess[string] unchanged; but it has the side effect of halting the process named by the string.

It is usually not necessary or desirable for the user to explicitly invoke CallProcess[] to access procedures that are linked into Mathematica by StartProcess[].  It is customary for a program launched by StartProcess[] to make a call to MathInstall() (described below) for each procedure that it wishes to make available to Mathematica.  This defines a Mathematica function that checks for the correct number and types of arguments and then makes the necessary call to CallProcess[] to invoke that procedure.



Procedures defined in mathlink.c for linking user-written procedures into Mathematica

MathInit() initialize communications between Mathematica and an external process

MathInstall(f,"fname","ftype","argnamepat","argtypes") tell Mathematica to define a function named fname which, when called with arguments matching the pattern argnamepat, will use CallProcess[] to invoke the C subroutine f, which takes arguments of C types argtypes and returns a value of C type ftype

MathExec("expr") call Mathematica from the external process to evaluate an expression
MathStart() put the external process into a service loop to await computation requests from Mathematica

The file mathlink.c defines four procedures that user-written programs can use to link their own C code into Mathematica.

MathInit() takes no arguments and returns no result.  It simply establishes communication between the user-written program and Mathematica.

MathInstall() should be called once for each procedure that the program wishes to make available to Mathematica.  The arguments to MathInstall() provide a pointer to the procedure, and specify the number and types of its arguments and the type of its result, as well as the name by which the procedure should be known within Mathematica and the patterns that its arguments must match.  For example, if the program prog had been launched from within Mathematica by executing StartProcess["prog"], then the effect of executing

MathInstall(myproc,"External","int","x_Integer,s_String","int, char *")

within prog would be to make the following definition within Mathematica:

External[x_Integer,s_String] := CallProcess["prog",myproc,{x,s}]

This makes it unnecessary for the user of Mathematica to invoke CallProcess[] explicitly, and reduces the chance that an installed procedure will be invoked with incorrect arguments.  (In the example, the rule that defines External[] will not be activated unless exactly two arguments, one of type Integer and one of type String, are provided.)

MathExec() takes a string as argument.  It passes the string to Mathematica as an expression to be parsed and evaluated.  There are no restrictions on what expressions may be evaluated by means of MathExec(), but the convention is to use it to perform initialization for the procedures defined by MathInstall().  This usually means defining usage messages, but might also include initializing global variables or other setup.

MathStart() takes no arguments and returns no result.  A call to MathStart() should be the last step in the main() procedure of a program launched by StartProcess[].  This puts the process into a service loop to await signals from CallProcess[] that computations are to be performed.

Here is a sample program that installs two functions into Mathematica.  (This program is only an example, and these particular functions could of course have been written in Mathematica's own programming language.) The program is short but complete; it illustrates all the necessary steps.

A sample C program that defines procedures to be called by Mathematica

#include "mathlink.h"

main()
{
int  BitAnd(), CheckSum();
/*
**  notify Mathematica that we are going to link code into it
*/
MathInit();
/*
**  install our new procedures
*/
MathInstall(BitAnd,"BitAnd","int","x_Integer,y_Integer","int, int");
MathInstall(CheckSum,"CheckSum","int","x_String","char *");
/*
**  give usage messages for them
*/
MathExec("BitAnd::usage = \\"BitAnd[x,y] computes the bitwise logical AND of the (machine-length) integers x and y.\\"");
MathExec("CheckSum::usage = \\"CheckSum[x] computes a checksum for the string x.\\"");

/*
**  relinquish control to Mathematica, and wait to be called
*/
MathStart();
}

int BitAnd(x,y)
{
return(x&y);
}

int CheckSum(x)
char *x;
{
register int n,i;
n = 0;
while ( i = *x++ ) n = (n+i) % 256;
return(n);
}

Actually, a program invoked by StartProcess is not required to invoke MathStart().  If it does not, it remains in control and can continue to make calls to MathExec() to request Mathematica to perform computations.  This is an alternative to the method used by the sample program in the section "Running Mathematica as a Subprogram".  It is still not a completely general and reliable method of using Mathematica as a subroutine, because it provides no provision for error trapping and correction.  Programs that need to use Mathematica as a subprocess to perform complicated computations should use the MathTalk protocol, described below, to communicate with Mathematica.



Mathematica Front Ends and MathTalk

The previous sections have discussed how you can either call Mathematica as a ``slave'' subprogram from within another program, or use it as a ``master'' program that calls other subprograms.

You might instead want to use Mathematica on an equal footing with another program.  For example, you might want to set up a ``Front End'' for Mathematica, which handles interaction with the user and calls Mathematica to perform actual computations.  In this situation, Mathematica cannot operate strictly as a subprogram, because it may need to make requests of the Front End, for example to handle Input functions and interrupts.

Mathematica supports communication with Front Ends using the MathTalk protocol.  MathTalk is a packet-based protocol in which data are exchanged through bidirectional pipes.  Versions of Mathematica running on all types of computers support compatible MathTalk interfaces.  This makes it possible to have Mathematica running on one computer and the Front End on another, perhaps of a different type, connected via a network or modem.  For example, you can run Mathematica on a NeXT Computer, but with a Front End on a Macintosh.

The standard Mathematica distribution includes the programs that are necessary to maintain MathTalk-based communications.  They are stored in the NextApps/Mathematica.app/Kernel/MathTalk.  Here is a list of the MathTalk utility programs:

The contents of the MathTalk directory

control watch ASCII data sent from the Front End to the kernel, intercepting interrupt requests, and generating the appropriate signals
leftcrc leftward cyclic redundancy error checking
leftend leftmost end of a bidirectional pipe
rightcrc rightward cyclic redundancy error checking
rightend rightmost end of a bidirectional pipe
twoway control program for setting up bidirectional pipes

When you run Mathematica with a Front End, the Front End typically sets up all the MathTalk-based communications that are necessary, and calls Mathematica itself in MathTalk mode.  This means that the user of a Front End need not know the details of how MathTalk works.

For further information about MathTalk, contact: Developer Relations Dept., Wolfram Research, Inc., P.O. Box 6059, Champaign, IL 61826-6059.




Using Mathematica's Ancillary Files

This section describes the ancillary files and programs distributed with Mathematica.  Most of these are utilities for displaying graphics.


Graphics Interpreters

Mathematica generates all graphics as page descriptions in the PostScript language.  This makes the graphics easy to print on any of the many PostScript-driven printers that are available, and easy to import into other programs (such as desktop publishing systems).

For each device on which PostScript graphics are to be displayed, there must be a PostScript interpreter.  The Mathematica distribution includes several interpreters for the subset of the PostScript language used by Mathematica in the graphics it creates.  On the NeXT Computer there is a version of the Mathematica PostScript interpreter for character-oriented terminals, and Tektronix-compatible vector graphics terminals.
Ordinarily, however, Mathematica on the NeXT computer displays graphics on the screen or renders them for the NeXT laserprinter by using the built-in NeXT Display PostScript interpreter.

Note: Mathematica's PostScript interpreters do not implement the full PostScript language. They are intended only for rendering the graphics produced by Mathematica, and not as general-purpose PostScript screen previewers.  In particular, they ignore font designations and use standard screen fonts for all text output.

PostScript interpreters for Mathematica

tekps Tektronix-emulation PostScript interpreter
ttyps character display PostScript interpreter

All the Mathematica PostScript interpreters read the standard input channel, and report any errors in the PostScript they receive to the standard error channel.

You can use Mathematica's Display[] function to write a PostScript description of a Mathematica graphic to a file.  Once you have done this, you can manually invoke the appropriate one of tekps, or ttyps, to display the graphic on your screen.  If you want to look at the resulting graphics file in the NeXT Display PostScript Previewer, you must first filter it through psfix (see the section "Prolog for Mathematica Graphics", below).

The distribution version of the Mathematica initialization file init.m tests for several environment variables in order to determine which type of terminal or window manager you are using, and loads a subsidiary initialization file for that type of display.  Each such file typically sets the Mathematica graphics display variable $Display to point to the appropriate PostScript interpreter.  Each time you ask Mathematica to display a graphic it launches the PostScript interpreter designated by $Display as a separate process, and pipes the PostScript description of the graphic to the standard input of this process.



Prolog for Mathematica Graphics

Like most programs that generate graphics in the form of PostScript page descriptions, Mathematica does not actually generate standard PostScript. Instead its graphics are defined in terms of higher-level operators that are extensions to the standard PostScript language.  These operators are built into Mathematica's own PostScript interpreters, but would have to be defined in terms of standard PostScript before a standard PostScript interpreter could render Mathematica graphics.

The shell script psfix, which is stored in the same directory as Mathematica's PostScript interpreters, prepends to a PostScript page description the definitions of Mathematica's special PostScript operators.  psfix first writes these definitions to its standard output, then copies any files named as command line arguments to its standard output.  (If no files are named, psfix copies its standard input.)  The result is that a PostScript page description that could be interpreted by any standard PostScript interpreter is written to standard output.  It is typical to pipe this output to a process like lpr that will send it to a PostScript-driven printer.

The psfix shell script accepts several optional parameters to modify the PostScript it generates. If any of these parameters are specified, they must precede all filenames.



Command line options for psfix

-lmarg n left margin in inches (default 1/2 inch)
-rmarg n right margin in inches (default 1/2  inch)
-bmarg n bottom margin in inches (default 1/2 inch)
-tmarg n top margin in inches (default 1/2 inch)
-width n paper width in inches (default  8 1/2 inches)
-height n paper height in inches (default 11 inches)
-land print image in ``landscape'' rather than ``portrait'' mode, i.e., image is oriented so that long side of paper is at top and bottom
-stretch stretch the image as necessary to fill the image area

The image area is the rectangle obtained by moving in from the edges of the paper by the amounts of the left, right, bottom, and top margins.  This rectangle will in general not have the same aspect ratio (i.e., ratio of height to width) as the image that is to be printed.  Unless the -stretch option is specified, the graphic is scaled evenly in both dimensions to just fit the smaller of the height and width of the image area.  This preserves the aspect ratio of the image, but does not fill the image area.  If -stretch is specified, then the image is scaled separately in height and width so as to completely fill the image area; this will distort the image.

psfix on the NeXT Computer generates encapsulated PostScript files conforming to the Adobe specifications for EPS.  psfix-generated  files can be viewed in the NeXT Preview application, provided you have named them with the .eps suffix.  You can open such files from within Preview, or double-click the filename in the Browser, or use the  command "open filename" at a UNIX prompt.

Header File for C Code Generated by Mathematica

The Sources subdirectory of the main Mathematica directory contains a file named mdefs.h that defines some procedures and constants that occur in C code generated by Mathematica's CForm[] output form.

CForm directs Mathematica to print symbolic expressions in the syntax of the C programming language.  The C code so generated can be incorporated into a user's C programs.  (This can be done automatically, with Mathematica's Splice operator.)  The C code generated by CForm refers to functions by their names in Mathematica.  The file mdefs.h contains declarations that translate these names into their standard C equivalents, and define numeric values for some of Mathematica's common symbolic constants, such as E and Pi.

Including mdefs.h into a C program allows the C code in the program that was generated by CForm to compile correctly.  A program that contains code generated by CForm[] will probably have to include mdefs.h to compile successfully.