ForTime

ForTime: A Fortran timing library for measuring wall-clock, date_and_time, CPU, OpenMP and MPI elapsed time.

fpm dependency

If you want to use ForTime as a dependency in your own fpm project, you can easily include it by adding the following line to your fpm.toml file:

[dependencies]
fortime = {git="https://github.com/gha3mi/fortime.git"}

Usage

ForTime exposes the timer type, the real kind rk, and the integer kind ik. Timing results are stored as real(rk) components on the timer object.

Simple Usage

system_clock wall time

use fortime, only: timer

type(timer) :: t

call t%timer_start()
! Code to time.
call t%timer_stop()

call t%timer_write('elapsed_time.txt')

date_and_time wall time

use fortime, only: timer

type(timer) :: t

call t%dtimer_start()
! Code to time.
call t%dtimer_stop()

call t%dtimer_write('elapsed_dtime.txt')

CPU time

use fortime, only: timer

type(timer) :: t

call t%ctimer_start()
! Code to time.
call t%ctimer_stop()

call t%ctimer_write('cpu_time.txt')

OpenMP wall time

use fortime, only: timer

type(timer) :: t

call t%otimer_start()
! Code to time.
call t%otimer_stop()

call t%otimer_write('omp_time.txt')

Compile with OpenMP enabled and define USE_OMP.

MPI wall time

use fortime, only: timer

type(timer) :: t

call t%mtimer_start()
! Code to time.
call t%mtimer_stop()

call t%mtimer_write('mpi_time.txt')

Compile with MPI enabled, define USE_MPI, and call the MPI timer while MPI is initialized.

Optional Variables and Stop Arguments

All stop routines accept the same optional keyword arguments:

call t%timer_stop(nloops,message,print,color,rfmt)
call t%dtimer_stop(nloops,message,print,color,rfmt)
call t%ctimer_stop(nloops,message,print,color,rfmt)
call t%otimer_stop(nloops,message,print,color,rfmt)
call t%mtimer_stop(nloops,message,print,color,rfmt)

nloops: positive default-integer loop count used to report an average time.
message: label printed before the timing value.
print: set to .false. to suppress output; the default is .true..
color: FACE foreground color for printed output.
rfmt: Fortran real edit descriptor; the default is F16.9.

Loop Averages

use fortime, only: timer

type(timer) :: t
integer :: i
integer, parameter :: nloops = 10

call t%timer_start()
do i = 1, nloops
   ! Repeated work.
end do
call t%timer_stop(nloops=nloops, message='Average elapsed time:')

Pause and Resume

call t%timer_start()
! Timed work.
call t%timer_pause()
! Work not included in elapsed_time.
call t%timer_resume()
! More timed work.
call t%timer_stop()

timer_pause and timer_resume apply only to the system_clock timer.

Timer Reference

Timer backend	Start	Stop	Result component	Write routine	Requirement
`system_clock`	`timer_start`	`timer_stop`	`elapsed_time`	`timer_write`	Always available
`date_and_time`	`dtimer_start`	`dtimer_stop`	`elapsed_dtime`	`dtimer_write`	Always available
`cpu_time`	`ctimer_start`	`ctimer_stop`	`cpu_time`	`ctimer_write`	Always available
`omp_get_wtime`	`otimer_start`	`otimer_stop`	`omp_time`	`otimer_write`	Compile with `USE_OMP`
`MPI_Wtime`	`mtimer_start`	`mtimer_stop`	`mpi_time`	`mtimer_write`	Compile with `USE_MPI`

To measure elapsed time within a pure procedure, use ForDebug.

Running Examples and Tests

Running Examples

To run a specific example from the example directory using your preferred Fortran compiler, use the following command:

fpm run --example <example_name> --compiler <compiler>

Replace <example_name> with the name of the example file (excluding the .f90 extension) and <compiler> with the name of your Fortran compiler (e.g., ifx, ifort, gfortran, nvfortran).

Running Tests

To execute tests, use the following command with your chosen compiler:

fpm test --compiler <compiler>

Replace <compiler> with the name of your Fortran compiler.

CI Status

Compiler	macos	ubuntu	windows
`flang-new`	-	fpm ✅ cmake ✅	fpm ✅ cmake ✅
`gfortran`	fpm ✅ cmake ✅	fpm ✅ cmake ✅	fpm ✅ cmake ✅
`ifx`	-	fpm ✅ cmake ✅	fpm ✅ cmake ✅
`lfortran`	fpm ❌ cmake ❌	fpm ❌ cmake ❌	fpm ❌ cmake ❌
`nvfortran`	-	fpm ✅ cmake ❌	-

This table is automatically generated by the CI workflow using setup-fortran-conda.

Documentation

The most up-to-date API documentation for the main branch is available here. To generate the API documentation for ForTime using ford run the following command:

ford README.md

Contributing

Contributions to ForTime are welcome! If you find any issues or would like to suggest improvements, please open an issue.