Overview

License Terms

TIM (Time-Instrumentation Methods) is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Introduction

TIM (Time-Instrumentation Methods) is a Fortran 95 module that defines two classes of portable routines which goal is to time-instrument sequential or parallel Fortran programs. The first class of routines enables the instrumentation of MPI (multi-process) or mixed MPI and OpenMP (multi-threaded) parallel applications while the second class enables the instrumentation of OpenMP or none parallel (single-threaded) applications. It has been developed by Jalel Chergui.

Installation

  1. You'll need a Fortran 95/(optionally OpenMP-2) compiler and a MPI-1 implementation.
  2. Download TIM sources.
  3. gzip -cd tim-(version).tar.gz | tar -xvf -
  4. cd TIM-(version)/MakeDep
    Configure the "Make.inc" file.
  5. cd .. ; make
    Compile the TIM module.
  6. make ex
    Compile, load and run the "matrix product" examples.

Quick guide

When used, TIM module gives access to PTIM and to OTIM classes of routines. The first class defines 4 public methods which goal is to measure each process CPU time and each process and thread elapsed times of MPI or mixed MPI/OpenMP applications. The second class defines 4 public methods which goal is to measure the process CPU time and the process and each thread elapsed times of OpenMP or none parallel applications.

  1. PTIM class of routines:
  2. OTIM class of routines:
This section will emphasize on the following points:

How to use the TIM module

Users must include a "USE TIM" instruction inside each program unit where PTIM or OTIM routines have to be called. Note that TIM module must be compiled prior to the user's program unit making USE of it.

Back to the subsection list

How to time-instrument MPI programs

MPI or mixed MPI/OpenMP programs can be instrumented using the PTIM class of routines. MPI only programs need only to invoke PTIM_start and PTIM_stop routines to time-instrument a selected section of the code as it is shown in the example below:

PROGRAM foo
  USE TIM
  IMPLICIT NONE

  include "mpif.h"
  INTEGER  :: ierr

  call MPI_Init(ierr)
  
  !... Start timing counters
  call PTIM_start(LABEL="MPI parallel work")
  !...
  !... Do some parallel work ...
  !...
  !... Stop counters and print timings
  call PTIM_stop(LABEL="MPI parallel work")
  ...
  CALL MPI_Finalize(ierr)
END PROGRAM foo

When PTIM_stop routine is called, timing report is resumed and printed in a table as the one shown below:
     Copyright (C) 2004, Jalel CHERGUI, IDRIS-CNRS FRANCE.
     TIM (release 3.1) summary report of *** MPI parallel work ***

     Process Rank | Process CPU Time (s) | Process Elapsed Time (s) | CPU/Elapsed
     =============|======================|==========================|============
        0         |         21.400       |          21.399          |       1.000
        1         |          8.480       |          21.360          |        .397
        2         |          7.860       |          21.395          |        .367
        3         |          8.320       |          21.375          |        .389
     =============|======================|==========================|============
     Total        |         46.060       |          85.529          |       2.154
     Minimum      |          7.860       |          21.360          |        .367
     Maximum      |         21.400       |          21.399          |       1.000
     Average      |         11.515       |          21.382          |        .538
     =============|======================|==========================|============

     TIM started on 05/11/2004 at 12:43:47 MET +01:00 from GMT
     TIM stopped on 05/11/2004 at 12:44:08 MET +01:00 from GMT
Back to the subsection list

How to time-instrument mixed MPI/OpenMP programs

Additionally to PTIM_start/stop routines, PTIM_omp_start and PTIM_omp_stop routines can be called inside OpenMP PARALLEL regions in order to measure each thread elapsed time as it is shown in the example below:

PROGRAM foo
  USE TIM
  IMPLICIT NONE

  include "mpif.h"
  INTEGER  :: ierr

  call MPI_Init(ierr)
  
  !... Start process time counters
  call PTIM_start(LABEL="Mixed parallel work")
  !... 
  !$OMP PARALLEL
  !... Start thread elapsed time counters
  call PTIM_omp_start()
  !...
  !... Multi-threaded work ...
  !...
  !... Measure thread elapsed time
  call PTIM_omp_stop()
  !$OMP END PARALLEL
  !... 
  !... Measure process times and print all timings
  call PTIM_stop(LABEL="Mixed parallel work")
  ...
  CALL MPI_Finalize(ierr)
END PROGRAM foo

PTIM_stop routine will produce a table, as the one below, where the timing report is resumed:

     Copyright (C) 2004, Jalel CHERGUI, IDRIS-CNRS FRANCE.
     TIM (release 3.1) summary report of *** Mixed parallel work ***

     Process Rank | Process CPU Time (s) | Process Elapsed Time (s) | CPU/Elapsed
     =============|======================|==========================|============
        0         |         23.240       |           8.914          |       2.607
                  |                      |--------------------------|
                  |                      | Thread Elapsed Time (s)  |
                  |                      |--------------------------|
                  |                      |   0:           7.957     |
                  |                      |   1:           7.957     |
                  |                      |   2:           6.376     |
     -------------|----------------------|--------------------------|------------
        1         |          5.830       |           8.915          |        .654
                  |                      |--------------------------|
                  |                      | Thread Elapsed Time (s)  |
                  |                      |--------------------------|
                  |                      |   0:           1.593     |
                  |                      |   1:           1.593     |
     -------------|----------------------|--------------------------|------------
        2         |          5.490       |           8.902          |        .617
                  |                      |--------------------------|
                  |                      | Thread Elapsed Time (s)  |
                  |                      |--------------------------|
                  |                      |   0:           1.555     |
                  |                      |   1:           1.555     |
     -------------|----------------------|--------------------------|------------
        3         |          4.630       |           8.917          |        .519
                  |                      |--------------------------|
                  |                      | Thread Elapsed Time (s)  |
                  |                      |--------------------------|
                  |                      |   0:           1.596     |
                  |                      |   1:           1.596     |
     =============|======================|==========================|============
     Total        |         39.190       |          35.649          |       4.397
     Minimum      |          4.630       |           8.902          |        .519
     Maximum      |         23.240       |           8.917          |       2.607
     Average      |          9.797       |           8.912          |       1.099
     =============|======================|==========================|============

     TIM started on 05/11/2004 at 13:25:26 MET +01:00 from GMT
     TIM stopped on 05/11/2004 at 13:25:35 MET +01:00 from GMT
Back to the subsection list

How to time-instrument none parallel programs

Single process (sequential or OpenMP) applications can be time-instrumented with the OTIM class of routines. Sequential sections of a program can be time-instrumented calling only OTIM_start and OTIM_stop routines as it is shown in the example below:

PROGRAM foo
  USE TIM
  IMPLICIT NONE

  !... Start process time counters
  call OTIM_start(LABEL="None parallel work")
  !...
  !... None parallel work ...
  !...
  !... Stop process time counters and prints timings
  call OTIM_stop(LABEL="None parallel work")
  ...
END PROGRAM foo

The instrumentation of this sequential program will produce a single line table (as the one below) where the timing report is resumed:

     Copyright (C) 2004, Jalel CHERGUI, IDRIS-CNRS FRANCE.
     TIM (release 3.1) summary report of *** None parallel work ***

     Process CPU Time (s) | Process Elapsed Time (s) | CPU/Elapsed
     =====================|==========================|============
               1.820      |           1.810          |       1.006
     =====================|==========================|============

     TIM started on 18/11/2004 at 13:59:10 MET +01:00 from GMT
     TIM stopped on 18/11/2004 at 13:59:12 MET +01:00 from GMT
Back to the subsection list

How to time-instrument OpenMP programs

OTIM class of routines can be used to time-instrument OpenMP programs with the need also to measure each thread elapsed time. Additionally to OTIM_start/stop routines, OTIM_omp_start and OTIM_omp_stop must be called inside each PARALLEL scope in order to register the thread elapsed time counter. The example below shows how to do that:

PROGRAM foo
  USE TIM
  IMPLICIT NONE
  
  !... Start process time counters
  call OTIM_start(LABEL="OpenMP parallel work")
  !... 
  !$OMP PARALLEL
  !... Start thread elapsed time counter
  call OTIM_omp_start()
  !...
  !... Multi-threaded work ...
  !...
  !... Stop thread elapsed time counter
  call OTIM_omp_stop()
  !$OMP END PARALLEL
  !... 
  !... Stop process time counters and print timings
  call OTIM_stop(LABEL="OpenMP parallel work")
  ...
END PROGRAM foo

The call to the OTIM_stop routine produces a timing report as the one shown in the table below:

     Copyright (C) 2004, Jalel CHERGUI, IDRIS-CNRS FRANCE.
     TIM (release 3.1) summary report of *** OpenMP parallel work ***

     Process CPU Time (s) | Process Elapsed Time (s) | CPU/Elapsed
     =====================|==========================|============
               2.070      |            .690          |       3.000
                          |--------------------------|
                          | Thread Elapsed Time (s)  |
                          |--------------------------|
                          |    0:         .691       |
                          |    1:         .691       |
                          |    2:         .691       |
     =====================|==========================|============

     TIM started on 18/11/2004 at 13:59:13 MET +01:00 from GMT
     TIM stopped on 18/11/2004 at 13:59:14 MET +01:00 from GMT
Back to the subsection list