DOCUMENTATION CENTER SEARCH

Configuration

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

$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 and `1` through `4` for connection type LinkConnect.

placeholder	meaning
`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 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

$RemoteCommand="ssh -x -f -l `3` `1` math -mathlink -linkmode Connect `4` -linkname '`2`' -noinit";

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

$RemoteCommand="ssh -n -x -f -l `3` `1` math -mathlink -linkmode Connect `4` -linkname '`2`' -noinit &";

Under Windows, $RemoteCommand is set by default to

$RemoteCommand="rsh `1` -n -l `3` \"math -mathlink -linkmode Connect `4` -linkname `2` -noinit >& /dev/null &\"";

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.

LaunchSlave["host1"]
LaunchSlave["host2"]

To connect to your local machine (recommended for testing and if you have a multiprocessor machine), you should be able to use

LaunchSlave["localhost"]

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"]

$RemoteCommand

the default oscommands to use

RemoteMachine["localhost"]

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 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.

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.

THIS IS DOCUMENTATION FOR AN OBSOLETE PRODUCT.