Refactoring of simple_controllers.py

[wallscheid]

The mentioned file contains basic, expert-driven feedback controllers for different motors. The file and its classes have historically evolved and require a major revision. Main issues are:

• in-code and API documentation is only very little. More detailed explanations required.
• a well-defined class structure and an allocation to the available motors is missing. For example the class "CascadedPI-Controller" is mentioned here, which can be applied de facto only to DC motors, but from the name definition it can be assumed that a general controller for different motors can be found here.
  • It would be good to derive specific controllers for individual motor/inverter/action-space classes or similar control tasks on the basis of generally valid basic controller definitions, as they already exist in some cases. In the end, it should in any case be clear which controller class can be used for which control problem (current, speed, ...) with which motor/inverter type.
• The controllers with integral action are missing anti reset-windup measures to ensure proper operation when their output is saturated.
• Feed forward compensation measures such as dq decoupling for three-phase motors or also induced voltage compensation for DC-motors is missing. Could be integrated as own classes which can be turned on and off by the user as a selectable controller features.
• Also the voltage reference conversion from dq to phase (abc/rst) coordinates is lacking a zero voltage injection / third harmonic injection in order to fully utilize the inverter voltage.

[wkirgsn]

• no consistent signatures among controllers
• alternating application of numpy and math std package
  • multi-reference control not possible and efficiency loss is a consequence
• Controllers receive full environment during init but do not use it to make assumptions about referenced states if none are given

[wallscheid]

Additional remark: ideally the controller parameter tuning is done with respect to some standard tuning procedure (e.g. symmetrical or magnitude optimum) which would of course require that the controller class is able to access the motor parameter vector. Currently, the default values of the controller parameter/gains are just arbitrary numbers which won't provide any suitable control performance (unless one is really lucky). With the above extension we would provide the user a simple and robust out-of-the-box tuning procedure which will garantuee decent controller performance under normal operation conditions.

[RohithCharanD]

FOC Controller seems to be implemented with incompatibilty

[RohithCharanD]

Summary of tasks implemented in Sprint -1 . Git Branch: issue_21

• detailed Documentation was added.
• Addition of dq decoupling and zero voltage injection for 3 phase motors.
• Addition of Voltage compensation for DC motors.
• Integral windup reset added for Integral controllers.
• Classes of controllerers were renamed and assert statements were added to let the user know which controller is suitable for which motor.

[GitPascalP]

@RohithCharanD I have a few remarks to the refactoring (if I misunderstood something, please correct me):

• maybe for continuation adding a comment for explicit use cases (which motors can be used) for PmsmOnOff, SynRmOnOffController, PmsmPController, ThreePhaseSteadyState (like for the other controller)

• maybe too picky: a more detailed comment to 3PhaseSteadyState: what should come out, use case. The functionality of the Controller is described very well.

• assert message for -- DCCascadedPIController (line 193) -- FOCController(line 389) (is Induction here also possible?) when env is wrong

General for future-updates eventually creating more examples for synchronous or induction motors is useful.

[wallscheid]

I'm afraid the commit for this sprint requres major revision. I've added already quite a few specific comments to the different commits - please review them.

Moreover, besides that what is completely missing:

• Test cases for the implemented controller additions -> the examples are more or less using the old controller definitions and did not have been extended e.g. PMSM-FOC with PI controllers for the current.
• Automatic controller tuning based on standard LTI guideline (e.g. symetric/magnitude optimum) for the standard PID-type controllers are missing.

[wallscheid]

For the 2nd sprint phase, the focus should initially be on a general modularization of controllers in classes derived from each other. An example of this is the introduction of a general P-controller and a general I-controller, which in turn can be combined in a common PI-controller class. The primary objective of the controller definitions should be to define a small number of basic and general controllers, which can be used for as many applications as possible. With a view to the above example of the PI controller: This can serve as a class for the current control of a DC motor, but can also be used just as well for field-oriented current control in a PMSM (whereby two controllers are then even required in parallel for the d and q current).

Again derived from this, a general modularization should also be introduced for cascaded controls. At present, a special cascaded controller (e.g. internal current control and external speed control) would have to be set up manually for each motor, so that later quite a number of individual controllers with basically similar functions would exist side by side. This must be avoided at all costs, e.g. by introducing a general class 'CascadedController', where the user can select (within technically reasonable limits) what the inner and outer control loops have for tasks and how these are parameterized.

Based on this basic modularization, the two DC motor examples (perm_dc_omega.py, pi_series_omega_control.py) are to be updated and revised. In the pi_series_omega_control.py example, two controller arrangements are to be compared with each other, one with the previous status that only the speed is controlled without an internal current controller (which is expected to lead to frequent overcurrent errors) and one with cascaded internal current control included. The respective PI-controllers in this example should be designed according to the symmetrical optimum with adjustable tuning parameter 'a', see chapter 9.3 in the following teaching script https://ei.uni-paderborn.de/fileadmin/elektrotechnik/fg/lea/Lehre/MEA/Dokumente/Skript_Mechatronik_DE_EN.pdf

In the final stage of this sprint, a general controller class for field-oriented control of three-phase motors is to be developed, which from the controller's point of view contains the necessary coordinate transformations. The superordinate class is to be defined as general as possible so that controls for PMSM, SynRM or IM can be derived from it. In addition, another class 'VoltageManipulation' including a sub-class '2-level ZeroShift' is to be programmed, which shifts the required nominal voltage in the abc-coordinate system for a 2-level inverter in such a way that the inverter uses the entire voltage hexagon under the assumption of a regular PWM/SVM. This zero shift is to be modularized and decoupled from the own FOC implementation, because at a later point in time further inverters (3-LEvel, Multi-Level, ...) can be added to the toolbox, which require a different kind of voltage manipulation in order to make the best possible use of the respective voltage range.

Finally, a PMSM-FOC with current control will be set up and its use will be illustrated in a user example. As an optional goal, a supplementary example with higher-level speed control is to be set up.

Please also directly contribute appropiate unit tests to the different controller (sub-)classes.

[wallscheid]

In the following you can find a simplifed UML class diagram in order to highlight a possible inheritance structure.

Based on the standard continuous and discrete action-type controller we should be able to build up also more sophisticated controller classes like cascaded controllers with intermixing of different controller types for the inner and outer control loop or FOC-based approaches for three-phase drives.

[wkirgsn]

This issue was dealt with in #136