.. _ACLine:

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

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``.

Note that the bus admittance matrix is built on fly and is not stored in the
object.

Notes
-----
1. Adding Algeb ``ud`` causes Line.algebs to encounter an AttributeError: 'NoneType'
   object has no attribute 'n'. The root cause is still under investigation.

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)          | 999     | *p.u.*   |              |
+---------+------------------+---------------------------------------------+---------+----------+--------------+
|  rate_b | :math:`R_{ATEB}` | short-term flow limit (placeholder)         | 999     | *p.u.*   |              |
+---------+------------------+---------------------------------------------+---------+----------+--------------+
|  rate_c | :math:`R_{ATEC}` | emergency flow limit (placeholder)          | 999     | *p.u.*   |              |
+---------+------------------+---------------------------------------------+---------+----------+--------------+
|  owner  |                  | owner code                                  |         |          |              |
+---------+------------------+---------------------------------------------+---------+----------+--------------+
|  xcoord |                  | x coordinates                               |         |          |              |
+---------+------------------+---------------------------------------------+---------+----------+--------------+
|  ycoord |                  | y coordinates                               |         |          |              |
+---------+------------------+---------------------------------------------+---------+----------+--------------+
|  amin   | :math:`a_{min}`  | minimum angle difference, from bus - to bus | -6.283  | *rad*    |              |
+---------+------------------+---------------------------------------------+---------+----------+--------------+
|  amax   | :math:`a_{max}`  | maximum angle difference, from bus - to bus | 6.283   | *rad*    |              |
+---------+------------------+---------------------------------------------+---------+----------+--------------+