mpipingpong
Applies To: Microsoft HPC Pack 2012, Microsoft HPC Pack 2012 R2
Runs the Message Passing Interface (MPI) ping-pong test by sending packets of data back and forth between paired nodes repeatedly, and displays or saves the latency and throughput measurements and statistics from the test to an XML file.
For examples of how to use this command, see Examples.
Syntax
mpipingpong [-m] [{-r [-rs <ring_step_size>] | -s | -t}]
[{-p <packet_size>[:<iterations>] | -pb | -pc | -pl | pt}] [{-oa | -ob}]
[{-op | -oq}] [[<path>:\]<output_file_name>]
mpipingpong -h
Parameters
Parameter |
Description |
|---|---|
–m |
Allows multiple cores on the same node to participate in the test. If you do not specify -m, only one core on each node can participate in the test. If you attempt to use more than one core on the same node when you have not specified the -m option, an error occurs. You can also specify the –m option as --multiple-cores. |
–r |
Runs a serial ring test. In a serial ring test, nodes send packets to each other one pair at a time in a ring pattern, while all nodes not in the pair that is running the test at the time remain idle. The first node pairs with a neighbor that is <ring_step_size> steps away, where <ring_step_size> is the value that the -rs option specifies. If you do not specify the -rs option, the node pairs with its immediate neighbor. When the test on the first pair is complete, the next node similarly pairs with a neighbor. This sequential pairing and testing continues until the test covers all of the nodes in the HPC cluster and each node has paired with two neighbors, one in each direction around the ring. The serial ring test tests <number_of_nodes> pairs of nodes. In mathematical terms, the serial ring test induces a cycle graph on the set of tested nodes. Use the serial ring test to obtain a reasonable indication of the performance of an HPC cluster in a minimal amount of time. The serial ring test takes less time than a serial or tournament-style test because it tests fewer pairs of nodes while still including all nodes in the test. You cannot specify the –r option if you also specify the –s option or the –t option. You can also specify the –r option as --ring. |
–rs <ring_step_size> |
Specifies the number of communication steps between neighboring nodes that pair with each other and participate in a serial ring test. The value of the ring step size can be from 1 to <number_of_nodes> - 1. The default value is 1. The –rs option only has an effect if you also specify the -r option. You can also specify the -rs option as --ring-step. |
–s |
Runs the MPI ping-pong test one pair at a time. While one pair of nodes runs the test, all nodes not in the pair that is running the test at the time remain idle. When one pair of nodes finishes the test, the test runs for another pair of nodes, and this testing of individual pairs proceeds serially until all possible pairs of nodes are tested. The serial test tests all possible <number_of_nodes> * (<number_of_nodes> - 1)/2 pairs of nodes. In mathematical terms, the serial test induces a complete graph of the set of tested nodes. You cannot specify the –s option if you also specify the –r option or the –t option. You can also specify the –s option as --serial. Use the serial test to thoroughly test all of the individual network links between nodes when the HPC cluster has a small number of nodes. Because the serial test runs the MPI ping-pong test on all possible pairs of nodes one pair at a time, the test can take a long time for large numbers of nodes. |
–t |
Runs the MPI ping-pong test in multiple rounds, similar to a tournament. In each round, all of the nodes in the HPC cluster pair off. The two nodes in each pair send packets to each other, and all of the pairs exchange packets in parallel. When one round is complete, another round begins, using a different set of node pairings than was used in previous rounds. The rounds continue until all possible node pairs have been tested. The tournament-style test tests all possible <number_of_nodes> * (<number_of_nodes> - 1)/2 pairs of nodes. In mathematical terms, the tournament-style test induces a complete graph on the tested set of nodes. When you use the -t option in combination with the -pl option to measure latency, the test introduces little noise into the simultaneous latency measurements of each round. The packets are small and even heavily over-subscribed network switches do not impede the packets. You can obtain more accurate latency measurements, if necessary, if you use the -s option to test all pairs serially. You cannot specify the –t option if you also specify the –r option or the –s option. You can also specify the –t option as --tournament. This option is the default. |
-p <packet_size>[:<iterations>] |
Specifies the size of the data packets to use in the MPI ping-pong test, in bytes. You can specify the -p option multiple times to use packets of multiple sizes in the test. You can optionally specify the number of times that a pair of nodes should send packets of a given size back and forth by specifying a value for <iterations>. If you do not specify the number of iterations, the mpipingpong command chooses an appropriate number of iterations for the packet size. The mpipingpong command uses a smaller number of iterations for larger packets sizes. You cannot specify the –p option if you also specify the –pb, -pc, -pl, or -pt option. You can also specify the –p option as --packet-size. |
–pb |
Tests both network latencies for 4-byte packets and network throughput for 4-megabyte (MB) packets. You cannot specify the –pb option if you also specify the –p, -pc, -pl, or -pt option. You can also specify the –pb option as --latency-thru. |
–pc |
Generates network performance data for a full set of packet sizes ranging from 4 bytes to 4 MB, with each packet size in the set increasing by a power of 2. You can use data for creating graphs that illustrate network performance. You cannot specify the –pc option if you also specify the –p, -pc, -pl, or -pt option. You can also specify the –pc option as --curve-data. |
–pl |
Tests network latencies by using 4-byte packets in the MPI ping-pong test. The latency is the average of half of the time that it takes for a packet to make a round trip between a pair of nodes, in microseconds. You cannot specify the –pl option if you also specify the –p, -pb, -pc, or -pt option You can also specify the –pl option as --latency. This option is the default. |
–pt |
Tests network throughput by using 4-MB packets in the MPI ping-pong test. The throughput is the average rate of data transfer between a pair of nodes, in MB/second. You cannot specify the –pt option if you also specify the –p, -pb, -pc, or -pl option. You can also specify the –pt option as --throughput. |
–oa |
Sends an abbreviated form of the XML output for the test results that does not include the LinkDetails section to standard output. The mpipingpong command still saves the complete version of the test results in the output file, if you specify a file. You cannot specify the –oa option if you also specify the –ob option. You can also specify the –oa option as --stdout-abbrev. |
–ob |
Sends a brief form of the XML output for the test results to standard output. These results include the TestOverview and Summary sections, but they leave out the NodeDetails and LinkDetails sections. The mpipingpong command still saves the complete version of the test results in the output file, if you specify a file. You cannot specify the –ob option if you also specify the –oa option. You can also specify the –ob option as --stdout-brief. |
–op |
Sends progress information that includes latency and throughput data for each pair of nodes that are tested to the standard error stream. If you do not specify the -op or -oq option, the progress information includes the percentage of pairs that are tested for different packets sizes. The use of the -op option is highly recommended, because the -op option provides the user with plain-text output in real time. You cannot specify the –op option if you also specify the –oq option. You can also specify the –op option as --progress-full. |
–oq |
Suppresses sending all progress information to the standard error stream report. You cannot specify the –oq option if you also specify the –op option. You can also specify the –oq option as --progress-quiet. |
–h |
Displays Help at the command prompt. You can also specify the -h option as -help or -?. |
[<path>:\]<output_file_name> |
Specifies the name of the XML file in which you want to save the results of the MPI ping-pong test, including a full network path if you do not want to save the file in the working directory of the task that you use to run the mpipingpong command. If you do not specify a file, the mpipingpong command sends the results to standard output. |
Remarks
The mpipingpong command is an MPI program that you run by using the mpiexec command. You need to submit the mpiexec command that runs the mpipingpong command as a task in a job.
When you use the mpipingpong command to measure latency or throughput, the command first warms up the network between each node pair by sending packets of the appropriate size back and forth between the nodes. These test results are ignored.
Examples
To run the MPI ping-pong test for an HPC cluster with 256 nodes and save the test results in the XML file located at \\headnode\MyPingPongResults\results.xml, using the default settings to measure latency in a tournament-style test, type the following command at a command prompt:
job submit /numnodes:256 mpiexec -n 256 mpipingpong \\headnode\MyPingPongResults\results.xml
To run a serial ring MPI ping-pong test for an HPC cluster with three nodes named headnode, computenode1, and computenode2, send progress information that includes latency and throughput data for each pair of nodes tested to the standard error stream, and save the test result in the XML file located at \\headnode\MyPingPongResults\test5.xml, using a packet size of 4096 bytes over 1600 iterations, use the following cmdlet in an HPC PowerShell window:
New-HpcJob -NumNodes:3-3 |
Add-HpcTask -RequiredNodes headnode,computenode1,computenode2 -CommandLine "mpiexec mpipingpong -r -p 4096:1600 -op
\\headnode\MyPingPongResults\test5.xml" | Submit-HpcJob