Allinea MAP

Allinea MAP is a full scale profiler for HPC programs. We recommend using Allinea MAP after reviewing reports from Allinea Performance Reports. MAP supports pthreads, OpenMP, and MPI software on CPU, GPU, and MIC based architectures.

Availability & Restrictions

Versions

The Allinea MAP versions currently available at OSC are

VERSION OAKLEY RUBY OWENS
5.1 X X  
6.0.1 X X  
6.0.6     X      
6.1.1   X  
7.0  X*  X*

 X*

* Current default version

You can use module spider allinea to view available modules for a given machine. Feel free to contact OSC Help if you need other versions for your work.

Access

Allinea MAP is available to all OSC users. We have 64 seats with 80 HPC tokens. Users can monitor the Allinea License Server Status.

Usage

Set-up

To load the default version of the Allinea MAP module, use module load allinea. To select a particular software version, use module load allinea/version. For example, use module load allinea/6.0 to load allinea MAP version 6.0, provided the version is available on the cluster in use. 

Using Allinea MAP

Profiling HPC software with Allinea MAP typically involves three steps: 

1. Prepare the executable for profiling.

Regular executables can be profiled with Allinea MAP, but source code line detail will not be available. You need executables with debugging information to view source code line detail: re-compile your code with a -g  option added among the other appropriate compiler options. For example:

mpicc wave.c -o wave -g -O3

This executable built with the debug flag can be used for Allinea Performance Reports as well.

Note: The -g  flag turns off all optimizations by default. For profiling your code you should use the same optimizations as your regular executable, so explicitly include the -On flag, where n is your normal level of optimization, typically -O2 or -O3, as well as any other compiler optimization options.

2. Run your code to produce the profile data file (.map file).

Profiles are normally generated in a batch job.  To generate a MAP profile for an MPI program:

module load allinea
map --profile -np <num proc> --mpiargs="<mpi args>" <program> <program args>

where <num procs> is the number of MPI processes to use, <mpi args> represents arguments to be passed to mpiexec (other than -n or -np), <program> is the executable to be run and <program args> represents arguments passed to your program.

For example, if you normally run your program with mpiexec -n 12 wave_c, you would use

map --profile -np 12 wave_c

To profile a non-MPI program:

module load allinea
map --profile --no-mpi <program> <program args>

The profile data is saved in a .map file in your current directory.

As a result of this step, a .map file that is the profile data file is created in your current directory. The file name is based on the executable name, number of processes, date and time, for example,  wave_c_12p_2016-02-05_12-46.map.

For more details on using Allinea MAP, refer to the Allinea Forge User Guide.

3. Analyze the profile data file using either the Allinea local client or the MAP GUI.

You can open the profile data file using a client running on your local desktop computer. For client installation and usage instructions, please refer to the section: Client Download and Setup. This option typically offers the best performance.

Alternatively, you can run MAP in interactive mode, which launches the graphical user interface (GUI).  For example:

map wave_c_12p_2016-02-05_12-46.map

For the GUI application, one should use an OnDemand VDI (Virtual Desktop Interface) or have X11 forwarding enabled (see Setting up X Windows). Note that X11 forwarding can be distractingly slow for interactive applications.

MAP with GPU

Allinea MAP can be used for CUDA codes. If you have an executable compiled with the CUDA library, you can launch Allinea MAP with

map {executable}

For more information, please read the chapter 15 of the Allinea Forge User Guide.

Client Download and Setup

1. Download the client.

To download the client, go to the Allinea website and choose the appropriate Allinea Forge remote client download for Windows, Mac, or Linux. For Windows and Mac, just double click on the downloaded file and allow the installer to run. For Linux, extract the tar file using the command tar -xf file_name and run the installer in the extracted file directory with ./installer. Please contact OSC Help, if you have any issues on downloading the client.

Note:  Allinea was recently bought out by Arm.  The Allinea Forge client can be downloaded from https://developer.arm.com/products/software-development-tools/hpc/downloads/download-arm-forge/older-versions-of-remote-client-for-arm-forge.
2. Configure the client.

After installation, you can configure the client as follows:

  • Open the client program. For Windows or Mac, just click the desktop icon or navigate to the application through its file path. For Linux use the command {allinea-forge-path}/bin/map.

  • Once the program is launched, select Allinea MAP in the left column.
  • In the Remote Launch drop down menu, select "Configure...".
  • Click Add to create a new profile for your login.
  • In the Host Name section, type your ssh connection. For example: "username@ruby.osc.edu".
  • For Remote Installation Directory, type /usr/local/allinea/forge-{version}, specifying the Allinea Forge version number that created the data profile file you are attempting to view. For example, /usr/local/allinea/forge-7.0 for Allinea Forge version 7.0.
  • You can test your login information by clicking Test Remote Launch. It will ask your password. Use the same password for the cluster login.
  • Close the Configure window. You will see a new option under the Remote Launch drop down menu for the host name you entered. Select your profile and login with your password. 
  • If the login was successful, then you should see License Serial:XXX in the bottom left corner of the window.

This login configuration is needed only for the first time of use. In subsequent times, you can just select your profile.

3. Open the profile data file.

After login, click on LOAD PROFILE DATA FILE. This opens a file browser of your home directory on the OSC cluster you logged onto. Go to the directory that contains the .map file and select it. This will open the file and allow you to navigate the source code line-by-line and investigate the performance characteristics. 

A license is not required to simply open the client, so it is possible to skip 2. Configure the client, if you download the profile data file to your desktop. You can then open it by just selecting LOAD PROFILE DATA FILE and navigating through a file browser on your local system.

Note that the client is Allinea Forge, a client that contains Allinea MAP and Allinea DDT. Allinea DDT is a debugger, and OSC has license only for Allinea MAP. If you need a debugger, you can use Totalview instead.

See Also

Documentation Attachment: 
Service: 
Fields of Science: