Update documentation, reorganize example scripts

.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/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,15 @@
+******
+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>
+
+This section will be extended in the future.

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} \\