.. _ACLine:

================================================================================
ACLine
================================================================================
Common Parameters: u, name, bus1, bus2, r, x

Common Variables: v1, v2, a1, a2

Available models:
Line_

.. _Line:

--------------------------------------------------------------------------------
Line
--------------------------------------------------------------------------------
AC transmission line model.

The model is also used for two-winding transformer. Transformers can set the
tap ratio in ``tap`` and/or phase shift angle ``phi``.

To reduce the number of variables, line injections are summed at bus
equations and are not stored. Current injections are not computed.

Parameters
----------

+---------+------------------+---------------------------------------+---------+----------+--------------+
|  Name   |      Symbol      |              Description              | Default |   Unit   |  Properties  |
+=========+==================+=======================================+=========+==========+==============+
|  idx    |                  | unique device idx                     |         |          |              |
+---------+------------------+---------------------------------------+---------+----------+--------------+
|  u      | :math:`u`        | connection status                     | 1       | *bool*   |              |
+---------+------------------+---------------------------------------+---------+----------+--------------+
|  name   |                  | device name                           |         |          |              |
+---------+------------------+---------------------------------------+---------+----------+--------------+
|  bus1   |                  | idx of from bus                       |         |          |              |
+---------+------------------+---------------------------------------+---------+----------+--------------+
|  bus2   |                  | idx of to bus                         |         |          |              |
+---------+------------------+---------------------------------------+---------+----------+--------------+
|  Sn     | :math:`S_n`      | Power rating                          | 100     | *MW*     | non_zero     |
+---------+------------------+---------------------------------------+---------+----------+--------------+
|  fn     | :math:`f`        | rated frequency                       | 60      | *Hz*     |              |
+---------+------------------+---------------------------------------+---------+----------+--------------+
|  Vn1    | :math:`V_{n1}`   | AC voltage rating                     | 110     | *kV*     | non_zero     |
+---------+------------------+---------------------------------------+---------+----------+--------------+
|  Vn2    | :math:`V_{n2}`   | rated voltage of bus2                 | 110     | *kV*     | non_zero     |
+---------+------------------+---------------------------------------+---------+----------+--------------+
|  r      | :math:`r`        | line resistance                       | 0.000   | *p.u.*   | z            |
+---------+------------------+---------------------------------------+---------+----------+--------------+
|  x      | :math:`x`        | line reactance                        | 0.000   | *p.u.*   | non_zero,z   |
+---------+------------------+---------------------------------------+---------+----------+--------------+
|  b      |                  | shared shunt susceptance              | 0       | *p.u.*   | y            |
+---------+------------------+---------------------------------------+---------+----------+--------------+
|  g      |                  | shared shunt conductance              | 0       | *p.u.*   | y            |
+---------+------------------+---------------------------------------+---------+----------+--------------+
|  b1     | :math:`b_1`      | from-side susceptance                 | 0       | *p.u.*   | y            |
+---------+------------------+---------------------------------------+---------+----------+--------------+
|  g1     | :math:`g_1`      | from-side conductance                 | 0       | *p.u.*   | y            |
+---------+------------------+---------------------------------------+---------+----------+--------------+
|  b2     | :math:`b_2`      | to-side susceptance                   | 0       | *p.u.*   | y            |
+---------+------------------+---------------------------------------+---------+----------+--------------+
|  g2     | :math:`g_2`      | to-side conductance                   | 0       | *p.u.*   | y            |
+---------+------------------+---------------------------------------+---------+----------+--------------+
|  trans  |                  | transformer branch flag               | 0       | *bool*   |              |
+---------+------------------+---------------------------------------+---------+----------+--------------+
|  tap    | :math:`t_{ap}`   | transformer branch tap ratio          | 1       | *float*  | non_negative |
+---------+------------------+---------------------------------------+---------+----------+--------------+
|  phi    | :math:`\phi`     | transformer branch phase shift in rad | 0       | *radian* |              |
+---------+------------------+---------------------------------------+---------+----------+--------------+
|  rate_a | :math:`R_{ATEA}` | long-term flow limit (placeholder)    | 0       | *MVA*    |              |
+---------+------------------+---------------------------------------+---------+----------+--------------+
|  rate_b | :math:`R_{ATEB}` | short-term flow limit (placeholder)   | 0       | *MVA*    |              |
+---------+------------------+---------------------------------------+---------+----------+--------------+
|  rate_c | :math:`R_{ATEC}` | emergency flow limit (placeholder)    | 0       | *MVA*    |              |
+---------+------------------+---------------------------------------+---------+----------+--------------+
|  owner  |                  | owner code                            |         |          |              |
+---------+------------------+---------------------------------------+---------+----------+--------------+
|  xcoord |                  | x coordinates                         |         |          |              |
+---------+------------------+---------------------------------------+---------+----------+--------------+
|  ycoord |                  | y coordinates                         |         |          |              |
+---------+------------------+---------------------------------------+---------+----------+--------------+

Variables
---------

+------+---------------+----------+-----------------------------------+------+------------+
| Name |    Symbol     |   Type   |            Description            | Unit | Properties |
+======+===============+==========+===================================+======+============+
|  a1  | :math:`a_{1}` | ExtAlgeb | phase angle of the from bus       |      |            |
+------+---------------+----------+-----------------------------------+------+------------+
|  a2  | :math:`a_{2}` | ExtAlgeb | phase angle of the to bus         |      |            |
+------+---------------+----------+-----------------------------------+------+------------+
|  v1  | :math:`v_{1}` | ExtAlgeb | voltage magnitude of the from bus |      |            |
+------+---------------+----------+-----------------------------------+------+------------+
|  v2  | :math:`v_{2}` | ExtAlgeb | voltage magnitude of the to bus   |      |            |
+------+---------------+----------+-----------------------------------+------+------------+

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

+------+---------------+----------+---------------+
| Name |    Symbol     |   Type   | Initial Value |
+======+===============+==========+===============+
|  a1  | :math:`a_{1}` | ExtAlgeb |               |
+------+---------------+----------+---------------+
|  a2  | :math:`a_{2}` | ExtAlgeb |               |
+------+---------------+----------+---------------+
|  v1  | :math:`v_{1}` | ExtAlgeb |               |
+------+---------------+----------+---------------+
|  v2  | :math:`v_{2}` | ExtAlgeb |               |
+------+---------------+----------+---------------+

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

+------+---------------+----------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Name |    Symbol     |   Type   |                                                                                    RHS of Equation "0 = g(x, y)"                                                                                    |
+======+===============+==========+=====================================================================================================================================================================================================+
|  a1  | :math:`a_{1}` | ExtAlgeb | :math:`u \left(- itap v_{1} v_{2} \left(- bhk \sin{\left(- a_{1} + a_{2} + \phi \right)} + ghk \cos{\left(- a_{1} + a_{2} + \phi \right)}\right) + itap_{2} v_{1}^{2} \left(gh + ghk\right)\right)` |
+------+---------------+----------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|  a2  | :math:`a_{2}` | ExtAlgeb | :math:`u \left(- itap v_{1} v_{2} \left(bhk \sin{\left(- a_{1} + a_{2} + \phi \right)} + ghk \cos{\left(- a_{1} + a_{2} + \phi \right)}\right) + v_{2}^{2} \left(gh + ghk\right)\right)`            |
+------+---------------+----------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|  v1  | :math:`v_{1}` | ExtAlgeb | :math:`u \left(- itap v_{1} v_{2} \left(- bhk \cos{\left(- a_{1} + a_{2} + \phi \right)} - ghk \sin{\left(- a_{1} + a_{2} + \phi \right)}\right) - itap_{2} v_{1}^{2} \left(bh + bhk\right)\right)` |
+------+---------------+----------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|  v2  | :math:`v_{2}` | ExtAlgeb | :math:`u \left(itap v_{1} v_{2} \left(bhk \cos{\left(- a_{1} + a_{2} + \phi \right)} - ghk \sin{\left(- a_{1} + a_{2} + \phi \right)}\right) - v_{2}^{2} \left(bh + bhk\right)\right)`              |
+------+---------------+----------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Services
----------

+--------+--------------------+--------------------------------------------------------------------------------+--------------+
|  Name  |       Symbol       |                                    Equation                                    |     Type     |
+========+====================+================================================================================+==============+
|  gh    | :math:`g_h`        | :math:`0.5 g + g_{1}`                                                          | ConstService |
+--------+--------------------+--------------------------------------------------------------------------------+--------------+
|  bh    | :math:`b_h`        | :math:`0.5 b + b_{1}`                                                          | ConstService |
+--------+--------------------+--------------------------------------------------------------------------------+--------------+
|  gk    | :math:`g_k`        | :math:`0.5 g + g_{2}`                                                          | ConstService |
+--------+--------------------+--------------------------------------------------------------------------------+--------------+
|  bk    | :math:`b_k`        | :math:`0.5 b + b_{2}`                                                          | ConstService |
+--------+--------------------+--------------------------------------------------------------------------------+--------------+
|  yh    | :math:`y_h`        | :math:`u \left(i bh + gh\right)`                                               | ConstService |
+--------+--------------------+--------------------------------------------------------------------------------+--------------+
|  yk    | :math:`y_k`        | :math:`u \left(i bk + gk\right)`                                               | ConstService |
+--------+--------------------+--------------------------------------------------------------------------------+--------------+
|  yhk   | :math:`y_{hk}`     | :math:`\frac{u}{r + i \left(x + 1.0 \cdot 10^{-8}\right) + 1.0 \cdot 10^{-8}}` | ConstService |
+--------+--------------------+--------------------------------------------------------------------------------+--------------+
|  ghk   | :math:`g_{hk}`     | :math:`\operatorname{re}{\left(yhk\right)}`                                    | ConstService |
+--------+--------------------+--------------------------------------------------------------------------------+--------------+
|  bhk   | :math:`b_{hk}`     | :math:`\operatorname{im}{\left(yhk\right)}`                                    | ConstService |
+--------+--------------------+--------------------------------------------------------------------------------+--------------+
|  itap  | :math:`1/t_{ap}`   | :math:`\frac{1}{tap}`                                                          | ConstService |
+--------+--------------------+--------------------------------------------------------------------------------+--------------+
|  itap2 | :math:`1/t_{ap}^2` | :math:`\frac{1}{tap^{2}}`                                                      | ConstService |
+--------+--------------------+--------------------------------------------------------------------------------+--------------+


Config Fields in [Line]

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