.. _StaticACDC:

================================================================================
StaticACDC
================================================================================
AC DC device for power flow

Common Parameters: u, name

Available models:
VSCShunt_

.. _VSCShunt:

--------------------------------------------------------------------------------
VSCShunt
--------------------------------------------------------------------------------
Data for VSC Shunt in power flow

Parameters
----------

+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|   Name   |      Symbol      |                        Description                        | Default |   Unit    | Properties |
+==========+==================+===========================================================+=========+===========+============+
|  idx     |                  | unique device idx                                         |         |           |            |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  u       | :math:`u`        | connection status                                         | 1       | *bool*    |            |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  name    |                  | device name                                               |         |           |            |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  bus     |                  | idx of connected bus                                      |         |           | mandatory  |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  node1   |                  | Node 1 index                                              |         |           | mandatory  |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  node2   |                  | Node 2 index                                              |         |           | mandatory  |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  Vn      | :math:`V_n`      | AC voltage rating                                         | 110     |           | non_zero   |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  Vdcn1   | :math:`V_{dcn1}` | DC voltage rating on node 1                               | 100     | *kV*      | non_zero   |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  Vdcn2   | :math:`V_{dcn2}` | DC voltage rating on node 2                               | 100     | *kV*      | non_zero   |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  Idcn    | :math:`I_{dcn}`  | DC current rating                                         | 1       | *kA*      | non_zero   |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  rsh     | :math:`r_{sh}`   | AC interface resistance                                   | 0.003   | *ohm*     | z          |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  xsh     | :math:`x_{sh}`   | AC interface reactance                                    | 0.060   | *ohm*     | z          |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  control |                  | Control method: 0-PQ, 1-PV, 2-vQ or 3-vV                  |         |           | mandatory  |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  v0      |                  | AC voltage setting (PV or vV) or initial guess (PQ or vQ) | 1       |           |            |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  p0      |                  | AC active power setting                                   | 0       | *pu*      |            |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  q0      |                  | AC reactive power setting                                 | 0       | *pu*      |            |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  vdc0    | :math:`v_{dc0}`  | DC voltage setting                                        | 1       | *pu*      |            |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  k0      |                  | Loss coefficient - constant                               | 0       |           |            |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  k1      |                  | Loss coefficient - linear                                 | 0       |           |            |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  k2      |                  | Loss coefficient - quadratic                              | 0       |           |            |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  droop   |                  | Enable dc voltage droop control                           | 0       | *boolean* |            |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  K       |                  | Droop coefficient                                         | 0       |           |            |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  vhigh   |                  | Upper voltage threshold in droop control                  | 9999    | *pu*      |            |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  vlow    |                  | Lower voltage threshold in droop control                  | 0       | *pu*      |            |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  vshmax  |                  | Maximum ac interface voltage                              | 1.100   | *pu*      |            |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  vshmin  |                  | Minimum ac interface voltage                              | 0.900   | *pu*      |            |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+
|  Ishmax  |                  | Maximum ac current                                        | 2       | *pu*      |            |
+----------+------------------+-----------------------------------------------------------+---------+-----------+------------+

Variables
---------

+------+---------------+----------+--------------------------------------+--------+------------+
| Name |    Symbol     |   Type   |             Description              |  Unit  | Properties |
+======+===============+==========+======================================+========+============+
|  ash | :math:`ash`   | Algeb    | voltage phase behind the transformer | *rad*  | v_str      |
+------+---------------+----------+--------------------------------------+--------+------------+
|  vsh | :math:`vsh`   | Algeb    | voltage magnitude behind transformer | *p.u.* | v_str      |
+------+---------------+----------+--------------------------------------+--------+------------+
|  psh | :math:`psh`   | Algeb    | active power injection into VSC      | *p.u.* | v_str      |
+------+---------------+----------+--------------------------------------+--------+------------+
|  qsh | :math:`qsh`   | Algeb    | reactive power injection into VSC    |        | v_str      |
+------+---------------+----------+--------------------------------------+--------+------------+
|  pdc | :math:`pdc`   | Algeb    | DC power injection                   |        | v_str      |
+------+---------------+----------+--------------------------------------+--------+------------+
|  a   | :math:`a`     | ExtAlgeb | AC bus voltage phase                 |        |            |
+------+---------------+----------+--------------------------------------+--------+------------+
|  v   | :math:`v`     | ExtAlgeb | AC bus voltage magnitude             |        |            |
+------+---------------+----------+--------------------------------------+--------+------------+
|  v1  | :math:`v_{1}` | ExtAlgeb | DC node 1 voltage                    |        |            |
+------+---------------+----------+--------------------------------------+--------+------------+
|  v2  | :math:`v_{2}` | ExtAlgeb | DC node 2 voltage                    |        |            |
+------+---------------+----------+--------------------------------------+--------+------------+

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

+------+---------------+----------+--------------------------------------------------+
| Name |    Symbol     |   Type   |                  Initial Value                   |
+======+===============+==========+==================================================+
|  ash | :math:`ash`   | Algeb    | :math:`a`                                        |
+------+---------------+----------+--------------------------------------------------+
|  vsh | :math:`vsh`   | Algeb    | :math:`v_{0}`                                    |
+------+---------------+----------+--------------------------------------------------+
|  psh | :math:`psh`   | Algeb    | :math:`p_{0} \left(mode_{s0} + mode_{s1}\right)` |
+------+---------------+----------+--------------------------------------------------+
|  qsh | :math:`qsh`   | Algeb    | :math:`q_{0} \left(mode_{s0} + mode_{s2}\right)` |
+------+---------------+----------+--------------------------------------------------+
|  pdc | :math:`pdc`   | Algeb    | :math:`0`                                        |
+------+---------------+----------+--------------------------------------------------+
|  a   | :math:`a`     | ExtAlgeb |                                                  |
+------+---------------+----------+--------------------------------------------------+
|  v   | :math:`v`     | ExtAlgeb |                                                  |
+------+---------------+----------+--------------------------------------------------+
|  v1  | :math:`v_{1}` | ExtAlgeb |                                                  |
+------+---------------+----------+--------------------------------------------------+
|  v2  | :math:`v_{2}` | ExtAlgeb |                                                  |
+------+---------------+----------+--------------------------------------------------+

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

+------+---------------+----------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| Name |    Symbol     |   Type   |                                                           RHS of Equation "0 = g(x, y)"                                                           |
+======+===============+==========+===================================================================================================================================================+
|  ash | :math:`ash`   | Algeb    | :math:`- psh + u \left(- bsh v vsh \sin{\left(a - ash \right)} + gsh v^{2} - gsh v vsh \cos{\left(a - ash \right)}\right)`                        |
+------+---------------+----------+---------------------------------------------------------------------------------------------------------------------------------------------------+
|  vsh | :math:`vsh`   | Algeb    | :math:`- qsh + u \left(- bsh v^{2} + bsh v vsh \cos{\left(a - ash \right)} - gsh v vsh \sin{\left(a - ash \right)}\right)`                        |
+------+---------------+----------+---------------------------------------------------------------------------------------------------------------------------------------------------+
|  psh | :math:`psh`   | Algeb    | :math:`u \left(mode_{s0} + mode_{s1}\right) \left(p_{0} - psh\right) + u \left(mode_{s2} + mode_{s3}\right) \left(v_{1} - v_{2} - vdc_{0}\right)` |
+------+---------------+----------+---------------------------------------------------------------------------------------------------------------------------------------------------+
|  qsh | :math:`qsh`   | Algeb    | :math:`u \left(mode_{s0} + mode_{s2}\right) \left(q_{0} - qsh\right) + u \left(mode_{s1} + mode_{s3}\right) \left(- v + v_{0}\right)`             |
+------+---------------+----------+---------------------------------------------------------------------------------------------------------------------------------------------------+
|  pdc | :math:`pdc`   | Algeb    | :math:`pdc + u \left(bsh v vsh \sin{\left(a - ash \right)} - gsh v vsh \cos{\left(a - ash \right)} + gsh vsh^{2}\right)`                          |
+------+---------------+----------+---------------------------------------------------------------------------------------------------------------------------------------------------+
|  a   | :math:`a`     | ExtAlgeb | :math:`- psh`                                                                                                                                     |
+------+---------------+----------+---------------------------------------------------------------------------------------------------------------------------------------------------+
|  v   | :math:`v`     | ExtAlgeb | :math:`- qsh`                                                                                                                                     |
+------+---------------+----------+---------------------------------------------------------------------------------------------------------------------------------------------------+
|  v1  | :math:`v_{1}` | ExtAlgeb | :math:`- \frac{pdc}{v_{1} - v_{2}}`                                                                                                               |
+------+---------------+----------+---------------------------------------------------------------------------------------------------------------------------------------------------+
|  v2  | :math:`v_{2}` | ExtAlgeb | :math:`\frac{pdc}{v_{1} - v_{2}}`                                                                                                                 |
+------+---------------+----------+---------------------------------------------------------------------------------------------------------------------------------------------------+

Services
----------

+------+----------------+-----------------------------------------+--------------+
| Name |     Symbol     |                Equation                 |     Type     |
+======+================+=========================================+==============+
|  gsh | :math:`g_{sh}` | :math:`\frac{rsh}{rsh^{2} + xsh^{2}}`   | ConstService |
+------+----------------+-----------------------------------------+--------------+
|  bsh | :math:`b_{sh}` | :math:`- \frac{xsh}{rsh^{2} + xsh^{2}}` | ConstService |
+------+----------------+-----------------------------------------+--------------+

Discretes
-----------

+-------+--------------+----------+------+
| Name  |    Symbol    |   Type   | Info |
+=======+==============+==========+======+
|  mode | :math:`mode` | Switcher |      |
+-------+--------------+----------+------+


Config Fields in [VSCShunt]

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