ltbams 0.9.9__py3-none-any.whl → 1.0.0__py3-none-any.whl

docs/source/groupdoc/ACLine.rst

@@ -0,0 +1,92 @@
+.. _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
+-----
+There is a known issue that adding Algeb ``ud`` will cause Line.algebs run into
+AttributeError: 'NoneType' object has no attribute 'n'. Not figured out why yet.
+
+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*    |              |
++---------+------------------+---------------------------------------------+---------+----------+--------------+
+
+

docs/source/groupdoc/ACShort.rst

@@ -0,0 +1,51 @@
+.. _ACShort:
+
+================================================================================
+ACShort
+================================================================================
+Common Parameters: u, name, idx, bus1, bus2
+
+Available models:
+Jumper_
+
+.. _Jumper:
+
+--------------------------------------------------------------------------------
+Jumper
+--------------------------------------------------------------------------------
+Jumper is a device to short two buses (merging two buses into one).
+
+Jumper can connect two buses satisfying one of the following conditions:
+
+- neither bus is voltage-controlled
+- either bus is voltage-controlled
+- both buses are voltage-controlled, and the voltages are the same.
+
+If the buses are controlled in different voltages, power flow will
+not solve (as the power flow through the jumper will be infinite).
+
+In the solutions, the ``p`` and ``q`` are flowing out of bus1
+and flowing into bus2.
+
+Setting a Jumper's connectivity status ``u`` to zero will disconnect the two
+buses. In the case of a system split, one will need to call
+``System.connectivity()`` immediately following the split to detect islands.
+
+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     |         |        |            |
++-------+-----------+-------------------+---------+--------+------------+
+
+

docs/source/groupdoc/ACTopology.rst

@@ -0,0 +1,66 @@
+.. _ACTopology:
+
+================================================================================
+ACTopology
+================================================================================
+Common Parameters: u, name, idx
+
+Common Variables: a, v
+
+Available models:
+Bus_
+
+.. _Bus:
+
+--------------------------------------------------------------------------------
+Bus
+--------------------------------------------------------------------------------
+AC Bus model.
+
+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                                             |         |        |            |
++---------+------------------+--------------------------------------------------------+---------+--------+------------+
+|  type   | :math:`type`     | bus type, 1=PQ, 2=PV, 3=ref, 4=isolated (place holder) | 1       |        |            |
++---------+------------------+--------------------------------------------------------+---------+--------+------------+
+
+Variables
+---------
+
++------+----------------+-------+-------------------+--------+
+| Name |     Symbol     | Type  |    Description    |  Unit  |
++======+================+=======+===================+========+
+|  a   | :math:`\theta` | Algeb | voltage angle     | *rad*  |
++------+----------------+-------+-------------------+--------+
+|  v   | :math:`V`      | Algeb | voltage magnitude | *p.u.* |
++------+----------------+-------+-------------------+--------+
+
+

docs/source/groupdoc/Collection.rst

@@ -0,0 +1,84 @@
+.. _Collection:
+
+================================================================================
+Collection
+================================================================================
+Collection of topology models
+
+Common Parameters: u, name, idx
+
+Available models:
+Area_,
+Zone_
+
+.. _Area:
+
+--------------------------------------------------------------------------------
+Area
+--------------------------------------------------------------------------------
+Area model.
+
+Parameters
+----------
+
++-------+-----------+-------------------+---------+--------+------------+
+| Name  |  Symbol   |    Description    | Default |  Unit  | Properties |
++=======+===========+===================+=========+========+============+
+|  idx  |           | unique device idx |         |        |            |
++-------+-----------+-------------------+---------+--------+------------+
+|  u    | :math:`u` | connection status | 1       | *bool* |            |
++-------+-----------+-------------------+---------+--------+------------+
+|  name |           | device name       |         |        |            |
++-------+-----------+-------------------+---------+--------+------------+
+
+Services
+----------
+
++-------------+-------------+--------------------+---------+
+|    Name     | Description |       Symbol       |  Type   |
++=============+=============+====================+=========+
+|  Bus        |             | :math:`Bus`        | BackRef |
++-------------+-------------+--------------------+---------+
+|  ACTopology |             | :math:`ACTopology` | BackRef |
++-------------+-------------+--------------------+---------+
+
+
+.. _Zone:
+
+--------------------------------------------------------------------------------
+Zone
+--------------------------------------------------------------------------------
+Zone model for zonal items.
+
+An ``area`` can have multiple zones.
+
+Notes
+-----
+1. Zone is a collection of buses.
+2. Model ``Zone`` is not actually defined in ANDES.
+
+Parameters
+----------
+
++-------+-----------+-------------------+---------+--------+------------+
+| Name  |  Symbol   |    Description    | Default |  Unit  | Properties |
++=======+===========+===================+=========+========+============+
+|  idx  |           | unique device idx |         |        |            |
++-------+-----------+-------------------+---------+--------+------------+
+|  u    | :math:`u` | connection status | 1       | *bool* |            |
++-------+-----------+-------------------+---------+--------+------------+
+|  name |           | device name       |         |        |            |
++-------+-----------+-------------------+---------+--------+------------+
+
+Services
+----------
+
++-------------+-------------+--------------------+---------+
+|    Name     | Description |       Symbol       |  Type   |
++=============+=============+====================+=========+
+|  Bus        |             | :math:`Bus`        | BackRef |
++-------------+-------------+--------------------+---------+
+|  ACTopology |             | :math:`ACTopology` | BackRef |
++-------------+-------------+--------------------+---------+
+
+

docs/source/groupdoc/Cost.rst

@@ -0,0 +1,135 @@
+.. _Cost:
+
+================================================================================
+Cost
+================================================================================
+Common Parameters: u, name, idx, gen
+
+Available models:
+GCost_,
+SFRCost_,
+VSGCost_,
+DCost_
+
+.. _GCost:
+
+--------------------------------------------------------------------------------
+GCost
+--------------------------------------------------------------------------------
+Generator cost model, similar to MATPOWER ``gencost`` format.
+
+``type`` is the cost model type. 1 for piecewise linear, 2 for polynomial.
+
+In piecewise linear cost model, cost function f(p) is defined by a set of points:
+(p0, c0), (p1, c1), (p2, c2), where p0 < p1 < p2.
+
+In quadratic cost model, cost function f(p) is defined by a set of coefficients:
+f(p) = c2 * p^2 + c1 * p + c0.
+
+Parameters
+----------
+
++-------+-----------------+-----------------------------------------------------------+---------+----------------+------------+
+| Name  |     Symbol      |                        Description                        | Default |      Unit      | Properties |
++=======+=================+===========================================================+=========+================+============+
+|  idx  |                 | unique device idx                                         |         |                |            |
++-------+-----------------+-----------------------------------------------------------+---------+----------------+------------+
+|  u    | :math:`u`       | connection status                                         | 1       | *bool*         |            |
++-------+-----------------+-----------------------------------------------------------+---------+----------------+------------+
+|  name |                 | device name                                               |         |                |            |
++-------+-----------------+-----------------------------------------------------------+---------+----------------+------------+
+|  gen  |                 | static generator index                                    |         |                | mandatory  |
++-------+-----------------+-----------------------------------------------------------+---------+----------------+------------+
+|  type | :math:`t_{ype}` | Cost model type. 1 for piecewise linear, 2 for polynomial | 2       |                |            |
++-------+-----------------+-----------------------------------------------------------+---------+----------------+------------+
+|  csu  | :math:`c_{su}`  | startup cost in US dollars                                | 0       | *$*            |            |
++-------+-----------------+-----------------------------------------------------------+---------+----------------+------------+
+|  csd  | :math:`c_{sd}`  | shutdown cost in US dollars                               | 0       | *$*            |            |
++-------+-----------------+-----------------------------------------------------------+---------+----------------+------------+
+|  c2   | :math:`c_{2}`   | coefficient 2                                             | 0       | *$/(p.u.*h)^2* |            |
++-------+-----------------+-----------------------------------------------------------+---------+----------------+------------+
+|  c1   | :math:`c_{1}`   | coefficient 1                                             | 0       | *$/p.u.*h*     |            |
++-------+-----------------+-----------------------------------------------------------+---------+----------------+------------+
+|  c0   | :math:`c_{0}`   | coefficient 0                                             | 0       | *$*            |            |
++-------+-----------------+-----------------------------------------------------------+---------+----------------+------------+
+
+
+.. _SFRCost:
+
+--------------------------------------------------------------------------------
+SFRCost
+--------------------------------------------------------------------------------
+Linear SFR cost model.
+
+Parameters
+----------
+
++-------+---------------+------------------------+---------+--------------+------------+
+| Name  |    Symbol     |      Description       | Default |     Unit     | Properties |
++=======+===============+========================+=========+==============+============+
+|  idx  |               | unique device idx      |         |              |            |
++-------+---------------+------------------------+---------+--------------+------------+
+|  u    | :math:`u`     | connection status      | 1       | *bool*       |            |
++-------+---------------+------------------------+---------+--------------+------------+
+|  name |               | device name            |         |              |            |
++-------+---------------+------------------------+---------+--------------+------------+
+|  gen  |               | static generator index |         |              | mandatory  |
++-------+---------------+------------------------+---------+--------------+------------+
+|  cru  | :math:`c_{r}` | cost for RegUp reserve | 0       | *$/(p.u.*h)* |            |
++-------+---------------+------------------------+---------+--------------+------------+
+|  crd  | :math:`c_{r}` | cost for RegDn reserve | 0       | *$/(p.u.*h)* |            |
++-------+---------------+------------------------+---------+--------------+------------+
+
+
+.. _VSGCost:
+
+--------------------------------------------------------------------------------
+VSGCost
+--------------------------------------------------------------------------------
+Linear cost model for VSG emulated inertia (M) and damping (D).
+
+Parameters
+----------
+
++-------+---------------+-------------------------------+---------+----------+------------+
+| Name  |    Symbol     |          Description          | Default |   Unit   | Properties |
++=======+===============+===============================+=========+==========+============+
+|  idx  |               | unique device idx             |         |          |            |
++-------+---------------+-------------------------------+---------+----------+------------+
+|  u    | :math:`u`     | connection status             | 1       | *bool*   |            |
++-------+---------------+-------------------------------+---------+----------+------------+
+|  name |               | device name                   |         |          |            |
++-------+---------------+-------------------------------+---------+----------+------------+
+|  reg  |               | Renewable generator idx       |         |          | mandatory  |
++-------+---------------+-------------------------------+---------+----------+------------+
+|  cm   | :math:`c_{r}` | cost for emulated inertia (M) | 0       | *$/s*    |            |
++-------+---------------+-------------------------------+---------+----------+------------+
+|  cd   | :math:`c_{r}` | cost for emulated damping (D) | 0       | *$/p.u.* |            |
++-------+---------------+-------------------------------+---------+----------+------------+
+
+
+.. _DCost:
+
+--------------------------------------------------------------------------------
+DCost
+--------------------------------------------------------------------------------
+Linear cost model for dispatchable loads.
+
+Parameters
+----------
+
++-------+-----------------+-------------------------------+---------+--------------+------------+
+| Name  |     Symbol      |          Description          | Default |     Unit     | Properties |
++=======+=================+===============================+=========+==============+============+
+|  idx  |                 | unique device idx             |         |              |            |
++-------+-----------------+-------------------------------+---------+--------------+------------+
+|  u    | :math:`u`       | connection status             | 1       | *bool*       |            |
++-------+-----------------+-------------------------------+---------+--------------+------------+
+|  name |                 | device name                   |         |              |            |
++-------+-----------------+-------------------------------+---------+--------------+------------+
+|  pq   |                 | static load index             |         |              | mandatory  |
++-------+-----------------+-------------------------------+---------+--------------+------------+
+|  cdp  | :math:`c_{d,p}` | cost for unserve load penalty | 999     | *$/(p.u.*h)* |            |
++-------+-----------------+-------------------------------+---------+--------------+------------+
+
+

docs/source/groupdoc/DG.rst

@@ -0,0 +1,204 @@
+.. _DG:
+
+================================================================================
+DG
+================================================================================
+Distributed generation (small-scale).
+
+See ANDES Documentation SynGen here for the notes on replacing StaticGen and setting the power
+ratio parameters.
+
+Reference:
+
+[1] ANDES Documentation, SynGen, [Online]
+
+Available:
+
+https://docs.andes.app/en/latest/groupdoc/SynGen.html#syngen
+
+Common Parameters: u, name, idx, bus, fn
+
+Available models:
+PVD1_,
+ESD1_,
+EV1_,
+EV2_
+
+.. _PVD1:
+
+--------------------------------------------------------------------------------
+PVD1
+--------------------------------------------------------------------------------
+Distributed PV model, revised from ANDES ``PVD1`` model for
+scheduling.
+
+Following parameters are omitted from the original dynamic model:
+``fn``, ``busf``, ``xc``, ``pqflag``, ``igreg``, ``v0``, ``v1``,
+``dqdv``, ``fdbd``, ``ddn``, ``ialim``, ``vt0``, ``vt1``, ``vt2``,
+``vt3``, ``vrflag``, ``ft0``, ``ft1``, ``ft2``, ``ft3``, ``frflag``,
+``tip``, ``tiq``, ``recflag``.
+
+Reference:
+
+[1] ANDES Documentation, PVD1
+
+Available:
+
+https://docs.andes.app/en/latest/groupdoc/DG.html#pvd1
+
+Parameters
+----------
+
++---------+------------------+------------------------------------------------+---------+--------+------------+
+|  Name   |      Symbol      |                  Description                   | Default |  Unit  | Properties |
++=========+==================+================================================+=========+========+============+
+|  idx    |                  | unique device idx                              |         |        |            |
++---------+------------------+------------------------------------------------+---------+--------+------------+
+|  u      | :math:`u`        | connection status                              | 1       | *bool* |            |
++---------+------------------+------------------------------------------------+---------+--------+------------+
+|  name   |                  | device name                                    |         |        |            |
++---------+------------------+------------------------------------------------+---------+--------+------------+
+|  bus    |                  | interface bus id (place holder)                |         |        | mandatory  |
++---------+------------------+------------------------------------------------+---------+--------+------------+
+|  gen    |                  | static generator index                         |         |        | mandatory  |
++---------+------------------+------------------------------------------------+---------+--------+------------+
+|  Sn     | :math:`S_n`      | device MVA rating                              | 100     | *MVA*  |            |
++---------+------------------+------------------------------------------------+---------+--------+------------+
+|  gammap | :math:`\gamma_p` | Ratio of ESD1.pref0 w.r.t to that of static PV | 1       |        |            |
++---------+------------------+------------------------------------------------+---------+--------+------------+
+|  gammaq | :math:`\gamma_q` | Ratio of ESD1.qref0 w.r.t to that of static PV | 1       |        |            |
++---------+------------------+------------------------------------------------+---------+--------+------------+
+
+
+.. _ESD1:
+
+--------------------------------------------------------------------------------
+ESD1
+--------------------------------------------------------------------------------
+Distributed energy storage model, revised from ANDES ``ESD1`` model for
+scheduling.
+
+Following parameters are omitted from the original dynamic model:
+``fn``, ``busf``, ``xc``, ``pqflag``, ``igreg``, ``v0``, ``v1``,
+``dqdv``, ``fdbd``, ``ddn``, ``ialim``, ``vt0``, ``vt1``, ``vt2``,
+``vt3``, ``vrflag``, ``ft0``, ``ft1``, ``ft2``, ``ft3``, ``frflag``,
+``tip``, ``tiq``, ``recflag``.
+
+Reference:
+
+[1] ANDES Documentation, ESD1
+
+Available:
+
+https://docs.andes.app/en/latest/groupdoc/DG.html#esd1
+
+Parameters
+----------
+
++----------+--------------------+------------------------------------------------+---------+--------+------------+
+|   Name   |       Symbol       |                  Description                   | Default |  Unit  | Properties |
++==========+====================+================================================+=========+========+============+
+|  idx     |                    | unique device idx                              |         |        |            |
++----------+--------------------+------------------------------------------------+---------+--------+------------+
+|  u       | :math:`u`          | connection status                              | 1       | *bool* |            |
++----------+--------------------+------------------------------------------------+---------+--------+------------+
+|  name    |                    | device name                                    |         |        |            |
++----------+--------------------+------------------------------------------------+---------+--------+------------+
+|  bus     |                    | interface bus id (place holder)                |         |        | mandatory  |
++----------+--------------------+------------------------------------------------+---------+--------+------------+
+|  gen     |                    | static generator index                         |         |        | mandatory  |
++----------+--------------------+------------------------------------------------+---------+--------+------------+
+|  Sn      | :math:`S_n`        | device MVA rating                              | 100     | *MVA*  |            |
++----------+--------------------+------------------------------------------------+---------+--------+------------+
+|  gammap  | :math:`\gamma_p`   | Ratio of ESD1.pref0 w.r.t to that of static PV | 1       |        |            |
++----------+--------------------+------------------------------------------------+---------+--------+------------+
+|  gammaq  | :math:`\gamma_q`   | Ratio of ESD1.qref0 w.r.t to that of static PV | 1       |        |            |
++----------+--------------------+------------------------------------------------+---------+--------+------------+
+|  SOCmin  | :math:`SOC_{min}`  | Minimum required value for SOC in limiter      | 0       |        |            |
++----------+--------------------+------------------------------------------------+---------+--------+------------+
+|  SOCmax  | :math:`SOC_{max}`  | Maximum allowed value for SOC in limiter       | 1       |        |            |
++----------+--------------------+------------------------------------------------+---------+--------+------------+
+|  SOCinit | :math:`SOC_{init}` | Initial state of charge                        | 0.500   |        |            |
++----------+--------------------+------------------------------------------------+---------+--------+------------+
+|  En      | :math:`E_n`        | Rated energy capacity                          | 100     | *MWh*  |            |
++----------+--------------------+------------------------------------------------+---------+--------+------------+
+|  EtaC    | :math:`Eta_C`      | Efficiency during charging                     | 1       |        |            |
++----------+--------------------+------------------------------------------------+---------+--------+------------+
+|  EtaD    | :math:`Eta_D`      | Efficiency during discharging                  | 1       |        |            |
++----------+--------------------+------------------------------------------------+---------+--------+------------+
+
+
+.. _EV1:
+
+--------------------------------------------------------------------------------
+EV1
+--------------------------------------------------------------------------------
+Aggregated EV model for scheduling at transmission level.
+
+For co-simulation with ADNES, it is expected to be used in
+conjunction with the dynamic models `EV1` or `EV2`.
+
+Reference:
+
+[1] J. Wang et al., "Electric Vehicles Charging Time Constrained Deliverable Provision of Secondary
+Frequency Regulation," in IEEE Transactions on Smart Grid, doi: 10.1109/TSG.2024.3356948.
+
+Parameters
+----------
+
++---------+------------------+------------------------------+---------+--------+------------+
+|  Name   |      Symbol      |         Description          | Default |  Unit  | Properties |
++=========+==================+==============================+=========+========+============+
+|  idx    |                  | unique device idx            |         |        |            |
++---------+------------------+------------------------------+---------+--------+------------+
+|  u      | :math:`u`        | connection status            | 1       | *bool* |            |
++---------+------------------+------------------------------+---------+--------+------------+
+|  name   |                  | device name                  |         |        |            |
++---------+------------------+------------------------------+---------+--------+------------+
+|  bus    |                  | interface bus idx            |         |        | mandatory  |
++---------+------------------+------------------------------+---------+--------+------------+
+|  gen    |                  | static generator index       |         |        | mandatory  |
++---------+------------------+------------------------------+---------+--------+------------+
+|  Sn     | :math:`S_n`      | device MVA rating            | 100     | *MVA*  |            |
++---------+------------------+------------------------------+---------+--------+------------+
+|  gammap | :math:`\gamma_P` | P ratio of linked static gen | 1       |        |            |
++---------+------------------+------------------------------+---------+--------+------------+
+|  gammaq | :math:`\gamma_Q` | Q ratio of linked static gen | 1       |        |            |
++---------+------------------+------------------------------+---------+--------+------------+
+|  N      | :math:`N`        | number of related EVs        | 10000   |        |            |
++---------+------------------+------------------------------+---------+--------+------------+
+
+
+.. _EV2:
+
+--------------------------------------------------------------------------------
+EV2
+--------------------------------------------------------------------------------
+EV aggregation model at transmission level, identical to :ref:`EV1`.
+
+Parameters
+----------
+
++---------+------------------+------------------------------+---------+--------+------------+
+|  Name   |      Symbol      |         Description          | Default |  Unit  | Properties |
++=========+==================+==============================+=========+========+============+
+|  idx    |                  | unique device idx            |         |        |            |
++---------+------------------+------------------------------+---------+--------+------------+
+|  u      | :math:`u`        | connection status            | 1       | *bool* |            |
++---------+------------------+------------------------------+---------+--------+------------+
+|  name   |                  | device name                  |         |        |            |
++---------+------------------+------------------------------+---------+--------+------------+
+|  bus    |                  | interface bus idx            |         |        | mandatory  |
++---------+------------------+------------------------------+---------+--------+------------+
+|  gen    |                  | static generator index       |         |        | mandatory  |
++---------+------------------+------------------------------+---------+--------+------------+
+|  Sn     | :math:`S_n`      | device MVA rating            | 100     | *MVA*  |            |
++---------+------------------+------------------------------+---------+--------+------------+
+|  gammap | :math:`\gamma_P` | P ratio of linked static gen | 1       |        |            |
++---------+------------------+------------------------------+---------+--------+------------+
+|  gammaq | :math:`\gamma_Q` | Q ratio of linked static gen | 1       |        |            |
++---------+------------------+------------------------------+---------+--------+------------+
+|  N      | :math:`N`        | number of related EVs        | 10000   |        |            |
++---------+------------------+------------------------------+---------+--------+------------+
+
+