Merge branch 'master' of github.com:upb-lea/gym-electric-motor

upb-lea · Aug 23, 2021 · f091d6b · f091d6b
2 parents e215a5d + 8a9f5c4
commit f091d6b
Show file tree

Hide file tree

Showing 288 changed files with 24,409 additions and 15,867 deletions.
diff --git a/.gitignore b/.gitignore
@@ -25,3 +25,4 @@ examples/logs/
 # unit tests
 .coverage
 
+/my_examples/
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,47 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2021-08-23
+### Added
+- classic controllers in examples with complete makeover
+- Possibility to seed all random number generators at once with a unified API - Reproduciblity improved.
+
+### Changed
+#### Environment IDs
+- The environments have changed the IDs for their creation. 
+- Furthermore, environments specialized for torque (TC), current (CC) and speed (SC) control tasks have been introduced.
+- The ids are now structured as follows:
+{_Cont/Finite_}-{_CC/TC/SC_}-_motorType_-v0
+- Details can be looked up on the code documentation pages.
+#### gem.make() parameters
+The arbitrary environment creation keyword arguments that were passed to every subcomponent of the environment
+have been removed. Instead, there is a fixed set of keyword parameters for every environment described in the 
+API-documentation of every environment.
+
+#### MPC example
+- Visualization improvements
+- fix: State variables were updated
+
+#### Miscellaneous
+- Documentation was updated
+- Changed all DC Envs to FourQuadrantConverters per default
+- Adjusted the dynamics of the speed references in DC environments
+- Adjusted the plots for better visibility of single points
+
+
+### Removed
+- simple_controllers.py in examples
+- Tensorforce tutorial due to deprecation
+
+
+## [0.3.1] - 2020-12-18
+### Added
+- Constraint monitor class
+
+### Changed
+- Visualization framework
diff --git a/README.md b/README.md
@@ -1,7 +1,9 @@
 # Gym Electric Motor
 ![](docs/plots/Motor_Logo.png)
 
-[**Paper**](https://arxiv.org/abs/1910.09434)
+
+[**Overview paper**](https://joss.theoj.org/papers/10.21105/joss.02498)
+| [**Reinforcement learning paper**](https://arxiv.org/abs/1910.09434)
 | [**Quickstart**](#getting-started)
 | [**Install guide**](#installation)
 | [**Reference docs**](https://upb-lea.github.io/gym-electric-motor/)
@@ -16,16 +18,14 @@
 
 ## Overview
 The gym-electric-motor (GEM) package is a Python toolbox for the simulation and control of various electric motors.
-
-It is built upon [OpenAI Gym Environments](https://gym.openai.com/), and, therefore, can be used for both, classical control simulation and r[einforcement 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 PI-controllers to [Deep Deterministic Policy Gradient](https://spinningup.openai.com/en/latest/algorithms/ddpg.html) agents.
+It is built upon [OpenAI Gym 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.
 
 ## 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)
-* [Tensorforce example](https://colab.research.google.com/github/upb-lea/gym-electric-motor/blob/master/examples/reinforcement_learning_controllers/tensorforce_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.
@@ -35,7 +35,7 @@ A basic routine is as simple as:
 import gym_electric_motor as gem
 
 if __name__ == '__main__':
-    env = gem.make("PMSMDisc-v1")  # instantiate a discretely controlled PMSM
+    env = gem.make("Finite-CC-PMSM-v0")  # instantiate a discretely controlled PMSM
     env.reset()
     for _ in range(1000):
         env.render()  # visualize environment
@@ -78,24 +78,42 @@ A GEM environment consists of following building blocks:
 ### Information Flow in a GEM Environment
 ![](docs/plots/SCML_Overview.png)
 
-Among various DC-motor models, the following three-phase motors - together with their power electronic counterparts - are available:
+Among various DC-motor models, the following AC motors - together with their power electronic counterparts - are available:
 - Permanent magnet synchronous motor (PMSM), 
 - Synchronous reluctance motor (SynRM)
 - Squirrel cage induction motor (SCIM)
 - Doubly-fed induction motor (DFIM)
 
-The converters can be driven by means of a duty cycle (continuous mode) or switching commands (discrete mode). 
+The converters can be driven by means of a duty cycle (continuous control set) or switching commands (finite control set). 
 
 ### Citation
-A whitepaper for this framework is available under (preprint: [arxiv.org/abs/1910.09434](https://arxiv.org/abs/1910.09434), full-paper: [IEEE-Xplore](https://ieeexplore.ieee.org/document/9241851)). Please use the following BibTeX entry for citing us:
+A white paper for the general toolbox in the context of drive simulation and control prototyping can be found in the [Journal of Open Sorce Software (JOSS)](https://joss.theoj.org/papers/10.21105/joss.02498). Please use the following BibTeX entry for citing it:
+```
+@article{Balakrishna2021,
+    doi = {10.21105/joss.02498},
+    url = {https://doi.org/10.21105/joss.02498},
+    year = {2021},
+    publisher = {The Open Journal},
+    volume = {6},
+    number = {58},
+    pages = {2498},
+    author = {Praneeth {Balakrishna} and Gerrit {Book} and Wilhelm {Kirchgässner} and Maximilian {Schenke} and Arne {Traue} and Oliver {Wallscheid}},
+    title = {gym-electric-motor (GEM): A Python toolbox for the simulation of electric drive systems},
+    journal = {Journal of Open Source Software}
+}
+
+```
+
+A white paper for the utilization of this framework within reinforcement learning is available at [IEEE-Xplore](https://ieeexplore.ieee.org/document/9241851) (preprint: [arxiv.org/abs/1910.09434](https://arxiv.org/abs/1910.09434)). Please use the following BibTeX entry for citing it:
 ```
-@ARTICLE{9241851,  
-author={A. {Traue} and G. {Book} and W. {Kirchgässner} and O. {Wallscheid}},  
-journal={IEEE Transactions on Neural Networks and Learning Systems},   
-title={Toward a Reinforcement Learning Environment Toolbox for Intelligent Electric Motor Control},   
-year={2020},  volume={},  number={},  
-pages={1-10},  
-doi={10.1109/TNNLS.2020.3029573}}
+@article{9241851,  
+    doi={10.1109/TNNLS.2020.3029573}
+    author={A. {Traue} and G. {Book} and W. {Kirchgässner} and O. {Wallscheid}},  
+    journal={IEEE Transactions on Neural Networks and Learning Systems},   
+    title={Toward a Reinforcement Learning Environment Toolbox for Intelligent Electric Motor Control},   
+    year={2020},  volume={},  number={},      
+    pages={1-10},  
+}
 ```
 
 ### Running Unit Tests with Pytest

diff --git a/docs/conf.py b/docs/conf.py
@@ -19,13 +19,13 @@
 # -- Project information -----------------------------------------------------
 
 project = 'gym-electric-motor'
-copyright = '2020, Praneeth Balakrishna, Gerrit Book, Wilhelm Kirchgässner, Maximilian Schenke, Arne Traue, Oliver Wallscheid'
-author = 'Praneeth Balakrishna, Gerrit Book, Wilhelm Kirchgässner, Maximilian Schenke, Arne Traue, Oliver Wallscheid'
+copyright = '2021, Praneeth Balakrishna, Gerrit Book, Felix Book, Darius Jakobeit, Wilhelm Kirchgässner, Maximilian Schenke, Arne Traue, Oliver Wallscheid'
+author = 'Praneeth Balakrishna, Gerrit Book, Felix Book, Darius Jakobeit, Wilhelm Kirchgässner, Maximilian Schenke, Arne Traue, Oliver Wallscheid'
 
 # The short X.Y version
 version = ''
 # The full version, including alpha/beta/rc tags
-release = '2020'
+release = '2021'
 
 
 # -- General configuration ---------------------------------------------------
@@ -43,7 +43,9 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
     'sphinx.ext.napoleon',
-    'm2r']
+    'sphinx_rtd_theme',
+    'm2r'
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -52,7 +54,7 @@
 # You can specify multiple suffix as a list of string:
 #
 source_suffix = ['.rst', '.md']
-#source_suffix = '.rst'
+# source_suffix = '.rst'
 
 # The master toctree document.
 master_doc = 'index'

diff --git a/docs/index.rst b/docs/index.rst
@@ -48,6 +48,7 @@ documentation specifies the basic interfaces inside a physical system.
     parts/core
     parts/utils
     parts/callbacks
+    parts/random_component
 
 Indices and tables
 ==================

diff --git a/docs/parts/environments/dc_extex_cont.rst b/docs/parts/environments/dc_extex_cont.rst
diff --git a/docs/parts/environments/dc_extex_disc.rst b/docs/parts/environments/dc_extex_disc.rst
diff --git a/docs/parts/environments/dc_permex_cont.rst b/docs/parts/environments/dc_permex_cont.rst
diff --git a/docs/parts/environments/dc_permex_disc.rst b/docs/parts/environments/dc_permex_disc.rst
diff --git a/docs/parts/environments/dc_series_cont.rst b/docs/parts/environments/dc_series_cont.rst
diff --git a/docs/parts/environments/dc_series_disc.rst b/docs/parts/environments/dc_series_disc.rst
diff --git a/docs/parts/environments/dc_shunt_cont.rst b/docs/parts/environments/dc_shunt_cont.rst
diff --git a/docs/parts/environments/dc_shunt_disc.rst b/docs/parts/environments/dc_shunt_disc.rst
diff --git a/docs/parts/environments/dfim/abccont_cc_dfim.rst b/docs/parts/environments/dfim/abccont_cc_dfim.rst
@@ -0,0 +1,4 @@
+Abc-Continuous Current Control Doubly Fed Induction Motor Environment
+**********************************************************************
+.. autoclass:: gym_electric_motor.envs.AbcContCurrentControlDoublyFedInductionMotorEnv
+   :members:
diff --git a/docs/parts/environments/dfim/abccont_sc_dfim.rst b/docs/parts/environments/dfim/abccont_sc_dfim.rst
@@ -0,0 +1,4 @@
+Abc-Continuous Speed Control Doubly Fed Induction Motor Environment
+**********************************************************************
+.. autoclass:: gym_electric_motor.envs.AbcContSpeedControlDoublyFedInductionMotorEnv
+   :members:
diff --git a/docs/parts/environments/dfim/abccont_tc_dfim.rst b/docs/parts/environments/dfim/abccont_tc_dfim.rst
@@ -0,0 +1,4 @@
+Abc-Continuous Torque Control Doubly Fed Induction Motor Environment
+**********************************************************************
+.. autoclass:: gym_electric_motor.envs.AbcContTorqueControlDoublyFedInductionMotorEnv
+   :members:
diff --git a/docs/parts/environments/dfim/dfim_envs.rst b/docs/parts/environments/dfim/dfim_envs.rst
@@ -0,0 +1,12 @@
+Doubly Fed Induction Motor Environments
+***************************************
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Environments:
+   :glob:
+
+   *
+
+
diff --git a/docs/parts/environments/dfim/dqcont_cc_dfim.rst b/docs/parts/environments/dfim/dqcont_cc_dfim.rst
@@ -0,0 +1,4 @@
+Dq-Continuous Current Control Doubly Fed Induction Motor Environment
+**********************************************************************
+.. autoclass:: gym_electric_motor.envs.DqContCurrentControlDoublyFedInductionMotorEnv
+   :members:
diff --git a/docs/parts/environments/dfim/dqcont_sc_dfim.rst b/docs/parts/environments/dfim/dqcont_sc_dfim.rst
@@ -0,0 +1,4 @@
+Dq-Continuous Speed Control Doubly Fed Induction Motor Environment
+**********************************************************************
+.. autoclass:: gym_electric_motor.envs.DqContSpeedControlDoublyFedInductionMotorEnv
+   :members:
diff --git a/docs/parts/environments/dfim/dqcont_tc_dfim.rst b/docs/parts/environments/dfim/dqcont_tc_dfim.rst
@@ -0,0 +1,4 @@
+Dq-Continuous Torque Control Doubly Fed Induction Motor Environment
+**********************************************************************
+.. autoclass:: gym_electric_motor.envs.DqContTorqueControlDoublyFedInductionMotorEnv
+   :members:
diff --git a/docs/parts/environments/dfim/finite_cc_dfim.rst b/docs/parts/environments/dfim/finite_cc_dfim.rst
@@ -0,0 +1,4 @@
+Finite Control Set Current Control Doubly Fed Induction Motor Environment
+**************************************************************************
+.. autoclass:: gym_electric_motor.envs.FiniteCurrentControlDoublyFedInductionMotorEnv
+   :members:
diff --git a/docs/parts/environments/dfim/finite_sc_dfim.rst b/docs/parts/environments/dfim/finite_sc_dfim.rst
@@ -0,0 +1,4 @@
+Finite Control Set Speed Control Doubly Fed Induction Motor Environment
+**************************************************************************
+.. autoclass:: gym_electric_motor.envs.FiniteSpeedControlDoublyFedInductionMotorEnv
+   :members:
diff --git a/docs/parts/environments/dfim/finite_tc_dfim.rst b/docs/parts/environments/dfim/finite_tc_dfim.rst
@@ -0,0 +1,4 @@
+Finite Control Set Torque Control Doubly Fed Induction Motor Environment
+**************************************************************************
+.. autoclass:: gym_electric_motor.envs.FiniteTorqueControlDoublyFedInductionMotorEnv
+   :members:
diff --git a/docs/parts/environments/dfim_cont.rst b/docs/parts/environments/dfim_cont.rst
diff --git a/docs/parts/environments/dfim_disc.rst b/docs/parts/environments/dfim_disc.rst
Original file line number	Diff line number	Diff line change
Expand Up		@@ -25,3 +25,4 @@ examples/logs/
		# unit tests
		.coverage

		/my_examples/