Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refactor the folder and import structure #130

Merged
merged 3 commits into from
Jun 7, 2024
Merged

Refactor the folder and import structure #130

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4a78ebc
Minor fixes in docs
mhinkkan Jun 5, 2024
b639ad1
New folder and import structure
mhinkkan Jun 6, 2024
ec04fe6
Refactor the folder and import structure
mhinkkan Jun 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/source/control/current_ctrl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -159,7 +159,7 @@ where :math:`\mathrm{sat}(\cdot)` is the saturation function. The limited voltag
.. math::
\frac{\mathrm{d} \boldsymbol{u}_\mathrm{i}}{\mathrm{d} t} = \boldsymbol{\alpha}_\mathrm{i}\left(\bar{\boldsymbol{u}}_\mathrm{s,ref} - \hat{\boldsymbol{v}}_\mathrm{s}\right)

The other parts of the above controller are not affected by the saturation. The implementation in the :class:`motulator.control.ComplexPICtrl` class is based on this disturbance-observer form.
The other parts of the above controller are not affected by the saturation. The implementation in the :class:`motulator.common.control.ComplexPICtrl` class is based on this disturbance-observer form.

Synchronous Machines
--------------------
Expand All @@ -184,7 +184,7 @@ The discrete-time variant of the disturbance-observer form :eq:`cc_disturbance`
\boldsymbol{u}_\mathrm{s,ref}(k) &= \boldsymbol{k}_\mathrm{t}\left[\boldsymbol{\psi}_{\mathrm{ref}}(k) - \hat{\boldsymbol{\psi}}(k)\right] + \hat{\boldsymbol{v}}_\mathrm{s} \\
\bar{\boldsymbol{u}}_\mathrm{s,ref}(k) &= \mathrm{sat}\left[\boldsymbol{u}_\mathrm{s,ref}(k)\right]

where :math:`T_\mathrm{s}` is the sampling period and :math:`k` is the discrete-time index. Depending on the machine type, either :eq:`flux_mapping_im` or :eq:`flux_mapping_sm` is used to map the stator current to the flux linkage. This discrete-time algorithm corresponds to the implementation in the :class:`motulator.control.sm.CurrentCtrl` class. The default gain selection corresponds to the complex-vector gains in :eq:`complex_vector_gains_flux`.
where :math:`T_\mathrm{s}` is the sampling period and :math:`k` is the discrete-time index. Depending on the machine type, either :eq:`flux_mapping_im` or :eq:`flux_mapping_sm` is used to map the stator current to the flux linkage. This discrete-time algorithm corresponds to the implementation in the :class:`motulator.drive.control.sm.CurrentCtrl` class. The default gain selection corresponds to the complex-vector gains in :eq:`complex_vector_gains_flux`.

.. rubric:: References

Expand Down
10 changes: 5 additions & 5 deletions docs/source/control/observers.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ An observer is commonly used to estimate the state of an electrical machine. In
Induction Machines
------------------

In the following, reduced-order observer designs for the induction machine are considered [#Ver1988]_, [#Har2001]_, [#Hin2010]_. Both sensored and sensorless observer variants are available in the :class:`motulator.control.im.Observer` class. Similar design principles are applied to synchronous machines as well.
In the following, reduced-order observer designs for the induction machine are considered [#Ver1988]_, [#Har2001]_, [#Hin2010]_. Both sensored and sensorless observer variants are available in the :class:`motulator.drive.control.im.Observer` class. Similar design principles are applied to synchronous machines as well.

Machine Model
^^^^^^^^^^^^^
Expand Down Expand Up @@ -74,7 +74,7 @@ The flux magnitude dynamics are
= \mathrm{Re}\{ \boldsymbol{v} + \boldsymbol{k}_1(\hat{\boldsymbol{v}} - \boldsymbol{v}) + \boldsymbol{k}_2(\hat{\boldsymbol{v}} - \boldsymbol{v})^* \}
:label: dhatpsiR_abs

Notice that the right-hand side of :eq:`hatws` is independent of :math:`\omega_\mathrm{s}`. Futhermore, in these coordinates, the condition :eq:`inherently` for an inherently sensorless observer reduces to :math:`\boldsymbol{k}_2 = \boldsymbol{k}_1`. This observer structure is implemented in the :class:`motulator.control.im.Observer`, where simple forward-Euler discretization is used.
Notice that the right-hand side of :eq:`hatws` is independent of :math:`\omega_\mathrm{s}`. Futhermore, in these coordinates, the condition :eq:`inherently` for an inherently sensorless observer reduces to :math:`\boldsymbol{k}_2 = \boldsymbol{k}_1`. This observer structure is implemented in the :class:`motulator.drive.control.im.Observer`, where simple forward-Euler discretization is used.

Gain Selection
^^^^^^^^^^^^^^
Expand Down Expand Up @@ -148,7 +148,7 @@ which results in the characteristic polynomial :math:`D(s)=s^2 + 2\sigma s + \om
Synchronous Machines
--------------------

In sensorless control of synchronous machine drives, the rotor position and speed estimates are needed [#Jon1989]_, [#Cap2001]_, [#Hin2018]_. As a side product, the stator flux linkage is also estimated. In the following, an observer design available in the :class:`motulator.control.sm.Observer` class is considered, which is based on [#Hin2018]_. This observer implementation also includes a sensored mode.
In sensorless control of synchronous machine drives, the rotor position and speed estimates are needed [#Jon1989]_, [#Cap2001]_, [#Hin2018]_. As a side product, the stator flux linkage is also estimated. In the following, an observer design available in the :class:`motulator.drive.control.sm.Observer` class is considered, which is based on [#Hin2018]_. This observer implementation also includes a sensored mode.


Machine Model in General Coordinates
Expand Down Expand Up @@ -197,7 +197,7 @@ In the sensored mode, :math:`\omega_\mathrm{s} = \omega_\mathrm{m}` is used. In
\frac{\mathrm{d}\hat{\vartheta}_\mathrm{m}}{\mathrm{d} t} &= \hat{\omega}_\mathrm{m} + \mathrm{Im}\{\boldsymbol{k}_\mathrm{p} \boldsymbol{e}\} = \omega_\mathrm{s}
:label: sm_speed_pos_observer

where :math:`\boldsymbol{k}_\mathrm{i}` and :math:`\boldsymbol{k}_\mathrm{p}` are complex gains. This observer structure is used in the :class:`motulator.control.sm.Observer` class.
where :math:`\boldsymbol{k}_\mathrm{i}` and :math:`\boldsymbol{k}_\mathrm{p}` are complex gains. This observer structure is used in the :class:`motulator.drive.control.sm.Observer` class.

.. note::
Real-valued column vectors and the corresponding :math:`2\times 2` gain matrix were used in [#Hin2018]_. The complex form in :eq:`sm_flux_observer` has the same degrees of freedom.
Expand All @@ -218,7 +218,7 @@ In the sensored case, the gain :math:`\boldsymbol{k}_2=0` can be set in :eq:`sm_
\frac{\mathrm{d} \Delta\tilde{\boldsymbol{\psi}}_\mathrm{s}}{\mathrm{d} t} = -(\boldsymbol{k}_1 + \mathrm{j}\omega_\mathrm{m0})\Delta\tilde{\boldsymbol{\psi}}_\mathrm{s}
:label: dtildepsis_sensored

where :math:`\tilde{\boldsymbol{\psi}}_\mathrm{s} = \boldsymbol{\psi}_\mathrm{s} - \hat{\boldsymbol{\psi}}_\mathrm{s}` is the estimation error, :math:`\Delta` marks the small-signal quantities, and the subscript 0 marks the operating-point quantities. It can be seen that the pole can be arbitrarily placed via the gain :math:`\boldsymbol{k}_1`. Well-damped estimation-error dynamics can be obtained simply by using a real gain, :math:`\boldsymbol{k}_1 = \sigma`, resulting in the pole at :math:`s = -\sigma - \mathrm{j}\omega_\mathrm{m0}`, where :math:`\sigma = 2\pi \cdot 15` rad/s is used as the default value in :class:`motulator.control.sm.Observer`.
where :math:`\tilde{\boldsymbol{\psi}}_\mathrm{s} = \boldsymbol{\psi}_\mathrm{s} - \hat{\boldsymbol{\psi}}_\mathrm{s}` is the estimation error, :math:`\Delta` marks the small-signal quantities, and the subscript 0 marks the operating-point quantities. It can be seen that the pole can be arbitrarily placed via the gain :math:`\boldsymbol{k}_1`. Well-damped estimation-error dynamics can be obtained simply by using a real gain, :math:`\boldsymbol{k}_1 = \sigma`, resulting in the pole at :math:`s = -\sigma - \mathrm{j}\omega_\mathrm{m0}`, where :math:`\sigma = 2\pi \cdot 15` rad/s is used as the default value in :class:`motulator.drive.control.sm.Observer`.

Sensorless Case
"""""""""""""""
Expand Down
6 changes: 3 additions & 3 deletions docs/source/control/speed_ctrl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
Speed Control
=============

Proportional-integral (PI) control is widely used in machine drives. A standard one-degree-of-freedom (1DOF) PI controller manipulates only the control error, i.e., it has single input and single output. Its two-degrees-of-freedom (2DOF) variants have two inputs (reference signal and feedback signal), which allows to design disturbance rejection and reference tracking separately [#Sko1996]_. In the following, we will use a speed controller as an example, cf. the :class:`motulator.control.SpeedCtrl` class. The presented control design can be extended to many other control tasks as well.
Proportional-integral (PI) control is widely used in machine drives. A standard one-degree-of-freedom (1DOF) PI controller manipulates only the control error, i.e., it has single input and single output. Its two-degrees-of-freedom (2DOF) variants have two inputs (reference signal and feedback signal), which allows to design disturbance rejection and reference tracking separately [#Sko1996]_. In the following, we will use a speed controller as an example, cf. the :class:`motulator.drive.control.SpeedCtrl` class. The presented control design can be extended to many other control tasks as well.

Continuous-Time Design
----------------------
Expand Down Expand Up @@ -52,7 +52,7 @@ where :math:`\mathrm{sat}(\cdot)` is the saturation function. If this saturation
.. math::
\frac{\mathrm{d} \tau_\mathrm{i}}{\mathrm{d} t} = \alpha_\mathrm{i}\left(\bar{\tau}_\mathrm{M,ref} - \hat \tau_\mathrm{L}\right)

The other parts of the above controller are not affected by the saturation. The implementation in the :class:`motulator.control.SpeedCtrl` class is based on this disturbance-observer form.
The other parts of the above controller are not affected by the saturation. The implementation in the :class:`motulator.drive.control.SpeedCtrl` class is based on this disturbance-observer form.

Gain Selection Example
^^^^^^^^^^^^^^^^^^^^^^
Expand Down Expand Up @@ -94,7 +94,7 @@ The discrete-time variant of the controller is given by
\tau_\mathrm{M,ref}(k) &= k_\mathrm{t}\left[\omega_\mathrm{M,ref}(k) - \omega_\mathrm{M}(k)\right] + \hat \tau_\mathrm{L}(k) \\
\bar{\tau}_\mathrm{M,ref}(k) &= \mathrm{sat}[\tau_\mathrm{M,ref}(k)]

where :math:`T_\mathrm{s}` is the sampling period and :math:`k` is the discrete-time index. This corresponds to the implementation in the :class:`motulator.control.SpeedCtrl` class.
where :math:`T_\mathrm{s}` is the sampling period and :math:`k` is the discrete-time index. This corresponds to the implementation in the :class:`motulator.drive.control.SpeedCtrl` class.

.. rubric:: References

Expand Down
2 changes: 1 addition & 1 deletion docs/source/installation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ Several powerful open-source IDEs are available for Python. The following instru

After completing the above steps, the virtual environment can be found in the ``.venv`` directory at the root of the repository. Now you should be able to run all the examples as well as to modify the existing code. When you start VS Code next time, it will automatically detect the virtual environment and use it.

If you installed the requirement in ``requirements-dev.txt``, you can also use the interactive IPython console (click on the *Play* button dropdown menu in VS Code). If you aim to work with the documentation, install also the requirements in ``docs/requirements.txt``. For previewing the documentation in VS Code, you can install the Esbonio extension: https://docs.esbon.io/en/latest/lsp/editors/vscode.html.
If you installed the ``dev`` requirements, you can also use the interactive IPython console (click on the *Play* button dropdown menu in VS Code). If you aim to work with the documentation, install also the ``docs`` requirements. For previewing the documentation in VS Code, you can install the Esbonio extension: https://docs.esbon.io/en/latest/lsp/editors/vscode.html.

If you use Windows, you may need to change the default terminal from the PowerShell to the Command Prompt (press Ctrl+Shift+P for the command palette and search for *Terminal: Select Default Profile*).

Expand Down
2 changes: 1 addition & 1 deletion docs/source/model/ac_filter.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ A dynamic model of the filter is

where :math:`L` and :math:`R` are the inductance and the series resistance of the inductor, respectively, and :math:`C` is the capacitance. Furthermore, :math:`\boldsymbol{i}_\mathrm{c}^\mathrm{s}` is the converter current, :math:`\boldsymbol{i}_\mathrm{s}^\mathrm{s}` is the stator current, :math:`\boldsymbol{u}_\mathrm{c}^\mathrm{s}` is the converter voltage, and :math:`\boldsymbol{u}_\mathrm{s}^\mathrm{s}` is the capacitor voltage (corresponding to the stator voltage).

The filter model is implemented in the class :class:`motulator.model.LCFilter`. For its usage, see the example :doc:`/auto_examples/vhz/plot_vhz_ctrl_im_2kw_lc`.
The filter model is implemented in the class :class:`motulator.drive.model.LCFilter`. For its usage, see the example :doc:`/auto_examples/vhz/plot_vhz_ctrl_im_2kw_lc`.

.. rubric:: References

Expand Down
8 changes: 4 additions & 4 deletions docs/source/model/converters.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Converters
Inverter
--------

The figure below shows a three-phase two-level inverter and its equivalent model, where ideal switches are assumed. In the equivalent model, each changeover switch is connected to either negative or positive potential of the DC bus. The switching phenomena are assumed to be infinitely fast. The inverter model is provided in the class :class:`motulator.model.Inverter`.
The figure below shows a three-phase two-level inverter and its equivalent model, where ideal switches are assumed. In the equivalent model, each changeover switch is connected to either negative or positive potential of the DC bus. The switching phenomena are assumed to be infinitely fast. The inverter model is provided in the class :class:`motulator.drive.model.Inverter`.


.. figure:: figs/inverter.svg
Expand All @@ -18,7 +18,7 @@ The figure below shows a three-phase two-level inverter and its equivalent model
Six-Pulse Diode Bridge
----------------------

The figure below shows a six-pulse diode bridge rectifier, where the inductor :math:`L` and the capacitor :math:`C` are placed in the DC link. For simplicity, a three-phase supply voltage is assumed to be stiff. The class :class:`motulator.model.FrequencyConverter` applies this model as a part of a frequency converter model.
The figure below shows a six-pulse diode bridge rectifier, where the inductor :math:`L` and the capacitor :math:`C` are placed in the DC link. For simplicity, a three-phase supply voltage is assumed to be stiff. The class :class:`motulator.drive.model.FrequencyConverter` applies this model as a part of a frequency converter model.

.. figure:: figs/diode_bridge.svg
:width: 100%
Expand All @@ -41,7 +41,7 @@ The figure below shows an inverter equipped with a generic three-phase load. In

Instantaneous switching states are defined by the carrier comparison. In this example, the switching states are :math:`q_\mathrm{a}=1`, :math:`q_\mathrm{b}=0`, and :math:`q_\mathrm{c}=0`.

The figure below shows the principle of carrier comparison. The logic shown in the figure is implemented in the class :class:`motulator.model.CarrierComparison`, where the switching instants are explicitly computed in the beginning of each sampling period (instead of searching for zero crossings), allowing faster simulations.
The figure below shows the principle of carrier comparison. The logic shown in the figure is implemented in the class :class:`motulator.drive.model.CarrierComparison`, where the switching instants are explicitly computed in the beginning of each sampling period (instead of searching for zero crossings), allowing faster simulations.

.. figure:: figs/carrier_comparison.svg
:width: 100%
Expand All @@ -62,7 +62,7 @@ The zero-sequence voltage does not affect the phase currents if the neutral of t
where :math:`\boldsymbol{q}_\mathrm{c}^\mathrm{s}` is the switching-state space vector.

.. note::
The carrier comparison is compatible with all standard pulse-width modulation (PWM) methods, such as space-vector PWM (see :class:`motulator.control.PWM`) and discontinuous PWM methods [#Hol1994]_, [#Hav1999]_.
The carrier comparison is compatible with all standard pulse-width modulation (PWM) methods, such as space-vector PWM (see :class:`motulator.common.control.PWM`) and discontinuous PWM methods [#Hol1994]_, [#Hav1999]_.

The sampling period :math:`T_\mathrm{s}` is returned by the control method, and it does not need to be constant.

Expand Down
10 changes: 5 additions & 5 deletions docs/source/model/machines.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,12 +20,12 @@ where :math:`i_\mathrm{a}`, :math:`i_\mathrm{b}`, and :math:`i_\mathrm{c}` are t

Even though the zero-sequence voltage exists at the ouput of typical converters (see :doc:`/model/converters`), there is no path for the zero-sequence current to flow if the stator winding is either delta-connected or the star point is not connected, i.e., :math:`i_\mathrm{s0} = 0`. Consequently, the zero-sequence voltage cannot produce neither power nor torque.

The space vector transformation in :eq:`space_vector` is implemented in the function :func:`motulator.abc2complex` and its inverse transformation in the function :func:`motulator.complex2abc`.
The space vector transformation in :eq:`space_vector` is implemented in the function :func:`motulator.common.utils.abc2complex` and its inverse transformation in the function :func:`motulator.common.utils.complex2abc`.

Induction Machine
-----------------

The induction machine models are provided in the package :mod:`motulator.model`. The models are implemented in stator coordinates. A Γ-equivalent model is used as a base model since it can be extended with the magnetic saturation model in a straightforward manner [#Sle1989]_.
The induction machine models are provided in the package :mod:`motulator.drive.model`. The models are implemented in stator coordinates. A Γ-equivalent model is used as a base model since it can be extended with the magnetic saturation model in a straightforward manner [#Sle1989]_.

.. figure:: figs/im_gamma.svg
:width: 100%
Expand Down Expand Up @@ -57,7 +57,7 @@ where :math:`\boldsymbol{u}_\mathrm{s}^\mathrm{s}` is the stator voltage, :math:
\boldsymbol{\psi}_\mathrm{r}^\mathrm{s} &= \boldsymbol{\psi}_\mathrm{s}^\mathrm{s} + L_\ell\boldsymbol{i}_\mathrm{r}^\mathrm{s}
:label: im_flux

where :math:`L_\mathrm{s}` is the stator inductance and :math:`L_\ell` is the leakage inductance. This linear magnetic model is applied in the class :class:`motulator.model.InductionMachine`. The electromagnetic torque is
where :math:`L_\mathrm{s}` is the stator inductance and :math:`L_\ell` is the leakage inductance. This linear magnetic model is applied in the class :class:`motulator.drive.model.InductionMachine`. The electromagnetic torque is

.. math::
\tau_\mathrm{M} = \frac{3 n_\mathrm{p}}{2}\mathrm{Im} \left\{\boldsymbol{i}_\mathrm{s}^\mathrm{s} (\boldsymbol{\psi}_\mathrm{s}^\mathrm{s})^* \right\}
Expand All @@ -81,12 +81,12 @@ The same class can also be used with the main-flux saturation models, such as :m

Inverse-Γ model.

Example control methods in the package :mod:`motulator.control.im` are based on the inverse-Γ model.
Example control methods in the package :mod:`motulator.drive.control.im` are based on the inverse-Γ model.

Synchronous Machine
-------------------

Synchronous machine models are provided in the package :mod:`motulator.model`. The models can be parametrized to represent permanent-magnet synchronous machines (PMSMs) and synchronous reluctance machines (SyRMs).
Synchronous machine models are provided in the package :mod:`motulator.drive.model`. The models can be parametrized to represent permanent-magnet synchronous machines (PMSMs) and synchronous reluctance machines (SyRMs).

.. figure:: figs/sm_block_rot.svg
:width: 100%
Expand Down
Loading
Loading