.. _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   |        |            |
+---------+------------------+------------------------------+---------+--------+------------+