pydynamicestimator.devices.inverter
===================================

.. py:module:: pydynamicestimator.devices.inverter


Classes
-------

.. autoapisummary::

   pydynamicestimator.devices.inverter.Inverter
   pydynamicestimator.devices.inverter.GridFollowing
   pydynamicestimator.devices.inverter.GridForming


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

.. py:class:: Inverter

   Bases: :py:obj:`pydynamicestimator.devices.device.DeviceRect`


   Metaclass for inverters


   .. py:attribute:: omega_net


   .. py:attribute:: Kp


   .. py:attribute:: Kq


   .. py:attribute:: Kpv


   .. py:attribute:: Kiv


   .. py:attribute:: Kffv


   .. py:attribute:: Kpc


   .. py:attribute:: Kic


   .. py:attribute:: Kffc


   .. py:attribute:: Rv


   .. py:attribute:: Lv


   .. py:attribute:: Rf


   .. py:attribute:: Lf


   .. py:attribute:: Cf


   .. py:attribute:: Rt


   .. py:attribute:: Lt


   .. py:attribute:: omega_f


   .. py:attribute:: ns
      :value: 13



   .. py:attribute:: Vfd_ext


   .. py:attribute:: Vfq_ext


   .. py:attribute:: ifd_ext


   .. py:attribute:: ifq_ext


   .. py:attribute:: itd_ext


   .. py:attribute:: itq_ext


   .. py:attribute:: Pc_tilde


   .. py:attribute:: delta_c


   .. py:attribute:: Qc_tilde


   .. py:attribute:: xi_d


   .. py:attribute:: xi_q


   .. py:attribute:: gamma_d


   .. py:attribute:: gamma_q


   .. py:attribute:: Pref


   .. py:attribute:: Qref


   .. py:attribute:: Vref


   .. py:method:: gcall(dae: pydynamicestimator.system.Dae) -> None


   .. py:method:: filter_init(dae: pydynamicestimator.system.Dae)

      Steady-state initialization of the inverter filter.
      Based on methods used in https://github.com/NREL-Sienna/PowerSimulationsDynamics.jl

      :param dae: DAE object
      :type dae: pydynamicestimator.system.Dae

      :returns:     Vswd (ndarray): d-component of the switching block voltage
                    Vswq (ndarray): q-component of the switching block voltage
                    ifd_ext (ndarray): d-component of the filter current in the network (external) dq-reference frame
                    ifq_ext (ndarray): q-component of the filter current in the network (external) dq-reference frame
                    Vfd_ext (ndarray): d-component of the filter voltage in the network (external) dq-reference frame
                    Vfq_ext (ndarray): q-component of the filter voltage in the network (external) dq-reference frame
                    itd_ext (ndarray): d-component of the terminal current in the network (external) dq-reference frame
                    itq_ext (ndarray): q-component of the terminal current in the network (external) dq-reference frame
      :rtype: Tuple



   .. py:method:: frequency_estimator_init(Vfd_ext: numpy.ndarray, Vfq_ext: numpy.ndarray) -> Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

      Steady-state initialization of the frequency estimator.
      Based on methods used in https://github.com/NREL-Sienna/PowerSimulationsDynamics.jl

      :param Vfd_ext: d-component of the filter voltage in the network (external) dq-reference frame
      :type Vfd_ext: ndarray
      :param Vfq_ext: q-component of the filter voltage in the network (external) dq-reference frame
      :type Vfq_ext: ndarray

      :returns:     Vfq_pll (ndarray): q-component of the filter voltage in the PLL's dq-reference frame
                    epsilon (ndarray): integrator state of the PLL
                    delta_pll (ndarray): angle difference between the dq-reference frame of the PLL and the network
      :rtype: Tuple



   .. py:method:: outer_loop_init(dae: pydynamicestimator.system.Dae, Vfd_ext: numpy.ndarray, Vfq_ext: numpy.ndarray) -> Tuple[numpy.ndarray, numpy.ndarray]

      Steady-state initialization of the inverter outer loop.
      Based on methods used in https://github.com/NREL-Sienna/PowerSimulationsDynamics.jl

      :param dae: DAE object
      :type dae: pydynamicestimator.system.Dae
      :param Vfd_ext: d-component of the filter voltage in the network (external) dq-reference frame
      :type Vfd_ext: ndarray
      :param Vfq_ext: q-component of the filter voltage in the network (external) dq-reference frame
      :type Vfq_ext: ndarray

      :returns:     Pref (ndarray): active power reference
                    Qref (ndarray): reactive power reference
      :rtype: Tuple



   .. py:method:: inner_loop_init(dae: pydynamicestimator.system.Dae, ifd_ext: numpy.ndarray, ifq_ext: numpy.ndarray, Vfd_ext: numpy.ndarray, Vfq_ext: numpy.ndarray, Vswd: numpy.ndarray, Vswq: numpy.ndarray) -> Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

      Steady-state initialization of the inverter inner loop.
      Based on methods used in https://github.com/NREL-Sienna/PowerSimulationsDynamics.jl

      :param dae: DAE object
      :type dae: pydynamicestimator.system.Dae
      :param ifd_ext:
      :param ifq_ext:
      :param Vfd_ext:
      :param Vfq_ext:
      :param Vswd:
      :param Vswq:

      :returns:     delta_c
                    Vref
                    xi_d
                    xi_q
                    gamma_d
                    gamma_q
                    Pc_tilde
                    Qc_tilde
      :rtype: Tuple



   .. py:method:: finit(dae: pydynamicestimator.system.Dae)

      :param dae:
      :type dae: pydynamicestimator.system.Dae

      :returns: None



.. py:class:: GridFollowing

   Bases: :py:obj:`Inverter`


   Grid-Following Inverter (with Droop)
   Based on the grid-following inverter model in https://doi.org/10.1109/TPWRS.2021.3061434

   The dynamic behavior of the grid-following converter is described by the following differential equations:

   **Converter Voltage Dynamics**


   .. math::

       \dot{v}_{fd_{ext}} = \frac{\omega_{b}}{c_{f}}(i_{fd_{ext}} - i_{td_{ext}}) + \omega_{net}\omega_{b}v_{fq_{ext}}

   .. math::

       \dot{v}_{fq_{ext}} = \frac{\omega_{b}}{c_{f}}(i_{fq_{ext}} - i_{tq_{ext}}) - \omega_{net}\omega_{b}v_{fd_{ext}}

   **Converter Current Dynamics**


   .. math::

       \dot{i}_{fd_{ext}} = \frac{\omega_{b}}{l_{f}}(v_{swd} - v_{fd_{ext}}) - \frac{\omega_{b}r_{f}}{l_{f}}i_{fd_{ext}} + \omega_{net}\omega_{b}i_{fq_{ext}}

   .. math::

       \dot{i}_{fq_{ext}} = \frac{\omega_{b}}{l_{f}}(v_{swq} - v_{fq_{ext}}) - \frac{\omega_{b}r_{f}}{l_{f}}i_{fq_{ext}} - \omega_{net}\omega_{b}i_{fd_{ext}}

   **Grid-Side Current Dynamics**


   .. math::

       \dot{i}_{td_{ext}} = \frac{\omega_b}{l_t}(v_{fd_{ext}} - v_{n_{re}}) - \frac{\omega_b r_t}{l_t}i_{td_{ext}} + \omega_{net} \omega_b i_{tq_{ext}}

   .. math::

       \dot{i}_{tq_{ext}} = \frac{\omega_b}{l_t}(v_{fq_{ext}} - v_{n_{im}}) - \frac{\omega_b r_t}{l_t}i_{tq_{ext}} - \omega_{net} \omega_b i_{td_{ext}}

   **Phase-Locked Loop (PLL) Dynamics**


   .. math::

       \dot{\epsilon} = v_{fq_{pll}}

   .. math::

       \delta\dot{\theta}_{pll} = \omega_{b}\delta\omega_{pll}

   **Power and Frequency Dynamics**


   .. math::

       \dot{\tilde{p}}_{c} = \omega_{f}(p_{c} - \tilde{p}_{c})

   .. math::

       \delta\dot{\theta}_{c} = \omega_{b}\delta\omega_{c}

   .. math::

       \dot{\tilde{q}}_{c} = \omega_{f}(q_{c} - \tilde{q}_{c})

   **Control Dynamics**


   .. math::

       \dot{\xi}_{d} = v_{fd^{*}} - v_{fd_{int}}

   .. math::

       \dot{\xi}_{q} = v_{fq^{*}} - v_{fq_{int}}

   .. math::

       \dot{\gamma}_{d} = i_{fd^{*}} - i_{fd_{int}}

   .. math::

       \dot{\gamma}_{q} = i_{fq^{*}} - i_{fq_{int}}



   .. py:attribute:: _type
      :value: 'Inverter'



   .. py:attribute:: _name
      :value: 'GridFollowing_inverter_model'



   .. py:attribute:: epsilon


   .. py:attribute:: delta_pll


   .. py:attribute:: Kpll_p


   .. py:attribute:: Kpll_i


   .. py:method:: fgcall(dae: pydynamicestimator.system.Dae) -> None

      A method that executes the differential and algebraic equations of the model
      and adds them to the appropriate places in the Dae class

      :param dae: an instance of a class Dae

      :type dae:

      :return: None

      :rtype: None



   .. py:method:: finit(dae: pydynamicestimator.system.Dae) -> None

      :param dae:
      :type dae: pydynamicestimator.system.Dae

      :returns: None



.. py:class:: GridForming

   Bases: :py:obj:`Inverter`


   Grid-Forming Inverter (Droop-Based)
   Based on the grid-forming inverter model in https://doi.org/10.1109/TPWRS.2021.3061434
   The dynamic behavior of the grid-forming converter is described by the following differential equations:

   **Converter Voltage Dynamics**


   .. math::

       \dot{v}_{fd_{ext}} = \frac{\omega_{b}}{c_{f}}(i_{fd_{ext}} - i_{td_{ext}}) + \omega_{net}\omega_{b}v_{fq_{ext}}

   .. math::

       \dot{v}_{fq_{ext}} = \frac{\omega_{b}}{c_{f}}(i_{fq_{ext}} - i_{tq_{ext}}) - \omega_{net}\omega_{b}v_{fd_{ext}}

   **Converter Current Dynamics**


   .. math::

       \dot{i}_{fd_{ext}} = \frac{\omega_{b}}{l_{f}}(v_{swd} - v_{fd_{ext}}) - \frac{\omega_{b}r_{f}}{l_{f}}i_{fd_{ext}} + \omega_{net}\omega_{b}i_{fq_{ext}}

   .. math::

       \dot{i}_{fq_{ext}} = \frac{\omega_{b}}{l_{f}}(v_{swq} - v_{fq_{ext}}) - \frac{\omega_{b}r_{f}}{l_{f}}i_{fq_{ext}} - \omega_{net}\omega_{b}i_{fd_{ext}}

   **Grid-Side Current Dynamics**


   .. math::

       \dot{i}_{td_{ext}} = \frac{\omega_b}{l_t}(v_{fd_{ext}} - v_{n_{re}}) - \frac{\omega_b r_t}{l_t}i_{td_{ext}} + \omega_{net} \omega_b i_{tq_{ext}}

   .. math::

       \dot{i}_{tq_{ext}} = \frac{\omega_b}{l_t}(v_{fq_{ext}} - v_{n_{im}}) - \frac{\omega_b r_t}{l_t}i_{tq_{ext}} - \omega_{net} \omega_b i_{td_{ext}}

   **Power and Frequency Dynamics**


   .. math::

       \dot{\tilde{p}}_{c} = \omega_{f}(p_{c} - \tilde{p}_{c})

   .. math::

       \delta\dot{\theta}_{c} = \omega_{b}\delta\omega_{c}

   .. math::

       \dot{\tilde{q}}_{c} = \omega_{f}(q_{c} - \tilde{q}_{c})

   **Control Dynamics**


   .. math::

       \dot{\xi}_{d} = v_{fd^{*}} - v_{fd_{int}}

   .. math::

       \dot{\xi}_{q} = v_{fq^{*}} - v_{fq_{int}}

   .. math::

       \dot{\gamma}_{d} = i_{fd^{*}} - i_{fd_{int}}

   .. math::

       \dot{\gamma}_{q} = i_{fq^{*}} - i_{fq_{int}}



   .. py:attribute:: _type
      :value: 'Inverter'



   .. py:attribute:: _name
      :value: 'GridForming_inverter_model'



   .. py:method:: fgcall(dae: pydynamicestimator.system.Dae) -> None

      A method that executes the differential and algebraic equations of the model
      and adds them to the appropriate places in the Dae class

      :param dae: an instance of a class Dae

      :type dae:

      :return: None

      :rtype: None



   .. py:method:: finit(dae) -> None

      :param dae:
      :type dae: pydynamicestimator.system.Dae

      :returns: None