Motulator

What's Changed

This release contains several additions and improvements. This is the first release of *motulator*, in which grid converter models and controls are included (merged from *gritulator*). The most significant changes are:

* Merge and rewrite grid converter system models, controls, and utilities from gritulator (e.g., 136 and many other PRs since that)
* Major update in the documentation (e.g., 148, 152, 154, 155, 165, 167)
* Major refactoring the system models to a more modular form (128)
* Add torque-control mode (133)
* Flux-vector control for induction machines (137)

**Full Changelog**: https://github.com/Aalto-Electric-Drives/motulator/compare/v0.3.0...v0.5.0

What's Changed

* The control package has been refactored (122), aiming to make it more modular. A new base class DriveCtrl(Ctrl) has been added. This adds common basic methods needed in different control systems for electric machine drives. This class supports both speed-control and torque-control modes.
* The system models have been refactored (128). The handling of the state variables, inputs, and outputs is changed so that the subsystems are now more modular. Furthermore, main-level system models are simpler and their amount is reduced significantly. The subsystems contain set_outputs() and rhs() methods, which are called by the main-level system model, whose base class is Model(ABC). The basic drive model is Drive(Model), which contains the interconnections of the subsystems in the interconnect() method. The same Drive class can now be used with both induction and synchronous machines (as well as with a diode bridge model, two-mass mechanics or other subsystems where the interconnections remain the same).
* The folder and import structure has been refactored to a more modular form (130). This makes it easier to add new system types later.
* Data classes are used to parametrize the machine models, both the system model and the parameter estimates in the control system (131). This change allows simpler parametrization in a typical use case of accurate parameter estimates. Furthermore, it clarifies the documentation clearer since the expected parameters are more accurately specified through data classes.
* The ExternalRotorSpeed class has been added to the mechanics module (133). This allows to simulate drive systems in torque-control mode. One example simulation script has also been added. Furthermore, the parameters of the TwoMassMechanicalSystem class are now provided through the data class.
* In addition to the above, this release contains various other minor improvements.

**Full Changelog**: https://github.com/Aalto-Electric-Drives/motulator/compare/v0.2.0...v0.3.0

This release has several new features, including:

- A nonlinear analytical saturation model suitable for PM-SyRMs has been added to the example (112). Also the experimental flux map data is available for the 5.5-kW PM-SyRM.
- A drive system class with a diode bridge now available also for synchronous machine drives (115).
- A model for an LC output filter is added (116).
- PM-flux disturbance estimation has been added to sensorless control (119).

Furthermore, the code has been refactored, build configuration has been revised, and documentation and docstrings have been improved.

Changes in this release:

- A full-order observer for induction motor added.
- Observers were moved to separate files (im._observers.py and sm._observers.py).
- Some minor bug fixes in the documentation.

This release contains a few minor fixes and improvements:

- Add the path to the saturation date file in an example script 'motulator/examples/obs_vhz/plot_obs_vhz_ctrl_pmsyrm_thor.py'. This addition allows to run the script from other folders.
- Initialization of the PICtrl and ComplexPICtrl classes was fixed: if the reference feedforward gain `k_t` is not provided as a parameter, `k_t = k_p` is used, resulting in the regular 1DOF PI controller. This fix simplifies the usage of these classes as regular PI controllers. See also the added comment in the example script 'motulator/examples/vector/plot_vector_ctrl_im_2kw.py'. For further details regarding the structure of these controllers, see their docstrings as well as the design notes (https://aalto-electric-drives.github.io/motulator/control/speed_ctrl.html).
- Minor improvements in the dosctrings and examples.

This release contains numerous improvements and new features. The most important ones are listed below:

1. The public API was cleaned. The docstrings and the documentation pages were improved. Examples scripts were simplified and reorganized. The naming of instances and classes was also improved by avoiding unnecessary abbreviations as well as avoiding repetition of from the upper hierarchy level.
2. A 2DOF speed controller was refactored and the design notes were added to the documentation. As a special case, the controller can be parametrized as a standard PI controller.
3. A 2DOF PI current controller was refactored and the design notes were added to the documentation. Now, the same base class can be used for both synchronous and asynchronous machines. As a special case, the controller can be parametrized as a standard PI controller.
4. The default machine parameters were removed from the system models and as well as from the control algorithms. Instead, this data is now provided in the example scripts. This change is expected to reduce the risk of user errors.
5. Saturation models were simplified and generalized. The SynchronousMotorSaturated class can be now used with both analytical saturation models and look-up tables. The detailed examples of how to parametrize saturated motor models were moved to the example scripts.
6. To reduce overlapping code, sensored observers were merged with sensorless observers. Design notes were added to the documentation.