Profile a program

When you click Profile on the Welcome page, the Run window displays.

The settings are grouped into sections. Click Details to expand a section.

Application

Application:

The full path name to your application. If you specified one on the command line, this is automatically filled in. You can browse and select your application.

Note

Many MPIs have problems working with directory and program names that contain spaces. We recommend that you do not use spaces in directory and file names.

Arguments (optional):

The arguments passed to your application. These are automatically filled if you entered some on the command line.

Note

Avoid using quote characters such as ’ and ", as these may be interpreted differently by MAP and your command shell. If you must use these characters but cannot get them to work as expected, contact Forge Support.

stdin file (optional):

This enables you to choose a file to be used as the standard input (stdin) for your program. Arguments are automatically added to mpirun to ensure your input file is used.

Working Directory (optional):

The working directory to use when running your program. If this is blank then MAP’s working directory will be used instead.

Duration

Start profiling after (optional):

This enables you to delay profiling by a number of seconds into the run of your program.

Stop profiling after (optional):

This enables you to specify a number of seconds after which the profiler will terminate your program.

Metrics

This section allows you to explicitly enable and disable metrics for which data is collected. Metrics are listed alphabetically with their display name and unique metric ID under their associated metric group. Select a metric to see a more detailed description, including the metric’s default enabled/disabled state.

Only metrics that can be displayed in the Metrics view are listed. Metrics that are unlicensed, unsupported, or always disabled are not listed. Additionally, you cannot disable metrics that are always enabled.

The initial state of enabled/disabled metrics are the combined settings given by the metric XML definitions, the previous user interface session, and those specified with the --enable-metrics and --disable-metrics command-line options. The command-line options take preference over the previous user interface session settings, and both take preference over the metric XML definitions settings. Of course, metrics that are always enabled or always disabled cannot be toggled.

All CPU instructions displays if available for enabling/disabling.

Capture Environment Variables

This option enables the feature to collect and view the Environment Variables set at the point of launch in the resulting profile.

See Program details for more information.

MPI

Note

If you only have a single process license or have selected none as your MPI Implementation, the MPI options will be missing. The MPI options are not available when in single process mode. See Profile a single-process program for more details about using a single process.

Number of Processes:

The number of processes that you want to profile. MAP supports hundreds of thousands of processes, but this is limited by your license. This option might not be displayed if it is disabled on the Job Submission page in the Options window.

Number of nodes:

This is the number of compute nodes that you want to use to run your program. This option is only displayed for certain MPI implementations, or if it is enabled on the Job Submission page in the Options window.

Processes per Node:

This is the number of MPI processes to run on each compute node. This option is only displayed for certain MPI implementations, or if it is enabled on the Job Submission page in the Options window.

Implementation:

The MPI implementation to use, for example, Open MPI, MPICH 3. Normally the Auto setting will detect the currently loaded MPI module correctly. If you are submitting a job to a queue, the queue settings will also be summarized here. Click Change to change the MPI implementation.

Note

The choice of MPI implementation is critical to correctly starting MAP. Your system will normally use one particular MPI implementation. If you are unsure which to pick, try generic, consult your system administrator, or Forge Support. A list of settings for common implementations is provided in MPI distribution notes and known issues.

Note

If the MPI command you want is not in your PATH, or you want to use an MPI run command that is not your default one, you can configure this using the Options window. See Optional configuration.

mpirun arguments (optional):

The arguments that are passed to mpirun or your equivalent, usually prior to your executable name in normal mpirun usage. You can place machine file arguments, if necessary, here. For most users this field can be left empty.

Note

You should not enter the -np argument because MAP will do this for you.

Profile selected ranks (optional):

If you do not want to profile all the ranks, you can use the --select-ranks command-line option to specify a set of ranks to profile. The ranks should be separated by commas, and intervals are accepted. Example: 5,6-10.

Note

This option acts as a filter for which processes collects and uses profiling data. Your license will still be limited to the number of processes you are launching and is not affected by the selected ranks.

OpenMP

Number of OpenMP threads:

The number of OpenMP threads to run your program with. This ensures the OMP_NUM_THREADS environment variable is set, but your program may override this by calling OpenMP-specific functions.

Environment variable

The optional Environment Variables section should contain additional environment variables that should be passed to mpirun or its equivalent. These environment variables may also be passed to your program, depending on which MPI implementation your system uses. Most users will not need to use this section.

Profiling

Click Run to start your program, or Submit if working through a queue. See Integration with queuing systems. This will compile an MPI wrapper library that can intercept the MPI_INIT call and gather statistics about MPI use in your program. If you have problems, see MPI wrapper libraries. Then Linaro MAP brings up the Running window and starts to connect to your processes.

The program runs inside MAP which starts collecting stats on your program through the MPI interface you selected and will allow your MPI implementation to determine which nodes to start which processes on.

Linaro MAP collects data for the entire program run by default. Its sampling algorithms ensure only a few tens of megabytes are collected even for very long-running jobs. You can stop your program at any time by using the Stop and Analyze button. MAP will then collect the data recorded so far, stop your program and end the MPI session before showing you the results. If any processes remain you may have to clean them up manually using the kill command, or a command provided with your MPI implementation, but this should not be necessary.

Profiling only part of a program

The easiest way to profile only part of a program in MAP is to use the Start profiling after and Stop profiling after settings in the Run dialog, or the equivalent --start-after and --stop-after command-line options. These options enable you to specify a range of wall-clock time (the job starts at 0 seconds) during which the job should be profiled. When the --stop-after time is reached, the job is terminated rather than letting it run to the end.

Alternatively, for more fine-grained control you can choose to start profiling programmatically at a later point by instrumenting your code. To do this you must set the FORGE_SAMPLER_DELAY_START=1 environment variable before starting your program. For MPI programs it is important that this variable is set in the environment of all the MPI processes. It is not necessarily sufficient to simply set the variable in the environment of the MPI command itself. You must arrange for the variable to be set or exported by your MPI command for all the MPI processes.

You can call allinea_start_sampling and allinea_stop_sampling once each. That is to say there must be one and only one contiguous sampling region. It is not possible to start, stop, start, stop. You cannot pause or resume sampling using the allinea_suspend_traces and allinea_resume_traces functions. This will not have the desired effect. You can only delay the start of sampling and stop sampling early.

C

To start sampling programmatically you should #include "mapsampler_api.h" and call the allinea_start_sampling function. You must point your C compiler at the Linaro MAP include directory, by passing the arguments -I /path/to/forge/map/wrapper and also link with the Linaro Forge sampler library, by passing the arguments -L /path/to/forge/lib/64 -lmap-sampler.

To stop sampling programmatically call the allinea_stop_sampling function.

Fortran

To start sampling programmatically call the ALLINEA_START_SAMPLING subroutine. You must also link with the Linaro Forge sampler library, for example by passing the arguments -L /path/to/forge/lib/64 -lmap-sampler.

To stop sampling programmatically call the ALLINEA_STOP_SAMPLING subroutine.

Python

To start sampling programmatically you should import the mapsampler_api module methods (from mapsampler_api import *) and call the allinea_start_sampling function.

To stop sampling programmatically call the allinea_stop_sampling function.