| Name | ethical-smart-grid JSON |
| Version |
2.0.0
JSON |
| download |
| home_page | None |
| Summary | A RL environment for learning ethically-aligned behaviours in a Smart Grid simulator. |
| upload_time | 2024-07-18 17:20:30 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | MIT License Copyright (c) 2022 Clément Scheirlinck and Rémy Chaput Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Datasets ## OpenEI The data in the `data/openei` folder is extracted from an [energy dataset](https://data.openei.org/submissions/153) that was made available by [OpenEI](https://openei.org/wiki/Information) through a Creative Commons Attribution 4.0 license ([CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)). |
| keywords |
gym
gymnasium
machine ethics
multi-agent system
openai gym
reinforcement learning
smart grid
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Ethical Smart Grid Simulator
> Authors: Clément Scheirlinck, Rémy Chaput
<!-- Badges -->
[](https://github.com/ethicsai/ethical-smart-grid/actions/workflows/docs.yml)
[](https://github.com/ethicsai/ethical-smart-grid/actions/workflows/testing.yml)
[](https://doi.org/10.21105/joss.05410)
## Description
This is a third-party [Gym] environment, focusing on learning ethically-aligned
behaviours in a Smart Grid use-case.
A Smart Grid contains several *prosumer* (prosumer-consumer) agents that
interact in a shared environment by consuming and exchanging energy.
These agents have an energy need, at each time step, that they must satisfy
by consuming energy. However, they should respect a set of moral values as
they do so, i.e., exhibiting an ethically-aligned behaviour.
Moral values are encoded in the reward functions, which determine the
"correctness" of an agent's action, with respect to these moral values.
Agents receive rewards as feedback that guide them towards a better behaviour.
## Installation
You may install **Ethical Smart Grid** through:
- [PyPi], using `pip install ethical-smart-grid` (latest stable version);
- pip and GitHub, using `pip install git+https://github.com/ethicsai/ethical-smart-grid.git`
(you may specify the version at the end of the URL);
- GitHub, using `git clone https://github.com/ethicsai/ethical-smart-grid`
(development version, not stable).
If you also wish to use argumentation-based reward functions, please install
[AJAR] through `pip install git+https://github.com/ethicsai/ajar.git@v1.0.0`,
or `pip install -r requirements.txt` if you cloned this repository.
## Quick usage
After installing, open a Python shell (3.7+), and execute the following
instructions:
```python
from smartgrid import make_basic_smartgrid
from algorithms.qsom import QSOM
env = make_basic_smartgrid(max_step=10)
model = QSOM(env)
done = False
obs = env.reset()
while not done:
actions = model.forward(obs)
obs, rewards, terminated, truncated, _ = env.step(actions)
print(rewards)
model.backward(obs, rewards)
done = all(terminated) or all(truncated)
env.close()
```
This will initialize a SmartGrid environment, learning agents that use the QSOM
algorithm, and run the simulation for 10 steps (configurable through the `max_step=10`
argument).
To go further, please refer to the [documentation]; the [Custom scenario] and
[Adding a new model] pages can be particularly interesting to learn,
respectively, how to configure the environment, and how to implement a new
learning algorithm.
Finally, [extending the environment][Extending] allows creating new components
(agents' profiles, reward functions, ...) to further customize the environment.
## Versioning
This project follows the [Semver] (Semantic Versioning): all versions respect
the `<major>.<minor>.<patch>` format. The `patch` number is increased when a
bugfix is released. The `minor` number is increased when new features are added
that *do not* break the code public API, i.e., it is compatible with the
previous minor version. Finally, the `major` number is increased when a breaking
change is introduced; an important distinction is that such a change may not
be "important" in terms of lines of code, or number of features modified.
Simply changing a function's return type can be considered a breaking change
in the public API, and thus worthy of a "major" update.
## Building and testing locally
This GitHub repository includes actions that automatically [test][actions-test]
the package and [build][actions-docs] the documentation on each commit, and
[publish][actions-publish] the package to [PyPi] on each release.
Instructions to perform these steps locally are given here, for potential
new contributors or forks:
- *Running the tests*
Tests are defined using [unittest] and run through [pytest]; please install it
first: `pip install pytest`.
We must add the current folder to the `PYTHONPATH` environment variable to
let pytest import the `smartgrid` module when executing the tests:
`export PYTHONPATH=$PWD` (from the root of this repository). Then, launch all
tests with `pytest tests`.
- *Building the documentation*
The documentation is built with [Sphinx] and requires additional requirements;
to install them, use `pip install -r docs/requirements.txt`. Then, to build the
documentation, use `cd docs && make html`. The built documentation will be in
the `docs/build/html` folder. It can be cleaned using `make clean` while in the
`docs` folder. Additionally, the `source/modules` folder is automatically
generated from the Python docstrings in the source code; it can be safely
deleted (e.g., with `rm -r source/modules`) to force re-building all
documentation files.
- *Building and publishing releases*
This project uses [hatch] to manage the building and publishing process; please
install it with `pip install hatch` first.
To build the package, use `hatch build` at the root of this repository. This
will create the *source distribution* (sdist) at
`dist/ethica_smart_grid_simulator-<version>.tar.gz`, and the *built distribution*
(wheel) at `dist/ethical_smart_grid_simulator-<version>-py3-none-any.whl`.
To publish these files to [PyPi], use `hatch publish`.
## Community
The community guidelines are available in the [CONTRIBUTING.md](CONTRIBUTING.md)
file; you can find a (short) summary below.
### Getting support
If you have a question (something that is not clear, how to get a specific
result, ...), do not hesitate to create a new [Discussion under the Q&A category](https://github.com/ethicsai/ethical-smart-grid/discussions/new?category=q-a).
Please do *not* use the issue tracker for support, to avoid cluttering it.
### Report a bug
If you found a bug (an error raised, or something not working as expected), you
can report it on the [Issue Tracker](https://github.com/ethicsai/ethical-smart-grid/issues/new).
Please try to be as *precise* as possible.
### Contributing
We very much welcome and appreciate contributions!
For fixing bugs, or improving the documentation, you can create a
[Pull Request](https://github.com/ethicsai/ethical-smart-grid/pulls).
New features are also welcome, but larger features should be discussed first in
a new [Discussion under the Ideas category](https://github.com/ethicsai/ethical-smart-grid/discussions/new?category=ideas).
All ideas, suggestions, and requests are also welcome for discussion.
## License
The source code is licensed under the [MIT License].
Some included data may be protected by other licenses, please refer to the
[LICENSE.md] file for details.
## Citation
If you use this package in your research, please cite the corresponding paper:
> Scheirlinck, C., Chaput, R., & Hassas, S. (2023). Ethical Smart Grid: a Gym
> environment for learning ethical behaviours. Journal of Open Source Software,
> 8(88), 5410. https://doi.org/10.21105/joss.05410
```bibtex
@article{Scheirlinck_Ethical_Smart_Grid_2023,
author = {Scheirlinck, Clément and Chaput, Rémy and Hassas, Salima},
doi = {10.21105/joss.05410},
journal = {Journal of Open Source Software},
month = aug,
number = {88},
pages = {5410},
title = {{Ethical Smart Grid: a Gym environment for learning ethical behaviours}},
url = {https://joss.theoj.org/papers/10.21105/joss.05410},
volume = {8},
year = {2023}
}
```
[Gym]: https://gymnasium.farama.org/
[AJAR]: https://github.com/ethicsai/ajar/
[documentation]: https://ethicsai.github.io/ethical-smart-grid/
[Custom scenario]: https://ethicsai.github.io/ethical-smart-grid/custom_scenario.html
[Adding a new model]: https://ethicsai.github.io/ethical-smart-grid/adding_model.html
[Extending]: https://ethicsai.github.io/ethical-smart-grid/extending/index.html
[Semver]: https://semver.org/
[PyPi]: https://pypi.org/project/ethical-smart-grid/
[unittest]: https://docs.python.org/3/library/unittest.html
[pytest]: https://pytest.org/
[actions-test]: https://github.com/ethicsai/ethical-smart-grid/actions/workflows/testing.yml
[actions-docs]: https://github.com/ethicsai/ethical-smart-grid/actions/workflows/docs.yml
[actions-publish]: https://github.com/ethicsai/ethical-smart-grid/actions/workflows/package.yml
[Sphinx]: https://www.sphinx-doc.org/
[hatch]: https://hatch.pypa.io/latest/
[MIT License]: https://choosealicense.com/licenses/mit/
[LICENSE.md]: LICENSE.md
Raw data
{
"_id": null,
"home_page": null,
"name": "ethical-smart-grid",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "R\u00e9my Chaput <rchaput.pro@gmail.com>",
"keywords": "Gym, Gymnasium, Machine Ethics, Multi-Agent System, OpenAI Gym, Reinforcement Learning, Smart Grid",
"author": null,
"author_email": "Cl\u00e9ment Scheirlinck <clement.scheirlinck@etu.univ-lyon1.fr>",
"download_url": "https://files.pythonhosted.org/packages/a9/96/de3048901d08fd4bba270a84ff6a3f52aaeb066be53d93da992a6a3e72c3/ethical_smart_grid-2.0.0.tar.gz",
"platform": null,
"description": "# Ethical Smart Grid Simulator\n\n> Authors: Cl\u00e9ment Scheirlinck, R\u00e9my Chaput\n\n<!-- Badges -->\n\n[](https://github.com/ethicsai/ethical-smart-grid/actions/workflows/docs.yml)\n[](https://github.com/ethicsai/ethical-smart-grid/actions/workflows/testing.yml)\n\n\n[](https://doi.org/10.21105/joss.05410)\n\n## Description\n\nThis is a third-party [Gym] environment, focusing on learning ethically-aligned\nbehaviours in a Smart Grid use-case.\n\nA Smart Grid contains several *prosumer* (prosumer-consumer) agents that\ninteract in a shared environment by consuming and exchanging energy.\nThese agents have an energy need, at each time step, that they must satisfy\nby consuming energy. However, they should respect a set of moral values as\nthey do so, i.e., exhibiting an ethically-aligned behaviour.\n\nMoral values are encoded in the reward functions, which determine the\n\"correctness\" of an agent's action, with respect to these moral values.\nAgents receive rewards as feedback that guide them towards a better behaviour.\n\n## Installation\n\nYou may install **Ethical Smart Grid** through:\n\n- [PyPi], using `pip install ethical-smart-grid` (latest stable version);\n- pip and GitHub, using `pip install git+https://github.com/ethicsai/ethical-smart-grid.git`\n (you may specify the version at the end of the URL);\n- GitHub, using `git clone https://github.com/ethicsai/ethical-smart-grid`\n (development version, not stable).\n\nIf you also wish to use argumentation-based reward functions, please install\n[AJAR] through `pip install git+https://github.com/ethicsai/ajar.git@v1.0.0`,\nor `pip install -r requirements.txt` if you cloned this repository.\n\n## Quick usage\n\nAfter installing, open a Python shell (3.7+), and execute the following\ninstructions:\n\n```python\nfrom smartgrid import make_basic_smartgrid\nfrom algorithms.qsom import QSOM\n\nenv = make_basic_smartgrid(max_step=10)\nmodel = QSOM(env)\n\ndone = False\nobs = env.reset()\nwhile not done:\n actions = model.forward(obs)\n obs, rewards, terminated, truncated, _ = env.step(actions)\n print(rewards)\n model.backward(obs, rewards)\n done = all(terminated) or all(truncated)\n\nenv.close()\n```\n\nThis will initialize a SmartGrid environment, learning agents that use the QSOM\nalgorithm, and run the simulation for 10 steps (configurable through the `max_step=10`\nargument).\n\nTo go further, please refer to the [documentation]; the [Custom scenario] and\n[Adding a new model] pages can be particularly interesting to learn,\nrespectively, how to configure the environment, and how to implement a new\nlearning algorithm.\nFinally, [extending the environment][Extending] allows creating new components\n(agents' profiles, reward functions, ...) to further customize the environment.\n\n## Versioning\n\nThis project follows the [Semver] (Semantic Versioning): all versions respect\nthe `<major>.<minor>.<patch>` format. The `patch` number is increased when a\nbugfix is released. The `minor` number is increased when new features are added\nthat *do not* break the code public API, i.e., it is compatible with the\nprevious minor version. Finally, the `major` number is increased when a breaking\nchange is introduced; an important distinction is that such a change may not\nbe \"important\" in terms of lines of code, or number of features modified.\nSimply changing a function's return type can be considered a breaking change\nin the public API, and thus worthy of a \"major\" update.\n\n## Building and testing locally\n\nThis GitHub repository includes actions that automatically [test][actions-test]\nthe package and [build][actions-docs] the documentation on each commit, and \n[publish][actions-publish] the package to [PyPi] on each release.\n\nInstructions to perform these steps locally are given here, for potential\nnew contributors or forks:\n\n- *Running the tests*\n\nTests are defined using [unittest] and run through [pytest]; please install it\nfirst: `pip install pytest`.\nWe must add the current folder to the `PYTHONPATH` environment variable to\nlet pytest import the `smartgrid` module when executing the tests:\n`export PYTHONPATH=$PWD` (from the root of this repository). Then, launch all\ntests with `pytest tests`.\n\n- *Building the documentation*\n\nThe documentation is built with [Sphinx] and requires additional requirements;\nto install them, use `pip install -r docs/requirements.txt`. Then, to build the\ndocumentation, use `cd docs && make html`. The built documentation will be in\nthe `docs/build/html` folder. It can be cleaned using `make clean` while in the\n`docs` folder. Additionally, the `source/modules` folder is automatically\ngenerated from the Python docstrings in the source code; it can be safely\ndeleted (e.g., with `rm -r source/modules`) to force re-building all\ndocumentation files.\n\n- *Building and publishing releases*\n\nThis project uses [hatch] to manage the building and publishing process; please\ninstall it with `pip install hatch` first.\n\nTo build the package, use `hatch build` at the root of this repository. This\nwill create the *source distribution* (sdist) at\n`dist/ethica_smart_grid_simulator-<version>.tar.gz`, and the *built distribution*\n(wheel) at `dist/ethical_smart_grid_simulator-<version>-py3-none-any.whl`.\n\nTo publish these files to [PyPi], use `hatch publish`.\n\n\n## Community\n\nThe community guidelines are available in the [CONTRIBUTING.md](CONTRIBUTING.md)\nfile; you can find a (short) summary below.\n\n### Getting support\n\nIf you have a question (something that is not clear, how to get a specific\nresult, ...), do not hesitate to create a new [Discussion under the Q&A category](https://github.com/ethicsai/ethical-smart-grid/discussions/new?category=q-a).\n\nPlease do *not* use the issue tracker for support, to avoid cluttering it.\n\n### Report a bug\n\nIf you found a bug (an error raised, or something not working as expected), you\ncan report it on the [Issue Tracker](https://github.com/ethicsai/ethical-smart-grid/issues/new).\n\nPlease try to be as *precise* as possible.\n\n### Contributing\n\nWe very much welcome and appreciate contributions!\n\nFor fixing bugs, or improving the documentation, you can create a\n[Pull Request](https://github.com/ethicsai/ethical-smart-grid/pulls).\n\nNew features are also welcome, but larger features should be discussed first in\na new [Discussion under the Ideas category](https://github.com/ethicsai/ethical-smart-grid/discussions/new?category=ideas).\n\nAll ideas, suggestions, and requests are also welcome for discussion.\n\n\n## License\n\nThe source code is licensed under the [MIT License].\nSome included data may be protected by other licenses, please refer to the\n[LICENSE.md] file for details.\n\n\n## Citation\n\nIf you use this package in your research, please cite the corresponding paper:\n\n> Scheirlinck, C., Chaput, R., & Hassas, S. (2023). Ethical Smart Grid: a Gym\n> environment for learning ethical behaviours. Journal of Open Source Software,\n> 8(88), 5410. https://doi.org/10.21105/joss.05410\n\n```bibtex\n@article{Scheirlinck_Ethical_Smart_Grid_2023,\n author = {Scheirlinck, Cl\u00e9ment and Chaput, R\u00e9my and Hassas, Salima},\n doi = {10.21105/joss.05410},\n journal = {Journal of Open Source Software},\n month = aug,\n number = {88},\n pages = {5410},\n title = {{Ethical Smart Grid: a Gym environment for learning ethical behaviours}},\n url = {https://joss.theoj.org/papers/10.21105/joss.05410},\n volume = {8},\n year = {2023}\n}\n```\n\n[Gym]: https://gymnasium.farama.org/\n[AJAR]: https://github.com/ethicsai/ajar/\n[documentation]: https://ethicsai.github.io/ethical-smart-grid/\n[Custom scenario]: https://ethicsai.github.io/ethical-smart-grid/custom_scenario.html\n[Adding a new model]: https://ethicsai.github.io/ethical-smart-grid/adding_model.html\n[Extending]: https://ethicsai.github.io/ethical-smart-grid/extending/index.html\n[Semver]: https://semver.org/\n[PyPi]: https://pypi.org/project/ethical-smart-grid/\n[unittest]: https://docs.python.org/3/library/unittest.html\n[pytest]: https://pytest.org/\n[actions-test]: https://github.com/ethicsai/ethical-smart-grid/actions/workflows/testing.yml\n[actions-docs]: https://github.com/ethicsai/ethical-smart-grid/actions/workflows/docs.yml\n[actions-publish]: https://github.com/ethicsai/ethical-smart-grid/actions/workflows/package.yml\n[Sphinx]: https://www.sphinx-doc.org/\n[hatch]: https://hatch.pypa.io/latest/\n[MIT License]: https://choosealicense.com/licenses/mit/\n[LICENSE.md]: LICENSE.md\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2022 Cl\u00e9ment Scheirlinck and R\u00e9my Chaput Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Datasets ## OpenEI The data in the `data/openei` folder is extracted from an [energy dataset](https://data.openei.org/submissions/153) that was made available by [OpenEI](https://openei.org/wiki/Information) through a Creative Commons Attribution 4.0 license ([CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)).",
"summary": "A RL environment for learning ethically-aligned behaviours in a Smart Grid simulator.",
"version": "2.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/ethicsai/ethical-smart-grid/issues",
"Documentation": "https://ethicsai.github.io/ethical-smart-grid/",
"Source code": "https://github.com/ethicsai/ethical-smart-grid"
},
"split_keywords": [
"gym",
" gymnasium",
" machine ethics",
" multi-agent system",
" openai gym",
" reinforcement learning",
" smart grid"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e52af147684b5a4179bc48d3a05d9886eb4ad464d12419e65c360bc86dfb52c9",
"md5": "327c6cfa80307d4e557ef49eede7817f",
"sha256": "e7571297932a31de0ee7f430a59331616095a4fc281accbc5ba3b00c933a87a2"
},
"downloads": -1,
"filename": "ethical_smart_grid-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "327c6cfa80307d4e557ef49eede7817f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 141264,
"upload_time": "2024-07-18T17:20:29",
"upload_time_iso_8601": "2024-07-18T17:20:29.076150Z",
"url": "https://files.pythonhosted.org/packages/e5/2a/f147684b5a4179bc48d3a05d9886eb4ad464d12419e65c360bc86dfb52c9/ethical_smart_grid-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a996de3048901d08fd4bba270a84ff6a3f52aaeb066be53d93da992a6a3e72c3",
"md5": "ae5e644dfead9858c27eabd8a6c92509",
"sha256": "608d6bb64d0870aeacfc8960ef2f65289bec270a3123e8902453673a8e789cc4"
},
"downloads": -1,
"filename": "ethical_smart_grid-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "ae5e644dfead9858c27eabd8a6c92509",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 118776,
"upload_time": "2024-07-18T17:20:30",
"upload_time_iso_8601": "2024-07-18T17:20:30.553062Z",
"url": "https://files.pythonhosted.org/packages/a9/96/de3048901d08fd4bba270a84ff6a3f52aaeb066be53d93da992a6a3e72c3/ethical_smart_grid-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-18 17:20:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ethicsai",
"github_project": "ethical-smart-grid",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "ethical-smart-grid"
}
