Chore - Pre-commit (#160)

* chore: add pre-commit

* chore: add read permission to gh actions

* chore: apply pre-commit

* chore: add pre-commit CI

.github/workflows/pre-commit.yml

@@ -0,0 +1,20 @@
+name: Pre-commit
+
+on:
+  push:
+
+permissions:
+  contents: read
+
+jobs:
+  pre-commit:
+    name: Run pre-commit
+    runs-on: ubuntu-22.04
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - uses: pre-commit/action@v3.0.1
+        with:
+          extra_args: --all-files

.github/workflows/pull_request.yml

@@ -2,6 +2,9 @@ name: Check docs on pull request
 
 on: [pull_request]
 
+permissions:
+  contents: read
+
 jobs:
   build:
     runs-on: ubuntu-latest # Easy to use GitHub hosted runner, self hosted runner would require manual configurations
@@ -17,4 +20,3 @@ jobs:
       with:
         name: DocumentationHTML
         path: docs/_build
-

.github/workflows/update_gh-pages.yml

@@ -5,6 +5,9 @@ on:
   push:
     branches: [main]
 
+permissions:
+  contents: read
+
 jobs:
   build-doc:
     runs-on: ubuntu-latest # Easy to use GitHub hosted runner, self hosted runner would require manual configurations

.pre-commit-config.yaml

@@ -0,0 +1,77 @@
+repos:
+
+  # Checkov
+  - repo: https://github.com/bridgecrewio/checkov
+    rev: 3.2.245
+    hooks:
+      - id: checkov
+        name: checkov
+        description: "Static code analysis for security and compliance"
+        files: .+
+        verbose: false
+
+  # Pip Audit
+  - repo: https://github.com/pypa/pip-audit
+    rev: v2.7.3
+    hooks:
+    - id: pip-audit
+      name: pip-audit
+      description: "Audits Python environments and dependency trees for known vulnerabilities"
+      entry: pip-audit
+      pass_filenames: false
+      language: python
+
+  # Generic
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: end-of-file-fixer
+        name: fix end of files
+        description: "Ensures that a file is either empty, or ends with one newline"
+        entry: end-of-file-fixer
+        types: [ text ]
+        stages: [ commit, push, manual ]
+        language: python
+
+      - id: trailing-whitespace
+        name: trim trailing whitespace
+        description: "Trims trailing whitespace"
+        entry: trailing-whitespace-fixer
+        types: [ text ]
+        stages: [ commit ]
+        language: python
+
+  # TOML
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: check-toml
+        name: check toml
+        description: "Checks .toml files for parseable syntax"
+        entry: check-toml
+        types: [toml]
+        language: python
+
+  # YAML
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: check-yaml
+        name: check yaml
+        description: "Checks .yaml files for parseable syntax"
+        entry: check-yaml
+        types: [ yaml ]
+        language: python
+
+  # YAPF
+  - repo: https://github.com/google/yapf
+    rev: v0.40.2
+    hooks:
+      - id: yapf
+        name: yapf
+        description: "A formatter for Python files"
+        entry: yapf
+        args: [ -i ] # inplace
+        language: python
+        types: [ python ]
+        additional_dependencies: [ toml ]

.vscode/extensions.json

@@ -5,4 +5,4 @@
         "eeyore.yapf",
         "streetsidesoftware.code-spell-checker",
     ]
-}
+}

.vscode/settings.json

@@ -16,4 +16,4 @@
         "docs/*"
     ],
     "esbonio.sphinx.confDir": "${workspaceFolder}/docs/source"
-}
+}

README.md

@@ -7,15 +7,15 @@
 
 Introduction
 ------------
-This open-source software includes simulation models and controllers for electric machine drives and grid converter systems. The machine models include an induction machine, a synchronous reluctance machine, and a permanent-magnet synchronous machine. Various subsystem models are provided for modeling grid converter systems, such as an LCL filter connected to an inductive-resistive grid. 
+This open-source software includes simulation models and controllers for electric machine drives and grid converter systems. The machine models include an induction machine, a synchronous reluctance machine, and a permanent-magnet synchronous machine. Various subsystem models are provided for modeling grid converter systems, such as an LCL filter connected to an inductive-resistive grid.
 
 The system models are simulated in the continuous-time domain while the control algorithms run in discrete time. The default solver is the explicit Runge-Kutta method of order 5(4) from scipy.integrate.solve_ivp. Various control algorithms are provided as examples. The documentation is available here:
 
 https://aalto-electric-drives.github.io/motulator/
 
 Installation
 ------------
-This software can be installed using pip: 
+This software can be installed using pip:
 
 ```bash
 pip install motulator

docs/.nojekyll

@@ -1 +0,0 @@
-

docs/source/contributing.rst

@@ -4,16 +4,16 @@ Contributing
 Style Guide
 -----------
 
-We follow the `Style Guide for Python Code PEP8 <https://peps.python.org/pep-0008/>`_. Furthermore, we use the `YAPF Python code formatter <https://github.com/google/yapf>`_, configured based on the PEP8 conventions in the ``pyproject.toml`` file. Public methods and classes should have proper `docstrings <https://peps.python.org/pep-0257/>`_, formatted according to the `NumPy docstring guide <https://numpydoc.readthedocs.io/en/latest/format.html>`_. 
+We follow the `Style Guide for Python Code PEP8 <https://peps.python.org/pep-0008/>`_. Furthermore, we use the `YAPF Python code formatter <https://github.com/google/yapf>`_, configured based on the PEP8 conventions in the ``pyproject.toml`` file. Public methods and classes should have proper `docstrings <https://peps.python.org/pep-0257/>`_, formatted according to the `NumPy docstring guide <https://numpydoc.readthedocs.io/en/latest/format.html>`_.
 
-`Sphinx <https://www.sphinx-doc.org>`_ is used to auto-generate documentation. We use `Sphinx-Gallery <https://sphinx-gallery.github.io/stable/index.html>`_ to automatically generate the `examples <https://aalto-electric-drives.github.io/motulator/drive_examples/index.html>`_ from the scripts in the ``examples`` folder. The format of the example scripts is essential for their proper rendering in the documentation (see the existing example scripts). 
+`Sphinx <https://www.sphinx-doc.org>`_ is used to auto-generate documentation. We use `Sphinx-Gallery <https://sphinx-gallery.github.io/stable/index.html>`_ to automatically generate the `examples <https://aalto-electric-drives.github.io/motulator/drive_examples/index.html>`_ from the scripts in the ``examples`` folder. The format of the example scripts is essential for their proper rendering in the documentation (see the existing example scripts).
 
 Install Optional Dependencies
 -----------------------------
 
 We recommend to install the ``dev`` dependencies (see also :doc:`/installation`). To enable YAPF in VS Code, you can install the `YAPF extension <https://marketplace.visualstudio.com/items?itemName=eeyore.yapf>`_. This extension will automatically format the code according when you save the file.
 
-If you aim to work with the documentation, install also the ``doc`` dependencies. For previewing the documentation in VS Code, you can install the `Esbonio extension <https://marketplace.visualstudio.com/items?itemName=swyddfa.esbonio>`_. Alternatively, you can build the documentation locally using the command ``make html`` in the ``docs`` directory. The documentation will be built in the ``docs/build`` directory. 
+If you aim to work with the documentation, install also the ``doc`` dependencies. For previewing the documentation in VS Code, you can install the `Esbonio extension <https://marketplace.visualstudio.com/items?itemName=swyddfa.esbonio>`_. Alternatively, you can build the documentation locally using the command ``make html`` in the ``docs`` directory. The documentation will be built in the ``docs/build`` directory.
 
 
 Submitting a Bug Report or a Feature Request
@@ -23,7 +23,7 @@ If you have found bugs or have feature requests, please submit them to the `issu
 
 - Name and version of your operating system.
 - Any relevant details about your local setup, such as the Python interpreter version and installed libraries.
-- A short reproducible code snippet, so that anyone can reproduce the bug easily. 
+- A short reproducible code snippet, so that anyone can reproduce the bug easily.
 - Try to be specific about what functions are involved and the shape of the data, especially when including a code snippet is not feasible.
 - Provide the full traceback to any exceptions that were raised.
 
@@ -39,4 +39,4 @@ When contributing code, please follow this workflow:
 
 Once a pull request has been created, it will be reviewed, and changes might be suggested, which you can make by simply adding new commits to your branch. After the successful review, we will merge your changes into the main repository.
 
-We aim to keep the codebase clean and maintainable. Therefore, we may not be able to accept all contributions (even if they are well-written and feasible). For this reason, it is advisable to discuss possible contributions beforehand in an issue.
+We aim to keep the codebase clean and maintainable. Therefore, we may not be able to accept all contributions (even if they are well-written and feasible). For this reason, it is advisable to discuss possible contributions beforehand in an issue.

docs/source/control/control_system.rst

@@ -4,34 +4,34 @@ Common
 Data Flow
 ---------
 
-The two figures below show the structure and data flow in a typical simulation model as well as an example of the internal structure of a discrete-time control system. The text in italics refers to the default object names used in the software. In discrete-time control systems, the signals are collected into the following :class:`types.SimpleNamespace` objects: 
+The two figures below show the structure and data flow in a typical simulation model as well as an example of the internal structure of a discrete-time control system. The text in italics refers to the default object names used in the software. In discrete-time control systems, the signals are collected into the following :class:`types.SimpleNamespace` objects:
 
-- The object `fbk` contains feedback signals for the controllers. These signals can be measured quantities (such as the measured DC-bus voltage `fbk.u_dc`) as well as estimated quantities (such as the estimated stator flux linkage `fbk.psi_s`). 
+- The object `fbk` contains feedback signals for the controllers. These signals can be measured quantities (such as the measured DC-bus voltage `fbk.u_dc`) as well as estimated quantities (such as the estimated stator flux linkage `fbk.psi_s`).
 
-- The object `ref` contains the reference signals, both externally provided (such as `ref.w_m` for the angular speed reference) and internally generated (such as `ref.d_c_abc` for the duty ratios). 
+- The object `ref` contains the reference signals, both externally provided (such as `ref.w_m` for the angular speed reference) and internally generated (such as `ref.d_c_abc` for the duty ratios).
 
 These objects `fbk` and `ref` may propagate through several blocks (implemented as classes in the software), which may add new signals or modify the existing one. At the end of their propagation chain, both objects `fbk` and `ref` are saved to the lists. Therefore, the most relevant internal signals of the control system are directly accessible after the simulation. Furthermore, the states and inputs of the continuous-time system model are also saved. In the post-processing stage, the saved data is converted to the NumPy arrays.
 
 .. figure:: figs/overall_system.svg
    :width: 100%
    :align: center
    :alt: Block diagram of the control system.
-   
-   Block diagram illustrating the structure and data flow in a typical simulation model. The lower part of the figure illustrates how the data is saved. The post-processing is done after the simulation. The internal structure of a typical control system is exemplified in the figure below. 
+
+   Block diagram illustrating the structure and data flow in a typical simulation model. The lower part of the figure illustrates how the data is saved. The post-processing is done after the simulation. The internal structure of a typical control system is exemplified in the figure below.
 
 .. figure:: figs/discrete_control_system.svg
    :width: 100%
    :align: center
    :alt: Block diagram of the control system.
-   
-   Block diagram exemplifying the internal structure of a typical cascade control system. The object `ref` at the control system output should contain the sampling period `T_s` and the converter duty ratios `d_c_abc` for the carrier comparison. The observer does not necessarily exist in all control systems (or it can be replaced with, e.g., a phase-locked loop). 
+
+   Block diagram exemplifying the internal structure of a typical cascade control system. The object `ref` at the control system output should contain the sampling period `T_s` and the converter duty ratios `d_c_abc` for the carrier comparison. The observer does not necessarily exist in all control systems (or it can be replaced with, e.g., a phase-locked loop).
 
 Main Control Loop
 -----------------
 
 A template for the main control loop is available in the base class for discrete-time control systems in :class:`motulator.common.control.ControlSystem`. The main control loop in this template has the following steps:
 
-1. Get the feedback signals `fbk` for the controllers from the outputs of the continuous-time system model `mdl`. This step may contain first getting the measurements and then optionally computing the observer outputs (or otherwise manipulating the measured signals).  
+1. Get the feedback signals `fbk` for the controllers from the outputs of the continuous-time system model `mdl`. This step may contain first getting the measurements and then optionally computing the observer outputs (or otherwise manipulating the measured signals).
 2. Get the reference signals `ref` and compute the controller outputs based on the feedback signals `fbk`. Cascade control systems may contain multiple controllers, where the output of the outer controller is the reference signal for the inner controller.
 3. Update the states of the control system for the next sampling instant.
 4. Save the feedback signals `fbk` and the reference signals `ref` so they can be accessed after the simulation.
@@ -54,14 +54,14 @@ The figure below shows a 2DOF PI controller with an optional feedforward term. I
    u &= k_\mathrm{t}r - k_\mathrm{p}y + u_\mathrm{i} + u_\mathrm{ff}
    :label: 2dof_pi
 
-where :math:`r` is the reference signal, :math:`y` is the measured (or estimated) feedback signal, :math:`u_\mathrm{i}` is the the integral state, and :math:`u_\mathrm{ff}` is the optional feedforward signal. Furthermore, :math:`k_\mathrm{t}` is the reference-feedforward gain, :math:`k_\mathrm{p}` is the proportional gain, and :math:`k_\mathrm{i}` is the integral gain. Setting :math:`k_\mathrm{t} = k_\mathrm{p}` and :math:`u_\mathrm{ff} = 0` results in the standard PI controller. This 2DOF PI controller can also be understood as a state-feedback controller with integral action and reference feedforward [#Fra1997]_. 
+where :math:`r` is the reference signal, :math:`y` is the measured (or estimated) feedback signal, :math:`u_\mathrm{i}` is the the integral state, and :math:`u_\mathrm{ff}` is the optional feedforward signal. Furthermore, :math:`k_\mathrm{t}` is the reference-feedforward gain, :math:`k_\mathrm{p}` is the proportional gain, and :math:`k_\mathrm{i}` is the integral gain. Setting :math:`k_\mathrm{t} = k_\mathrm{p}` and :math:`u_\mathrm{ff} = 0` results in the standard PI controller. This 2DOF PI controller can also be understood as a state-feedback controller with integral action and reference feedforward [#Fra1997]_.
 
 .. figure:: figs/2dof_pi.svg
    :width: 100%
    :align: center
    :alt: 2DOF PI controller.
 
-   2DOF PI controller with an optional feedforward term. The operator :math:`1/s` refers to integration. A discrete-time variant of this controller with the integrator anti-windup is implemented in the :class:`motulator.common.control.PIController` class.  
+   2DOF PI controller with an optional feedforward term. The operator :math:`1/s` refers to integration. A discrete-time variant of this controller with the integrator anti-windup is implemented in the :class:`motulator.common.control.PIController` class.
 
 Disturbance-Observer Structure
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -71,7 +71,7 @@ The controller :eq:`2dof_pi` can be equally represented using the disturbance-ob
 .. math::
 	\frac{\mathrm{d} u_\mathrm{i}}{\mathrm{d} t} &= \alpha_\mathrm{i}\left(u - \hat v\right) \\
    \hat v &= u_\mathrm{i} - (k_\mathrm{p} - k_\mathrm{t})y + u_\mathrm{ff} \\
-   u &= k_\mathrm{t}\left(r - y\right) + \hat v 
+   u &= k_\mathrm{t}\left(r - y\right) + \hat v
    :label: 2dof_pi_disturbance_observer
 
 where :math:`\alpha_\mathrm{i} = k_\mathrm{i}/k_\mathrm{t}` is the redefined integral gain and :math:`\hat v` is the input-equivalent disturbance estimate. This structure is convenient to prevent the integral windup that originates from the actuator saturation [#Fra1997]_. The actuator output is limited in practice due to physical constraints. Consequently, the realized actuator output is
@@ -85,7 +85,7 @@ where :math:`\mathrm{sat}(\cdot)` is the saturation function. If this saturation
 	\frac{\mathrm{d} u_\mathrm{i}}{\mathrm{d} t} = \alpha_\mathrm{i}\left(\bar{u} - \hat v \right)
    :label: anti_windup
 
-The other parts of the above controller are not affected by the saturation. 
+The other parts of the above controller are not affected by the saturation.
 
 Discrete-Time Algorithm
 ^^^^^^^^^^^^^^^^^^^^^^^
@@ -99,7 +99,7 @@ The discrete-time variant of the controller :eq:`2dof_pi_disturbance_observer` w
    \bar{u}(k) &= \mathrm{sat}[u(k)]
    :label: discrete_2dof_pi
 
-where :math:`T_\mathrm{s}` is the sampling period and :math:`k` is the discrete-time index. This algorithm corresponds to the actual implementation in the :class:`motulator.common.control.PIController` class. 
+where :math:`T_\mathrm{s}` is the sampling period and :math:`k` is the discrete-time index. This algorithm corresponds to the actual implementation in the :class:`motulator.common.control.PIController` class.
 
 .. _complex-vector-2dof-pi-controller:
 
@@ -113,7 +113,7 @@ As shown in the figure below, the 2DOF PI controller presented above can be exte
     \boldsymbol{u} &= \boldsymbol{k}_\mathrm{t}\boldsymbol{r} - \boldsymbol{k}_\mathrm{p}\boldsymbol{y} + \boldsymbol{u}_\mathrm{i} + \boldsymbol{u}_\mathrm{ff}
     :label: complex_vector_2dof_pi
 
-where :math:`\boldsymbol{u}` is the output of the controller, :math:`\boldsymbol{r}` is the reference signal, :math:`\boldsymbol{u}_\mathrm{i}` is the the integral state, and :math:`\boldsymbol{u}_\mathrm{ff}` is the optional feedforward signal. Furthermore, :math:`\boldsymbol{k}_\mathrm{t}` is the reference-feedforward gain, :math:`\boldsymbol{k}_\mathrm{p}` is the proportional gain, and :math:`\boldsymbol{k}_\mathrm{i}` is the integral gain. 
+where :math:`\boldsymbol{u}` is the output of the controller, :math:`\boldsymbol{r}` is the reference signal, :math:`\boldsymbol{u}_\mathrm{i}` is the the integral state, and :math:`\boldsymbol{u}_\mathrm{ff}` is the optional feedforward signal. Furthermore, :math:`\boldsymbol{k}_\mathrm{t}` is the reference-feedforward gain, :math:`\boldsymbol{k}_\mathrm{p}` is the proportional gain, and :math:`\boldsymbol{k}_\mathrm{i}` is the integral gain.
 
 .. figure:: figs/complex_vector_2dof_pi.svg
    :width: 100%
@@ -131,5 +131,3 @@ The discrete-time implementation of :eq:`complex_vector_2dof_pi` with the anti-w
 .. [#Fra1997] Franklin, Powell, Workman, "Digital Control of Dynamic Systems," 3rd ed., Menlo Park, CA: Addison-Wesley, 1997
 
 .. [#Bri1999] Briz del Blanco, Degner, Lorenz, “Dynamic analysis of current regulators for AC motors using complex vectors,” IEEE Trans.Ind. Appl., 1999, https://doi.org/10.1109/28.806058
-
-