A MathLink Tutorial
Todd Gayley
Wolfram Rearch
MathLink is a library of functions that implement a protocol for nding and receiving Mathematica expressions. Its us fall into two general categories. The easiest and most common application is to allow external functions written in other languages to be called from within the Mathematica environment. If you have an algorithm that needs to be implemented in a compiled language for efficiency reasons, or if you have code that you don't want to rewrite in Mathematica, it is a relatively simple matter to incorporate the routines into Mathematica. This u of MathLink is treated in the first chapter of this tutorial.
The cond u of MathLink is to allow your program, running in the foreground, to u the Mathematica kernel in the background as a computational engine. In effect, the program is a "front end" for the Mathematica kernel. This requires a deeper understanding of MathLink, and is treated in the cond chapter.
Each of the two chapters is designed to stand on its own, so there is some repetition. There are also topics that are relevant to all MathLink programmers that are treated more fully in one chapter than in the other. I strongly recommend that you read both, but keep in mind that some of the information may not apply to you, depending on how you plan to u MathLink.
This document is designed to supplement the information in the MathLink Reference Guide, which is the main documentation for MathLink. There is also some information on newer features of MathLink in the Major New Feautres of Mathematica Version 2.2 document, which comes with Version 2.2, and is also available on MathSource. My intention here is to flesh out some details, provide uful code fragments, discuss some underdocumented features, and show how to accomplish some common tasks.
The information prented here refers to Version 2.2.2 of MathLink and later. Most of the information is also correct for earlier versions, but a few of the functions and features may not be prent.
1. Calling External Programs from the Mathematica Kernel
1.1 The Simplest Example: addtwo
1.2 Using :Evaluate: to Include Accessory Mathematica Code
1.3 Putting and Getting Arguments Manually
1.4 Passing Lists and Arrays
1.5 Passing Arbitrary Expressions
1.6 Requesting Evaluations by the Kernel
1.7 Error Handling
1.8 Troubleshooting and Debugging
1.9 Large Projects
1.10 Special Topics
2. Calling the Mathematica Kernel from External Programs
2.1 A Simple Program
2.2 Opening a Link to the Kernel
2.3 Sending Expressions to the Kernel
2.4 Receiving Expressions from the Kernel
山竹功效
2.5 Blocking, Yield Functions, and All That
2.6 Graphics
3. Using Other Languages
3.1 C++
3.2 FORTRAN and Others
I will refer to external functions that are called from Mathematica as "installable" functions, since they u the Install mechanism to be incorporated into the Mathematica environment. The intent is that yo
u should be able to take pre-existing C language routines, and with as little effort as possible (ideally with no source code changes to the routines themlves), package them so they can be called from Mathematica. For each function you want to call from Mathematica, you write a template entry that specifies the name of the function, the arguments that the function needs to be pasd and their types, and the type of argument it returns. This template file is then pasd through a tool called mprep, which writes C code that manages most, possibly all, of the MathLink-related aspects of the program.
I want to emphasize how easy, even trivial, it is to perform the steps for many external functions. With just a little more effort you can handle unusual functions or more sophisticated communication. The MathLink Reference Guide is perhaps a little intimidating, but some of the information is not directly relevant for programmers who merely want to call external functions from Mathematica. I hope that this chapter will encapsulate much of the information you need in a conci form.
Let's look at a trivial example of an installable program, the addtwo program that is supplied with MathLink. We will modify the program in veral ways to demonstrate more advanced techniques. H
ere is the C source file addtwo.c:
#include "mathlink.h"
int addtwo(int i, int j) {
return i+j;
}
int main(int argc, char* argv[]) {
return MLMain(argc, argv);
}
Note that if you already had a C routine that took two int s and returned an int, all you would have to do to make it installable would be to inrt the one-line main function (actually, for Windows urs main is slightly more complicated, but it is still something that can simply be pasted into your own code). The main function is simply a "stub" that calls the real main function (named MLMain), which is written by mprep.
三检制度Here is the template :
:Begin:
:Function: addtwo
:Pattern: AddTwo[i_Integer, j_Integer]
:Arguments: { i, j }
:ArgumentTypes: { Integer, Integer }
:ReturnType: Integer
:End:
The :Function: line specifies the name of the C routine. The :Pattern: line shows how the routine will be called in Mathematica. The pattern given on this line will become the left-hand side of a function definition, exactly as you would type it if you were creating the entire function in Mathematica. The :Arguments: line specifies the expressions to be pasd to the external program. The expressions
don't have to be the same as the variable names on the :Pattern: line, although they often will be. You could, for example, put {Abs[i], j^3}. The point is that what you put on the :Pattern: line and the :Arguments: line is Mathematica code; it will be ud verbatim in a definition that could be caricatured as follows:
AddTwo[i_Integer, j_Integer] :=
SendToExternalProgramAndWaitForAnswer[{i, j}]
The :ArgumentTypes: and :ReturnType: lines contain special keywords ud by mprep to create the appropriate MLGet and MLPut calls that transfer data across the link.
The details of building the executable from and addtwo.c source files differ from platform to platform. On Unix, you will usually u the mcc script that comes with Mathematica. You would u a line like
addtwo.c -o addtwo
The steps that mcc performs are as follows: (1) run mprep on the .tm file, to create a .tm.c file; and (2) compile and link all the source files, including the .tm.c file, specifying to the 'cc' compiler where t
o find the mathlink.h file and the MathLink library file (named libML.a on Unix machines). It is the .tm.c file that contains the mprep-generated C source. Normally, this file is deleted by mcc after it has been compiled, but if you want to e what it looks like you can prevent its deletion by specifying the -g command-line option to mcc. Advanced urs of MathLink can learn a lot by studying this file. On Macintosh and Windows, the steps to build the program will be different, and you should consult the README file that comes with MathLink. The mcc method is convenient for simple projects, but it has some drawbacks, one of which is that it is hard-coded to call the 'cc' compiler. You might want to skip mcc altogether and write your own makefile. In that ca, you will be calling mprep yourlf. Here's an example:
/math/Bin/MathLink/ -
Note that mprep is not on your Unix path, so you will need to specify the full pathname. The MathLink library, libML.a, is also located in the math/Bin/MathLink directory, and the mathlink.h file is in math/Source/Includes.
To u the AddTwo function in Mathematica, you launch the external program with the Install function:
link = Install["addtwo"]
干学生LinkObject[addtwo, 2, 2]
珠海社保电话The function LinkPatterns shows what functions are defined by the external program associated with a given link:
LinkPatterns[link]
{AddTwo[i_Integer, j_Integer]}
AddTwo[3,4]
7
You may wonder, "How does the definition for AddTwo appear in Mathematica?" After all, the only thing we've done is start up the kernel, type Install, and suddenly Mathematica knows about a function called AddTwo. The answer is that the external program nds to Mathematica the definitions for the functions it exports when the link is first opened. Here's what such a definition looks like:
?AddTwo
Global`AddTwo
AddTwo[i_Integer, j_Integer] :=
ExternalCall[LinkObject["addtwo", 2, 2], CallPacket[0, {i, j}]]
脆皮鸡腿
Of cour, the programmer never es any of this process, becau it is handled at one end by the code that mprep writes and at the other end by the Install code. Most programmers have no reason to care how this feat is performed, but you should know that all the code involved is accessible. If you are interested, you might want to take a look at a .tm.c file and the Mathematica package Install.m, which resides in the StartUp subdirectory of the Packages directory.
采薪之忧
It was mentioned earlier that when the external program is installed it nds code to Mathematica to t up the "Mathematica side" of the functions it exports. You can also specify arbitrary Mathematica
code to be nt. You might have some accessory code that your functions need to have exist in Mathematica. A simple example is usage messages.
You can specify arbitrary Mathematica code to be nt to the kernel when your program is installed by using another feature of template files, the :Evaluate: line. Here's an example of specifying a usage message:
:Evaluate: AddTwo::usage = "AddTwo[i, j] adds two integers."
:Begin:
:Function: addtwo
:Pattern: AddTwo[i_Integer, j_Integer]
:Arguments: { i, j }
站的英文:ArgumentTypes: { Integer, Integer }
:ReturnType: Integer
为自己活:
End:
Defining messages is a trivial example of the u of :Evaluate: lines. Another common u is to make your functions appear in a package context. The current behavior of Install is to cau all functions defined in installable programs to appear in the Global` context, not the current
