# pyCubexR
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pycubexr?style=plastic)](https://badge.fury.io/py/pycubexr)
![GitHub release (latest by date)](https://img.shields.io/github/v/release/extra-p/pycubexr?style=plastic)
[![PyPI version](https://badge.fury.io/py/pycubexr.png)](https://badge.fury.io/py/pycubexr)
[![PyPI - License](https://img.shields.io/pypi/l/pycubexr?style=plastic)](https://badge.fury.io/py/pycubexr)
![GitHub issues](https://img.shields.io/github/issues/extra-p/pycubexr?style=plastic)
![GitHub pull requests](https://img.shields.io/github/issues-pr/extra-p/pycubexr?style=plastic)
![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](https://www.scalasca.org/scalasca/software/cube-4.x/download.html) (.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](https://www.vi-hps.org/projects/score-p) performance instrumentation and measurement infrastructure or
the [Scalasca version 2.x](https://www.scalasca.org/scalasca/software/scalasca-2.x/download.html) trace analyzer (and
other compatible tools).
For additional information about the supported features of the Cube4 file format, see
the [Cube file format documentation](docs/cube_file_format.md). The [report](docs/pyCubexR.pdf) 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:
```python
from pycubexr import CubexParser
cubex_file_path = "some/profile.cubex"
with CubexParser(cubex_file_path) as cubex:
# iterate over all metrics in cubex file
for metric in cubex.get_metrics():
metric_values = cubex.get_metric_values(metric=metric)
# return the name of the current metric
metric_name = metric.name
# iterate over all callpaths in cubex file
for cnode_id in metric_values.cnode_indices:
cnode = cubex.get_cnode(cnode_id)
# return the current region i.e. callpath
region = cubex.get_region(cnode)
# return the name of the current region
region_name = region.name
# return the measurement values for all mpi processes for the current metric and callpath
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.
```python
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)
# return only a specific number of measurement values for the current metric and callpath
cnode_values = metric_values.cnode_values(cnode)[:5]
region = cubex.get_region(cnode)
# print the data read from the file
print('\t' + '-' * 100)
print(f'\tRegion: {region.name}\n\tMetric: {metric.name}\n\tMetricValues: {cnode_values})')
except MissingMetricError as e:
# Ignore missing metrics
pass
```
The call tree of a .cubex file can be displayed with the following code:
```python
from pycubexr import CubexParser
cubex_file_path = "some/profile.cubex"
with CubexParser(cubex_file_path) as cubex:
# print the call tree of the .cubex file
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](LICENSE)
Raw data
{
"_id": null,
"home_page": "https://github.com/extra-p/pycubexr",
"name": "pycubexr",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": "Extra-P project",
"author_email": "extra-p@lists.parallel.informatik.tu-darmstadt.de",
"download_url": "https://files.pythonhosted.org/packages/63/d5/9b128a6678dee3635a0bc854b42c567567536f576e8ac2a0259430d996e6/pycubexr-2.0.1.tar.gz",
"platform": null,
"description": "# pyCubexR\n\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pycubexr?style=plastic)](https://badge.fury.io/py/pycubexr)\n![GitHub release (latest by date)](https://img.shields.io/github/v/release/extra-p/pycubexr?style=plastic)\n[![PyPI version](https://badge.fury.io/py/pycubexr.png)](https://badge.fury.io/py/pycubexr)\n[![PyPI - License](https://img.shields.io/pypi/l/pycubexr?style=plastic)](https://badge.fury.io/py/pycubexr)\n![GitHub issues](https://img.shields.io/github/issues/extra-p/pycubexr?style=plastic)\n![GitHub pull requests](https://img.shields.io/github/issues-pr/extra-p/pycubexr?style=plastic)\n![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/extra-p/pycubexr/python-package.yml?style=plastic)\n\npyCubexR is a Python package for reading\nthe [Cube4](https://www.scalasca.org/scalasca/software/cube-4.x/download.html) (.cubex) file format. Cube is used as a\nperformance report explorer for Scalasca and Score-P. It is used as a generic tool for displaying a multidimensional\nperformance space consisting of the dimensions (i) performance metric, (ii) call path, and (iii) system resource. Each\ndimension can be represented as a tree, where non-leaf nodes of the tree can be collapsed or expanded to achieve the\ndesired level of granularity. The Cube4 (.cubex) data format is provided for Cube files produced with\nthe [Score-P](https://www.vi-hps.org/projects/score-p) performance instrumentation and measurement infrastructure or\nthe [Scalasca version 2.x](https://www.scalasca.org/scalasca/software/scalasca-2.x/download.html) trace analyzer (and\nother compatible tools).\n\nFor additional information about the supported features of the Cube4 file format, see\nthe [Cube file format documentation](docs/cube_file_format.md). The [report](docs/pyCubexR.pdf) contains general\ninformation about Cube, pyCubexR, and other related tools.\n\nFor questions regarding pyCubexR please send a message to <extra-p-support@lists.parallel.informatik.tu-darmstadt.de>.\n\n## Installation\n\nTo install the current release, which includes support for Ubuntu and Windows:\n\n```\n$ pip install pycubexr\n```\n\nTo update pyCubexR to the latest version, add `--upgrade` flag to the above commands.\n\n## Usage\n\nThe following code provides a minimal example that shows how pyCubexR can be used to read all metrics, callpaths, and\nmeasurement values of a .cubex file:\n\n```python\nfrom pycubexr import CubexParser\n\ncubex_file_path = \"some/profile.cubex\"\nwith CubexParser(cubex_file_path) as cubex:\n # iterate over all metrics in cubex file\n for metric in cubex.get_metrics():\n metric_values = cubex.get_metric_values(metric=metric)\n\n # return the name of the current metric\n metric_name = metric.name\n\n # iterate over all callpaths in cubex file\n for cnode_id in metric_values.cnode_indices:\n cnode = cubex.get_cnode(cnode_id)\n\n # return the current region i.e. callpath\n region = cubex.get_region(cnode)\n\n # return the name of the current region\n region_name = region.name\n\n # return the measurement values for all mpi processes for the current metric and callpath\n cnode_values = metric_values.cnode_values(cnode)\n```\n\nNot all .cubex files must contain measurement values for all metrics for each callpath. This is especially true for MPI\nfunctions such as MPI_Waitall. In some cases, metrics can be missing. Use the `MissingMetricError` to deal with these\nexceptions.\n\n```python\nfrom pycubexr import CubexParser\nfrom pycubexr.utils.exceptions import MissingMetricError\n\ncubex_file_path = \"some/profile.cubex\"\nwith CubexParser(cubex_file_path) as cubex:\n for metric in cubex.get_metrics():\n\n try:\n metric_values = cubex.get_metric_values(metric=metric)\n\n for cnode_id in metric_values.cnode_indices:\n cnode = cubex.get_cnode(cnode_id)\n\n # return only a specific number of measurement values for the current metric and callpath\n cnode_values = metric_values.cnode_values(cnode)[:5]\n\n region = cubex.get_region(cnode)\n\n # print the data read from the file\n print('\\t' + '-' * 100)\n print(f'\\tRegion: {region.name}\\n\\tMetric: {metric.name}\\n\\tMetricValues: {cnode_values})')\n\n except MissingMetricError as e:\n # Ignore missing metrics\n pass\n```\n\nThe call tree of a .cubex file can be displayed with the following code:\n\n```python\nfrom pycubexr import CubexParser\n\ncubex_file_path = \"some/profile.cubex\"\nwith CubexParser(cubex_file_path) as cubex:\n # print the call tree of the .cubex file\n cubex.print_calltree() \n```\n\nIn special cases, it is also possible that a .cubex file is missing measurement values for some of the callpaths of a\nmetric or that a .cubex file of the same application contains fewer callpaths than another file. These cases need to be\nhandled externally and are not supported by pyCubexR.\n\n## License\n\n[BSD 3-Clause \"New\" or \"Revised\" License](LICENSE)\n",
"bugtrack_url": null,
"license": null,
"summary": "pyCubexR is a Python package for reading the Cube4 file format.",
"version": "2.0.1",
"project_urls": {
"Homepage": "https://github.com/extra-p/pycubexr"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8e7ef22ab88ff3838901abb4e5941f9e2bcc6c874f6821a520f312549db362d2",
"md5": "bfecf0c9f5b6e98a17f595ab3900b6ba",
"sha256": "18a27b409ffb230f58a284da92c964d5a9eb1bccb02886fac691deb817b07d5e"
},
"downloads": -1,
"filename": "pycubexr-2.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bfecf0c9f5b6e98a17f595ab3900b6ba",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 21914,
"upload_time": "2024-12-04T09:44:13",
"upload_time_iso_8601": "2024-12-04T09:44:13.997477Z",
"url": "https://files.pythonhosted.org/packages/8e/7e/f22ab88ff3838901abb4e5941f9e2bcc6c874f6821a520f312549db362d2/pycubexr-2.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "63d59b128a6678dee3635a0bc854b42c567567536f576e8ac2a0259430d996e6",
"md5": "fbc503768278a3b22fe25d991e567a32",
"sha256": "699643c076b603fb1140564da6c4589b73ec9efd3b9112cd3d957f5bee646915"
},
"downloads": -1,
"filename": "pycubexr-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "fbc503768278a3b22fe25d991e567a32",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 75329,
"upload_time": "2024-12-04T09:44:15",
"upload_time_iso_8601": "2024-12-04T09:44:15.774249Z",
"url": "https://files.pythonhosted.org/packages/63/d5/9b128a6678dee3635a0bc854b42c567567536f576e8ac2a0259430d996e6/pycubexr-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-04 09:44:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "extra-p",
"github_project": "pycubexr",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pycubexr"
}