You copied the Doc URL to your clipboard.

3 Running with an example program

This section takes you through compiling and running one of the the example programs.

3.1 Overview of the example source code

3.2 Compiling

Arm provides a simple 1-D wave equation solver that is useful as a profiling example program. Both C and Fortran variants are provided:

  • examples/wave.c
  • examples/wave.f90

Both are built using the same makefile:


   cd <INSTALL_DIR>/examples/ 
make -f wave.makefile

There is also a mixed-mode MPI+OpenMP variant in examples/wave_openmp.c, which is built with the openmp.makefile Makefile.

Depending on the default compiler on your system you may see some errors when running this, for example:


   pgf90-Error-Unknown switch: -fno-inline

The Arm example makefile is set up for the GNU compilers by default. There are lines in examples/wave.makefile that you can uncomment to enable support for other compilers.

In the above case, to enable PGI compiler support you can switch the commented lines:


   # gnu 
# ${MPICC} -g -O3 -fno-inline wave.c -o wave_c -lm -lrt
# ${MPIF90} -g -O3 -fno-inline wave.f90 -o wave_f -lm -lrt
# intel
# ${MPICC} -g -fno-inline-functions -O3 wave.c -o wave_c -lm -lrt
# ${MPIF90} -g -fno-inline-functions -O3 wave.f90 -o wave_f -lm -lrt
# pgi
${MPICC} -g -O3 wave.c -o wave_c -lm -lrt -Meh_frame
${MPIF90} -g -O3 wave.f90 -o wave_f -lm -lrt -Meh_frame

Note that although these example Makefiles include the -g flag, Arm Performance Reports does not need this and you should not use them in your own Makefiles.

In most cases Arm Performance Reports can run on an unmodified binary with no recompilation or linking required.

3.2.1 Cray X-series

On Cray X-series systems the example program must either be dynamically linked (using -dynamic) or explicitly linked with the Arm profiling libraries.

Example how to dynamically link:


   cc -dynamic -g -O3 wave.c -o wave -lm -lrt 

ftn -dynamic -G2 -O3 wave.f90 -o wave -lm -lrt

Example how to explicitly link with the Arm profiling libraries: First create the libraries using the command make-profiler-libraries --platform=cray --lib-type=static:


   Created the libraries in /home/user/examples: 
libmap-sampler.a
libmap-sampler-pmpi.a

To instrument a program, add these compiler options:
compilation for use with MAP - not required for Performance Reports:
-g (or -G2 for native Cray fortran) (and -O3 etc.)
linking (both MAP and Performance Reports):
-Wl,@/home/user/examplesm/allinea-profiler.ld ... EXISTING_MPI_LIBRARIES
If your link line specifies EXISTING_MPI_LIBRARIES (e.g. -lmpi), then
these must appear *after* the Arm sampler and MPI wrapper libraries in
the link line. There's a comprehensive description of the link ordering
requirements in the 'Preparing a Program for Profiling' section of either
userguide-forge.pdf or userguide-reports.pdf, located in
/opt/arm/forge/doc/.

Then follow the instructions in the output to link the example program with the Arm profiling libraries:

   cc -g -O3 wave.c -o wave -g -Wl,@allinea-profiler.ld -lm -lrt 

ftn -G2 -O3 wave.f90 -o wave -G2 -Wl,@allinea-profiler.ld -lm -lrt

3.3 Running

As this example uses MPI you need to run on a compute node on your cluster. Your site's help pages and support staff can tell you exactly how to do this on your machine. The simplest way when running small programs is often to request an interactive session, as follows:


   $ qsub -I 
qsub: waiting for job 31337 to start
qsub: job 31337 ready
$ cd arm/reports/examples
$ mpiexec -n 4 ./wave_c
Wave solution running with 4 processes

0: points = 1000000, running for 30 seconds
points / second: 63.9M (16.0M per process)
compute / communicate efficiency: 94% | 97% | 100%

Points for validation:
0:0.00 200000:0.95 400000:0.59 600000:-0.59 800000:-0.95 999999:0.00
wave finished

If you see output similar to this then the example program is compiled and working correctly.

3.4 Generating a performance report

Make sure the Arm Performance Reports module for your system has been loaded:


   $ perf-report --version 
Arm Performance Reports
Copyright (c) 2002-2017 Arm Limited (or its affiliates). All rights reserved.
...

If this command cannot be found consult the site documentation to find the name of the correct module.

Once the module is loaded, you can add the perf-report command in front of your existing mpiexec command-line:


   perf-report mpiexec -n 4 examples/wave_c

If your program is submitted through a batch queuing system, then modify your submission script to load the Arm module and add the 'perf-report' line in front of the mpiexec command you want to generate a report for.

The program runs as usual, although startup and shutdown may take a few minutes longer while Arm Performance Reports generates and links the appropriate wrapper libraries before running and collects the data at the end of the run. The runtime of your code (between MPI_Init and MPI_Finalize should not be affected by more than a few percent at most.

After the run finishes, a performance report is saved to the current working directory, using a name based on the application executable:


   $ ls -lrt wave_c* 
-rwx------ 1 mark mark 403037 Nov 14 03:21 wave_c
-rw------- 1 mark mark 1911 Nov 14 03:28 wave_c_4p_2013-11-14_03-27.txt
-rw------- 1 mark mark 174308 Nov 14 03:28 wave_c_4p_2013-11-14_03-27.html

Note that both .txt and .html versions are automatically generated.

Was this page helpful? Yes No