pyCubexR
![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/extra-p/pycubexr/python-package.yml?style=plastic)
pyCubexR is a Python package for reading
the Cube4 (.cubex) file format. Cube is used as a
performance report explorer for Scalasca and Score-P. It is used as a generic tool for displaying a multidimensional
performance space consisting of the dimensions (i) performance metric, (ii) call path, and (iii) system resource. Each
dimension can be represented as a tree, where non-leaf nodes of the tree can be collapsed or expanded to achieve the
desired level of granularity. The Cube4 (.cubex) data format is provided for Cube files produced with
the Score-P performance instrumentation and measurement infrastructure or
the Scalasca version 2.x trace analyzer (and
other compatible tools).
For additional information about the supported features of the Cube4 file format, see
the Cube file format documentation. The report contains general
information about Cube, pyCubexR, and other related tools.
For questions regarding pyCubexR please send a message to extra-p-support@lists.parallel.informatik.tu-darmstadt.de.
Installation
To install the current release, which includes support for Ubuntu and Windows:
$ pip install pycubexr
To update pyCubexR to the latest version, add --upgrade
flag to the above commands.
Usage
The following code provides a minimal example that shows how pyCubexR can be used to read all metrics, callpaths, and
measurement values of a .cubex file:
from pycubexr import CubexParser
cubex_file_path = "some/profile.cubex"
with CubexParser(cubex_file_path) as cubex:
for metric in cubex.get_metrics():
metric_values = cubex.get_metric_values(metric=metric)
metric_name = metric.name
for cnode_id in metric_values.cnode_indices:
cnode = cubex.get_cnode(cnode_id)
region = cubex.get_region(cnode)
region_name = region.name
cnode_values = metric_values.cnode_values(cnode)
Not all .cubex files must contain measurement values for all metrics for each callpath. This is especially true for MPI
functions such as MPI_Waitall. In some cases, metrics can be missing. Use the MissingMetricError
to deal with these
exceptions.
from pycubexr import CubexParser
from pycubexr.utils.exceptions import MissingMetricError
cubex_file_path = "some/profile.cubex"
with CubexParser(cubex_file_path) as cubex:
for metric in cubex.get_metrics():
try:
metric_values = cubex.get_metric_values(metric=metric)
for cnode_id in metric_values.cnode_indices:
cnode = cubex.get_cnode(cnode_id)
cnode_values = metric_values.cnode_values(cnode)[:5]
region = cubex.get_region(cnode)
print('\t' + '-' * 100)
print(f'\tRegion: {region.name}\n\tMetric: {metric.name}\n\tMetricValues: {cnode_values})')
except MissingMetricError as e:
pass
The call tree of a .cubex file can be displayed with the following code:
from pycubexr import CubexParser
cubex_file_path = "some/profile.cubex"
with CubexParser(cubex_file_path) as cubex:
cubex.print_calltree()
In special cases, it is also possible that a .cubex file is missing measurement values for some of the callpaths of a
metric or that a .cubex file of the same application contains fewer callpaths than another file. These cases need to be
handled externally and are not supported by pyCubexR.
License
BSD 3-Clause "New" or "Revised" License