.. _VoltComp:

================================================================================
VoltComp
================================================================================
Voltage compensator group for synchronous generators.

Common Parameters: u, name, rc, xc

Common Variables: vcomp

Available models:
IEEEVC_

.. _IEEEVC:

--------------------------------------------------------------------------------
IEEEVC
--------------------------------------------------------------------------------
Voltage compensator IEEEVC model.

Reference:

[1] PowerWorld, Voltage Compensator, IEEEVC, [Online],

[2] NEPLAN, Exciters Models, [Online],

Available:

https://www.powerworld.com/WebHelp/Content/TransientModels_HTML/Voltage%20Compensator%20IEEEVC.htm?TocPath=%7C%7C%7CIEEEVC%7C_____0

https://www.neplan.ch/wp-content/uploads/2015/08/Nep_EXCITERS1.pdf

Parameters
----------

+-------+-------------+-------------------------------+---------+--------+------------+
| Name  |   Symbol    |          Description          | Default |  Unit  | Properties |
+=======+=============+===============================+=========+========+============+
|  idx  |             | unique device idx             |         |        |            |
+-------+-------------+-------------------------------+---------+--------+------------+
|  u    | :math:`u`   | connection status             | 1       | *bool* |            |
+-------+-------------+-------------------------------+---------+--------+------------+
|  name |             | device name                   |         |        |            |
+-------+-------------+-------------------------------+---------+--------+------------+
|  avr  |             | Exciter idx                   |         |        | mandatory  |
+-------+-------------+-------------------------------+---------+--------+------------+
|  rc   | :math:`r_c` | Active compensation degree.   | 0       |        | z          |
+-------+-------------+-------------------------------+---------+--------+------------+
|  xc   | :math:`x_c` | Reactive compensation degree. | 0       |        | z          |
+-------+-------------+-------------------------------+---------+--------+------------+
|  syn  |             | Retrieved generator idx       | 0       |        |            |
+-------+-------------+-------------------------------+---------+--------+------------+

Variables
---------

+--------+---------------+----------+---------------------------------------+------+------------+
|  Name  |    Symbol     |   Type   |              Description              | Unit | Properties |
+========+===============+==========+=======================================+======+============+
|  vcomp | :math:`vcomp` | Algeb    | Compensator output voltage to exciter |      | v_str      |
+--------+---------------+----------+---------------------------------------+------+------------+
|  v     | :math:`v`     | ExtAlgeb | Retrieved bus terminal voltage        |      |            |
+--------+---------------+----------+---------------------------------------+------+------------+
|  vd    | :math:`vd`    | ExtAlgeb | d-axis machine voltage                |      |            |
+--------+---------------+----------+---------------------------------------+------+------------+
|  vq    | :math:`vq`    | ExtAlgeb | q-axis machine voltage                |      |            |
+--------+---------------+----------+---------------------------------------+------+------------+
|  Id    | :math:`Id`    | ExtAlgeb | d-axis machine current                |      |            |
+--------+---------------+----------+---------------------------------------+------+------------+
|  Iq    | :math:`Iq`    | ExtAlgeb | q-axis machine current                |      |            |
+--------+---------------+----------+---------------------------------------+------+------------+
|  Eterm | :math:`Eterm` | ExtAlgeb |                                       |      | v_str      |
+--------+---------------+----------+---------------------------------------+------+------------+

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

+--------+---------------+----------+---------------------+
|  Name  |    Symbol     |   Type   |    Initial Value    |
+========+===============+==========+=====================+
|  vcomp | :math:`vcomp` | Algeb    | :math:`- u v + vct` |
+--------+---------------+----------+---------------------+
|  v     | :math:`v`     | ExtAlgeb |                     |
+--------+---------------+----------+---------------------+
|  vd    | :math:`vd`    | ExtAlgeb |                     |
+--------+---------------+----------+---------------------+
|  vq    | :math:`vq`    | ExtAlgeb |                     |
+--------+---------------+----------+---------------------+
|  Id    | :math:`Id`    | ExtAlgeb |                     |
+--------+---------------+----------+---------------------+
|  Iq    | :math:`Iq`    | ExtAlgeb |                     |
+--------+---------------+----------+---------------------+
|  Eterm | :math:`Eterm` | ExtAlgeb | :math:`vcomp`       |
+--------+---------------+----------+---------------------+

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

+--------+---------------+----------+-------------------------------+
|  Name  |    Symbol     |   Type   | RHS of Equation "0 = g(x, y)" |
+========+===============+==========+===============================+
|  vcomp | :math:`vcomp` | Algeb    | :math:`- u v - vcomp + vct`   |
+--------+---------------+----------+-------------------------------+
|  v     | :math:`v`     | ExtAlgeb | :math:`0`                     |
+--------+---------------+----------+-------------------------------+
|  vd    | :math:`vd`    | ExtAlgeb | :math:`0`                     |
+--------+---------------+----------+-------------------------------+
|  vq    | :math:`vq`    | ExtAlgeb | :math:`0`                     |
+--------+---------------+----------+-------------------------------+
|  Id    | :math:`Id`    | ExtAlgeb | :math:`0`                     |
+--------+---------------+----------+-------------------------------+
|  Iq    | :math:`Iq`    | ExtAlgeb | :math:`0`                     |
+--------+---------------+----------+-------------------------------+
|  Eterm | :math:`Eterm` | ExtAlgeb | :math:`vcomp`                 |
+--------+---------------+----------+-------------------------------+

Services
----------

+------+----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+------------+
| Name |     Symbol     |                                                                       Equation                                                                       |    Type    |
+======+================+======================================================================================================================================================+============+
|  vct | :math:`V_{CT}` | :math:`u \sqrt{Id^{2} rc^{2} + Id^{2} xc^{2} + 2 Id rc vd + 2 Id vq xc + Iq^{2} rc^{2} + Iq^{2} xc^{2} + 2 Iq rc vq - 2 Iq vd xc + vd^{2} + vq^{2}}` | VarService |
+------+----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+------------+


Config Fields in [IEEEVC]

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