.. _PLL:

================================================================================
PLL
================================================================================
Phase-locked loop models.

Common Parameters: u, name

Common Variables: am

Available models:
PLL1_,
PLL2_

.. _PLL1:

--------------------------------------------------------------------------------
PLL1
--------------------------------------------------------------------------------
Simple Phasor Lock Loop (PLL) using one PI controller. The PI controller
minimizes the error between the input and output angle.

Input bus angle signal -> Lag filter 1 with Tf -> Output angle `af_y`.

(af_y - am) -> PI Controller (Kp, Ki) -> PI_y

Estimated angle ae = (2 * pi * fn * PI_y) -> Lag filter 2 with Tp -> am.

The output signal is ``am``, a state variable.

Parameters
----------

+-------+-------------+---------------------------------+---------+--------+------------+
| Name  |   Symbol    |           Description           | Default |  Unit  | Properties |
+=======+=============+=================================+=========+========+============+
|  idx  |             | unique device idx               |         |        |            |
+-------+-------------+---------------------------------+---------+--------+------------+
|  u    | :math:`u`   | connection status               | 1       | *bool* |            |
+-------+-------------+---------------------------------+---------+--------+------------+
|  name |             | device name                     |         |        |            |
+-------+-------------+---------------------------------+---------+--------+------------+
|  bus  |             | bus idx                         |         |        | mandatory  |
+-------+-------------+---------------------------------+---------+--------+------------+
|  fn   | :math:`f_n` | nominal frequency               | 60      | *Hz*   |            |
+-------+-------------+---------------------------------+---------+--------+------------+
|  Kp   | :math:`K_p` | proportional gain               | 0.100   |        |            |
+-------+-------------+---------------------------------+---------+--------+------------+
|  Ki   | :math:`K_i` | integral gain                   | 0.100   |        |            |
+-------+-------------+---------------------------------+---------+--------+------------+
|  Tf   | :math:`T_f` | input digital filter time const | 0.050   | *sec*  |            |
+-------+-------------+---------------------------------+---------+--------+------------+
|  Tp   | :math:`T_p` | output filter time const.       | 0.050   | *sec*  |            |
+-------+-------------+---------------------------------+---------+--------+------------+

Variables
---------

+--------+-------------------+----------+----------------------------------+------+------------+
|  Name  |      Symbol       |   Type   |           Description            | Unit | Properties |
+========+===================+==========+==================================+======+============+
|  af_y  | :math:`af_{y}`    | State    | State in lag transfer function   |      | v_str      |
+--------+-------------------+----------+----------------------------------+------+------------+
|  PI_xi | :math:`\pi_{\xi}` | State    | Integrator output                |      | v_str      |
+--------+-------------------+----------+----------------------------------+------+------------+
|  ae    | :math:`ae`        | State    | PLL angle output before filter   |      | v_str      |
+--------+-------------------+----------+----------------------------------+------+------------+
|  am    | :math:`am`        | State    | PLL output angle after filtering |      | v_str      |
+--------+-------------------+----------+----------------------------------+------+------------+
|  PI_y  | :math:`\pi_{y}`   | Algeb    | PI output                        |      | v_str      |
+--------+-------------------+----------+----------------------------------+------+------------+
|  a     | :math:`a`         | ExtAlgeb | Bus voltage angle                |      |            |
+--------+-------------------+----------+----------------------------------+------+------------+

Initialization Equations
------------------------

+--------+-------------------+----------+---------------------------------------+
|  Name  |      Symbol       |   Type   |             Initial Value             |
+========+===================+==========+=======================================+
|  af_y  | :math:`af_{y}`    | State    | :math:`a`                             |
+--------+-------------------+----------+---------------------------------------+
|  PI_xi | :math:`\pi_{\xi}` | State    | :math:`0.0`                           |
+--------+-------------------+----------+---------------------------------------+
|  ae    | :math:`ae`        | State    | :math:`a`                             |
+--------+-------------------+----------+---------------------------------------+
|  am    | :math:`am`        | State    | :math:`a`                             |
+--------+-------------------+----------+---------------------------------------+
|  PI_y  | :math:`\pi_{y}`   | Algeb    | :math:`Kp u \left(af_{y} - am\right)` |
+--------+-------------------+----------+---------------------------------------+
|  a     | :math:`a`         | ExtAlgeb |                                       |
+--------+-------------------+----------+---------------------------------------+

Differential Equations
-----------------------------

+--------+-------------------+-------+---------------------------------------+-------------+
|  Name  |      Symbol       | Type  |   RHS of Equation "T x' = f(x, y)"    |   T (LHS)   |
+========+===================+=======+=======================================+=============+
|  af_y  | :math:`af_{y}`    | State | :math:`a - af_{y}`                    | :math:`T_f` |
+--------+-------------------+-------+---------------------------------------+-------------+
|  PI_xi | :math:`\pi_{\xi}` | State | :math:`Ki u \left(af_{y} - am\right)` |             |
+--------+-------------------+-------+---------------------------------------+-------------+
|  ae    | :math:`ae`        | State | :math:`2 \pi \pi_{y} fn`              |             |
+--------+-------------------+-------+---------------------------------------+-------------+
|  am    | :math:`am`        | State | :math:`ae - am`                       | :math:`T_p` |
+--------+-------------------+-------+---------------------------------------+-------------+

Algebraic Equations
-----------------------------

+-------+-----------------+----------+-------------------------------------------------------------+
| Name  |     Symbol      |   Type   |                RHS of Equation "0 = g(x, y)"                |
+=======+=================+==========+=============================================================+
|  PI_y | :math:`\pi_{y}` | Algeb    | :math:`Kp u \left(af_{y} - am\right) + \pi_{\xi} - \pi_{y}` |
+-------+-----------------+----------+-------------------------------------------------------------+
|  a    | :math:`a`       | ExtAlgeb | :math:`0`                                                   |
+-------+-----------------+----------+-------------------------------------------------------------+

Blocks
-------

+------+------------+--------------+---------------------------+
| Name |   Symbol   |     Type     |           Info            |
+======+============+==============+===========================+
|  af  | :math:`af` | Lag          | input angle signal filter |
+------+------------+--------------+---------------------------+
|  PI  | :math:`PI` | PIController | PI controller             |
+------+------------+--------------+---------------------------+


Config Fields in [PLL1]

+---------------+--------+-------+---------------------------------------+-----------------+
|    Option     | Symbol | Value |                 Info                  | Accepted values |
+===============+========+=======+=======================================+=================+
|  allow_adjust |        | 1     | allow adjusting upper or lower limits | (0, 1)          |
+---------------+--------+-------+---------------------------------------+-----------------+
|  adjust_lower |        | 0     | adjust lower limit                    | (0, 1)          |
+---------------+--------+-------+---------------------------------------+-----------------+
|  adjust_upper |        | 1     | adjust upper limit                    | (0, 1)          |
+---------------+--------+-------+---------------------------------------+-----------------+


.. _PLL2:

--------------------------------------------------------------------------------
PLL2
--------------------------------------------------------------------------------
Synchronously-rotating Reference Frame (SRF) Phasor Lock Loop (PLL).

The PLL minimizes ``vq = v sin(a - am)`` using a PI controller.

The output signal is ``am``, a state variable.

Parameters
----------

+-------+-------------+-------------------+---------+--------+------------+
| Name  |   Symbol    |    Description    | Default |  Unit  | Properties |
+=======+=============+===================+=========+========+============+
|  idx  |             | unique device idx |         |        |            |
+-------+-------------+-------------------+---------+--------+------------+
|  u    | :math:`u`   | connection status | 1       | *bool* |            |
+-------+-------------+-------------------+---------+--------+------------+
|  name |             | device name       |         |        |            |
+-------+-------------+-------------------+---------+--------+------------+
|  bus  |             | bus idx           |         |        | mandatory  |
+-------+-------------+-------------------+---------+--------+------------+
|  fn   | :math:`f_n` | nominal frequency | 60      | *Hz*   |            |
+-------+-------------+-------------------+---------+--------+------------+
|  Kp   | :math:`K_p` | proportional gain | 0.100   |        |            |
+-------+-------------+-------------------+---------+--------+------------+
|  Ki   | :math:`K_i` | integral gain     | 0.100   |        |            |
+-------+-------------+-------------------+---------+--------+------------+

Variables
---------

+--------+-------------------+----------+-----------------------+------+------------+
|  Name  |      Symbol       |   Type   |      Description      | Unit | Properties |
+========+===================+==========+=======================+======+============+
|  PI_xi | :math:`\pi_{\xi}` | State    | Integrator output     |      | v_str      |
+--------+-------------------+----------+-----------------------+------+------------+
|  am    | :math:`am`        | State    | PLL angle output      |      | v_str      |
+--------+-------------------+----------+-----------------------+------+------------+
|  PI_y  | :math:`\pi_{y}`   | Algeb    | PI output             |      | v_str      |
+--------+-------------------+----------+-----------------------+------+------------+
|  a     | :math:`a`         | ExtAlgeb | Bus voltage angle     |      |            |
+--------+-------------------+----------+-----------------------+------+------------+
|  v     | :math:`v`         | ExtAlgeb | Bus voltage magnitude |      |            |
+--------+-------------------+----------+-----------------------+------+------------+

Initialization Equations
------------------------

+--------+-------------------+----------+-----------------------------------------+
|  Name  |      Symbol       |   Type   |              Initial Value              |
+========+===================+==========+=========================================+
|  PI_xi | :math:`\pi_{\xi}` | State    | :math:`0`                               |
+--------+-------------------+----------+-----------------------------------------+
|  am    | :math:`am`        | State    | :math:`a`                               |
+--------+-------------------+----------+-----------------------------------------+
|  PI_y  | :math:`\pi_{y}`   | Algeb    | :math:`Kp v \sin{\left(a - am \right)}` |
+--------+-------------------+----------+-----------------------------------------+
|  a     | :math:`a`         | ExtAlgeb |                                         |
+--------+-------------------+----------+-----------------------------------------+
|  v     | :math:`v`         | ExtAlgeb |                                         |
+--------+-------------------+----------+-----------------------------------------+

Differential Equations
-----------------------------

+--------+-------------------+-------+-----------------------------------------+---------+
|  Name  |      Symbol       | Type  |    RHS of Equation "T x' = f(x, y)"     | T (LHS) |
+========+===================+=======+=========================================+=========+
|  PI_xi | :math:`\pi_{\xi}` | State | :math:`Ki v \sin{\left(a - am \right)}` |         |
+--------+-------------------+-------+-----------------------------------------+---------+
|  am    | :math:`am`        | State | :math:`2 \pi \pi_{y} fn`                |         |
+--------+-------------------+-------+-----------------------------------------+---------+

Algebraic Equations
-----------------------------

+-------+-----------------+----------+---------------------------------------------------------------+
| Name  |     Symbol      |   Type   |                 RHS of Equation "0 = g(x, y)"                 |
+=======+=================+==========+===============================================================+
|  PI_y | :math:`\pi_{y}` | Algeb    | :math:`Kp v \sin{\left(a - am \right)} + \pi_{\xi} - \pi_{y}` |
+-------+-----------------+----------+---------------------------------------------------------------+
|  a    | :math:`a`       | ExtAlgeb | :math:`0`                                                     |
+-------+-----------------+----------+---------------------------------------------------------------+
|  v    | :math:`v`       | ExtAlgeb | :math:`0`                                                     |
+-------+-----------------+----------+---------------------------------------------------------------+

Blocks
-------

+------+------------+--------------+------+
| Name |   Symbol   |     Type     | Info |
+======+============+==============+======+
|  PI  | :math:`PI` | PIController |      |
+------+------------+--------------+------+


Config Fields in [PLL2]

+---------------+--------+-------+---------------------------------------+-----------------+
|    Option     | Symbol | Value |                 Info                  | Accepted values |
+===============+========+=======+=======================================+=================+
|  allow_adjust |        | 1     | allow adjusting upper or lower limits | (0, 1)          |
+---------------+--------+-------+---------------------------------------+-----------------+
|  adjust_lower |        | 0     | adjust lower limit                    | (0, 1)          |
+---------------+--------+-------+---------------------------------------+-----------------+
|  adjust_upper |        | 1     | adjust upper limit                    | (0, 1)          |
+---------------+--------+-------+---------------------------------------+-----------------+