underworld.timing module
========================

This module implements some high level timing operations for Underworld,
allowing users to determine how walltime is divided between different
Underworld API calls.  Note that this module *only* records timing
for Underworld API calls, and has no way of knowing how much time has
been spent elsewhere (such as `numpy`, `scipy` etc). The total runtime
is also recorded which gives users an indication of how much time
is spent outside Underworld.

Timing routines enabled by this module should introduce negligible
computational overhead.

Only the root process records timing information.

Note that to utilise timing routines, you must first set the
'UW_ENABLE_TIMING' environment variable, and this must be done
before you call `import underworld`.

Example
-------
>>> import os
>>> os.environ["UW_ENABLE_TIMING"] = "1"
>>> import underworld as uw
>>> uw.timing.start()
>>> someMesh = uw.mesh.FeMesh_Cartesian()
>>> with someMesh.deform_mesh():
...     someMesh.data[0] = [0.1,0.1]
>>> uw.timing.stop()
>>> # uw.timing.print_table()   # This will print the data.
>>>                      # Commented out as not doctest friendly.
>>> del os.environ["UW_ENABLE_TIMING"]  # remove to prevent timing for future doctests



.. module:: underworld.timing

Functions
~~~~~~~~~~

.. autosummary::
    :nosignatures:

    underworld.timing.get_data
    underworld.timing.log_result
    underworld.timing.print_table
    underworld.timing.reset
    underworld.timing.start
    underworld.timing.stop

.. autofunction:: underworld.timing.get_data
.. autofunction:: underworld.timing.log_result
.. autofunction:: underworld.timing.print_table
.. autofunction:: underworld.timing.reset
.. autofunction:: underworld.timing.start
.. autofunction:: underworld.timing.stop