Merge pull request #257 from upb-lea/nightly

PR for version 3.0.0

.github/workflows/build_and_test.yml

@@ -15,7 +15,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [3.8, 3.9, "3.10"]
+        python-version: [3.9, "3.10", "3.11", "3.12", "3.13"]
 
     steps:
     - uses: actions/checkout@v3
@@ -32,16 +32,15 @@ jobs:
       env:
         PY_VER: ${{ matrix.python-version }}
       run: |
-        if [[ "$PY_VER" = "3.7" ]]; then pytest --cov=gym_electric_motor tests/; else pytest; fi
-        if [[ "$PY_VER" = "3.7" ]]; then bash <(curl -s https://codecov.io/bash); fi # code coverage report upload
+        pytest
   build-doc:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v3
     - name: Build Sphinx documentation
-      uses: ammaraskar/sphinx-action@master
+      uses: nicholasphair/sphinx-action@7.0.0
       with:
-        pre-build-command: "python -m pip install sphinx m2r2 sphinx_rtd_theme && python -m pip install -r requirements.txt & python -m pip install ."
+        pre-build-command: "python -m pip install sphinx m2r2 sphinx_rtd_theme==1.3.0 && python -m pip install -r requirements.txt && python -m pip install ."
         docs-folder: "docs/"
     # Publish built docs to gh-pages branch.
     # ===============================

.gitignore

@@ -30,4 +30,5 @@ examples/logs/
 /my_examples/
 .vscode/settings.json
 .vscode/launch.json
-plots/
+plots/
+saved_plots/

CHANGELOG.md

@@ -9,6 +9,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## Changed
 ## Fixed
 
+## [3.0.0] - Unreleased
+## Added
+- Support for Python 3.11, 3.12, 3.13
+- Ruff: Python linter & formatter (see [DEVELOPMENT.md](DEVELOPMENT.md))
+- StateObserver: An easy way to get state values with error checking [example](examples/observers/state_observer_example.py)
+- Integrated gem_controls repository into gem. classic_controllers will be removed in further version
+- Using pyproject.toml, dropping deprecated setup.py
+- Enabled Gymnasium env checker [see here](https://gymnasium.farama.org/api/experimental/wrappers/#gymnasium.experimental.wrappers.PassiveEnvCheckerV0)
+## Changed
+- Dropped support for Python 3.8
+- Linted and formatted all files
+- Changed max. steps in some test files to improve test speed by 30%
+- Changed the syntax from gem_controller.py to be compatible with the gymnasium interface
+## Fixed
+- #244 Sphinx docu build
+- #233 EESM ODE update
+- #224 DqToAbcActionProcessor uses now the correct angle to apply the dq to abc transformation 
+- #223 CosSinProcessor uses now the denormalized angel for calculating the sin and cos
+- #253 #256 all examples to the current syntax
+
 ## [2.0.0] - 2023-08-15
 ## Added
 - Support for Python 3.10

DEVELOPMENT.md

@@ -0,0 +1,41 @@
+# Packaging
+Update build tool: `python -m pip install --upgrade build`
+
+Build: `python -m build`
+
+# Testing 
+Run: `pytest --sw`
+> --sw, --stepwise      Exit on test failure and continue from last failing test next time
+
+Warning as error:
+> python -W error -m pytest --sw -v
+
+# Linter and Formater
+Ruff: https://docs.astral.sh/ruff/installation/
+
+Use `ruff check src/` for linting
+or `ruff format src/` for formatting
+
+
+# Install package for local development
+Run: `pip install -e .`
+> -e, --editable <path/url>   Install a project in editable mode (i.e. setuptools "develop mode") from a local project path or a VCS url
+
+Check correct package install directory with python interpreter
+Run: `python`
+
+```
+>>> import gym_electric_motor as gem
+>>> gem
+<module 'gym_electric_motor' from '/home/***/gym-electric-motor/src/gym_electric_motor/__init__.py'>
+```
+
+# Sidenotes
+```
+python -V
+Python 3.10.13
+```
+
+
+## No poetry
+Some complex dependency systems don't work good with poetry (e.g. pytorch) (https://python-poetry.org/)

README.md

@@ -4,6 +4,7 @@
 
 [**Overview paper**](https://joss.theoj.org/papers/10.21105/joss.02498)
 | [**Reinforcement learning paper**](https://arxiv.org/abs/1910.09434)
+| [**GEM control paper**](https://ieeexplore.ieee.org/document/10239044)
 | [**Quickstart**](#getting-started)
 | [**Install guide**](#installation)
 | [**Reference docs**](https://upb-lea.github.io/gym-electric-motor/)
@@ -18,14 +19,15 @@
 
 ## Overview
 The gym-electric-motor (GEM) package is a Python toolbox for the simulation and control of various electric motors.
-It is built upon [Faram Gymnasium Environments](https://gym.openai.com/), and, therefore, can be used for both, classical control simulation and [reinforcement learning](https://github.com/upb-lea/reinforcement_learning_course_materials) experiments. It allows you to construct a typical drive train with the usual building blocks, i.e., supply voltages, converters, electric motors and load models, and obtain not only a closed-loop simulation of this physical structure, but also a rich interface for plugging in any decision making algorithm, from linear feedback control to [Deep Deterministic Policy Gradient](https://spinningup.openai.com/en/latest/algorithms/ddpg.html) agents.
+It is built upon [Faram Gymnasium Environments](https://gymnasium.farama.org/), and, therefore, can be used for both, classical control simulation and [reinforcement learning](https://github.com/upb-lea/reinforcement_learning_course_materials) experiments. It allows you to construct a typical drive train with the usual building blocks, i.e., supply voltages, converters, electric motors and load models, and obtain not only a closed-loop simulation of this physical structure, but also a rich interface for plugging in any decision making algorithm, from linear feedback control to [Deep Deterministic Policy Gradient](https://spinningup.openai.com/en/latest/algorithms/ddpg.html) agents.
+In addition, an automated framework for classical control structures based on PI controllers is provided.
 
 ## Getting Started
 An easy way to get started with GEM is by playing around with the following interactive notebooks in Google Colaboratory. Most important features of GEM as well as application demonstrations are showcased, and give a kickstart for engineers in industry and academia.
 
 * [GEM cookbook](https://colab.research.google.com/github/upb-lea/gym-electric-motor/blob/master//examples/environment_features/GEM_cookbook.ipynb)
-* [Keras-rl2 example](https://colab.research.google.com/github/upb-lea/gym-electric-motor/blob/master/examples/reinforcement_learning_controllers/keras_rl2_dqn_disc_pmsm_example.ipynb)
-* [Stable-baselines3 example](https://colab.research.google.com/github/upb-lea/gym-electric-motor/blob/master/examples/reinforcement_learning_controllers/stable_baselines3_dqn_disc_pmsm_example.ipynb)
+* [Stable-baselines3 DDPG example](https://colab.research.google.com/github/upb-lea/gym-electric-motor/blob/master/examples/reinforcement_learning_controllers/stable_baselines3_ddpg_pmsm_dq_current_control.ipynb)
+* [Stable-baselines3 DQN example](https://colab.research.google.com/github/upb-lea/gym-electric-motor/blob/master/examples/reinforcement_learning_controllers/stable_baselines3_dqn_disc_pmsm_example.ipynb)
 * [MPC  example](https://colab.research.google.com/github/upb-lea/gym-electric-motor/blob/master/examples/model_predictive_controllers/pmsm_mpc_dq_current_control.ipynb)
 
 There is a list of [standalone example scripts](examples/) as well for minimalistic demonstrations.
@@ -68,7 +70,7 @@ pip install -e .
 ## Building Blocks
 A GEM environment consists of following building blocks:
 - Physical structure:
-   - Supply voltage
+   - Voltage supply
    - Converter
    - Electric motor
    - Load model
@@ -78,8 +80,9 @@ A GEM environment consists of following building blocks:
 ![](docs/plots/SCML_Overview.png)
 
 Among various DC-motor models, the following AC motors - together with their power electronic counterparts - are available:
-- Permanent magnet synchronous motor (PMSM), 
+- Permanent magnet synchronous motor (PMSM) 
 - Synchronous reluctance motor (SynRM)
+- Externally exited synchronous motor (EESM)
 - Squirrel cage induction motor (SCIM)
 - Doubly-fed induction motor (DFIM)
 
@@ -116,6 +119,19 @@ A white paper for the utilization of this framework within reinforcement learnin
   doi={10.1109/TNNLS.2020.3029573}}
 ```
 
+A white paper for the classical control approaches of gym-electric-motor control is available at [IEEE-Xplore](https://ieeexplore.ieee.org/document/10239044). Please use the following BibTeX entry for citing it:
+```
+@INPROCEEDINGS{10239044,
+  author={Book, Felix and Traue, Arne and Schenke, Maximilian and Haucke-Korber, Barnabas and Wallscheid, Oliver},
+  booktitle={2023 IEEE International Electric Machines & Drives Conference (IEMDC)}, 
+  title={Gym-Electric-Motor (GEM) Control: An Automated Open-Source Controller Design Suite for Drives}, 
+  year={2023},
+  volume={},
+  number={},
+  pages={1-7},
+  doi={10.1109/IEMDC55163.2023.10239044}}
+```
+
 ### Running Unit Tests with Pytest
 To run the unit tests ''pytest'' is required.
 All tests can be found in the ''tests'' folder.