motulator_multiphase.utils
==========================

.. py:module:: motulator_multiphase.utils

.. autoapi-nested-parse::

   Utilities for multi-three-phase machine drives.

   The machine has n three-phase winding sets. The phase a of the set k is located at the
   angle `theta_sets[k]` with respect to the stationary α axis. The space vector of the set
   k in its own coordinates is `abc2complex(x_abc_k)`, and in the common stationary
   coordinates `exp(1j*theta_sets[k])*abc2complex(x_abc_k)`.

   The decoupled multi-stator (DMS) transformation maps the space vectors of the sets in
   the common stationary coordinates to the common mode (CM) and n - 1 differential modes
   (DMs), see :func:`dms_matrix`. For two sets, `x_cm = (x_1 + x_2)/2` and `x_dm = (x_1 -
   x_2)/2`. Including the set angles, the modes are `D @ x_sets`, where `D =
   T*exp(1j*theta_sets)` and `x_sets` are the set vectors in their own coordinates, and the
   inverse is `n*D.conj().T`.

   The plotting function and the base values of motulator are re-exported for
   convenience.

   ..
       !! processed by numpydoc !!


Functions
---------

.. autoapisummary::

   motulator_multiphase.utils.default_set_angles
   motulator_multiphase.utils.dms_matrix
   motulator_multiphase.utils.plot_sets
   motulator_multiphase.utils.to_parallel


Module Contents
---------------

.. py:function:: default_set_angles(n_sets)

   
   Angles of the winding sets of an asymmetrical multi-three-phase machine.

   The sets are displaced by `pi/(3*n_sets)`, e.g., 30° for a dual-three-phase machine
   and 15° for a quadruple-three-phase machine.

   :param n_sets: Number of three-phase sets.
   :type n_sets: int

   :returns: Angles (rad) of the phases a of the sets.
   :rtype: ndarray, shape (n_sets,)

   .. rubric:: Examples

   >>> from motulator_multiphase.utils import default_set_angles
   >>> np.degrees(default_set_angles(2))
   array([ 0., 30.])















   ..
       !! processed by numpydoc !!

.. py:function:: dms_matrix(n_sets)

   
   Decoupled multi-stator (DMS) transformation matrix.

   The transformation maps the space vectors of the sets in common coordinates to the
   common mode and the differential modes [#Rub2021]_. The first row gives the common
   mode as the mean of the sets. The other rows give the differential modes, `x_dm_u ∝
   (n - u)*x_u - sum(x_{u+1}, ..., x_n)`. The rows are orthogonal and scaled such that
   the inverse is `n_sets*T.T`.

   :param n_sets: Number of three-phase sets.
   :type n_sets: int

   :returns: Transformation matrix.
   :rtype: ndarray, shape (n_sets, n_sets)

   .. rubric:: References

   .. [#Rub2021] Rubino, Dordevic, Armando, Bojoi, Levi, "A novel matrix transformation
      for decoupled control of modular multiphase PMSM drives," IEEE Trans. Power
      Electron., 2021, https://doi.org/10.1109/TPEL.2020.3043083

   .. rubric:: Examples

   >>> from motulator_multiphase.utils import dms_matrix
   >>> dms_matrix(2)
   array([[ 0.5,  0.5],
          [ 0.5, -0.5]])
   >>> T = dms_matrix(4)
   >>> bool(np.allclose(4 * T.T @ T, np.eye(4)))
   True















   ..
       !! processed by numpydoc !!

.. py:function:: plot_sets(res, t_lims = None, latex = False, save_path = None, **savefig_kwargs)

   
   Plot the set and differential-mode currents.

   The first subplot shows the current magnitudes of the sets. The second subplot shows
   the DM currents in the controller coordinates (d solid, q dash-dotted) and their
   references (black dashed).

   :param res: Simulation results of a multi-three-phase drive.
   :type res: SimulationResults
   :param t_lims: Time axis limits. If None, uses full time range.
   :type t_lims: tuple[float, float], optional
   :param latex: Use LaTeX fonts for the labels, defaults to False.
   :type latex: bool, optional
   :param save_path: Path to save the figure. If None, the figure is not saved.
   :type save_path: str | Path, optional
   :param \*\*savefig_kwargs: Additional keyword arguments passed to `plt.savefig()`.















   ..
       !! processed by numpydoc !!

.. py:function:: to_parallel(par, n_sets)

   
   Parameters of the equivalent machine with the sets connected in parallel.

   The given parameters describe one three-phase set, when all sets carry equal
   currents (i.e., the common mode only). When the sets are connected in parallel,
   the voltages and the flux linkages remain unchanged, while the currents are
   multiplied by `n_sets`. Hence, the resistances and inductances are divided by
   `n_sets`, and the core-loss conductance is multiplied by it. The equivalent machine
   produces the total torque of the machine. The maps of saturated machines are scaled
   accordingly, keeping their analytic Jacobians (e.g., of GradNet flux maps).

   :param par: Parameters of one set (balanced operation of all sets).
   :type par: MachinePars
   :param n_sets: Number of three-phase sets.
   :type n_sets: int

   :returns: Parameters of the equivalent three-phase machine, of the same type as `par`.
   :rtype: MachinePars

   .. rubric:: Examples

   >>> from motulator_multiphase import model, utils
   >>> par = model.SynchronousMachinePars(
   ...     n_p=3, R_s=3.6, L_d=0.036, L_q=0.051, psi_f=0.545
   ... )
   >>> utils.to_parallel(par, 2)
   SynchronousMachinePars(n_p=3, R_s=1.8, L_d=0.018, L_q=0.0255, psi_f=0.545, G_c=0.0)















   ..
       !! processed by numpydoc !!