Update README.rst

The gitlab template seems to be incapable of handling footnotes properly!
parent f5014669
......@@ -6,13 +6,13 @@
Introduction
===============
Very often applications need some simple and cheap timing information, both for internal purposes, such as cleanly shutting down (checkpointing) before batch system time limits are encountered, or for profiling the various parts of the code. For this, we developed a simple library at the `MPCDF <https://www.mpcdf.mpg.de>`_ called ftimings, that is primarily aimed at Fortran-based codes. It is similar in spirit to the venerable perflib in that it uses explicit calls placed by the user in the code to instrument sections of interest. [i]_ It always measures wall-clock time, and calls from within OpenMP parallel regions are only considered for the first thread.
Very often applications need some simple and cheap timing information, both for internal purposes, such as cleanly shutting down (checkpointing) before batch system time limits are encountered, or for profiling the various parts of the code. For this, we developed a simple library at the `MPCDF <https://www.mpcdf.mpg.de>`_ called ftimings, that is primarily aimed at Fortran-based codes. It is similar in spirit to the venerable perflib in that it uses explicit calls placed by the user in the code to instrument sections of interest. [#]_ It always measures wall-clock time, and calls from within OpenMP parallel regions are only considered for the first thread.
The ftimings library provides a simple object-oriented Fortran interface, and can also be used from a C/C++ code or from C/C++ code sections of a Fortran program. A specific feature of ``ftimings`` is that timing sections can be nested and will be presented consistently as a tree in the output.
Availability
============
ftimings is open-source and is already available as a module on many of the clusters as well as on the Draco and Cobra installations at the MPCDF. It provides a `pkg-config <https://www.freedesktop.org/wiki/Software/pkg-config/>`_ file with the usual ``--libs`` and ``--cflags`` arguments, as well as the Fortran specific flags in ``–variables=fcflags``. For codes that are already equipped with perflib instrumentation, there is also a wrapper library that provides a compatible API of most of perflib's interface. There are additional pkg-config files (e.g. ftimings_perflib-1-gcc-8) that provide the necessary linker arguments to link with that shim layer. [ii]_
ftimings is open-source and is already available as a module on many of the clusters as well as on the Draco and Cobra installations at the MPCDF. It provides a `pkg-config <https://www.freedesktop.org/wiki/Software/pkg-config/>`_ file with the usual ``--libs`` and ``--cflags`` arguments, as well as the Fortran specific flags in ``–variables=fcflags``. For codes that are already equipped with perflib instrumentation, there is also a wrapper library that provides a compatible API of most of perflib's interface. There are additional pkg-config files (e.g. ftimings_perflib-1-gcc-8) that provide the necessary linker arguments to link with that shim layer. [#]_
Quick start
......@@ -36,14 +36,43 @@ Adding ftimings to a Fortran code
Add the necessary parts to the source code
==========================================
a) include the ftimings module
.. code-block:: fortran
use ftimings
b) instantiate a ``timer_t`` object
.. code-block:: fortran
type(timer_t) :: timer
c) enable the timer
.. code-block:: fortran
call timer%enable()
d) start/stop the timer: wrapped around the sections of your code for timing
.. code-block:: fortran
call timer%start("section1")
[...]
call timer%stop("section1")
e) print the measured times
.. code-block:: fortran
call timer%print("section1")
f) destroy the ``ftimer_t`` object
.. code-block:: fortran
call timer%free()
==========================================
......@@ -319,5 +348,5 @@ This project is licensed under the GNU Lesser General Public License v3.0. Full
------------
.. [i] Note that the focus of perflib is slightly different from ftimings', perflib has less overhead and strives to exclude that overhead from the resulting numbers. ftimings' focus is to provide hierarchical/nested time information.
.. [ii] Note the peculiar name, ftimings-1-gcc-8, of the pkg-config file. This signifies the API version (1) of ftimings as well as the Fortran compiler used to build it – since Fortran modules are compiler dependent, unfortunately this is necessary.
\ No newline at end of file
.. [#] Note that the focus of perflib is slightly different from ftimings', perflib has less overhead and strives to exclude that overhead from the resulting numbers. ftimings' focus is to provide hierarchical/nested time information.
.. [#] Note the peculiar name, ftimings-1-gcc-8, of the pkg-config file. This signifies the API version (1) of ftimings as well as the Fortran compiler used to build it – since Fortran modules are compiler dependent, unfortunately this is necessary.
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment