Package: ethical-smart-grid
Ethical Smart Grid SimulatorAuthors: Clément Scheirlinck, Rémy ChaputDescriptionThis is a third-partyGymenvironment, focusing on learning ethically-aligned
behaviours in a Smart Grid use-case.A Smart Grid contains severalprosumer(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.InstallationYou may installEthical Smart Gridthrough:PyPi, usingpip install ethical-smart-grid(latest stable version);pip and GitHub, usingpip install git+https://github.com/ethicsai/ethical-smart-grid.git(you may specify the version at the end of the URL);GitHub, usinggit clone https://github.com/ethicsai/ethical-smart-grid(development version, not stable).If you also wish to use argumentation-based reward functions, please installAJARthroughpip install git+https://github.com/ethicsai/ajar.git@v1.0.0,
orpip install -r requirements.txtif you cloned this repository.Quick usageAfter installing, open a Python shell (3.7+), and execute the following
instructions:fromsmartgridimportmake_basic_smartgridfromalgorithms.qsomimportQSOMenv=make_basic_smartgrid(max_step=10)model=QSOM(env)done=Falseobs=env.reset()whilenotdone:actions=model.forward(obs)obs,rewards,terminated,truncated,_=env.step(actions)print(rewards)model.backward(obs,rewards)done=all(terminated)orall(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 themax_step=10argument).To go further, please refer to thedocumentation; theCustom scenarioandAdding a new modelpages can be particularly interesting to learn,
respectively, how to configure the environment, and how to implement a new
learning algorithm.
Finally,extending the environmentallows creating new components
(agents' profiles, reward functions, ...) to further customize the environment.VersioningThis project follows theSemver(Semantic Versioning): all versions respect
the<major>.<minor>.<patch>format. Thepatchnumber is increased when a
bugfix is released. Theminornumber is increased when new features are added
thatdo notbreak the code public API, i.e., it is compatible with the
previous minor version. Finally, themajornumber 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 locallyThis GitHub repository includes actions that automaticallytestthe package andbuildthe documentation on each commit, andpublishthe package toPyPion each release.Instructions to perform these steps locally are given here, for potential
new contributors or forks:Running the testsTests are defined usingunittestand run throughpytest; please install it
first:pip install pytest.
We must add the current folder to thePYTHONPATHenvironment variable to
let pytest import thesmartgridmodule when executing the tests:export PYTHONPATH=$PWD(from the root of this repository). Then, launch all
tests withpytest tests.Building the documentationThe documentation is built withSphinxand requires additional requirements;
to install them, usepip install -r docs/requirements.txt. Then, to build the
documentation, usecd docs && make html. The built documentation will be in
thedocs/build/htmlfolder. It can be cleaned usingmake cleanwhile in thedocsfolder. Additionally, thesource/modulesfolder is automatically
generated from the Python docstrings in the source code; it can be safely
deleted (e.g., withrm -r source/modules) to force re-building all
documentation files.Building and publishing releasesThis project useshatchto manage the building and publishing process; please
install it withpip install hatchfirst.To build the package, usehatch buildat the root of this repository. This
will create thesource distribution(sdist) atdist/ethica_smart_grid_simulator-<version>.tar.gz, and thebuilt distribution(wheel) atdist/ethical_smart_grid_simulator-<version>-py3-none-any.whl.To publish these files toPyPi, usehatch publish.CommunityThe community guidelines are available in theCONTRIBUTING.mdfile; you can find a (short) summary below.Getting supportIf you have a question (something that is not clear, how to get a specific
result, ...), do not hesitate to create a newDiscussion under the Q&A category.Please donotuse the issue tracker for support, to avoid cluttering it.Report a bugIf you found a bug (an error raised, or something not working as expected), you
can report it on theIssue Tracker.Please try to be aspreciseas possible.ContributingWe very much welcome and appreciate contributions!For fixing bugs, or improving the documentation, you can create aPull Request.New features are also welcome, but larger features should be discussed first in
a newDiscussion under the Ideas category.All ideas, suggestions, and requests are also welcome for discussion.LicenseThe source code is licensed under theMIT License.
Some included data may be protected by other licenses, please refer to theLICENSE.mdfile for details.CitationIf 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@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}}