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

Functions

underworld.timing.get_data	Returns dict with timing data.
underworld.timing.log_result	Allows the user to manually add entries to data.
underworld.timing.print_table	Print timing results to stdout or to a provided file.
underworld.timing.reset	Reset timing data.
underworld.timing.start	Call this function to start recording timing data.
underworld.timing.stop	Call this function to stop recording timing data.

underworld.timing.get_data(group_by='line_routine')

Returns dict with timing data.

Parameters:group_by (str) – Reported timing data is grouped according to the following options: “line” : Calling line of code. “routine” : Class routine. “line_routine”: Line&routine form an individual timing group.

underworld.timing.log_result(time, name, foffset=1)

Allows the user to manually add entries to data.

Parameters:

• time (float) – Time spent.
• name (str) – Name to record to dataset. Note that the current stack information is generated internally and recorded.
• foffset (int) – Frame offset. This is useful when you want to record this measurement against a call up the stack list. Defaults to 1.

underworld.timing.print_table(group_by='line_routine', sort_by='total', display_fraction=0.95, float_precision='.3f', output_file=None, **kwargs)

Print timing results to stdout or to a provided file. Call this function stops timing.

Parameters:

• group_by (str) – See get_data() function
• sort_by (str) – Data is sorted according to: “total” : Total time allocated to any group. “average” : Average time attributed to any group
• display_fraction (float) – Set this option to cull insignificant (short time) results.
• output_file (str) – File to record table to. If none provided, outputs to stdout.
• **kwargs – Any extra kwargs are passed to tabulate module (if installed). This allows you to tweak the output format. Consule the tabulate module instructions for details.

underworld.timing.reset()

Reset timing data. Note that this function calls stop(), and the user must call start() to resume recording timing data.

underworld.timing.start()

Call this function to start recording timing data.

underworld.timing.stop()

Call this function to stop recording timing data. Note that this is automatically called when print_table() is called.