.. _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:`y_{af}`       | State    | State in lag transfer function   |      | v_str      |
+--------+----------------------+----------+----------------------------------+------+------------+
|  PI_xi | :math:`xi_{PI}`      | State    | Integrator output                |      | v_str      |
+--------+----------------------+----------+----------------------------------+------+------------+
|  ae    | :math:`\theta_{est}` | State    | PLL angle output before filter   |      | v_str      |
+--------+----------------------+----------+----------------------------------+------+------------+
|  am    | :math:`\theta_{m}`   | State    | PLL output angle after filtering |      | v_str      |
+--------+----------------------+----------+----------------------------------+------+------------+
|  PI_y  | :math:`y_{PI}`       | Algeb    | PI output                        |      | v_str      |
+--------+----------------------+----------+----------------------------------+------+------------+
|  a     | :math:`\theta`       | ExtAlgeb | Bus voltage angle                |      |            |
+--------+----------------------+----------+----------------------------------+------+------------+

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

+--------+----------------------+----------+----------------------------------------------------+
|  Name  |        Symbol        |   Type   |                   Initial Value                    |
+========+======================+==========+====================================================+
|  af_y  | :math:`y_{af}`       | State    | :math:`\theta`                                     |
+--------+----------------------+----------+----------------------------------------------------+
|  PI_xi | :math:`xi_{PI}`      | State    | :math:`0.0`                                        |
+--------+----------------------+----------+----------------------------------------------------+
|  ae    | :math:`\theta_{est}` | State    | :math:`\theta`                                     |
+--------+----------------------+----------+----------------------------------------------------+
|  am    | :math:`\theta_{m}`   | State    | :math:`\theta`                                     |
+--------+----------------------+----------+----------------------------------------------------+
|  PI_y  | :math:`y_{PI}`       | Algeb    | :math:`K_{p} u \left(- \theta_{m} + y_{af}\right)` |
+--------+----------------------+----------+----------------------------------------------------+
|  a     | :math:`\theta`       | ExtAlgeb |                                                    |
+--------+----------------------+----------+----------------------------------------------------+

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

+--------+----------------------+-------+----------------------------------------------------+-------------+
|  Name  |        Symbol        | Type  |          RHS of Equation "T x' = f(x, y)"          |   T (LHS)   |
+========+======================+=======+====================================================+=============+
|  af_y  | :math:`y_{af}`       | State | :math:`\theta - y_{af}`                            | :math:`T_f` |
+--------+----------------------+-------+----------------------------------------------------+-------------+
|  PI_xi | :math:`xi_{PI}`      | State | :math:`K_{i} u \left(- \theta_{m} + y_{af}\right)` |             |
+--------+----------------------+-------+----------------------------------------------------+-------------+
|  ae    | :math:`\theta_{est}` | State | :math:`2 \pi f_{n} y_{PI}`                         |             |
+--------+----------------------+-------+----------------------------------------------------+-------------+
|  am    | :math:`\theta_{m}`   | State | :math:`\theta_{est} - \theta_{m}`                  | :math:`T_p` |
+--------+----------------------+-------+----------------------------------------------------+-------------+

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

+-------+----------------+----------+-----------------------------------------------------------------------+
| Name  |     Symbol     |   Type   |                     RHS of Equation "0 = g(x, y)"                     |
+=======+================+==========+=======================================================================+
|  PI_y | :math:`y_{PI}` | Algeb    | :math:`K_{p} u \left(- \theta_{m} + y_{af}\right) + xi_{PI} - y_{PI}` |
+-------+----------------+----------+-----------------------------------------------------------------------+
|  a    | :math:`\theta` | 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:`xi_{PI}`    | State    | Integrator output     |      | v_str      |
+--------+--------------------+----------+-----------------------+------+------------+
|  am    | :math:`\theta_{m}` | State    | PLL angle output      |      | v_str      |
+--------+--------------------+----------+-----------------------+------+------------+
|  PI_y  | :math:`y_{PI}`     | Algeb    | PI output             |      | v_str      |
+--------+--------------------+----------+-----------------------+------+------------+
|  a     | :math:`\theta`     | ExtAlgeb | Bus voltage angle     |      |            |
+--------+--------------------+----------+-----------------------+------+------------+
|  v     | :math:`V`          | ExtAlgeb | Bus voltage magnitude |      |            |
+--------+--------------------+----------+-----------------------+------+------------+

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

+--------+--------------------+----------+---------------------------------------------------------+
|  Name  |       Symbol       |   Type   |                      Initial Value                      |
+========+====================+==========+=========================================================+
|  PI_xi | :math:`xi_{PI}`    | State    | :math:`0`                                               |
+--------+--------------------+----------+---------------------------------------------------------+
|  am    | :math:`\theta_{m}` | State    | :math:`\theta`                                          |
+--------+--------------------+----------+---------------------------------------------------------+
|  PI_y  | :math:`y_{PI}`     | Algeb    | :math:`K_{p} V \sin{\left(\theta - \theta_{m} \right)}` |
+--------+--------------------+----------+---------------------------------------------------------+
|  a     | :math:`\theta`     | ExtAlgeb |                                                         |
+--------+--------------------+----------+---------------------------------------------------------+
|  v     | :math:`V`          | ExtAlgeb |                                                         |
+--------+--------------------+----------+---------------------------------------------------------+

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

+--------+--------------------+-------+---------------------------------------------------------+---------+
|  Name  |       Symbol       | Type  |            RHS of Equation "T x' = f(x, y)"             | T (LHS) |
+========+====================+=======+=========================================================+=========+
|  PI_xi | :math:`xi_{PI}`    | State | :math:`K_{i} V \sin{\left(\theta - \theta_{m} \right)}` |         |
+--------+--------------------+-------+---------------------------------------------------------+---------+
|  am    | :math:`\theta_{m}` | State | :math:`2 \pi f_{n} y_{PI}`                              |         |
+--------+--------------------+-------+---------------------------------------------------------+---------+

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

+-------+----------------+----------+----------------------------------------------------------------------------+
| Name  |     Symbol     |   Type   |                       RHS of Equation "0 = g(x, y)"                        |
+=======+================+==========+============================================================================+
|  PI_y | :math:`y_{PI}` | Algeb    | :math:`K_{p} V \sin{\left(\theta - \theta_{m} \right)} + xi_{PI} - y_{PI}` |
+-------+----------------+----------+----------------------------------------------------------------------------+
|  a    | :math:`\theta` | 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)          |
+---------------+--------+-------+---------------------------------------+-----------------+