> For the complete documentation index, see [llms.txt](https://www.opal-rt.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.opal-rt.com/docs/hypersim/model-and-simulation/phasor-domain-with-ephasorsim/configure-ephasorsim-block-ports/multiphase-pin-identifiers.md).

# Multiphase Pin Identifiers

## Introduction <a href="#available-i-o-pins" id="available-i-o-pins"></a>

This page lists the available **Pin Identifiers** for components used in **multiphase networks**. Use these identifiers in the **Pins** worksheet to configure the ePHASORSIM block ports.

In the tables below, ***j*** identifies the wire and can be `1`, `2`, or `3`.

## Bus <a href="#available-i-o-pins" id="available-i-o-pins"></a>

| Pin Description           | Direction       | Value / Unit                          | Pin Identifier                                                                              |
| ------------------------- | --------------- | ------------------------------------- | ------------------------------------------------------------------------------------------- |
| **Bus trip signal**       | Input or Output | <p>0 = Normal<br>1 = Disconnected</p> | **busID**/trip                                                                              |
| **Bus voltage magnitude** | Output          | V (RMS)                               | **busID**/Vmag                                                                              |
| **Bus voltage angle**     | Output          | Degree                                | <p><strong>busID</strong>/Vang (Wrapped)</p><p><strong>busID</strong>/VangU (Unwrapped)</p> |

## Fault

| Pin Description                                  | Direction       | Value / Unit                      | Pin Identifier      |
| ------------------------------------------------ | --------------- | --------------------------------- | ------------------- |
| **Fault status**                                 | Input or Output | <p>1 = Active<br>0 = Inactive</p> | **faultID**/status  |
| **Fault current magnitude in wire&#x20;*****j*** | Output          | A (RMS)                           | **faultID**/Imag*j* |
| **Fault current angle in wire&#x20;*****j***     | Output          | Degree                            | **faultID**/Iang*j* |

## Machine

### Synchronous generator models

| Pin Description                | Direction       | Value / Unit                                | Pin Identifier                  |
| ------------------------------ | --------------- | ------------------------------------------- | ------------------------------- |
| **Rotor angle**                | Output          | Radian                                      | **machineID**/pins/delta        |
| **Rotor speed deviation**      | Output          | pu                                          | **machineID**/pins/slip         |
| **Injected current magnitude** | Output          | pu (machine base)                           | **machineID**/pins/Imag         |
| **Injected current angle**     | Output          | Degree                                      | **machineID**/pins/Iang         |
| **Internal voltage magnitude** | Output          | pu                                          | **machineID**/pins/internalVmag |
| **Internal voltage angle**     | Output          | Degree                                      | **machineID**/pins/internalVang |
| **Excitation voltage**         | Input or Output | pu                                          | **machineID**/pins/Efd          |
| **Mechanical input torque**    | Input or Output | pu (machine base)                           | **machineID**/pins/Pmech        |
| **Machine status**             | Input or Output | <p>1 = In service<br>0 = Out of service</p> | **machineID**/pins/status       |
| **Generated active power**     | Output          | MW                                          | **machineID**/pins/Pelec        |
| **Generated reactive power**   | Output          | MVAr                                        | **machineID**/pins/Qelec        |

### Asynchronous generator induction models

| Pin Description                | Direction       | Value / Unit                                | Pin Identifier            |
| ------------------------------ | --------------- | ------------------------------------------- | ------------------------- |
| **Rotor speed deviation**      | Output          | pu                                          | **machineID**/pins/slip   |
| **Injected current magnitude** | Output          | pu (machine base)                           | **machineID**/pins/Imag   |
| **Injected current angle**     | Output          | Degree                                      | **machineID**/pins/Iang   |
| **Machine status**             | Input or Output | <p>1 = In service<br>0 = Out of service</p> | **machineID**/pins/status |
| **Generated active power**     | Output          | MW                                          | **machineID**/pins/Pelec  |
| **Generated reactive power**   | Output          | MVAr                                        | **machineID**/pins/Qelec  |

## Power System Stabilizer (PSS)

| Pin Description                               | Direction | Value / Unit | Pin Identifier        |
| --------------------------------------------- | --------- | ------------ | --------------------- |
| **Stabilizer output (V**<sub>**s**</sub>**)** | Output    | pu           | **pssID**/pins/Vothsg |

## Turbine & Governor

| Pin Description                 | Direction       | Value / Unit | Pin Identifier                |
| ------------------------------- | --------------- | ------------ | ----------------------------- |
| **Initial voltage reference**   | Output          | pu           | **turbineID**/Gref0           |
| **Voltage reference increment** | Input or Output | pu           | **turbineID**/pins/dGref      |
| **Governor output Pmech**       | Output          | pu           | **turbineID/**&#x70;ins/Pmech |

## Voltage source

| Pin Description                | Direction       | Value / Unit | Pin Identifier           |
| ------------------------------ | --------------- | ------------ | ------------------------ |
| **Internal voltage magnitude** | Input or Output | V (RMS)      | **VsourceID**/vMag       |
| **Internal voltage angle**     | Input or Output | Degree       | **VsourceID**/vAng       |
| **Internal resistance**        | Input or Output | Ω            | **VsourceID**/resistance |
| **Internal reac­tance**        | Input or Output | Ω            | **VsourceID**/reactance  |
| **Injected current magnitude** | Output          | A (RMS)      | **VsourceID**/Imag       |
| **Injected current angle**     | Output          | Degree       | **VsourceID**/Iang       |

## Current source

### Controllable current source

| Pin Description                   | Direction       | Value / Unit                                | Pin Identifier    |
| --------------------------------- | --------------- | ------------------------------------------- | ----------------- |
| **Current source service status** | Input or Output | <p>1 = In service<br>0 = Out of service</p> | **itemID**/status |
| **Current magnitude**             | Input or Output | A (RMS)                                     | **itemID**/Imag   |
| **Current angle**                 | Input or Output | Degree                                      | **itemID**/Iang   |
| **Active power input**            | Input           | MW                                          | **itemID**/P      |
| **Reactive power input**          | Input           | MVAr                                        | **itemID**/Q      |
| **Active power output**           | Output          | MW                                          | **itemID**/Pout   |
| **Reactive power output**         | Output          | MVAr                                        | **itemID**/Qout   |

{% hint style="danger" %}

* When using **power control**, both **P** and **Q** must be provided.
* When using **current control**, both **Imag** and **Iang** must be provided.
* The component can operate in **either power-control mode or current-control mode**, but not both simultaneously. Mixing both control modes will produce undefined results.
  {% endhint %}

### Current injector

| Pin Description       | Direction       | Value / Unit | Pin Identifier  |
| --------------------- | --------------- | ------------ | --------------- |
| **Current magnitude** | Input or Output | A (RMS)      | **itemID**/Imag |
| **Current angle**     | Input or Output | Degree       | **itemID**/Iang |

## Line

| Pin Description                                          | Direction       | Value / Unit                                | Pin Identifier         |
| -------------------------------------------------------- | --------------- | ------------------------------------------- | ---------------------- |
| **Line service status**                                  | Input or Output | <p>1 = In service<br>0 = Out of service</p> | **lineID**/status      |
| **Sending-end current magnitude of wire&#x20;*****j***   | Output          | A (RMS)                                     | **lineID**/ImagFrom*j* |
| **Receiving-end current magnitude of wire&#x20;*****j*** | Output          | A (RMS)                                     | **lineID**/ImagTo*j*   |
| **Sending-end current angle of wire&#x20;*****j***       | Output          | Degree                                      | **lineID**/IangFrom*j* |
| **Receiving-end current angle of wire&#x20;*****j***     | Output          | Degree                                      | **lineID**/IangTo*j*   |
| **Sending-end active power of wire&#x20;*****j***        | Output          | kW                                          | **lineID**/PFrom*j*    |
| **Sending-end reactive power of wire&#x20;*****j***      | Output          | kVAr                                        | **lineID**/QFrom*j*    |
| **Receiving-end active power of wire&#x20;*****j***      | Output          | kW                                          | **lineID**/PTo*j*      |
| **Receiving-end reactive power of wire&#x20;*****j***    | Output          | kVAr                                        | **lineID**/QTo*j*      |
| **Active power loss of wire&#x20;*****j***               | Output          | kW                                          | **lineID**/PL*j*       |
| **Reactive power loss of wire&#x20;*****j***             | Output          | kVAr                                        | **lineID**/QL*j*       |

## Load

| Pin Description                            | Direction       | Value / Unit                             | Pin Identifier     |
| ------------------------------------------ | --------------- | ---------------------------------------- | ------------------ |
| **Load service status**                    | Input or Output | <p>0 = Disconnected<br>1 = Connected</p> | **loadID**/status  |
| **Active power of load&#x20;*****j***      | Input or Output | kW                                       | **loadID**/P*j*    |
| **Reactive power of load&#x20;*****j***    | Input or Output | kVAr                                     | **loadID**/Q*j*    |
| **Current magnitude of load&#x20;*****j*** | Output          | A (RMS)                                  | **loadID**/Imag*j* |
| **Current angle of load&#x20;*****j***     | Output          | Degree                                   | **loadID**/Iang*j* |

## Shunt

| Pin Description                             | Direction       | Value / Unit                             | Pin Identifier        |
| ------------------------------------------- | --------------- | ---------------------------------------- | --------------------- |
| **Shunt&#x20;*****j*****&#x20;status**      | Input or Output | <p>0 = Disconnected<br>1 = Connected</p> | **shuntID**/status*j* |
| **Current magnitude of shunt&#x20;*****j*** | Output          | A (RMS)                                  | **shuntID**/Imag*j*   |
| **Current angle of shunt&#x20;*****j***     | Output          | Degree                                   | **shuntID**/Iang*j*   |
| **Active power of shunt&#x20;*****j***      | Input or Output | kW                                       | **shuntID**/P*j*      |
| **Reactive power of shunt&#x20;*****j***    | Input or Output | kVAr                                     | **shuntID**/Q*j*      |

## Switch

| Pin Description              | Direction       | Value / Unit                  | Pin Identifier      |
| ---------------------------- | --------------- | ----------------------------- | ------------------- |
| **Switch status**            | Input or Output | <p>1 = Closed<br>0 = Open</p> | **switchID**/status |
| **Switch current magnitude** | Output          | A (RMS)                       | **switchID**/Imag   |
| **Switch current angle**     | Output          | Degree                        | **switchID**/Iang   |

## Transformer

| Pin Description                                                | Direction | Value / Unit                         | Pin Identifier                |
| -------------------------------------------------------------- | --------- | ------------------------------------ | ----------------------------- |
| **Tap position**                                               | Input     | Integer between `[min_tap, max_tap]` | **transformerID**/tap\_*j*    |
| **Tap voltage coefficient of winding&#x20;*****j***            | Output    | %                                    | **transformerID**/tap\_*j*    |
| **Current magnitude at sending end of winding&#x20;*****j***   | Output    | A (RMS)                              | **transformerID**/ImagFrom*j* |
| **Current magnitude at receiving end of winding&#x20;*****j*** | Output    | A (RMS)                              | **transformerID**/ImagTo*j*   |
| **Current angle at sending end of winding&#x20;*****j***       | Output    | Degree                               | **transformerID**/IangFrom*j* |
| **Current angle at receiving end of winding&#x20;*****j***     | Output    | Degree                               | **transformerID**/IangTo*j*   |

### Tap-changer behavior

The tap position determines the effective voltage multiplier applied by the transformer. The multiplier varies linearly between the configured minimum and maximum voltage-adjustment ranges.

Consider the following transformer configuration:

* **Min Range**: `0%`
* **Max Range**: `20%`
* **Lowest Tap**: `0`
* **Highest Tap**: `5`

If a **Tap position** of `3` is input, the resulting effective voltage multiplier is **1.12**.

The voltage adjustment per tap is:

$$
\Delta V\_{\mathrm{tap}}
========================

\frac{\mathrm{Max\ Range}-\mathrm{Min\ Range}}
{\mathrm{Highest\ Tap}-\mathrm{Lowest\ Tap}}
============================================

# \frac{20%-0%}{5-0}

4%
$$

At tap position 3, the effective voltage multiplier is:

$$
k\_{\mathrm{tap}}
=================

# 1+\frac{3\times4}{100}

1.12
$$

## Multiport Thevenin Equivalent Impedance (probe)

| Pin Description                          | Direction | Value / Unit | Pin Identifier                                |
| ---------------------------------------- | --------- | ------------ | --------------------------------------------- |
| **Real part of Thevenin impedance**      | Output    | pu           | **ProbeID\_zBusIndex1\_BusIndex2**/resistance |
| **Imaginary part of Thevenin impedance** | Output    | pu           | **ProbeID\_zBusIndex1\_BusIndex2**/reactance  |

where:

* **ProbeID** is the probe identifier defined in the Probe worksheet.
* **BusIndex1** is the index of the first bus in the probe bus list.
* **BusIndex2** is the index of the second bus in the probe bus list.

**Bus-to-ground impedance example:**

If **ProbeID** is `calc1`, the Thevenin impedance between the bus with index `2` and ground can be accessed using the following **Pin Identifiers**:

* **`calc1_z2_2`**`/resistance` and
* **`calc1_z2_2`**`/reactance`

**Bus-to-bus impedance example:**

If **ProbeID** is `calc2`, the Thevenin impedance between the buses with indexes `2` and `3` can be accessed using the following **Pin Identifiers**:

* **`calc2_z2_3`**`/resistance` and
* **`calc2_z2_3`**`/reactance`

### Complete example

This example uses the **PHASOR-07** 4-bus distribution system to calculate Thevenin equivalent impedances. In this multiphase model, each bus is represented by phase-specific identifiers such as `1_a`, `1_b`, and `1_c`.

1. Add a `ZTH_MP` probe to the **Probes** worksheet with the probe ID `calc`.
2. In the **Bus** field, list the bus identifiers for which impedance calculations will be performed (for example: bus identifiers 1\_a, 1\_b, 1\_c, 2\_a, 2\_b, 2\_c, 3\_a, 3\_b, 3\_c, 4\_a, 4\_b and 4\_c).

   <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-eccb4d587e71140e8d40eceea839e9f2d88c3931%2Feph-excel-probes-multiphase.png?alt=media" alt=""><figcaption></figcaption></figure>
3. Add the desired impedance outputs to the **Pins** worksheet. In the context of probes, **Bus Indexes** and **Bus Identifiers** are different. Bus indexes correspond to the position of each bus in the Probe worksheet: the first listed bus has index `1`, the second has index `2`, and so on. When defining probe **Pin Identifiers** in the **Pins** worksheet, use the **Bus Indexes** shown in red in the figure above, not the network **Bus Identifiers** shown in black.

For example:

* `calc_z2_3/resistance` outputs the Thevenin resistance between bus indexes `2` and `3`.
* `calc_z5_5/resistance` outputs the Thevenin resistance between bus index `5` and ground.
* The corresponding reactance values are obtained using the same identifiers with `/reactance`.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-a9754214d84f5400901cb5ccdb99e82f7f7eb711%2Feph-excel-probes-pins-multiphase.png?alt=media" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.opal-rt.com/docs/hypersim/model-and-simulation/phasor-domain-with-ephasorsim/configure-ephasorsim-block-ports/multiphase-pin-identifiers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
