.. _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:`v_{comp}` | Algeb    | Compensator output voltage to exciter |      | v_str      |
+--------+------------------+----------+---------------------------------------+------+------------+
|  v     | :math:`V`        | ExtAlgeb | Retrieved bus terminal voltage        |      |            |
+--------+------------------+----------+---------------------------------------+------+------------+
|  vd    | :math:`V_{d}`    | ExtAlgeb | d-axis machine voltage                |      |            |
+--------+------------------+----------+---------------------------------------+------+------------+
|  vq    | :math:`V_{q}`    | ExtAlgeb | q-axis machine voltage                |      |            |
+--------+------------------+----------+---------------------------------------+------+------------+
|  Id    | :math:`I_{d}`    | ExtAlgeb | d-axis machine current                |      |            |
+--------+------------------+----------+---------------------------------------+------+------------+
|  Iq    | :math:`I_{q}`    | ExtAlgeb | q-axis machine current                |      |            |
+--------+------------------+----------+---------------------------------------+------+------------+
|  Eterm | :math:`Eterm`    | ExtAlgeb |                                       |      | v_str      |
+--------+------------------+----------+---------------------------------------+------+------------+

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

+--------+------------------+----------+------------------------+
|  Name  |      Symbol      |   Type   |     Initial Value      |
+========+==================+==========+========================+
|  vcomp | :math:`v_{comp}` | Algeb    | :math:`- V u + V_{CT}` |
+--------+------------------+----------+------------------------+
|  v     | :math:`V`        | ExtAlgeb |                        |
+--------+------------------+----------+------------------------+
|  vd    | :math:`V_{d}`    | ExtAlgeb |                        |
+--------+------------------+----------+------------------------+
|  vq    | :math:`V_{q}`    | ExtAlgeb |                        |
+--------+------------------+----------+------------------------+
|  Id    | :math:`I_{d}`    | ExtAlgeb |                        |
+--------+------------------+----------+------------------------+
|  Iq    | :math:`I_{q}`    | ExtAlgeb |                        |
+--------+------------------+----------+------------------------+
|  Eterm | :math:`Eterm`    | ExtAlgeb | :math:`v_{comp}`       |
+--------+------------------+----------+------------------------+

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

+--------+------------------+----------+-----------------------------------+
|  Name  |      Symbol      |   Type   |   RHS of Equation "0 = g(x, y)"   |
+========+==================+==========+===================================+
|  vcomp | :math:`v_{comp}` | Algeb    | :math:`- V u + V_{CT} - v_{comp}` |
+--------+------------------+----------+-----------------------------------+
|  v     | :math:`V`        | ExtAlgeb | :math:`0`                         |
+--------+------------------+----------+-----------------------------------+
|  vd    | :math:`V_{d}`    | ExtAlgeb | :math:`0`                         |
+--------+------------------+----------+-----------------------------------+
|  vq    | :math:`V_{q}`    | ExtAlgeb | :math:`0`                         |
+--------+------------------+----------+-----------------------------------+
|  Id    | :math:`I_{d}`    | ExtAlgeb | :math:`0`                         |
+--------+------------------+----------+-----------------------------------+
|  Iq    | :math:`I_{q}`    | ExtAlgeb | :math:`0`                         |
+--------+------------------+----------+-----------------------------------+
|  Eterm | :math:`Eterm`    | ExtAlgeb | :math:`v_{comp}`                  |
+--------+------------------+----------+-----------------------------------+

Services
----------

+------+----------------+------------------------------------------------------------------------------------------------------+------------+
| Name |     Symbol     |                                               Equation                                               |    Type    |
+======+================+======================================================================================================+============+
|  vct | :math:`V_{CT}` | :math:`u \left|{V_{d} + i V_{q} + \left(I_{d} + i I_{q}\right) \left(r_{c} + i x_{c}\right)}\right|` | 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)          |
+---------------+--------+-------+---------------------------------------+-----------------+