Update documentation, reorganize example scripts (#148)

* add updated documentation

* edited gitignore

* updated complexFFPI current controller diagram. Now uses complex vector design instead of IMC

* refactored imports: CarrierComparison, Simulation and VoltageSourceConverter are now imported as part of grid.model package. BaseValues and NominalValues classes are defined in common/utils/ and imported into drive.utils and grid.utils

* updated example scripts to use new import structure

* move example scripts into separate drive and grid subfolders

* updated equations in gfl current controller

* documentation layout updated

* updated Usage section, fix to conf.py

* links fixed in documentation, all examples. and also most of the models and control

* updated grid voltage source documentation

* small fixes in documentation, removed unnecessary comment from common.model

* edited section names in control docs

* readded CarrierComparison to common.model init to fix some links in documentation, fixed import in CarrierComparison docstring usage example

* set autoapi option to have api reference in alphabetical order, change import in common/model/converter.py to fix some links in api reference

* removed conductances

* fix import in IM flux vector example, fix cross-references in GFM example readme

* LC- and L-filter figures updates

* modified notation in grid filter documentation, added an exception that is raised if ACFilter is not given correct parameters

* modified generic system model section, added describtion of the main control loop

* updated converter documentation and figures

* minor typo fix in LC filter

* typo fixes, also removed unneccessary newlines in files ac_filter.rst and system.rst

* added observer section to Synchronization, removed unnecessary newlines

* edits to documentation structure: removed sections that will be improved and included in a later PR, removed mentions to future extensions on some pages

* renamed Generic System Model section to Introduction, moved main control loop description to a separate page under Design notes

* updated converter figures i_ext -> i_dc, i_dc -> i_dc'. The same change in equations and text. Notation changed to follow normal convention in the text books.

* grid filter, equation notation fixed

* U_gN -> u_gN in PLL section

* changed grid.control folder structure to simplify imports in examples, all grid converter control-related classes are now imported directly from motulator.grid.control

---------

Co-authored-by: Mikko Sarén <[email protected]>
Co-authored-by: Mikko Sarén <[email protected]>

.gitignore

@@ -11,6 +11,8 @@ __pycache__/
 # Sphinx documentation
 docs/source/_build/
 docs/source/auto_examples/
+docs/source/drive_examples/
+docs/source/grid_examples/
 docs/build/
 docs/source/autoapi/
 docs/source/sg_execution_times.rst

docs/source/conf.py

@@ -56,25 +56,24 @@
 autoapi_python_class_content = "class"  # "both"
 autoapi_keep_files = True
 autoapi_add_toctree_entry = False
+autoapi_member_order = "alphabetical"
 
 from sphinx_gallery.sorting import ExplicitOrder
 
 sphinx_gallery_conf = {
-    "examples_dirs":
-    "../../examples",  # path to your example scripts
-    "gallery_dirs":
-    "auto_examples",  # path to where to save gallery generated output
+    "examples_dirs": ["../../examples/drive", "../../examples/grid"],
+    "gallery_dirs": ["drive_examples", "grid_examples"],
     "nested_sections":
     True,
     "subsection_order":
     ExplicitOrder([
-        "../../examples/vector",
-        "../../examples/vhz",
-        "../../examples/obs_vhz",
-        "../../examples/flux_vector",
-        "../../examples/signal_inj",
-        "../../examples/grid_following",
-        "../../examples/grid_forming",
+        "../../examples/drive/vector",
+        "../../examples/drive/vhz",
+        "../../examples/drive/obs_vhz",
+        "../../examples/drive/flux_vector",
+        "../../examples/drive/signal_inj",
+        "../../examples/grid/grid_following",
+        "../../examples/grid/grid_forming",
     ]),
 }
 

docs/source/control/control_system.rst

@@ -0,0 +1,15 @@
+Control Systems
+===============
+
+Main Control Loop
+-----------------
+
+By default, the discrete-time controllers in *motulator* run the following scheme in a main control loop:
+
+   1. Get the feedback signals. This step may contain first getting the measurements and then optionally computing the observer outputs.
+   2. Compute the reference signals (controller outputs) based on the feedback signals.
+   3. Update the control system states for the next sampling instant.
+   4. Save the feedback signals and the reference signals.
+   5. Return the sampling period `T_s` and the duty ratios `d_abc` for the carrier comparison.
+
+The main control loop is implemented in the base class for control systems in :class:`motulator.common.control.ControlSystem`.

docs/source/control/current_ctrl.rst → docs/source/control/drive/current_ctrl.rst

@@ -11,7 +11,7 @@ Induction Machines
 System Model
 ^^^^^^^^^^^^
 
-The inverse-Γ model of an induction machine is considered (see :doc:`/model/machines`). Using the stator current :math:`\boldsymbol{i}_\mathrm{s}` and the rotor flux linkage :math:`\boldsymbol{\psi}_\mathrm{R}` as state variables, the model in synchronous coordinates rotating at :math:`\omega_\mathrm{s}` can be written as
+The inverse-Γ model of an induction machine is considered (see :doc:`/model/drive/machines`). Using the stator current :math:`\boldsymbol{i}_\mathrm{s}` and the rotor flux linkage :math:`\boldsymbol{\psi}_\mathrm{R}` as state variables, the model in synchronous coordinates rotating at :math:`\omega_\mathrm{s}` can be written as
 
 .. math::
     L_\sigma \frac{\mathrm{d} \boldsymbol{i}_\mathrm{s}}{\mathrm{d} t} &= \boldsymbol{u}_\mathrm{s} - (R_\sigma + \mathrm{j} \omega_\mathrm{s}L_\sigma)\boldsymbol{i}_\mathrm{s} - \underbrace{\left(\mathrm{j}\omega_\mathrm{m} - \frac{R_\mathrm{R}}{L_\mathrm{M}}\right)\boldsymbol{\psi}_\mathrm{R}}_{\text{back-emf } \boldsymbol{e}_\mathrm{s}} \\

docs/source/control/drive/index.rst

@@ -0,0 +1,13 @@
+******
+Drives
+******
+
+Design notes for selected control methods for machine drives are provided in this section. The aim of these notes is to link the implemented methods to the theory and to provide a reference for the implementation. Further details are available in the references provided. 
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 2
+
+   speed_ctrl
+   current_ctrl
+   Observers <observers>

docs/source/control/observers.rst → docs/source/control/drive/observers.rst

@@ -11,7 +11,7 @@ In the following, reduced-order observer designs for the induction machine are c
 Machine Model
 ^^^^^^^^^^^^^
 
-The inverse-Γ model of an induction machine is considered (see :doc:`/model/machines`). In a coordinate system rotating at the angular speed :math:`\omega_\mathrm{s}`, the rotor flux dynamics can be expressed using the stator and rotor quantities, respectively, as
+The inverse-Γ model of an induction machine is considered (see :doc:`/model/drive/machines`). In a coordinate system rotating at the angular speed :math:`\omega_\mathrm{s}`, the rotor flux dynamics can be expressed using the stator and rotor quantities, respectively, as
 
 .. math::
 	\frac{\mathrm{d} \boldsymbol{\psi}_\mathrm{R}}{\mathrm{d} t} + \mathrm{j}\omega_\mathrm{s}\boldsymbol{\psi}_\mathrm{R} &= \boldsymbol{u}_\mathrm{s} - R_\mathrm{s}\boldsymbol{i}_\mathrm{s} - L_\sigma \frac{\mathrm{d} \boldsymbol{i}_\mathrm{s}}{\mathrm{d} t} - \mathrm{j} \omega_\mathrm{s}L_\sigma\boldsymbol{i}_\mathrm{s} \\
@@ -154,7 +154,7 @@ In sensorless control of synchronous machine drives, the rotor position and spee
 Machine Model in General Coordinates
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-In :doc:`/model/machines`, the synchronous machine model is given in rotor coordinates. For the observer design and analysis, it is convenient to express this model in general coordinates, aligned at :math:`\vartheta_\mathrm{s}` and rotating at :math:`\omega_\mathrm{s} = \mathrm{d} \vartheta_\mathrm{s}/\mathrm{d} t` with respect to stator coordinates. Furthermore, the rotor is aligned at :math:`\vartheta_\mathrm{m}` and rotates at :math:`\omega_\mathrm{m} = \mathrm{d} \vartheta_\mathrm{m}/\mathrm{d} t` with respect to stator coordinates. This coordinate transformation results in 
+In :doc:`/model/drive/machines`, the synchronous machine model is given in rotor coordinates. For the observer design and analysis, it is convenient to express this model in general coordinates, aligned at :math:`\vartheta_\mathrm{s}` and rotating at :math:`\omega_\mathrm{s} = \mathrm{d} \vartheta_\mathrm{s}/\mathrm{d} t` with respect to stator coordinates. Furthermore, the rotor is aligned at :math:`\vartheta_\mathrm{m}` and rotates at :math:`\omega_\mathrm{m} = \mathrm{d} \vartheta_\mathrm{m}/\mathrm{d} t` with respect to stator coordinates. This coordinate transformation results in 
 
 .. math::
     \frac{\mathrm{d}\boldsymbol{\psi}_\mathrm{s}}{\mathrm{d} t} &= \boldsymbol{u}_\mathrm{s} - R_\mathrm{s}\boldsymbol{i}_\mathrm{s} - \mathrm{j}\omega_\mathrm{s}\boldsymbol{\psi}_\mathrm{s} \\