cubex

cubex is a Python module for analysing CUBE (.cubex) profiles.

Quick start guide

cubex is still a work in progress, but it is currently useable and the following instructions should help you get started.

To create a new Cube object, open a new file.

>> import cubex
>> prof = cubex.open('profile.cubex')

Use the show_metrics() function to list the available metrics.

>>> prof.show_metrics()
bytes_sent
visits
time
...

By default, cubex does not load all available metrics into memory. To load the desired metric, say time, use the read_data() function.

>> prof.read_data('time')

The Cube stores the call tree in a list, prof.calltrees. For most programs, this will consist of a single entry. For profiles containing multiple executables (MPMD), each program's calltree will be an element in the list.

The call tree can be printed using the print_calltree() function inside the profile's calltree.

>> prof.calltrees[0].print_tree()

This displays each node of the call tree, indented by depth, and labeled with its corresponding region.

At this point, it helps if the user has some intuitive feel for the call tree in the profile. (And if anyone has feedback on how to improve this, please submit feedback.)

Having said that, if one knows the function (or "region" in CUBE parlance) of interest, then the data is accessed with the region property.

>> prof.regions[reg].cnodes
[<cubex.calltree.CallTree object at 0x7f4437892f90>,
 <cubex.calltree.CallTree object at 0x7f4437539f10>,
 ...
]

This returns a list of each node (actually subtree) in the call tree where this function was called.

To distinguish between cnodes, one can inspect its call tree (using print_tree()) or inspect its parent node.

>> cnode = prof.regions[reg].cnodes[0]
>> cnode.parent.region.name
'function_name_calling_cnode_'

One can also inspect the node index (cnode.idx) although this requires some knowledge of the tree itself, which can be checked using the CUBE graphical browser.

Finally, to get the metric values at the target cnode, access its metrics property.

>> prof.regions[reg].cnodes[0].metrics['time']
(496.59532077590507, 291.106782542039, 496.5975198073004, ...)

This returns a list of the time measured in each computational unit, such as an MPI rank or OpenMP thread.

Notes

• Region names follow C conventions. Fortran programs will typically convert any function names to lower case and will append a _ to the end of the function name. For example, a function named GET_LAPLACIAN will be stored as get_laplacian_.

  This is the usual convention, but other compilers may deviate from thisj so it's recommended that you inspect the regions before accessing them.

• Currently only Score-P output is supported in the main branch. Scalasca output is slightly different and currently does not work as well in cubex.

  We have some internal versions that do work, but are not yet user-friendly and would need a bit of a cleanup before releasing publicly.