{ "info": { "author": "Chakib Belgaid, Arthur d'Az\u00e9mar, Guillaume Fieni, Romain Rouvoy", "author_email": "powerapi-staff@inria.fr", "bugtrack_url": null, "classifiers": [ "License :: OSI Approved :: MIT License", "Programming Language :: Python :: 3.7" ], "description": "# PyRAPL\n\n[![License: MIT](https://img.shields.io/pypi/l/pyRAPL)](https://spdx.org/licenses/MIT.html)\n[![Build Status](https://img.shields.io/circleci/project/github/powerapi-ng/pyRAPL.svg)](https://circleci.com/gh/powerapi-ng/pyrapl)\n\n\n# About\n**pyRAPL** is a software toolkit to measure the energy footprint of a host machine along the execution of a piece of Python code.\n\n**pyRAPL** uses the Intel \"_Running Average Power Limit_\" (RAPL) technology that estimates power consumption of a CPU.\nThis technology is available on Intel CPU since the [Sandy Bridge generation](https://fr.wikipedia.org/wiki/Intel#Historique_des_microprocesseurs_produits).\n\nMore specifically, pyRAPL can measure the energy consumption of the following CPU domains:\n - CPU socket package \n - DRAM (for server architectures)\n - GPU (for client architectures)\n\n# Installation\n\nYou can install **pyRAPL** with pip: `pip install pyRAPL`\n\n# Basic usage\n\nHere are some basic usages of **pyRAPL**. Please note that the reported energy consumption is not only the energy consumption of the code you are running. This includes the _global energy consumption_ of all the process running on the machine during this period, thus including the operating system and other applications.\nThat is why we recommend to eliminate any extra programs that may alter the energy consumption of the machine hosting experiments and to keep _only_ the code under measurement (_i.e._, no extra applications, such as graphical interface, background running task...). This will give the closest measure to the real energy consumption of the measured code.\n\n## Decorate a function to measure its energy consumption\n\nTo measure the energy consumed by the machine during the execution of the function `foo()` run the following code:\n```python\n\timport pyRAPL\n\n\tpyRAPL.setup() \n\n\t@pyRAPL.measure\n\tdef foo():\n\t\t# Instructions to be evaluated.\n\n\tfoo()\n```\n\nThis will print in the console the recorded energy consumption of all the CPU domains during the execution of function `foo`.\n\n## Configure the decorator specifying the device to monitor\n\nYou can easily configure which device and which socket to monitor using the parameters of the `pyRAPL.setup` function. \nFor example, the following example only monitors the CPU power consumption on the CPU socket `1`.\nBy default, **pyRAPL** monitors all the available devices of the CPU sockets.\n```python\n\n\timport pyRAPL\n\n\tpyRAPL.setup(devices=[pyRAPL.Device.PKG], socket_ids=[1])\n\n\t@pyRAPL.measure\n\tdef foo():\n\t\t# Instructions to be evaluated.\n\n\tfoo()\t\n```\n\nYou can append the device `pyRAPL.Device.DRAM` to the `devices` parameter list to monitor RAM device too. \n\n## Running the test multiple times \n\nFor short functions, you can configure the number of runs and it will calculate the mean energy consumption of all runs. \nAs an example, if you want to run the evaluation 100 times:\n```python\n\timport pyRAPL\n\n\tpyRAPL.setup()\n\n\n\t@pyRAPL.measure(number=100)\n\tdef foo():\n\t\t# Instructions to be evaluated.\n\n\tfor _ in range(100):\n\t\tfoo()\n```\t\n\n## Configure the output of the decorator\n\nIf you want to handle data with different output than the standard one, you can configure the decorator with an `Output` instance from the `pyRAPL.outputs` module.\n\nAs an example, if you want to write the recorded energy consumption in a .csv file:\n```python\n\timport pyRAPL\n\n\tpyRAPL.setup()\n\n\tcsv_output = pyRAPL.outputs.CSVOutput('result.csv')\n\n\t@pyRAPL.measure(output=csv_output)\n\tdef foo():\n\t\t# Instructions to be evaluated.\n\n\tfor _ in range(100):\n\t\tfoo()\n\n\tcsv_output.save()\n```\n\nThis will produce a csv file of 100 lines. Each line containing the energy\nconsumption recorded during one execution of the function `fun`.\nOther predefined `Output` classes exist to export data to *MongoDB* and *Panda*\ndataframe.\nYou can also create your own Output class (see the\n[documentation](https://pyrapl.readthedocs.io/en/latest/Outputs_API.html))\n\n## Measure the energy consumption of a piece of code\n\nTo measure the energy consumed by the machine during the execution of a given\npiece of code, run the following code :\n```python\n\timport pyRAPL\n\n\tpyRAPL.setup()\n\tmeter = pyRAPL.Measurement('bar')\n\tmeter.begin()\n\t# ...\n\t# Instructions to be evaluated.\n\t# ...\n\tmeter.end()\n```\n\nYou can also access the result of the measurements by using the property `meter.result`, which returns a [`Result`](https://pyrapl.readthedocs.io/en/latest/API.html#pyRAPL.Result) object.\n\nYou can also use an output to handle this results, for example with the .csv output: `meter.export(csv_output)`\n\n## Measure the energy consumption of a block \n\n**pyRAPL** allows developers to measure a block of instructions using the keyword ```with``` as the example below: \n```python\n\timport pyRAPL\n\tpyRAPL.setup()\n\n\twith pyRAPL.Measurement('bar'):\n\t\t# ...\n\t\t# Instructions to be evaluated.\n\t\t# ...\n```\n\nThis will report the energy consumption of the block. To process the measurements instead of printing them, you can use any [`Output`](https://pyrapl.readthedocs.io/en/latest/Outputs_API.html) class that you pass to the `Measurement` object:\n```python\n\timport pyRAPL\n\tpyRAPL.setup()\n\n\treport = pyRAPL.outputs.DataFrameOutput()\n\n\twith pyRAPL.Measurement('bar',output=report):\n\t\t# ...\n\t\t# Instructions to be evaluated.\n\t\t# ...\n\n\treport.data.head()\n```\n\n# Miscellaneous\n\n## About\n\n**pyRAPL** is an open-source project developed by the [Spirals research group](https://team.inria.fr/spirals) (University of Lille and Inria) that is part of the [PowerAPI](http://powerapi.org) initiative.\n\nThe documentation is available [here](https://pyrapl.readthedocs.io/en/latest/).\n\n## Mailing list\n\nYou can follow the latest news and asks questions by subscribing to our mailing list.\n\n## Contributing\n\nIf you would like to contribute code, you can do so via GitHub by forking the repository and sending a pull request.\n\nWhen submitting code, please make every effort to follow existing coding conventions and style in order to keep the code as readable as possible.\n\nMIT License\n\nCopyright (c) 2018, INRIA\nCopyright (c) 2018, University of Lille\nAll rights reserved.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n", "description_content_type": "text/markdown", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "", "keywords": "energy", "license": "MIT License", "maintainer": "", "maintainer_email": "", "name": "pyRAPL", "package_url": "https://pypi.org/project/pyRAPL/", "platform": "linux", "project_url": "https://pypi.org/project/pyRAPL/", "project_urls": { "Homepage": "http://powerapi.org/", "Source": "https://github.com/powerapi-ng/pyRAPL" }, "release_url": "https://pypi.org/project/pyRAPL/0.2.3.1/", "requires_dist": [ "sphinx (>=1.8.1) ; extra == 'docs'", "sphinx-autodoc-typehints (>=1.6.0) ; extra == 'docs'", "pymongo (>=3.9.0) ; extra == 'mongodb'", "pandas (>=0.25.1) ; extra == 'pandas'" ], "requires_python": ">=3.7", "summary": "", "version": "0.2.3.1", "yanked": false, "yanked_reason": null }, "last_serial": 6331726, "releases": { "0.0.2": [ { "comment_text": "", "digests": { "md5": "7a5c491e681647c90772e63cbd52b466", "sha256": "c3a69efd7880b1d7dacc6d6f118e25061ab8e91451c02ab0e31dc99b189a1978" }, "downloads": -1, "filename": "pyRAPL-0.0.2-py2.py3-none-any.whl", "has_sig": false, "md5_digest": "7a5c491e681647c90772e63cbd52b466", "packagetype": "bdist_wheel", "python_version": "py2.py3", "requires_python": ">= 3.7", "size": 6815, "upload_time": "2019-09-23T15:41:21", "upload_time_iso_8601": "2019-09-23T15:41:21.570784Z", "url": "https://files.pythonhosted.org/packages/b6/54/6e0745f8adada4a79f1a15ad9bc85e9eb929de9c5700ca3213bc55b7603b/pyRAPL-0.0.2-py2.py3-none-any.whl", "yanked": false, "yanked_reason": null }, { "comment_text": "", "digests": { "md5": "2fbee5bd8eccb43aa85bb71931e4d81d", "sha256": "0bea1adc60cc912178002bb04a9cd4c11e923064c38e4c4120e65ae2cb24956a" }, "downloads": -1, "filename": "pyRAPL-0.0.2.tar.gz", "has_sig": false, "md5_digest": "2fbee5bd8eccb43aa85bb71931e4d81d", "packagetype": "sdist", "python_version": "source", "requires_python": ">= 3.7", "size": 4335, "upload_time": "2019-09-23T15:41:26", "upload_time_iso_8601": "2019-09-23T15:41:26.638719Z", "url": "https://files.pythonhosted.org/packages/b5/c3/df8a0a20581a1a40bff2cd2d26a0355295a8bd9ca7a0a2e2d2251341b0fb/pyRAPL-0.0.2.tar.gz", "yanked": false, "yanked_reason": null } ], "0.1.0": [ { "comment_text": "", "digests": { "md5": "eddfaf023be3ec9fba702c9f6492d0e8", "sha256": "a3d28bc79dee523ccf0ae81338e7f638a399b78027dbd7553695e6a19ebcbc60" }, "downloads": -1, "filename": "pyRAPL-0.1.0-py2.py3-none-any.whl", "has_sig": false, "md5_digest": "eddfaf023be3ec9fba702c9f6492d0e8", "packagetype": "bdist_wheel", "python_version": "py2.py3", "requires_python": ">= 3.7", "size": 7396, "upload_time": "2019-09-25T15:43:27", "upload_time_iso_8601": "2019-09-25T15:43:27.734787Z", "url": "https://files.pythonhosted.org/packages/a3/bb/3c9e58252f70b37f174b53b8583739b6bda79a31d87e879ad02b442a6e8a/pyRAPL-0.1.0-py2.py3-none-any.whl", "yanked": false, "yanked_reason": null }, { "comment_text": "", "digests": { "md5": "7888b177347acf645fe6ac7f4c9b3c15", "sha256": "548bf04da5f33d06d8c59b757a0ce8ebfe737ca8a176b50a33f8042987e4e92c" }, "downloads": -1, "filename": "pyRAPL-0.1.0.tar.gz", "has_sig": false, "md5_digest": "7888b177347acf645fe6ac7f4c9b3c15", "packagetype": "sdist", "python_version": "source", "requires_python": ">= 3.7", "size": 5142, "upload_time": "2019-09-25T15:43:29", "upload_time_iso_8601": "2019-09-25T15:43:29.237706Z", "url": "https://files.pythonhosted.org/packages/04/c1/0a091909cd371b7e0f1516c50e2cd82c909b101d3e941fd68f05daa17c05/pyRAPL-0.1.0.tar.gz", "yanked": false, "yanked_reason": null } ], "0.2.0": [ { "comment_text": "", "digests": { "md5": "dba4ca58b1a523b145a8e6e99451bde3", "sha256": "9af563e33b4024e08160d8d389dcbd5daa09cbeb7dfd51dbd7f34d4ee548a8a6" }, "downloads": -1, "filename": "pyRAPL-0.2.0-py2.py3-none-any.whl", "has_sig": false, "md5_digest": "dba4ca58b1a523b145a8e6e99451bde3", "packagetype": "bdist_wheel", "python_version": "py2.py3", "requires_python": ">= 3.7", "size": 27024, "upload_time": "2019-10-14T08:58:30", "upload_time_iso_8601": "2019-10-14T08:58:30.944498Z", "url": "https://files.pythonhosted.org/packages/9b/60/24e2df6704564ec8417ad0c21ff6da3c1e2c25af1530140f7e6768b21b18/pyRAPL-0.2.0-py2.py3-none-any.whl", "yanked": false, "yanked_reason": null }, { "comment_text": "", "digests": { "md5": "787148761ca2c6fc6da3c90ca47b1791", "sha256": "8f49e575c7b251bf0856327dc66a29bac91ef392c605cdb8348fded870e90869" }, "downloads": -1, "filename": "pyRAPL-0.2.0.tar.gz", "has_sig": false, "md5_digest": "787148761ca2c6fc6da3c90ca47b1791", "packagetype": "sdist", "python_version": "source", "requires_python": ">= 3.7", "size": 13940, "upload_time": "2019-10-14T08:58:32", "upload_time_iso_8601": "2019-10-14T08:58:32.566779Z", "url": "https://files.pythonhosted.org/packages/22/9d/a2abca668db89c83c49201d6b48ec39c19284d1ee43efec775fe4bb6218f/pyRAPL-0.2.0.tar.gz", "yanked": false, "yanked_reason": null } ], "0.2.1": [ { "comment_text": "", "digests": { "md5": "6fb82409eb9f702b8f46837f8c107316", "sha256": "58049f0bc5c64d84658af9d11b6e3cabe150f21ebef3200e988d30b2bd29aff0" }, "downloads": -1, "filename": "pyRAPL-0.2.1-py2.py3-none-any.whl", "has_sig": false, "md5_digest": "6fb82409eb9f702b8f46837f8c107316", "packagetype": "bdist_wheel", "python_version": "py2.py3", "requires_python": ">=3.7", "size": 27058, "upload_time": "2019-10-17T15:52:47", "upload_time_iso_8601": "2019-10-17T15:52:47.355541Z", "url": "https://files.pythonhosted.org/packages/32/57/fba2729c2b935e2d93153e21aad60183791d1f0bcdedb1ff7b16bab72fa1/pyRAPL-0.2.1-py2.py3-none-any.whl", "yanked": false, "yanked_reason": null }, { "comment_text": "", "digests": { "md5": "f8c6f5a6b6c2c022f8eba6408769ef4d", "sha256": "36be694901cde1436995f03bfe8be69c84e69fdb77a6b31b3a21e61bf8d72124" }, "downloads": -1, "filename": "pyRAPL-0.2.1.tar.gz", "has_sig": false, "md5_digest": "f8c6f5a6b6c2c022f8eba6408769ef4d", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.7", "size": 13993, "upload_time": "2019-10-17T15:52:48", "upload_time_iso_8601": "2019-10-17T15:52:48.850778Z", "url": "https://files.pythonhosted.org/packages/83/97/74f1fa4e3819e1ede70fd1b14e79aa0ad691b33c6d8778f42502a0b486ac/pyRAPL-0.2.1.tar.gz", "yanked": false, "yanked_reason": null } ], "0.2.2": [ { "comment_text": "", "digests": { "md5": "463b4c4a7d60aba91f88c0375bc4ae75", "sha256": "91a85c1564d7e5cdfd35f61a7d734cef65cd691b7062a67d6de5f2954dcd0747" }, "downloads": -1, "filename": "pyRAPL-0.2.2-py2.py3-none-any.whl", "has_sig": false, "md5_digest": "463b4c4a7d60aba91f88c0375bc4ae75", "packagetype": "bdist_wheel", "python_version": "py2.py3", "requires_python": ">=3.7", "size": 27315, "upload_time": "2019-10-21T13:03:38", "upload_time_iso_8601": "2019-10-21T13:03:38.634778Z", "url": "https://files.pythonhosted.org/packages/2b/63/2a24c3d32961499459d2f9c95db71edbf75c45f4f3399ef9f36566d0f67f/pyRAPL-0.2.2-py2.py3-none-any.whl", "yanked": false, "yanked_reason": null }, { "comment_text": "", "digests": { "md5": "f60cec1660d9ef8228c49a63e7cf0039", "sha256": "2e4d2715dde3b7fcc4e2a312f22bbc72aca09d1344594e263190bb8e0466d3ee" }, "downloads": -1, "filename": "pyRAPL-0.2.2.tar.gz", "has_sig": false, "md5_digest": "f60cec1660d9ef8228c49a63e7cf0039", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.7", "size": 14192, "upload_time": "2019-10-21T13:03:40", "upload_time_iso_8601": "2019-10-21T13:03:40.683237Z", "url": "https://files.pythonhosted.org/packages/7a/d6/29174a65b084ee5d61a675f04fa29617060509c35ddf2e3b7f19ca6269c9/pyRAPL-0.2.2.tar.gz", "yanked": false, "yanked_reason": null } ], "0.2.3": [ { "comment_text": "", "digests": { "md5": "71935cedc5aeff7eadfea055a6ec1894", "sha256": "5f5e67780e6c766edef6242f280c3f3d61e67ba3912e4f5bfa21bc24caa5147d" }, "downloads": -1, "filename": "pyRAPL-0.2.3-py2.py3-none-any.whl", "has_sig": false, "md5_digest": "71935cedc5aeff7eadfea055a6ec1894", "packagetype": "bdist_wheel", "python_version": "py2.py3", "requires_python": ">=3.7", "size": 27694, "upload_time": "2019-10-24T14:43:26", "upload_time_iso_8601": "2019-10-24T14:43:26.500925Z", "url": "https://files.pythonhosted.org/packages/1d/b8/151319e5015b49e87aa6c8af1c975c0909b0648da6afbfa54a4c1c264389/pyRAPL-0.2.3-py2.py3-none-any.whl", "yanked": false, "yanked_reason": null }, { "comment_text": "", "digests": { "md5": "2cb77302d80301aa3f31c024880e5d16", "sha256": "3acb34575c9409b56dc376d4044ef36137a84f0917afae77b428ff289e027e35" }, "downloads": -1, "filename": "pyRAPL-0.2.3.tar.gz", "has_sig": false, "md5_digest": "2cb77302d80301aa3f31c024880e5d16", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.7", "size": 14898, "upload_time": "2019-10-24T14:43:28", "upload_time_iso_8601": "2019-10-24T14:43:28.060491Z", "url": "https://files.pythonhosted.org/packages/11/d7/06e3e8e5ff3c8343f10a0c18cbf61d1057ee6b616d046208887050c45918/pyRAPL-0.2.3.tar.gz", "yanked": false, "yanked_reason": null } ], "0.2.3.1": [ { "comment_text": "", "digests": { "md5": "9eea05548ba0436673f1e6bb9303a182", "sha256": "508c832f7f80fd32e9fdd1194630483c68fdde40bf540537b47502d37295ec76" }, "downloads": -1, "filename": "pyRAPL-0.2.3.1-py2.py3-none-any.whl", "has_sig": false, "md5_digest": "9eea05548ba0436673f1e6bb9303a182", "packagetype": "bdist_wheel", "python_version": "py2.py3", "requires_python": ">=3.7", "size": 27803, "upload_time": "2019-12-19T12:00:40", "upload_time_iso_8601": "2019-12-19T12:00:40.609923Z", "url": "https://files.pythonhosted.org/packages/93/bd/eca5e3464768e560d53b6bb7d77d6dd927035c5dece16fe157f7a04eb642/pyRAPL-0.2.3.1-py2.py3-none-any.whl", "yanked": false, "yanked_reason": null }, { "comment_text": "", "digests": { "md5": "5efb802db54fe82138b037b0870e279f", "sha256": "c92e7e0644ceee2e55a312d515fc35de8941abd8d810095383e02183afa29b77" }, "downloads": -1, "filename": "pyRAPL-0.2.3.1.tar.gz", "has_sig": false, "md5_digest": "5efb802db54fe82138b037b0870e279f", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.7", "size": 15099, "upload_time": "2019-12-19T12:00:41", "upload_time_iso_8601": "2019-12-19T12:00:41.755106Z", "url": "https://files.pythonhosted.org/packages/f1/a0/d52262538e60ad9fca62d576277f02d0a689ad0881d8a624487d67f08d82/pyRAPL-0.2.3.1.tar.gz", "yanked": false, "yanked_reason": null } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "9eea05548ba0436673f1e6bb9303a182", "sha256": "508c832f7f80fd32e9fdd1194630483c68fdde40bf540537b47502d37295ec76" }, "downloads": -1, "filename": "pyRAPL-0.2.3.1-py2.py3-none-any.whl", "has_sig": false, "md5_digest": "9eea05548ba0436673f1e6bb9303a182", "packagetype": "bdist_wheel", "python_version": "py2.py3", "requires_python": ">=3.7", "size": 27803, "upload_time": "2019-12-19T12:00:40", "upload_time_iso_8601": "2019-12-19T12:00:40.609923Z", "url": "https://files.pythonhosted.org/packages/93/bd/eca5e3464768e560d53b6bb7d77d6dd927035c5dece16fe157f7a04eb642/pyRAPL-0.2.3.1-py2.py3-none-any.whl", "yanked": false, "yanked_reason": null }, { "comment_text": "", "digests": { "md5": "5efb802db54fe82138b037b0870e279f", "sha256": "c92e7e0644ceee2e55a312d515fc35de8941abd8d810095383e02183afa29b77" }, "downloads": -1, "filename": "pyRAPL-0.2.3.1.tar.gz", "has_sig": false, "md5_digest": "5efb802db54fe82138b037b0870e279f", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.7", "size": 15099, "upload_time": "2019-12-19T12:00:41", "upload_time_iso_8601": "2019-12-19T12:00:41.755106Z", "url": "https://files.pythonhosted.org/packages/f1/a0/d52262538e60ad9fca62d576277f02d0a689ad0881d8a624487d67f08d82/pyRAPL-0.2.3.1.tar.gz", "yanked": false, "yanked_reason": null } ], "vulnerabilities": [] }