GEOS-Chem timers

This page describes how to set up and use the GEOS-Chem Timers.

The initial source code modifications for this feature were validated in with the 1-month benchmark simulation v11-01c (approved on 14 Sept 2015).

Setting up and using Timers

The ability to time and display the running time of various GEOS-Chem components is now a feature. It is disabled by default. Enabling GEOS-Chem Timers should not have a significant change to your running time or memory footprint.

To enable GEOS-Chem Timers in your model output, simply add TIMERS=1 to your compile command. This will set GEOS-Chem Timers to Mode 1, and will enable timing and output. Timer output can be viewed in the GEOS-Chem log file.

Default Timers

The following Timers are enabled by default:

Name	Description
Initialization	This timer runs from right before the input file is read, and stops right before time stepping begins..
Timesteps	This timer covers all active time stepping done by GEOS-Chem.
HEMCO	This timer runs whenever a HEMCO command is called. This includes initialization, as well as running.
Chemistry	This timer covers all Chemistry commands. In most runs this will just be DO_CHEMISTRY. As Chemistry takes a great deal of time, Chemistry has a number of sub-timers.
Chemistry-Stratospheric	This timer runs inside DO_CHEMISTRY. It covers DO_STRAT_CHEM.
Chemistry-Gas-Phase	This timer runs inside DO_CHEMISTRY. It covers CHEMDR.
Chemistry-Sulfate	This timer runs inside DO_CHEMISTRY. It covers CHEMSULFATE.
Aerosols	This timer runs inside DO_CHEMISTRY. It covers all Aerosol Chemistry, such as CHEMSEASALT, CALC_STRAT_AER, CHEMDUST, and CHEMCARBON.
Transport	This timer covers all transport calculations. This includes DO_TRANSPORT.
Convection	This timer runs if it's a convection timestep. This covers DO_MIXING and DO_CONVECTION.
Emissions	This timer runs if it's a emissions timestep. This includes EMISSIONS_RUN.
Deposition	This timer runs whenever Dry Deposition or Wet Deposition is running.
Radiation	This timer covers RRTMG Radiative Transfer.
Diagnostics	This timer runs whenever GEOS-Chem is writing diagnostics.
Reading met fields	This timer runs whenever GEOS-Chem is reading met fields from disk.

Development with Timers

This section is for those curious about extending GEOS-Timer functionality to custom applications.

Initialization

Please note that you must compile GEOS-Chem with TIMERS=1 for the timers to run.

Before any other GEOS-Timer commands are run, the command GEOS_Timer_Setup( ModeNumber ) should be called, with the number of the mode to set the timers to. (This call is placed near the top of the GEOS_Chem main program, GeosCore/main.F.) At present, only ModeNumber = 1 is supported. Setting the mode to any other number will effectively disable the GEOS-Chem timers.

Adding a new Timer

As of this writing, there is currently a cap on the number of simultaneous initiated timers. This cap is set to 15, but you may increase it by editing TimerMaxSize inside GeosUtil/geos_timers_mod.F, if you need to go above this limit. Increasing this limit will increase the memory footprint of the GEOS-Chem timers accordingly.

Adding a new timer is simple. Call function GEOS_Timer_Add( TimerName, RC ) with the name of the timer you wish to add. This name will be needed to start or stop the timer in the future. Names should be unique. Timer names are limited to 30 characters. The RC variable return 0 if the timer was added successfully.

Starting / Stopping Timers

To start a Timer, call function GEOS_Timer_Start( TimerName, RC ), where TimerName is the name of a previously added timer. Warnings will be printed if a timer by that name does not exist, or is currently already running.

To stop a Timer, call function GEOS_Timer_End( TimerName, RC ), where TimerName is the name of a previously added timer. Timers need to be ended before they will store their running times. Warnings will be printed if a timer by that name does not exist, or is not running.

The RC variable will contain a value of zero if the calls to GEOS_Timer_Start or GEOS_Timer_End executed succesfully. A nonzero value indicates an error condition.

Printing Timers

There are two methods to printing out the values of timers.

The function GEOS_Timer_Print() can be called with the name of a timer to print. Warnings will be printed if a timer by that name does not exist, or is currently already running.

The function GEOS_Timer_PrintAll() will print out all Initialized timers. Warnings will be printed if a timer is still running. Timers will be printed out even if they did not run.