Configuration Properties for the MPI Cluster Debugger
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
Deployment information
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:
Project debugging properties
Cluster Debugger Configuration properties
Node selection and process placement
Specific node selection and the -hosts parameter
Project debugging properties
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
Property |
Description |
Default Value |
|---|---|---|
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 |
Application Command |
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. |
$(TargetPath) |
Application Arguments |
Specifies arguments that you want to pass to the application. |
None |
MPIShim Location |
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. Important To apply this filter, in MPI Network Security Mode, select Accept connections from a specified range of addresses. |
None |
Debugger Type |
Specifies the debugger type for the code you are running: native, managed, mixed, or script. |
Auto The debugger type is selected based on the content of the .exe file. |
Cluster Debugger Configuration properties
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
Property |
Description |
Default Value |
|---|---|---|
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. |
localhost |
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. Note The Deployment Directory is not deleted if it contains files other than those put there by Visual Studio. For example, if your application produces output to the Deployment Directory, you should use a post-debug script to delete the directory. If False, the Deployment Directory is not deleted. |
True |
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). Note The resources that you select in the cluster debugger properties override any resource allocations specified in the job description file. 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. |
None |
Deployment directory |
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. |
Local debugging: The project output directory. Cluster debugging: \\$(HeadNode)\CcpSpoolDir |
Execution\work 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. |
None |
MPIExec Command |
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. |
MPIexec.exe |
MPIExec Arguments |
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 (https://go.microsoft.com/fwlink/?LinkId=144910). |
None |
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. Note The resource selection that is specified in this property overrides the Number of process property and any resource allocations that are specified in the job description file. For additional considerations, see the Specific node selection and the -hosts parameter section in this topic. |
None |
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. |
True |
Pre-debug script |
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. |
None |
Pre-debug script arguments |
Specifies the argument string that is passed to the pre-debug script. |
None |
Post-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. |
None |
Post-debug script arguments |
Specifies the argument string that is passed to the post-debug script. |
None |
Node selection and process placement
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.
Note
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.
Click OK.
For additional considerations, see the Specific node selection and the -hosts parameter section in this topic.
Specific node selection and the -hosts parameter
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.
Note
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:
-
You have specified an MPI stack that does not support the -hosts parameter.
-
You have specified the -hosts parameter in the Additional MPIExec Arguments property.
See Also
Using the MPI Cluster Debugger Add-In for Visual Studio 2008