This is documentation for an obsolete product.
Current products and services
Previous section-----Next section

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 and ssh 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 daemon.
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 setting.
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 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 nor Mathematica supply an ssh client for Windows, but there are several available commercially. You can then use the following command to launch remote kernels:
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 installation.

Remote machines running Mac OS X

No math 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 for more information.
The kernel is typically at $InstallationDirectory/Contents/MacOS/MathKernel.
The Mathematica 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.

Passive Connections

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 or port1@host,port2@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".
Alternatively, ConnectSlave 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.
Mathematica 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[1]:= appears.
  • 2. At the In[1]:= 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[2]:=, 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.
LaunchSlave["remotehost", "oscommands"]
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)
LaunchSlave["localhost", "oscommands"]
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
$ProcessorIDa 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 and `1` through `4` for connection type LinkConnect.
`1`host namethe remote host name, the first argument of LinkLaunch.
`2`link namethe name of the link object created
`3`remote userthe user name on the remote machine, the value of $RemoteUserName, which defaults to $UserName.
`4`protocola 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 namedefault value
InitCode$InitCodea sequence of commands (wrapped inside Hold) to send to each remote kernel upon startup
ConnectionTypeAutomaticthe 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
LinkProtocolAutomaticthis 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        1an estimate of the relative speed of the remote kernel

Options of LaunchSlave.

The default value of the variable $InitCode is Hold[$DisplayFunction=Identity;].
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
If $RemoteCommand is set up correctly, you can simply use the following commands to start a kernel on remote hosts named, for example, host1 and host2.
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.
RemoteMachine["remotehost", "oscommands"]
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"]
$RemoteCommandthe default oscommands to use
host description for the local machine
$mathkernelthe 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 and $RemoteCommand 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 and $RemoteCommand 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 package.
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 or ConnectSlave 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.

Kernel Initialization

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.