.. _ACTopology:

================================================================================
ACTopology
================================================================================
Common Parameters: u, name

Common Variables: a, v

Available models:
Bus_

.. _Bus:

--------------------------------------------------------------------------------
Bus
--------------------------------------------------------------------------------
AC Bus model.

Power balance equation have the form of ``load - injection = 0``.
Namely, load is positively summed, while injections are negative.

Parameters
----------

+---------+------------------+-----------------------------+---------+--------+------------+
|  Name   |      Symbol      |         Description         | Default |  Unit  | Properties |
+=========+==================+=============================+=========+========+============+
|  idx    |                  | unique device idx           |         |        |            |
+---------+------------------+-----------------------------+---------+--------+------------+
|  u      | :math:`u`        | connection status           | 1       | *bool* |            |
+---------+------------------+-----------------------------+---------+--------+------------+
|  name   |                  | device name                 |         |        |            |
+---------+------------------+-----------------------------+---------+--------+------------+
|  Vn     | :math:`V_n`      | AC voltage rating           | 110     | *kV*   | non_zero   |
+---------+------------------+-----------------------------+---------+--------+------------+
|  vmax   | :math:`V_{max}`  | Voltage upper limit         | 1.100   | *p.u.* |            |
+---------+------------------+-----------------------------+---------+--------+------------+
|  vmin   | :math:`V_{min}`  | Voltage lower limit         | 0.900   | *p.u.* |            |
+---------+------------------+-----------------------------+---------+--------+------------+
|  v0     | :math:`V_0`      | initial voltage magnitude   | 1       | *p.u.* | non_zero   |
+---------+------------------+-----------------------------+---------+--------+------------+
|  a0     | :math:`\theta_0` | initial voltage phase angle | 0       | *rad*  |            |
+---------+------------------+-----------------------------+---------+--------+------------+
|  xcoord |                  | x coordinate (longitude)    | 0       |        |            |
+---------+------------------+-----------------------------+---------+--------+------------+
|  ycoord |                  | y coordinate (latitude)     | 0       |        |            |
+---------+------------------+-----------------------------+---------+--------+------------+
|  area   |                  | Area code                   |         |        |            |
+---------+------------------+-----------------------------+---------+--------+------------+
|  zone   |                  | Zone code                   |         |        |            |
+---------+------------------+-----------------------------+---------+--------+------------+
|  owner  |                  | Owner code                  |         |        |            |
+---------+------------------+-----------------------------+---------+--------+------------+

Variables
---------

+------+----------------+-------+-------------------+--------+------------+
| Name |     Symbol     | Type  |    Description    |  Unit  | Properties |
+======+================+=======+===================+========+============+
|  a   | :math:`\theta` | Algeb | voltage angle     | *rad*  | v_str      |
+------+----------------+-------+-------------------+--------+------------+
|  v   | :math:`V`      | Algeb | voltage magnitude | *p.u.* | v_str      |
+------+----------------+-------+-------------------+--------+------------+

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

+------+----------------+-------+---------------------------------------------------------------------------------+
| Name |     Symbol     | Type  |                                  Initial Value                                  |
+======+================+=======+=================================================================================+
|  a   | :math:`\theta` | Algeb | :math:`\theta_{0} \cdot \left(1 - z_{flat}\right) + 1.0 \cdot 10^{-8} z_{flat}` |
+------+----------------+-------+---------------------------------------------------------------------------------+
|  v   | :math:`V`      | Algeb | :math:`V_{0} \cdot \left(1 - z_{flat}\right) + z_{flat}`                        |
+------+----------------+-------+---------------------------------------------------------------------------------+

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

+------+----------------+-------+-------------------------------+
| Name |     Symbol     | Type  | RHS of Equation "0 = g(x, y)" |
+======+================+=======+===============================+
|  a   | :math:`\theta` | Algeb | :math:`0`                     |
+------+----------------+-------+-------------------------------+
|  v   | :math:`V`      | Algeb | :math:`0`                     |
+------+----------------+-------+-------------------------------+


Config Fields in [Bus]

+---------------+------------------+-------+---------------------------------------+-----------------+
|    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)          |
+---------------+------------------+-------+---------------------------------------+-----------------+
|  flat_start   | :math:`z_{flat}` | 0     | flat start for voltages               | (0, 1)          |
+---------------+------------------+-------+---------------------------------------+-----------------+