Mathematica

DESCRIPTION

This module provides an interface to the symbolic mathematical manipulation program Mathematica. The module delivers lattices and parameters to Mathematica (across a MathLink communication channel), creates variables from these datasets, causes Mathematica to read and execute the file named in the Program File widget, and retrieves any datasets corresponding to output ports.

THE MATHEMATICA PROGRAM FILE

If the Program File widget is present, that file is read each time the widget value changes (signified by a carriage return in the typein area). If the Program File widget is not present, a file name is constructed automatically from the module name and the suffix '.m'. This is particularly useful in creating an "alternate executable" module which does not have its own program, but causes the Mathematica module to be invoked. For a module MyModule (lacking the Program File widget), the file MyModule.m is automatically read each time MyModule fires.

DATA COMMUNICATION WITH THE MATHEMATICA SERVER

The Mathematica module transmits lattices and parameters to and from a Mathematica server process. Thus a Mathematica module may have lattice and/or parameter inputs and outputs. The lattices may have optional data and/or coordinates. In the event of a missing structure on input, the corresponding Mathematica variable will simply not be defined. To represent a missing data or coordinate array on output, use the empty list (written {} in Mathemtica).

EXPLORER PORT VARIABLE NAMES IN MATHEMATICA

You may use any variable names you like in constructing your Mathematica program. Certain names corresponding to the module's input and output ports will already be defined when your program executes. You can use these variables to receive input and construct output for the module. The main rule to remember in determining the Mathematica program name for an input or output port is that the name will not contain any underscores, spaces, or other punctuation characters.

A port name has all illegal characters stripped from it to create the Mathematica variable name. Thus the port "First In" would become the variable FirstIn. The port name "First Param In" would become FirstParamIn.

If the input port is of type cxLattice, then two additional variables are defined for the data and coordinates of the lattice. Their names append Data and Coord to the port's name. For instance, if the port is named "First In", then the three Mathematica variables are FirstIn, FirstInData, and FirstInCoord. On output you may supply either FirstOut or both of FirstOutData and FirstOutCoord to construct the "First Out" output port; supply all three and the module will use the FirstOut variable.

Parameters have only a single variable name associated with them.

LATTICE AND PARAMETER DATASET CONSTRUCTION

A lattice is represented as a list of data and coord in Mathematica, for instance the list {data, coord}. The data and coord list elements are both Mathematica Tables (arrays). All Mathematica conventions on arrays are preserved, so you may perform any operations you like on the input variables. The output arrays must conform in the usual sense for lattices. That is, the arrays must be regular arrays of data (not general lists), and they must have the same number and shape of dimensions. The inner dimension (nDataVar or nCoordVar) may differ between data and coord.

Although the Mathematica module will accept any coordinate type, it will convert uniform and perimeter coordinates to curvilinear form before sending to the Mathematica server. All output coordinates must be in curvilinear form.

A parameter may be represented by an integer, a floating point number, or a string. All three types are acceptable for input to, or output from, Mathematica.

WRITING YOUR OWN MATHEMATICA MODULE -- ALTERNATE EXECUTABLE MODULES

See the Module Writer's Guide for more information on writing an 'alternate executable' module. In this form of module writing, you use the Module Builder to define a module's ports and give it a control panel. This is how you construct a Mathematica module with your own port names and widgets.

ISSUING EXPLORER COMMANDS FROM THE MATHEMATICA PROGRAM

The Mathematica module understands a very limited set of Explorer UI commands. Thus you may set the value of the widget "My X Widget" to 27.5 by adding the statement

 	cxInWdgtSet["My X Widget", 27.5];

to your Mathematica program. Similarly, you may call cxInWdgtHide[], cxInWdgtShow[], and cxModAlert[].

DEBUGGING

If the input parameter port "Debugging" exists and has a non-zero parameter value, then the module logs to standard error a debugging trace of all packets sent to and from Mathematica. This can be useful if you wish to understand how the module communicates across MathLink, or if you suspect that incorrect packets are being sent to the module.

Use your normal Mathematica debugging techniques in the '.m' file to delve deeper into the actions of your own program.

COMPILING THE MODULE

The module compiles and runs with MathLink 2.2 on IRIX 4.0.5. You may need to change the MATHLINK_2_2 compiler definition in the Imakefile.Mathematica file if you are not using MathLink 2.2. You may also need to change the default location of the Mathematica header files and library from the directory '/usr/apps/math/...' used in development at SGI; these are also defined in Imakefile.Mathematica.

In order for the module to be able to find the Mathematica program file, you must set the environment variable EXPLORERUSERHOME, remake the Makefile for the Mathematica module, and issue the command 'make install'. This will put the module and its *.m files in a location accessible to Explorer. It is helpful if you also issue the 'make Makefile; make install' command in the directory of any Mathematica-based module you build, so that the module and its corresponding .m file also get installed where the Explorer Librarian knows to look for them. (Note, you use the EXPLORERUSERHOME variable to avoid overwriting the EXPLORERHOME directories, where the Explorer system resides.)

SOURCE CODE EXTENSIBILITY

The source code (.c and .m files) is organized in a way that will hopefully make it easy for other Mathematica users to augment the module. Other useful work could include adding output support for Mathematica Graphics types (both 2D and 3D), input and output support for pyramids (for instance as collections of Mathematica points, lines, and polygons, corresponding to a 2D compressed Explorer pyramid), fleshing out the suite of Explorer UI commands available to the Mathematica user, etc.

INPUTS

Port: First In
Type: Lattice
Optional: This port is optional
Input lattice

Port: Second In
Type: Lattice
Optional: This port is optional
Input lattice

Port: Third In
Type: Lattice
Optional: This port is optional
Input lattice

WIDGETS

Port: Program File
Type: Text
The file containing the Mathematica program to be executed.

Port: Debugging
Type: Option Menu
Menu Item: Off
Menu Item: On
Log information about all MathLink calls used to send and receive data.

OUTPUTS

Port: First Out
Type: Lattice
Output lattice

Port: Second Out
Type: Lattice
Output lattice

Port: Third Out
Type: Lattice
Output lattice

PROBLEMS

The Mathematica module takes a few seconds to become operational, as it must wait for Mathematica to start up before executing. On subsequent firings, the module flushes all waiting input packets before sending new information to the Mathematica server. This allows the module to recover gracefully from errors in the Program File program, but will not give you any information about the packets that are being discarded.