pycubexr


Namepycubexr JSON
Version 2.0.1 PyPI version JSON
download
home_pagehttps://github.com/extra-p/pycubexr
SummarypyCubexR is a Python package for reading the Cube4 file format.
upload_time2024-12-04 09:44:15
maintainerNone
docs_urlNone
authorExtra-P project
requires_python>=3.7
licenseNone
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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"
}
        
Elapsed time: 0.37082s