Profiling GEOS-Chem

On this page, we provide information on how you can use software profiling tools with GEOS-Chem.

Overview

Profiling is a debugging technique that allows you to examine how much time is spent in a given GEOS-Chem routine. This is helpful in identifying potential bottlenecks caused by sub-optimally written code. GEOS-Chem v11-01 and higher versions contains support for two software profiling packages:

1. gprof, the GNU profiler
2. TAU, the Tuning and Analysis Utilities published by Paratools, Inc.

The following sections describe how you can use GEOS-Chem with these utilities.

--Bob Yantosca (talk) 18:25, 14 December 2016 (UTC)

Profiling GEOS-Chem with gprof

The GNU profiler (gprof) is a free, open source software package that you can use to determine which GEOS-Chem routines take the most time to execute. If your computer system has the GNU Compiler Collection (GCC)] already installed (as do most modern Unix/Linux clusters), then gprof should also be available for you to use. GEOS-Chem v11-01 and higher versions contain support for gprof.

Compiling and running GEOS-Chem with gprof

To profile GEOS-Chem, you must first compile with the GPROF=y Makefile option, e.g.:

make -j4 GPROF=y   ...etc. other makefile options ...

This will add the following compiler switches to the compilation sequence:

Compiler	Switch to invoke gprof
Intel Fortran compiler (ifort)	-p
GNU Fortran compiler (gfortran)	-pg
PGI Fortran compiler (pgfortran)	-pg

Once you have compiled GEOS-Chem with GPROF=y, you can run GEOS-Chem as you normally would. GEOS-Chem will create a binary file called gmon.out containing the profiling information. To generate readable output from gmon.out, you need to call the gprof program as described in the next section.

--Bob Yantosca (talk) 18:09, 14 December 2016 (UTC)

Generating profiling output

The general syntax for calling gprof is:

gprof [optional commands] [name of GEOS-Chem executable file] gmon.out > [name of text file to contain profiling results]

Please see this list of optional commands for gprof from the web-based documentation.

--Bob Yantosca (talk) 18:09, 14 December 2016 (UTC)

Creating a table of time spent in each GEOS-Chem routine

To create a simple text table of time spent in each GEOS-Chem subroutine (also called a flat profile), you can call gprof as follows:

gprof geos.mp gmon.out > GEOS-Chem_Profile_Results.txt

where geos.mp is the GEOS-Chem executable file. (It may have a different name than geos.mp depending on how, and in which run directory, you compiled GEOS-Chem.) You can also refine the output by specifying optional commands to gprof.

The GEOS-Chem_Profile_Results.txt file will contain output similar to this:

Flat profile:

Each sample counts as 0.01 seconds.
  %   cumulative   self              self     total           
 time   seconds   seconds    calls  Ks/call  Ks/call  name    
 16.50    801.03   801.03 11317370     0.00     0.00  gckpp_linearalgebra_mp_kppdecomp_
  9.63   1268.29   467.26 43751785     0.00     0.00  gckpp_linearalgebra_mp_kppsolve_
  6.29   1573.53   305.24 26835672     0.00     0.00  gckpp_function_mp_fun_
  4.09   1772.06   198.53    17402     0.00     0.00  tpcore_fvdas_mod_mp_fzppm_
  4.04   1967.96   195.90  6834149     0.00     0.00  gckpp_jacobian_mp_jac_sp_
  2.86   2106.99   139.03       72     0.00     0.04  flexchem_mod_mp_do_flexchem_
  2.23   2215.23   108.25 182368327     0.00     0.00  gckpp_linearalgebra_mp_waxpy_
  2.20   2322.10   106.87    45915     0.00     0.00  convection_mod_mp_do_merra_convection_
  2.05   2421.82    99.72      648     0.00     0.00  dao_mod_mp_airqnt_
  2.05   2521.43    99.61     3051     0.00     0.00  fast_jx_mod_mp_blkslv_
  2.05   2620.81    99.38     3487     0.00     0.00  fast_jx_mod_mp_opmie_
  1.80   2708.34    87.53      144     0.00     0.00  convection_mod_mp_do_convection_
  1.78   2794.64    86.30     6533     0.00     0.00  vdiff_mod_mp_vdiff_
  ... etc ...

The information is arranged into several columns:

Column	Description
% time	This is the percentage of the total execution time your program spent in this function. These should all add up to 100%.
cumulative seconds	This is the cumulative total number of seconds the computer spent executing this functions, plus the time spent in all the functions above this one in this table.
self seconds	This is the number of seconds accounted for by this function alone. The flat profile listing is sorted first by this number.
calls	This is the total number of times the function was called. If the function was never called, or the number of times it was called cannot be determined (probably because the function was not compiled with profiling enabled), the calls field is blank.
self ms/call	This represents the average number of milliseconds spent in this function per call, if this function is profiled. Otherwise, this field is blank for this function.
total ms/call	This represents the average number of milliseconds spent in this function and its descendants per call, if this function is profiled. Otherwise, this field is blank for this function. This is the only field in the flat profile that uses call graph analysis.
name	This is the name of the function. The flat profile is sorted by this field alphabetically after the self seconds and calls fields are sorted.

Looking down the self seconds column will show you the amount of time spent in each routine. From the example above, we see that the first 3 routines (which are part of the KPP chemical solver) account for approximately one-third of the total run time.

--Bob Yantosca (talk) 18:19, 14 December 2016 (UTC)

For more information

We invite you to read the gprof Manual to learn about other types of profiling output that you can generate with gprof.

--Bob Yantosca (talk) 18:30, 14 December 2016 (UTC)

Profiling GEOS-Chem with TAU

Information to be added