.. _Calculation:

================================================================================
Calculation
================================================================================
Group of classes that calculates based on other models.

Common Parameters: u, name

Available models:
ACE_,
ACEc_,
COI_

.. _ACE:

--------------------------------------------------------------------------------
ACE
--------------------------------------------------------------------------------
Area Control Error model.

Discrete frequency sampling.
System base frequency from ``system.config.freq`` is used.

Frequency sampling period (in seconds) can be specified in
``ACE.config.interval``. The sampling start time (in seconds)
can be specified in ``ACE.config.offset``.

Note: area idx is automatically retrieved from `bus`.

Parameters
----------

+-------+---------------+-------------------------------+---------+------------+------------+
| Name  |    Symbol     |          Description          | Default |    Unit    | Properties |
+=======+===============+===============================+=========+============+============+
|  idx  |               | unique device idx             |         |            |            |
+-------+---------------+-------------------------------+---------+------------+------------+
|  u    | :math:`u`     | connection status             | 1       | *bool*     |            |
+-------+---------------+-------------------------------+---------+------------+------------+
|  name |               | device name                   |         |            |            |
+-------+---------------+-------------------------------+---------+------------+------------+
|  bus  |               | bus idx for freq. measurement |         |            | mandatory  |
+-------+---------------+-------------------------------+---------+------------+------------+
|  bias | :math:`\beta` | bias parameter                | 1       | *MW/0.1Hz* | power      |
+-------+---------------+-------------------------------+---------+------------+------------+
|  busf |               | Optional BusFreq device idx   |         |            |            |
+-------+---------------+-------------------------------+---------+------------+------------+
|  area |               |                               | 0       |            |            |
+-------+---------------+-------------------------------+---------+------------+------------+

Variables
---------

+------+-------------+----------+--------------------+-------------+------------+
| Name |   Symbol    |   Type   |    Description     |    Unit     | Properties |
+======+=============+==========+====================+=============+============+
|  ace | :math:`ace` | Algeb    | area control error | *p.u. (MW)* |            |
+------+-------------+----------+--------------------+-------------+------------+
|  f   | :math:`f`   | ExtAlgeb | Bus frequency      | *p.u. (Hz)* |            |
+------+-------------+----------+--------------------+-------------+------------+

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

+------+-------------+----------+---------------+
| Name |   Symbol    |   Type   | Initial Value |
+======+=============+==========+===============+
|  ace | :math:`ace` | Algeb    |               |
+------+-------------+----------+---------------+
|  f   | :math:`f`   | ExtAlgeb |               |
+------+-------------+----------+---------------+

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

+------+-------------+----------+--------------------------------------------------------------+
| Name |   Symbol    |   Type   |                RHS of Equation "0 = g(x, y)"                 |
+======+=============+==========+==============================================================+
|  ace | :math:`ace` | Algeb    | :math:`- ace + 10 bias f_{sys} imva \left(fs_{v} - 1\right)` |
+------+-------------+----------+--------------------------------------------------------------+
|  f   | :math:`f`   | ExtAlgeb | :math:`0`                                                    |
+------+-------------+----------+--------------------------------------------------------------+

Services
----------

+-------+----------------------+-----------------------------+--------------+
| Name  |        Symbol        |          Equation           |     Type     |
+=======+======================+=============================+==============+
|  imva | :math:`1/S_{b, sys}` | :math:`\frac{1}{S_{b,sys}}` | ConstService |
+-------+----------------------+-----------------------------+--------------+

Discretes
-----------

+------+-------------+----------+---------------+
| Name |   Symbol    |   Type   |     Info      |
+======+=============+==========+===============+
|  fs  | :math:`f_s` | Sampling | Sampled freq. |
+------+-------------+----------+---------------+


Config Fields in [ACE]

+---------------+--------+---------+---------------------------------------+-----------------+
|    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)          |
+---------------+--------+---------+---------------------------------------+-----------------+
|  freq_model   |        | BusFreq | default freq. measurement model       | ('BusFreq',)    |
+---------------+--------+---------+---------------------------------------+-----------------+
|  interval     |        | 4       | sampling time interval                |                 |
+---------------+--------+---------+---------------------------------------+-----------------+
|  offset       |        | 0       | sampling time offset                  |                 |
+---------------+--------+---------+---------------------------------------+-----------------+


.. _ACEc:

--------------------------------------------------------------------------------
ACEc
--------------------------------------------------------------------------------
Area Control Error model.

Continuous frequency sampling.
System base frequency from ``system.config.freq`` is used.

Note: area idx is automatically retrieved from `bus`.

Parameters
----------

+-------+---------------+-------------------------------+---------+------------+------------+
| Name  |    Symbol     |          Description          | Default |    Unit    | Properties |
+=======+===============+===============================+=========+============+============+
|  idx  |               | unique device idx             |         |            |            |
+-------+---------------+-------------------------------+---------+------------+------------+
|  u    | :math:`u`     | connection status             | 1       | *bool*     |            |
+-------+---------------+-------------------------------+---------+------------+------------+
|  name |               | device name                   |         |            |            |
+-------+---------------+-------------------------------+---------+------------+------------+
|  bus  |               | bus idx for freq. measurement |         |            | mandatory  |
+-------+---------------+-------------------------------+---------+------------+------------+
|  bias | :math:`\beta` | bias parameter                | 1       | *MW/0.1Hz* | power      |
+-------+---------------+-------------------------------+---------+------------+------------+
|  busf |               | Optional BusFreq device idx   |         |            |            |
+-------+---------------+-------------------------------+---------+------------+------------+
|  area |               |                               | 0       |            |            |
+-------+---------------+-------------------------------+---------+------------+------------+

Variables
---------

+------+-------------+----------+--------------------+-------------+------------+
| Name |   Symbol    |   Type   |    Description     |    Unit     | Properties |
+======+=============+==========+====================+=============+============+
|  ace | :math:`ace` | Algeb    | area control error | *p.u. (MW)* |            |
+------+-------------+----------+--------------------+-------------+------------+
|  f   | :math:`f`   | ExtAlgeb | Bus frequency      | *p.u. (Hz)* |            |
+------+-------------+----------+--------------------+-------------+------------+

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

+------+-------------+----------+---------------+
| Name |   Symbol    |   Type   | Initial Value |
+======+=============+==========+===============+
|  ace | :math:`ace` | Algeb    |               |
+------+-------------+----------+---------------+
|  f   | :math:`f`   | ExtAlgeb |               |
+------+-------------+----------+---------------+

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

+------+-------------+----------+---------------------------------------------------------+
| Name |   Symbol    |   Type   |              RHS of Equation "0 = g(x, y)"              |
+======+=============+==========+=========================================================+
|  ace | :math:`ace` | Algeb    | :math:`- ace + 10 bias f_{sys} imva \left(f - 1\right)` |
+------+-------------+----------+---------------------------------------------------------+
|  f   | :math:`f`   | ExtAlgeb | :math:`0`                                               |
+------+-------------+----------+---------------------------------------------------------+

Services
----------

+-------+----------------------+-----------------------------+--------------+
| Name  |        Symbol        |          Equation           |     Type     |
+=======+======================+=============================+==============+
|  imva | :math:`1/S_{b, sys}` | :math:`\frac{1}{S_{b,sys}}` | ConstService |
+-------+----------------------+-----------------------------+--------------+


Config Fields in [ACEc]

+---------------+--------+---------+---------------------------------------+-----------------+
|    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)          |
+---------------+--------+---------+---------------------------------------+-----------------+
|  freq_model   |        | BusFreq | default freq. measurement model       | ('BusFreq',)    |
+---------------+--------+---------+---------------------------------------+-----------------+


.. _COI:

--------------------------------------------------------------------------------
COI
--------------------------------------------------------------------------------
Center of inertia calculation class.

Parameters
----------

+-------+-----------+--------------------------+---------+--------+------------+
| Name  |  Symbol   |       Description        | Default |  Unit  | Properties |
+=======+===========+==========================+=========+========+============+
|  idx  |           | unique device idx        |         |        |            |
+-------+-----------+--------------------------+---------+--------+------------+
|  u    | :math:`u` | connection status        | 1       | *bool* |            |
+-------+-----------+--------------------------+---------+--------+------------+
|  name |           | device name              |         |        |            |
+-------+-----------+--------------------------+---------+--------+------------+
|  M    |           | Linearly stored SynGen.M | 0       |        |            |
+-------+-----------+--------------------------+---------+--------+------------+

Variables
---------

+------------+----------------------+----------+----------------------------------------------+------+----------------+
|    Name    |        Symbol        |   Type   |                 Description                  | Unit |   Properties   |
+============+======================+==========+==============================================+======+================+
|  wgen      | :math:`wgen`         | ExtState | Linearly stored SynGen.omega                 |      |                |
+------------+----------------------+----------+----------------------------------------------+------+----------------+
|  agen      | :math:`agen`         | ExtState | Linearly stored SynGen.delta                 |      |                |
+------------+----------------------+----------+----------------------------------------------+------+----------------+
|  omega     | :math:`\omega`       | Algeb    | COI speed                                    |      | v_str,v_setter |
+------------+----------------------+----------+----------------------------------------------+------+----------------+
|  delta     | :math:`\delta`       | Algeb    | COI rotor angle                              |      | v_str,v_setter |
+------------+----------------------+----------+----------------------------------------------+------+----------------+
|  omega_sub | :math:`\omega_{sub}` | ExtAlgeb | COI frequency contribution of each generator |      |                |
+------------+----------------------+----------+----------------------------------------------+------+----------------+
|  delta_sub | :math:`\delta_{sub}` | ExtAlgeb | COI angle contribution of each generator     |      |                |
+------------+----------------------+----------+----------------------------------------------+------+----------------+

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

+------------+----------------------+----------+---------------+
|    Name    |        Symbol        |   Type   | Initial Value |
+============+======================+==========+===============+
|  wgen      | :math:`wgen`         | ExtState |               |
+------------+----------------------+----------+---------------+
|  agen      | :math:`agen`         | ExtState |               |
+------------+----------------------+----------+---------------+
|  omega     | :math:`\omega`       | Algeb    | :math:`a0a`   |
+------------+----------------------+----------+---------------+
|  delta     | :math:`\delta`       | Algeb    | :math:`d0a`   |
+------------+----------------------+----------+---------------+
|  omega_sub | :math:`\omega_{sub}` | ExtAlgeb |               |
+------------+----------------------+----------+---------------+
|  delta_sub | :math:`\delta_{sub}` | ExtAlgeb |               |
+------------+----------------------+----------+---------------+

Differential Equations
-----------------------------

+-------+--------------+----------+----------------------------------+---------+
| Name  |    Symbol    |   Type   | RHS of Equation "T x' = f(x, y)" | T (LHS) |
+=======+==============+==========+==================================+=========+
|  wgen | :math:`wgen` | ExtState | :math:`0`                        |         |
+-------+--------------+----------+----------------------------------+---------+
|  agen | :math:`agen` | ExtState | :math:`0`                        |         |
+-------+--------------+----------+----------------------------------+---------+

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

+------------+----------------------+----------+-------------------------------+
|    Name    |        Symbol        |   Type   | RHS of Equation "0 = g(x, y)" |
+============+======================+==========+===============================+
|  omega     | :math:`\omega`       | Algeb    | :math:`- \omega`              |
+------------+----------------------+----------+-------------------------------+
|  delta     | :math:`\delta`       | Algeb    | :math:`- \delta`              |
+------------+----------------------+----------+-------------------------------+
|  omega_sub | :math:`\omega_{sub}` | ExtAlgeb | :math:`Mw wgen`               |
+------------+----------------------+----------+-------------------------------+
|  delta_sub | :math:`\delta_{sub}` | ExtAlgeb | :math:`Mw agen`               |
+------------+----------------------+----------+-------------------------------+

Services
----------

+------+--------------------------+----------------------+--------------+
| Name |          Symbol          |       Equation       |     Type     |
+======+==========================+======================+==============+
|  Mw  | :math:`M_w`              | :math:`\frac{M}{Mr}` | ConstService |
+------+--------------------------+----------------------+--------------+
|  d0w | :math:`\delta_{gen,0,w}` | :math:`Mw d_{0}`     | ConstService |
+------+--------------------------+----------------------+--------------+
|  a0w | :math:`\omega_{gen,0,w}` | :math:`Mw a_{0}`     | ConstService |
+------+--------------------------+----------------------+--------------+


Config Fields in [COI]

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