Mathematica 9 is now available
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 Unix and Mac OS X

To make a connection from your local Unix or Mac OS X machine you can use the rsh or ssh programs.
The shell ssh is a replacement for rsh that offers secure cryptographic authentication and encryption of the communication between the local and remote machine. It is, therefore, usable in situations where the rsh security is insufficient such as on the internet. If your site is requiring ssh, please contact your system administrator about your local setup. Parallel Computing Toolkit has been tested with Version 2 of ssh.

Using ssh

To test whether ssh is configured correctly, the following command can be given in a shell window.
Here, remotehost is the name of the remote machine and math is the command to start a Mathematica kernel on the remote machine. If the remote machine is outside of the local area network, then remotehost must be a fully qualified domain name. If the math command is not on the search path, the full pathname can be given instead, for example /usr/local/bin/math.
It is a good idea to try to establish a connection in a shell window to see whether everything is set up correctly before trying to use the given remote host in Parallel Computing Toolkit. If everything is fine, the remote kernel should print the familiar In[1]:= prompt. You can then use Quit[] to terminate the remote kernel and the connection to the remote machine.
Once ssh is working, you can use the following command to start a kernel on a remote Unix machine.
The placeholder `1` is replaced by the remote host name remotehost, `2` is replaced by the link specification of the link created by LinkCreate[]. The resulting command is then executed by the operating system. LaunchSlave[] supports a number of additional placeholders to accommodate more complicated situation, see the section Configuring the Parallel Computing Toolkit.
If you leave out the second argument, the following default is used.
For an active connection that uses standard input and output as MathLink transport, use the following command.
The placeholder `1` is replaced by the remote host name remotehost. The resulting command is then executed by the operating system.
You may have to prefix the remote kernel command math with the appropriate pathname on the remote machine, such as /usr/local/bin/math.

rsh

The following shell command starts an interactive Mathematica kernel on a remote machine.
Here, remotehost is the name of the remote machine and math is the command to start a Mathematica kernel. If the remote machine is outside of the local area network, then remotehost must be a fully qualified domain name. If the math command is not on the search path, the full path name can be given instead, for example /usr/local/bin/math.
It is a good idea to try to establish a connection in a shell window to see whether everything is set up correctly before trying to use the given remote host in Parallel Computing Toolkit. If everything is fine, the remote kernel should print the familiar In[1]:= prompt. You can then use Quit[] to terminate the remote kernel and the connection to the remote machine.
Once rsh is working, you can use the following Toolkit command to start a kernel on a remote Unix machine, using a callback connection.
The placeholder `1` is replaced by the remote host name remotehost, `2` is replaced by the link specification of the link created by LinkCreate[]. The resulting command is then executed by the operating system.
For an active connection that uses standard input and output as MathLink transport, use the following command.
The placeholder `1` is replaced by the remote host name remotehost. The resulting command is then executed by the operating system.
You may have to prefix the remote kernel command math with the appropriate pathname, such as /usr/local/bin/math.
To start a kernel on a remote Windows machine, the remote machine must have an rsh daemon running. You can start a remote kernel on a Windows machine from a Unix host by using commands similar to those explained in the section Remote Execution under Windows. For example, issue the following command on a local Unix machine to start a remote kernel on a remote Windows host.

Security considerations

You can only use rsh if you are allowed to log into the remote machine without a password. For this to work, your local machine must be in the remote machine's /etc/hosts.equiv or ~/.rhosts file. See the Unix Manual for rlogin and rsh for more details and consult your system administrator.

Starting kernels on your local machine

For testing, and if you have a multiprocessor machine available, you can also start kernels on your local machine where you operate the master kernel and the front end.
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.
Here is a typical value for Mac OS X.

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 support.wolfram.com/applicationpacks/parallel/ 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.
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.
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.

Unix and Mac OS X Remote Computers

To start a kernel on Unix, give the following command in a shell or Telnet window.
Mathematica will output the listening ports on standard output. If math is not on your search path, give an absolute path name, such as /usr/local/bin/math.
Once you receive the listening port information, you can connect to the waiting remote kernel from your local computer with the command ConnectSlave["linkname",LinkProtocol->"TCPIP"] (you can omit the option setting on a Unix local computer).

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.
In[1]:=
  • 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.
In[2]:=
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)
LaunchSlave["localhost"]
use the operating system (shell) command stored in $mathkernel to start a kernel on the local machine
LaunchSlave["remotehost"]
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.
placeholdermeaning
`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.
For Unix and Mac OS X, the default value is
One requirement is that the command return quickly, even though Mathematica keeps running. If it does not return, you can put the command into the background with a setting like the following
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
RemoteMachine["remotehost"]
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
RemoteMachine["localhost"]
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 Unix and Mac OS X

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 Unix machine on which to start a kernel and you substitute valid values for variable arguments.
Load the Parallel Computing Toolkit package.
Set your default $RemoteCommand.
Set the default remote username if it is different from your local user name.
Set the default initialization for your remote kernels.
List any normally available machines.
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, 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.


Any questions about topics on this page? Click here to get an individual response.Buy NowMore Information
THIS IS DOCUMENTATION FOR AN OBSOLETE PRODUCT.