Mathematica Tutorial

Setting Up External Functions to Be Called from Mathematica

If you have a function defined in an external program, then what you need to do in order to make it possible to call the function from within Mathematica is to add appropriate MathLink code that passes arguments to the function, and takes back the results it produces.

In simple cases, you can generate the necessary code just by giving an appropriate MathLink template for each external function.

:Begin:
:Function:      f
:Pattern:       f[x_Integer, y_Integer]
:Arguments:     {x, y}
:ArgumentTypes: {Integer, Integer}
:ReturnType:    Integer
:End:

A file f.tm containing a MathLink template for an external function f.

:Begin:	begin the template for a particular function
:Function:	the name of the function in the external program
:Pattern:	the pattern to be defined to call the function
:Arguments:	the arguments to the function
:ArgumentTypes:	the types of the arguments to the function
:ReturnType:	the type of the value returned by the function
:End:	end the template for a particular function
:Evaluate:	Mathematica input to evaluate when the function is installed

The elements of a MathLink template.

Once you have constructed a MathLink template for a particular external function, you have to combine this template with the actual source code for the function. Assuming that the source code is written in the C programming language, you can do this just by adding a line to include the standard MathLink header file, and then inserting a small main program.

Include the standard MathLink header file.

#include "mathlink.h"

Here is the actual source code for the function f.

int f(int x, int y) {
   return x+y;
}

This sets up the external program to be ready to take requests from Mathematica.

int main(int argc, char *argv[]) {
   return MLMain(argc, argv);
}

A file f.c containing C source code.

Note that the form of main required on different systems may be slightly different. The release notes included in the MathLink Developer Kit on your particular computer system should give the appropriate form.

mcc	preprocess and compile MathLink source files
mprep	preprocess MathLink source files

Typical external programs for processing MathLink source files.

MathLink templates are conventionally put in files with names of the form file.tm. Such files can also contain C source code, interspersed between templates for different functions.

Once you have set up the appropriate files, you then need to process the MathLink template information, and compile all of your source code. Typically you do this by running various external programs, but the details will depend on your computer system.

Under Unix, for example, the MathLink Developer Kit includes a program named mcc which will preprocess MathLink templates in any file whose name ends with .tm, and then call cc on the resulting C source code. mcc will pass command-line options and other files directly to cc.

This preprocesses f.tm, then compiles the resulting C source file together with the file f.c.

mcc -o f.exe f.tm f.c

This installs the binary in the current Mathematica session.

In[1]:=

Out[1]=

Now f[x, y] calls the external function f(intx, inty) and adds two integers together.

In[2]:=

Out[2]=

The external program handles only machine integers, so this gives a peculiar result.

In[3]:=

Out[3]=

On Windows, the MathLink Developer Kit includes a program named mprep, which you have to call directly, giving as input all of the .tm files that you want to preprocess. mprep will generate C source code as output, which you can then feed to a C compiler.

Install["prog"]	install an external program
Uninstall[link]	uninstall an external program
Links["prog"]	show active links associated with "prog"
Links[]	show all active links
LinkPatterns[link]	show patterns that can be evaluated on a particular link

Handling links to external programs.

This finds the link to the f.exe program.

In[4]:=

Out[4]=

This shows the Mathematica patterns that can be evaluated using the link.

In[5]:=

Out[5]=

Install sets up the actual function f to execute an appropriate ExternalCall function.

In[6]:=

When a MathLink template file is processed, two basic things are done. First, the :Pattern: and :Arguments: specifications are used to generate a Mathematica definition that calls an external function via MathLink. And second, the :Function:, :ArgumentTypes: and :ReturnType: specifications are used to generate C source code that calls your function within the external program.

:Begin:

This gives the name of the actual C function to call in the external program.

:Function:      prog_add

This gives the Mathematica pattern for which a definition should be set up.

:Pattern:       SkewAdd[x_Integer, y_Integer:1]

The values of the two list elements are the actual arguments to be passed to the external function.

:Arguments:     {x, If[x > 1, y, y + x - 2]}

This specifies that the arguments should be passed as integers to the C function.

:ArgumentTypes: {Integer, Integer}

This specifies that the return value from the C function will be an integer.

:ReturnType:    Integer

:End:

Both the :Pattern: and :Arguments: specifications in a MathLink template can be any Mathematica expressions. Whatever you give as the :Arguments: specification will be evaluated every time you call the external function. The result of the evaluation will be used as the list of arguments to pass to the function.

Sometimes you may want to set up Mathematica expressions that should be evaluated not when an external function is called, but instead only when the external function is first installed.

You can do this by inserting :Evaluate: specifications in your MathLink template. The expression you give after :Evaluate: can go on for several lines: it is assumed to end when there is first a blank line, or a line that does not begin with spaces or tabs.

This specifies that a usage message for SkewAdd should be set up when the external program is installed.

:Evaluate:    SkewAdd::usage = "SkewAdd[x, y] performs
       a skew addition in an external program."

When an external program is installed, the specifications in its MathLink template file are used in the order they were given. This means that any expressions given in :Evaluate: specifications that appear before :Begin: will have been evaluated before definitions for the external function are set up.

Here are Mathematica expressions to be evaluated before the definitions for external functions are set up.

:Evaluate:  BeginPackage["XPack`"]
:Evaluate:  XF1::usage = "XF1[x, y] is one external function."
:Evaluate:  XF2::usage = "XF2[x] is another external function."
:Evaluate:  Begin["`Private`"]

This specifies that the function XF1 in Mathematica should be set up to call the function f in the external C program.

:Begin:
:Function:       f
:Pattern:        XF1[x_Integer, y_Integer]
:Arguments:      {x, y}
:ArgumentTypes:  {Integer, Integer}
:ReturnType:     Integer
:End:

This specifies that XF2 in Mathematica should call g. Its argument and return value are taken to be approximate real numbers.

:Begin:
:Function:       g
:Pattern:        XF2[x_?NumberQ]
:Arguments:      {x}
:ArgumentTypes:  {Real}
:ReturnType:     Real
:End:

These Mathematica expressions are evaluated after the definitions for the external functions. They end the special context used for the definitions.

:Evaluate:  End[ ]
:Evaluate:  EndPackage[ ]

Here is the actual source code for the function f. There is no need for the arguments of this function to have the same names as their Mathematica counterparts.

int f(int i, int j) {
   return i + j;
}

Here is the actual source code for g. Numbers that you give in Mathematica will automatically be converted into C double types before being passed to g.

double g(double x) {
   return x*x;
}

By using :Evaluate: specifications, you can evaluate Mathematica expressions when an external program is first installed. You can also execute code inside the external program at this time simply by inserting the code in main() before the call to MLMain(). This is sometimes useful if you need to initialize the external program before any functions in it are used.

MLEvaluateString(stdlink,"string")
	evaluate a string as Mathematica input

Executing a command in Mathematica from within an external program.

int diff(int i, int j) {

This evaluates a Mathematica Print function if i<j.

    if (i < j) MLEvaluateString(stdlink, "Print[\"negative\"]");
    return i - j;
}

This installs an external program containing the diff function defined above.

In[7]:=

Out[7]=

Calling diff causes Print to be executed.

In[8]:=

Out[8]=

Note that any results generated in the evaluation requested by MLEvaluateString() are ignored. To make use of such results requires full two-way communication between Mathematica and external programs, as discussed in "Two-Way Communication with External Programs".