Remote Execution Options
To use active or callback connections, you need a way to execute a command to start Mathematica
on the remote computer.
The available methods for remote command execution depend on the operating system of the master and slave machines. The network applications rsh
are standard under Unix. Under Windows you can use any rsh
program that may be provided with the system or available from a number of sources.
Your local machine, from which you want to initiate a connection, needs an ssh
or rsh client program
; the remote machine needs a corresponding daemon
Remote Execution under Windows
Under Windows you can use any available rsh
program to start remote kernels. The remote kernel can then establish a TCPIP connection back to the local kernel. This is most easily done by creating a MathLink
object locally to which the remote kernel can establish a callback connection.
On the remote end, the Mathematica
kernel command-line arguments -linkmode Connect -linkprotocol TCPIP -linkname port1@host,port2@host
instruct the kernel to connect to an open port on your local machine, host
. The Toolkit
will provide the port1@host,port2@host
argument for you. Use `2`
to interpolate it into the command string.
You need a rsh
daemon for all remote machines. Note that Mathematica
does not provide an rsh
If your version of Windows includes rsh
, you can use these arguments to LaunchSlave
to make connections to remote hosts.
This command uses the following template for starting the remote kernel:
The first placeholder `1`
will be replaced by the hostname remotehost
as usual; the second placeholder `2`
will be replaced by a link object created on the local machine to which the remote kernel can connect. The placeholder `3`
is replaced by the username. If the remote host does not require a login user name, omit the -l `3`
option. The placeholder `4`
is replaced by the correct -linkprotocol
You may have to prefix the remote kernel command math
with the appropriate pathname, such as /usr/local/bin/math
for a remote Unix system. Be sure to give the correct user name for connecting to the remote machine.
Available third-party software
A list of third-party rsh
daemons and clients can be found at support.wolfram.com/applicationpacks/parallel/
. The author, MathConsult AG, and Wolfram Research, Inc. do not endorse any of the products listed at that URL. We provide this information in the hope that it may be useful.
If you have an ssh
client installed on Windows, you may be able to connect to a remote Unix or Mac OS X slave using ssh
. Neither Parallel Computing Toolkit
supply an ssh
client for Windows, but there are several available commercially. You can then use the following command to launch remote kernels:
","ssh -x -f -l `3` `1` \"math -mathlink -linkmode Connect `4` -linkname '`2`' </dev/null >&/dev/null &\""]
The exact arguments needed may vary with network and machine configurations.
Starting a kernel on a local Windows machine
For testing and in multiprocessor machines, you can conveniently start a kernel on the local machine. Use this command.
This command uses the value of the variable $mathkernel
as the command to launch a kernel. It should be set up suitably for your Mathematica
Remote machines running Mac OS X
script is installed on Mac OS X. To launch a remote kernel on a Mac OS X machine, you can either give the full pathname of the MathKernel
executable or write your own math
script; see the support pages support.wolfram.com/applicationpacks/parallel/
for more information.
The kernel is typically at $InstallationDirectory/Contents/MacOS/MathKernel
","ssh `1` \"/Mathematica.app/Contents/MacOS/MathKernel
-mathlink -linkmode Connect `4` -linkname '`2`' </dev/null >&/dev/null &\""]
5.2 pathname contains space characters, so the pathname needs to be enclosed in double quotes and the space escaped by a backslash. Here is an example command to launch a Mathematica
5.2 kernel on a Mac OS X machine.
","ssh `1` \"\"/Mathematica\\ 5.2.app/Contents/MacOS/MathKernel
\" -mathlink -linkmode Connect `4` -linkname '`2`' </dev/null >&/dev/null &\""]
If your local computer does not provide an rsh
client or the remote computer does not provide an rsh
daemon, you have to start the required remote kernels manually on each remote computer.
These command-line options should be given to the kernel command on the remote machines.
Under Windows, you should add -linkprotocol TCPIP
The kernel will start up and tell you the address or linkname
where it is listening. Addresses have the form port@host
, where port
is a TCP port number (a decimal integer) and host
is the computer's name.
With this information, you can establish a connection from your local kernel to the remote one with the following command.
Under Windows, you should include the option setting LinkProtocol->"TCPIP"
can take an already established MathLink
link object as its argument.
Note that you may be able to use a Telnet application to log in to a remote computer, so you can give the commands described in the following section from your local machine. Otherwise, you will have to enter the command at the computer's console.
Windows Remote Computer
To start a kernel on Windows, give the following command in an MS-DOS window on the remote computer.
math -mathlink -linkcreate -linkprotocol TCPIP
will open a small panel that displays the ports on which it is listening. You must close this panel before the connection can be used.
Once you have the listening port information, connect to the waiting remote kernel from your local computer with the command ConnectSlave["linkname",LinkProtocol->"TCPIP"]
Using a Running Kernel
You can also prepare a running kernel as a remote kernel for parallel computations. Start the kernel by double-clicking on the Mathkernel (not Mathematica
) icon or starting math
in a shell window. You can then create the required link from within the Mathematica
kernel as follows.
- 1. Launch (double-click) MathKernel. Do not launch Mathematica! A window with the prompt In:= appears.
- 2. At the In:= prompt, give the following command shown here with the expected form of the result.
- 3. Take note of the port numbers that appears in place of port.
- 4. At the next input prompt, In:=, give the following command. No output will be produced.
With this information, you can now connect to the waiting remote kernel from your local computer with the command ConnectSlave["port1@host,port2@host"]
Configuring Parallel Computing Toolkit
This section lists the commands available in PCT and shows you how you can prepare a configuration file to automate the task of starting the remote kernels that are usually available to you.
Launching Remote Kernels
To start a remote kernel and add it to the list of available slave processors, use the command LaunchSlave
| ||use the operating system (shell) command oscommands to start a kernel on a remote machine named remotehost and have it connect to a link created on the local machine|LaunchSlave["remotehost", "oscommands", ConnectionType->LinkLaunch]
| ||use the operating system (shell) command oscommands to start a kernel on a remote machine named remotehost using LinkLaunch (no separate MathLink connections)|
| ||use the operating system (shell) command oscommands to start a kernel on the local machine (using LinkLaunch)|
| ||use the operating system (shell) command stored in $mathkernel to start a kernel on the local machine|
| ||use the operating system (shell) command stored in $RemoteCommand to start a kernel|
|$ProcessorID||a unique integer assigned to each remote kernel (Numbers are assigned starting with 1.)|
Starting remote kernels.
The argument oscommands
can be a template containing the character sequences `1`
for connection type LinkLaunch
for connection type LinkConnect
|`1`||host name||the remote host name, the first argument of LinkLaunch.|
|`2`||link name||the name of the link object created|
|`3`||remote user||the user name on the remote machine, the value of $RemoteUserName, which defaults to $UserName.|
|`4`||protocol||a suitable -linkprotocol proto setting for the MathLink argument list|
Placeholders in operating system command templates.
If there is no LinkProtocol->"proto"
setting in LaunchSlave
, the placeholder `4` expands to the empty string for local connections (to use the native default protocol) and to -linkprotocol TCPIP
for remote connections. If an explicit LinkProtocol->"proto"
setting exists, `4` expands to -linkprotocol proto
The following options can be given in LaunchSlave
|option name||default value|| |
|InitCode||$InitCode||a sequence of commands (wrapped inside Hold) to send to each remote kernel upon startup|
|ConnectionType||Automatic||the MathLink connection type, which can be either LinkLaunch or LinkCreate; by default, LinkLaunch is used for local kernels, and LinkCreate is used for remote kernels|
|LinkProtocol||Automatic||this option is passed on to LinkLaunch or LinkCreate. by default, "TCPIP" is used for remote kernels, and no setting is used for local kernels|
|LinkHost||""||this option is passed on to LinkCreate. It can be used to specify the interface on which the link is listening.|
|ProcessorSpeed ||1||an estimate of the relative speed of the remote kernel|
Options of LaunchSlave.
The default value of the variable $InitCode
These options can also be given to ConnectSlave
If all or most of your remote hosts can be reached with the same command, you can set $RemoteCommand
to a suitable command template that is used by default in LaunchSlave
Under Windows, $RemoteCommand
is set by default to
$RemoteCommand="rsh `1` -n -l `3` \"math -mathlink -linkmode Connect `4` -linkname `2` -noinit >& /dev/null &\"";
is set up correctly, you can simply use the following commands to start a kernel on remote hosts named, for example, host1
To connect to your local machine (recommended for testing and if you have a multiprocessor machine), you should be able to use
You may want to verify that $mathkernel
contains the appropriate command for invoking a local kernel by evaluating $mathkernel
Using Passive Connections
For passive connections, you should manually start the remote kernels with the -linkcreate
argument as described earlier
, note the ports on which the remote kernels are listening, and use ConnectSlave
for each remote kernel.
|ConnectSlave["linkname"]||connect to a listening link on the given computer|
|ConnectSlave[link]||connect to an existing MathLink object|
Connecting to listening kernels.
Port numbers will usually be different each time you start a remote kernel; therefore, this method cannot easily be automated.
Preparing a Host Description List
To automate the task of starting remote kernels, you can prepare a list of available machines.
| ||a host description for a computer named remotehost using the command oscommands for connection and using the default connection type defined for LaunchSlave|
| ||host description for a computer named remotehost using the default command $RemoteCommand for connection|
|"remotehost"||simple host name; shortcut for RemoteMachine["remotehost"]|
|$RemoteCommand||the default oscommands to use|
| ||host description for the local machine|
|$mathkernel||the default command to start a local kernel|
Host description entries.
The command LaunchSlaves[list]
takes a list of such host descriptions as an argument and tries to establish a connection to each of the hosts listed.
Finally, you can assign a list of host descriptions to the global variable $AvailableMachines
and use LaunchSlaves
without an argument, which will consult this variable.
Defining a Default Configuration
Note that you can put assignments for $AvailableMachines
into your personal Mathematica
kernel startup file init.m
You do not need to load Parallel Computing Toolkit
to define a default configuration. There is a smaller package Parallel`Configuration`
that you can load instead.
Alternatively, you can put assignments for $AvailableMachines
into a notebook and evaluate them to set up the connections. You can use one of the samples here as a template. Copy the appropriate cell group into a new notebook and save it under a name such as UnixInit.nb or WindowsInit.nb. Then you can simply open this notebook and evaluate its cells to set up your remote kernels.
Sample configuration for Windows
Some of the input cells in this template have been made inactive (not evaluatable), because they contain commands for optional features. Enable these cells on a case-by-case basis according to your needs. These commands will evaluate properly only if you have access to a Windows machine on which to start a kernel and you substitute valid values for variable arguments.
Load the Parallel Computing Toolkit
Set your default remote command if the default is not suitable.
Set the default remote username if it is different from your local user name.
If you have ssh
available, you can set $RemoteCommand
to use ssh
Set the default initialization for your remote kernels.
List any normally available machines, filling in the hostname
variable in each entry.
Now you can try to start a remote kernel on all defined remote machines.
You can also put LaunchSlave
commands for special cases here and evaluate them as needed.
Start a kernel on the local machine.
Connect to a manually started remote kernel.
Now verify that all remote kernels are operating correctly by collecting information about them.
After finishing your computations, you should close all connections.
To prevent the execution of the initialization commands you may have put into your init.m file, add the argument -noinit
to any kernel invocation command. This is recommended unless you have put specific commands for initializing remote kernels into init.m.
You can put your remote kernel initialization commands into the PCT variable $InitCode