.. _DynLoad:

================================================================================
DynLoad
================================================================================
Dynamic load group.

Common Parameters: u, name

Available models:
ZIP_,
FLoad_

.. _ZIP:

--------------------------------------------------------------------------------
ZIP
--------------------------------------------------------------------------------
ZIP load model (polynomial load).
This model is initialized after power flow.

Please check the config of PQ to avoid double counting.
If this ZIP model is in use, one should typically set
`p2p=1.0` and `q2q=1.0` while leaving the others
(`p2i`, `p2z`, `q2i`, `q2z`, and `pq2z`) as zeros.
This setting allows one to impose the desired powers
by the static PQ and to convert them based on the percentage
specified in the ZIP.

The percentages for active power, (`kpp`, `kpi`, and `kpz`)
must sum up to 100. Otherwise, initialization will fail.
The same applies to the reactive power percentages.

Parameters
----------

+-------+----------------+--------------------------------+---------+--------+------------+
| Name  |     Symbol     |          Description           | Default |  Unit  | Properties |
+=======+================+================================+=========+========+============+
|  idx  |                | unique device idx              |         |        |            |
+-------+----------------+--------------------------------+---------+--------+------------+
|  u    | :math:`u`      | connection status              | 1       | *bool* |            |
+-------+----------------+--------------------------------+---------+--------+------------+
|  name |                | device name                    |         |        |            |
+-------+----------------+--------------------------------+---------+--------+------------+
|  pq   |                | idx of the PQ to replace       |         |        | mandatory  |
+-------+----------------+--------------------------------+---------+--------+------------+
|  kpp  | :math:`K_{pp}` | Percentage of active power     |         |        | mandatory  |
+-------+----------------+--------------------------------+---------+--------+------------+
|  kpi  | :math:`K_{pi}` | Percentage of active current   |         |        | mandatory  |
+-------+----------------+--------------------------------+---------+--------+------------+
|  kpz  | :math:`K_{pz}` | Percentage of conductance      |         |        | mandatory  |
+-------+----------------+--------------------------------+---------+--------+------------+
|  kqp  | :math:`K_{qp}` | Percentage of reactive power   |         |        | mandatory  |
+-------+----------------+--------------------------------+---------+--------+------------+
|  kqi  | :math:`K_{qi}` | Percentage of reactive current |         |        | mandatory  |
+-------+----------------+--------------------------------+---------+--------+------------+
|  kqz  | :math:`K_{qz}` | Percentage of susceptance      |         |        | mandatory  |
+-------+----------------+--------------------------------+---------+--------+------------+
|  bus  |                | retrieved bux idx              | 0       |        |            |
+-------+----------------+--------------------------------+---------+--------+------------+

Variables
---------

+------+-----------+----------+-------------+------+------------+
| Name |  Symbol   |   Type   | Description | Unit | Properties |
+======+===========+==========+=============+======+============+
|  a   | :math:`a` | ExtAlgeb |             |      |            |
+------+-----------+----------+-------------+------+------------+
|  v   | :math:`v` | ExtAlgeb |             |      |            |
+------+-----------+----------+-------------+------+------------+

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

+------+-----------+----------+---------------+
| Name |  Symbol   |   Type   | Initial Value |
+======+===========+==========+===============+
|  a   | :math:`a` | ExtAlgeb |               |
+------+-----------+----------+---------------+
|  v   | :math:`v` | ExtAlgeb |               |
+------+-----------+----------+---------------+

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

+------+-----------+----------+-------------------------------------------+
| Name |  Symbol   |   Type   |       RHS of Equation "0 = g(x, y)"       |
+======+===========+==========+===========================================+
|  a   | :math:`a` | ExtAlgeb | :math:`\pi_{0} v + pp_{0} + pz_{0} v^{2}` |
+------+-----------+----------+-------------------------------------------+
|  v   | :math:`v` | ExtAlgeb | :math:`qi_{0} v + qp_{0} + qz_{0} v^{2}`  |
+------+-----------+----------+-------------------------------------------+

Services
----------

+------+------------------+-------------------------------------+--------------+
| Name |      Symbol      |              Equation               |     Type     |
+======+==================+=====================================+==============+
|  kps | :math:`K_{psum}` | :math:`kpi + kpp + kpz`             | ConstService |
+------+------------------+-------------------------------------+--------------+
|  kqs | :math:`K_{qsum}` | :math:`kqi + kqp + kqz`             | ConstService |
+------+------------------+-------------------------------------+--------------+
|  rpp | :math:`r_{pp}`   | :math:`\frac{kpp u}{100}`           | ConstService |
+------+------------------+-------------------------------------+--------------+
|  rpi | :math:`r_{pi}`   | :math:`\frac{kpi u}{100}`           | ConstService |
+------+------------------+-------------------------------------+--------------+
|  rpz | :math:`r_{pz}`   | :math:`\frac{kpz u}{100}`           | ConstService |
+------+------------------+-------------------------------------+--------------+
|  rqp | :math:`r_{qp}`   | :math:`\frac{kqp u}{100}`           | ConstService |
+------+------------------+-------------------------------------+--------------+
|  rqi | :math:`r_{qi}`   | :math:`\frac{kqi u}{100}`           | ConstService |
+------+------------------+-------------------------------------+--------------+
|  rqz | :math:`r_{qz}`   | :math:`\frac{kqz u}{100}`           | ConstService |
+------+------------------+-------------------------------------+--------------+
|  pp0 | :math:`P_{p0}`   | :math:`p_{0} rpp`                   | ConstService |
+------+------------------+-------------------------------------+--------------+
|  pi0 | :math:`P_{i0}`   | :math:`\frac{p_{0} rpi}{v_{0}}`     | ConstService |
+------+------------------+-------------------------------------+--------------+
|  pz0 | :math:`P_{z0}`   | :math:`\frac{p_{0} rpz}{v_{0}^{2}}` | ConstService |
+------+------------------+-------------------------------------+--------------+
|  qp0 | :math:`Q_{p0}`   | :math:`q_{0} rqp`                   | ConstService |
+------+------------------+-------------------------------------+--------------+
|  qi0 | :math:`Q_{i0}`   | :math:`\frac{q_{0} rqi}{v_{0}}`     | ConstService |
+------+------------------+-------------------------------------+--------------+
|  qz0 | :math:`Q_{z0}`   | :math:`\frac{q_{0} rqz}{v_{0}^{2}}` | ConstService |
+------+------------------+-------------------------------------+--------------+


Config Fields in [ZIP]

+---------------+--------+-------+---------------------------------------+-----------------+
|    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)          |
+---------------+--------+-------+---------------------------------------+-----------------+


.. _FLoad:

--------------------------------------------------------------------------------
FLoad
--------------------------------------------------------------------------------
Voltage and frequency dependent load.

Parameters
----------

+-------+-----------+-------------------------------------------+---------+--------+--------------+
| Name  |  Symbol   |                Description                | Default |  Unit  |  Properties  |
+=======+===========+===========================================+=========+========+==============+
|  idx  |           | unique device idx                         |         |        |              |
+-------+-----------+-------------------------------------------+---------+--------+--------------+
|  u    | :math:`u` | connection status                         | 1       | *bool* |              |
+-------+-----------+-------------------------------------------+---------+--------+--------------+
|  name |           | device name                               |         |        |              |
+-------+-----------+-------------------------------------------+---------+--------+--------------+
|  pq   |           | idx of the PQ to replace                  |         |        | mandatory    |
+-------+-----------+-------------------------------------------+---------+--------+--------------+
|  busf |           | optional idx of the BusFreq device to use |         |        |              |
+-------+-----------+-------------------------------------------+---------+--------+--------------+
|  kp   |           | active power percentage                   | 100     | *%*    |              |
+-------+-----------+-------------------------------------------+---------+--------+--------------+
|  kq   |           | active power percentage                   | 100     | *%*    |              |
+-------+-----------+-------------------------------------------+---------+--------+--------------+
|  Tf   |           | filter time constant                      | 0.020   | *s*    | non_negative |
+-------+-----------+-------------------------------------------+---------+--------+--------------+
|  ap   |           | active power voltage exponent             | 1       |        |              |
+-------+-----------+-------------------------------------------+---------+--------+--------------+
|  aq   |           | reactive power voltage exponent           | 0       |        |              |
+-------+-----------+-------------------------------------------+---------+--------+--------------+
|  bp   |           | active power frequency exponent           | 0       |        |              |
+-------+-----------+-------------------------------------------+---------+--------+--------------+
|  bq   |           | reactive power frequency exponent         | 0       |        |              |
+-------+-----------+-------------------------------------------+---------+--------+--------------+
|  bus  |           |                                           | 0       |        |              |
+-------+-----------+-------------------------------------------+---------+--------+--------------+

Variables
---------

+------+-----------+----------+-------------+------+------------+
| Name |  Symbol   |   Type   | Description | Unit | Properties |
+======+===========+==========+=============+======+============+
|  f   | :math:`f` | ExtAlgeb |             |      |            |
+------+-----------+----------+-------------+------+------------+
|  a   | :math:`a` | ExtAlgeb |             |      |            |
+------+-----------+----------+-------------+------+------------+
|  v   | :math:`v` | ExtAlgeb |             |      |            |
+------+-----------+----------+-------------+------+------------+

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

+------+-----------+----------+---------------+
| Name |  Symbol   |   Type   | Initial Value |
+======+===========+==========+===============+
|  f   | :math:`f` | ExtAlgeb |               |
+------+-----------+----------+---------------+
|  a   | :math:`a` | ExtAlgeb |               |
+------+-----------+----------+---------------+
|  v   | :math:`v` | ExtAlgeb |               |
+------+-----------+----------+---------------+

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

+------+-----------+----------+-------------------------------+
| Name |  Symbol   |   Type   | RHS of Equation "0 = g(x, y)" |
+======+===========+==========+===============================+
|  f   | :math:`f` | ExtAlgeb | :math:`0`                     |
+------+-----------+----------+-------------------------------+
|  a   | :math:`a` | ExtAlgeb | :math:`f^{bp} pv_{0} v^{ap}`  |
+------+-----------+----------+-------------------------------+
|  v   | :math:`v` | ExtAlgeb | :math:`f^{bq} qv_{0} v^{aq}`  |
+------+-----------+----------+-------------------------------+

Services
----------

+------+-------------+---------------------------------------------+--------------+
| Name |   Symbol    |                  Equation                   |     Type     |
+======+=============+=============================================+==============+
|  pv0 | :math:`pv0` | :math:`\frac{kp p_{0} u v_{0}^{- ap}}{100}` | ConstService |
+------+-------------+---------------------------------------------+--------------+
|  qv0 | :math:`qv0` | :math:`\frac{kq q_{0} u v_{0}^{- aq}}{100}` | ConstService |
+------+-------------+---------------------------------------------+--------------+


Config Fields in [FLoad]

+---------------+--------+-------+---------------------------------------+-----------------+
|    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)          |
+---------------+--------+-------+---------------------------------------+-----------------+