Configuration Properties for the MPI Cluster Debugger
Updated: February 3, 2010
The MPI Cluster Debugger Add-In has several configuration properties that let you define how to run your debugging session. In the properties pages for you project, you can select the MPI Cluster Debugger, provide arguments for your application, and configure advanced MPI and network settings. The Cluster Debugger Configuration pane includes properties that you can configure to specify information such as:
The cluster and the nodes on which to run the debugging session
The number of processes to run
Pre-debug and post-debug scripts
The sections in this topic provide detailed information about the MPI Cluster Debugger properties, how to access them, and additional information about node selection and process allocation. This topic includes the following sections:
This section describes how to select the MPI Cluster Debugger in Visual Studio, and it describes the MPI Cluster Debugger properties that you can use to provide arguments for your application and to configure advanced MPI and network settings.
To select and configure the MPI Cluster Debugger
On the Project menu, click <yourProjectName> Properties.
In the properties dialog box, under Configuration Properties, select Debugging.
In Debugger to launch, select MPI Cluster Debugger from the drop-down list.
The properties that appear in the dialog box reflect the debugger that you select.
The following table describes the properties that you can configure in project properties dialog box:
Project Debugging properties
MPIRun Command, MPIRun Arguments, MPIRun Working Directory
These properties are equivalent to MPIExec Command, MPIExec Arguments, and the Execution\work directory properties in Cluster Debugger Configuration properties.
The values provided in the Cluster Debugger Configuration pane override any changes to these properties.
Values specified for MPIExec Command, MPIExec Arguments, and Execution\work directory
Specifies the application name or the application path that MPI runs on each cluster node (this is the application that you are debugging in Visual Studio). The path can be a shared resource or a local path.
The debugger copies the application file to the deployment folder.
Specifies arguments that you want to pass to the application.
Specifies the full path to the MPIshim executable file on your development computer. Visual Studio attempts to copy MPIshim from this location to the Deployment Directory.
MPIshim is included with Visual Studio and is installed with the remote debugging features to enable parallel debugging.
You can provide a value for this property as part of a fully customized launch of the MPI Cluster Debugger.
%ProgramFiles%\Microsoft Visual Studio 9.0\Common7\IDE\Remote Debugger
MPI network security mode
Specifies the IP addresses that are allowed to connect to the current instance of Visual Studio.
There are three security modes:
Accept connections from any address
MPI network filter
Specifies the IP address range from which to accept connections. Specify the starting IP address and the subnet mask for this range.
For example, a network filter of 192.168.0.1/255.255.255.0 includes all the addresses between 192.168.0.1 and 192.168.0.254.
Specifies the debugger type for the code you are running: native, managed, mixed, or script.
The debugger type is selected based on the content of the .exe file.
This section describes how to access and use the Cluster Debugger Configuration properties. Use these properties to specify the cluster to use, the number of processes to launch, and additional deployment information.
To open the Cluster Debugger Configuration pane
On the Tools menu, click Cluster Debugger Configuration.
The Cluster Debugger Configuration pane appears.
The following table describes the properties that you can configure in the Cluster Debugger Configuration pane.
Cluster Debugger Configuration properties
Cluster head node
Specifies the head node to use when launching the debugger on the cluster.
The list of head nodes is populated from the Active Directory domain controller. Only clusters in your domain appear in the list. If you do not see your head node, type the name or the IPv4 address of the head node in this field.
Number of processes
The number of MPI processes to start.
This property is overridden by any node and process allocation that you specify in the Nodes to use for debugging property.
Clean up when the debugger stops
Specifies whether Visual Studio will delete the Deployment Directory after debugging.
If True, the Deployment Directory is deleted and the shared resource is removed when the debugger stops.
If False, the Deployment Directory is not deleted.
Job description file
Specifies the path to the job description file (XML) that contains tasks to add to the debugging job. The tasks specified in this file are added before the tasks that the debugger creates (the debugger creates a deployment, a debugging, and a clean-up task).
To create a job description file from a new or queued job in the HPC Job Manager console, in the New Job or the View Job dialog box, click Save Job as.
Specifies the directory in which the project output files will be copied when the debugger starts. This directory is generally on the cluster head node, and it must be a network shared resource that can be read by all of the compute nodes that are participating in the debugging session, for example:
The CcpSpoolDir shared folder is created when HPC Pack 2008 is installed on the head node.
If the Deployment Directory does not exist and you have write permissions in the root directory that is specified, the Deployment Directory is created automatically.
The project output directory.
Specifies the working directory that is used by each process. This is where the executable runs.
During cluster debugging, if this is different than the Deployment Directory, the files from the Deployment Directory are copied into the working directories on the compute nodes.
The Deployment directory
Additional files to deploy
Specifies the files and directories to be copied to the Deployment Directory, in addition to those that are required by the project and its dependencies.
Specifies the full path to the MPI program that coordinates the launch of your MPI application.
If you have another MPI library implementation installed on your compute nodes, and you want to use the associated MPI stack to launch your application, use this property to specify the full path to that executable on each compute node. If the path is not identical on each node, then you must include MPIexec.exe and its dependent libraries in the Additional Files to Deploy property for the debugger.
If the MPI stack that you specify does not support the -hosts parameter, you may encounter runtime errors in specific circumstances. For more information, see Specific node selection and the -hosts parameter.
Specifies additional arguments to pass to MPIexec.exe. For example, you can use additional arguments to set environment variables for the processes that are launched by MPIexec.exe.
If you specify the -hosts parameter, you may encounter runtime errors in specific circumstances. For more information, see Specific node selection and the -hosts parameter.
For more information about the MPIexec command, see mpiexec Command Reference (http://go.microsoft.com/fwlink/?LinkId=144910).
Nodes to use for debugging
Specifies compute nodes to use for debugging and the allocation of processes per compute node.
To request specific nodes and allocate processes, select Edit... from the drop-down list. This opens the Node Selector Tool dialog box. For more information, see the Node selection and process placement section in this topic.
For additional considerations, see the Specific node selection and the -hosts parameter section in this topic.
Deploy CRT files
Specifies whether Visual Studio deploys the C run-time (CRT) assemblies with the application.
If True, the CRT assemblies are deployed with the application.
If False, the CRT assemblies are not deployed with the application.
If your multithreaded debug dynamic-link libraries (DLLs) are statically linked, you do not need to deploy the CRT files. If your multithreaded debug DLLs are dynamically linked, you need to deploy the CRT files.
Specifies the path to the script to run before debugging. The script runs in the same computer where Visual Studio is running.
For example, you can use a pre-debug script to stage data for your application on the nodes or to adjust the firewall settings on the cluster to allow the remote debugger.
Pre-debug script arguments
Specifies the argument string that is passed to the pre-debug script.
Specifies the path to the script to run after debugging stops.
For example, you can use a post-debug script to clean up staged data or the output files that are produced by your application or to adjust the firewall settings on the cluster to disallow the remote debugger after your debugging session.
Post-debug script arguments
Specifies the argument string that is passed to the post-debug script.
You can select which nodes to use for debugging and how to allocate processes by using the Node Selector Tool dialog box. The dialog box lists the nodes on the cluster, and provides some metrics and information about each node.
The Node Selector Tool provides three allocation options:
On the selected nodes, run one process on each <resource type>. This option runs one process on each core, node, or socket for the nodes that you select in the node list.
Total process to allocate. This option runs the specified number of processes on cores from the nodes that you select in the node list. For example, if you specify 12 processes and select two 8-core nodes, the debugger may start eight processes on the first node, and four on the second. If you use at least one core on a node, the entire node is allocated to your debugging job.
Use the node selection pane to specify how many processes to run on each node. This option enables you to allocate a specific number of processes to each node. When you select this option, a column named # Cores appears in the node list. Use this column to select the number of processes to run individual nodes.
The resource selection that you specify in the Node Selector Tool overrides the Number of processes property and any resource allocations that are specified in the job description file.
To specify nodes and process allocation
In the Cluster Debugger Configuration pane, in Nodes to use for debugging, select Edit from the drop-down list.
The Node Selector Tool dialog box appears.
Select the radio button for the desired allocation option.
Select one or more nodes in the node list to use for debugging.
For additional considerations, see the Specific node selection and the -hosts parameter section in this topic.
When you configure the MPI Cluster Debugger, you must specify the cluster to use and the number of processes to launch. Optionally, you can select specific nodes to use for the debugging session.
The MPI Cluster Debugger uses the -hosts parameter with the MPIexec command to place the processes when both of the following conditions are true:
You select specific nodes to use for the debugging session.
The number of processes that you selected is smaller than the number of resources on the required nodes.
If you request specific nodes and the total number of resources on the required nodes is greater than the number of processes that you specified, the debugger uses the -hosts parameter to place the processes. For example, if you select two nodes (NODE01 and NODE02) with four cores each, and specify that you want to launch six processes, the debugger passes the following argument to MPIexec.exe: -hosts 2 NODE01 4 NODE2 2.
If the MPI Cluster Debugger uses the -hosts parameter to place the processes, a run-time error occurs if either of the following conditions is true: