.. _Interface:

================================================================================
Interface
================================================================================
Group for interface models.

Available models:
Fortescue_

.. _Fortescue:

--------------------------------------------------------------------------------
Fortescue
--------------------------------------------------------------------------------
Fortescue's symmetric component interface.

This model interfaces a positive-sequence, single-phase-equivalent bus with
three buses representing three phases. It is effectively a transformer with
one terminal on the primary side and three on the secondary. Only the
positive sequence component on the secondary winding is used for simulation.

The positive-sequence voltage magnitude and angle of the secondary winding
are named ``vp`` and ``ap``.

The negative and zero sequence variables given in the d- and q-axis due the
angle being undefined when the voltage is zero. The negative sequence
voltages are ``vnd`` and ``vnq`` for the d- anx q-axis, respectively.
Likewise, the zero-sequence voltages are ``vzd`` and ``vzq``.

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 the single-phase equivalent |         |        | mandatory  |
+-------+-------------+-----------------------------------------+---------+--------+------------+
|  busa |             | bus idx for phase a                     |         |        | mandatory  |
+-------+-------------+-----------------------------------------+---------+--------+------------+
|  busb |             | bus idx for phase b                     |         |        | mandatory  |
+-------+-------------+-----------------------------------------+---------+--------+------------+
|  busc |             | bus idx for phase c                     |         |        | mandatory  |
+-------+-------------+-----------------------------------------+---------+--------+------------+
|  Sn   | :math:`S_n` | Power rating                            | 100     | *MW*   | non_zero   |
+-------+-------------+-----------------------------------------+---------+--------+------------+
|  r    | :math:`r`   | resistance                              | 0.001   | *p.u.* | z          |
+-------+-------------+-----------------------------------------+---------+--------+------------+
|  x    | :math:`x`   | short-circuit reactance                 | 0.025   | *p.u.* | non_zero,z |
+-------+-------------+-----------------------------------------+---------+--------+------------+
|  g    |             | iron loss                               | 0       | *p.u.* | y          |
+-------+-------------+-----------------------------------------+---------+--------+------------+
|  b    |             | magnetizing susceptance                 | 0.005   | *p.u.* | y          |
+-------+-------------+-----------------------------------------+---------+--------+------------+

Variables
---------

+------+-------------+----------+-------------------------------------------+------+------------+
| Name |   Symbol    |   Type   |                Description                | Unit | Properties |
+======+=============+==========+===========================================+======+============+
|  vp  | :math:`vp`  | Algeb    | positive sequence voltage magnitude       |      | v_str      |
+------+-------------+----------+-------------------------------------------+------+------------+
|  ap  | :math:`ap`  | Algeb    | positive sequence voltage phase           |      | v_str      |
+------+-------------+----------+-------------------------------------------+------+------------+
|  vnd | :math:`vnd` | Algeb    | negative sequence voltage on d-axis (cos) |      | v_str      |
+------+-------------+----------+-------------------------------------------+------+------------+
|  vnq | :math:`vnq` | Algeb    | negative sequence voltage on q-axis (sin) |      | v_str      |
+------+-------------+----------+-------------------------------------------+------+------------+
|  vzd | :math:`vzd` | Algeb    | zero sequence voltage on d-axis (cos)     |      | v_str      |
+------+-------------+----------+-------------------------------------------+------+------------+
|  vzq | :math:`vzq` | Algeb    | zero sequence voltage on q-axis (sin)     |      | v_str      |
+------+-------------+----------+-------------------------------------------+------+------------+
|  a   | :math:`a`   | ExtAlgeb | phase angle of single-phase eq. bus       |      |            |
+------+-------------+----------+-------------------------------------------+------+------------+
|  aa  | :math:`aa`  | ExtAlgeb | phase angle of bus for phase a            |      |            |
+------+-------------+----------+-------------------------------------------+------+------------+
|  ab  | :math:`ab`  | ExtAlgeb | phase angle of bus for phase b            |      |            |
+------+-------------+----------+-------------------------------------------+------+------------+
|  ac  | :math:`ac`  | ExtAlgeb | phase angle of bus for phase c            |      |            |
+------+-------------+----------+-------------------------------------------+------+------------+
|  v   | :math:`v`   | ExtAlgeb | voltage of single-phase eq. bus           |      |            |
+------+-------------+----------+-------------------------------------------+------+------------+
|  va  | :math:`va`  | ExtAlgeb | voltage of bus for phase a                |      |            |
+------+-------------+----------+-------------------------------------------+------+------------+
|  vb  | :math:`vb`  | ExtAlgeb | voltage of bus for phase b                |      |            |
+------+-------------+----------+-------------------------------------------+------+------------+
|  vc  | :math:`vc`  | ExtAlgeb | voltage of bus for phase c                |      |            |
+------+-------------+----------+-------------------------------------------+------+------------+

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

+------+-------------+----------+----------------------------------------------------+
| Name |   Symbol    |   Type   |                   Initial Value                    |
+======+=============+==========+====================================================+
|  vp  | :math:`vp`  | Algeb    | :math:`\frac{va}{3} + \frac{vb}{3} + \frac{vc}{3}` |
+------+-------------+----------+----------------------------------------------------+
|  ap  | :math:`ap`  | Algeb    | :math:`aa + ab + ac`                               |
+------+-------------+----------+----------------------------------------------------+
|  vnd | :math:`vnd` | Algeb    | :math:`0.0`                                        |
+------+-------------+----------+----------------------------------------------------+
|  vnq | :math:`vnq` | Algeb    | :math:`0.0`                                        |
+------+-------------+----------+----------------------------------------------------+
|  vzd | :math:`vzd` | Algeb    | :math:`0.0`                                        |
+------+-------------+----------+----------------------------------------------------+
|  vzq | :math:`vzq` | Algeb    | :math:`0.0`                                        |
+------+-------------+----------+----------------------------------------------------+
|  a   | :math:`a`   | ExtAlgeb |                                                    |
+------+-------------+----------+----------------------------------------------------+
|  aa  | :math:`aa`  | ExtAlgeb |                                                    |
+------+-------------+----------+----------------------------------------------------+
|  ab  | :math:`ab`  | ExtAlgeb |                                                    |
+------+-------------+----------+----------------------------------------------------+
|  ac  | :math:`ac`  | ExtAlgeb |                                                    |
+------+-------------+----------+----------------------------------------------------+
|  v   | :math:`v`   | ExtAlgeb |                                                    |
+------+-------------+----------+----------------------------------------------------+
|  va  | :math:`va`  | ExtAlgeb |                                                    |
+------+-------------+----------+----------------------------------------------------+
|  vb  | :math:`vb`  | ExtAlgeb |                                                    |
+------+-------------+----------+----------------------------------------------------+
|  vc  | :math:`vc`  | ExtAlgeb |                                                    |
+------+-------------+----------+----------------------------------------------------+

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

+------+-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Name |   Symbol    |   Type   |                                                                                                            RHS of Equation "0 = g(x, y)"                                                                                                             |
+======+=============+==========+======================================================================================================================================================================================================================================================+
|  vp  | :math:`vp`  | Algeb    | :math:`- vp + \frac{\sqrt{\left(vb \sin{\left(- aa + ab + d_{120} \right)} - vc \sin{\left(aa - ac + d_{120} \right)}\right)^{2} + \left(va + vb \cos{\left(- aa + ab + d_{120} \right)} + vc \cos{\left(aa - ac + d_{120} \right)}\right)^{2}}}{3}` |
+------+-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|  ap  | :math:`ap`  | Algeb    | :math:`aa - ap + \operatorname{atan}_{2}{\left(vb \sin{\left(- aa + ab + d_{120} \right)} - vc \sin{\left(aa - ac + d_{120} \right)},va + vb \cos{\left(- aa + ab + d_{120} \right)} + vc \cos{\left(aa - ac + d_{120} \right)} \right)}`            |
+------+-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|  vnd | :math:`vnd` | Algeb    | :math:`va \cos{\left(aa \right)} + vb \cos{\left(ab - d_{120} \right)} + vc \cos{\left(ac + d_{120} \right)} - vnd`                                                                                                                                  |
+------+-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|  vnq | :math:`vnq` | Algeb    | :math:`va \sin{\left(aa \right)} + vb \sin{\left(ab - d_{120} \right)} + vc \sin{\left(ac + d_{120} \right)} - vnq`                                                                                                                                  |
+------+-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|  vzd | :math:`vzd` | Algeb    | :math:`va \cos{\left(aa \right)} + vb \cos{\left(ab \right)} + vc \cos{\left(ac \right)} - vzd`                                                                                                                                                      |
+------+-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|  vzq | :math:`vzq` | Algeb    | :math:`va \sin{\left(aa \right)} + vb \sin{\left(ab \right)} + vc \sin{\left(ac \right)} - vzq`                                                                                                                                                      |
+------+-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|  a   | :math:`a`   | ExtAlgeb | :math:`u \left(v^{2} \left(g + ghk\right) - v vp \left(bhk \sin{\left(a - ap \right)} + ghk \cos{\left(a - ap \right)}\right)\right)`                                                                                                                |
+------+-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|  aa  | :math:`aa`  | ExtAlgeb | :math:`\frac{u \left(- v va \left(- bhk \sin{\left(a - aa \right)} + ghk \cos{\left(a - aa \right)}\right) + va^{2} \left(g + ghk\right)\right)}{3}`                                                                                                 |
+------+-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|  ab  | :math:`ab`  | ExtAlgeb | :math:`\frac{u \left(- v vb \left(bhk \sin{\left(- a + ab + d_{120} \right)} + ghk \cos{\left(- a + ab + d_{120} \right)}\right) + vb^{2} \left(g + ghk\right)\right)}{3}`                                                                           |
+------+-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|  ac  | :math:`ac`  | ExtAlgeb | :math:`\frac{u \left(- v vc \left(- bhk \sin{\left(a - ac + d_{120} \right)} + ghk \cos{\left(a - ac + d_{120} \right)}\right) + vc^{2} \left(g + ghk\right)\right)}{3}`                                                                             |
+------+-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|  v   | :math:`v`   | ExtAlgeb | :math:`u \left(- v^{2} \left(b + bhk\right) - v vp \left(- bhk \cos{\left(a - ap \right)} + ghk \sin{\left(a - ap \right)}\right)\right)`                                                                                                            |
+------+-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|  va  | :math:`va`  | ExtAlgeb | :math:`\frac{u \left(v va \left(bhk \cos{\left(a - aa \right)} + ghk \sin{\left(a - aa \right)}\right) - va^{2} \left(b + bhk\right)\right)}{3}`                                                                                                     |
+------+-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|  vb  | :math:`vb`  | ExtAlgeb | :math:`\frac{u \left(v vb \left(bhk \cos{\left(- a + ab + d_{120} \right)} - ghk \sin{\left(- a + ab + d_{120} \right)}\right) - vb^{2} \left(b + bhk\right)\right)}{3}`                                                                             |
+------+-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|  vc  | :math:`vc`  | ExtAlgeb | :math:`\frac{u \left(v vc \left(bhk \cos{\left(a - ac + d_{120} \right)} + ghk \sin{\left(a - ac + d_{120} \right)}\right) - vc^{2} \left(b + bhk\right)\right)}{3}`                                                                                 |
+------+-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Services
----------

+-------+----------------+---------------------------------------------+--------------+
| Name  |     Symbol     |                  Equation                   |     Type     |
+=======+================+=============================================+==============+
|  yhk  | :math:`y_{hk}` | :math:`\frac{u}{r + i x}`                   | ConstService |
+-------+----------------+---------------------------------------------+--------------+
|  ghk  | :math:`g_{hk}` | :math:`\operatorname{re}{\left(yhk\right)}` | ConstService |
+-------+----------------+---------------------------------------------+--------------+
|  bhk  | :math:`b_{hk}` | :math:`\operatorname{im}{\left(yhk\right)}` | ConstService |
+-------+----------------+---------------------------------------------+--------------+
|  d120 | :math:`120^o`  | :math:`\frac{2 \pi}{3}`                     | ConstService |
+-------+----------------+---------------------------------------------+--------------+


Config Fields in [Fortescue]

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