> 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/rt-lab/model-and-simulation/phasor-domain-with-ephasorsim/configure-ephasorsim-block-ports/positive-sequence-pin-identifiers.md).

# Positive-sequence 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 **positive-sequence networks**. Use these identifiers in the **Pins** worksheet to configure the ePHASORSIM block ports.

## 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          | pu (RMS)                              | **busID**/Vmag                                                                              |
| **Bus voltage angle**                         | Output          | Degree                                | <p><strong>busID</strong>/Vang (Wrapped)</p><p><strong>busID</strong>/VangU (Unwrapped)</p> |
| **Three-phase-to-ground fault status at bus** | Input or Output | <p>1 = Active<br>0 = Inactive</p>     | **busID**/active3PGFault                                                                    |
| **Fault conductance at bus**                  | Input or Output | pu                                    | **busID**/G\_fault                                                                          |
| **Fault susceptance at bus**                  | Input or Output | pu                                    | **busID**/B\_fault                                                                          |

Applying a fault to a bus causes a fault impedance to be connected between the bus and ground. The impedance is specified through the `G_fault` (conductance) and `B_fault` (susceptance) pins. When these pins are not connected, the default values are used (`G_fault = 1e5 pu`, `B_fault = 0 pu`).

## 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  |

## Exciter

| Pin Description                  | Direction       | Value / Unit | Pin Identifier           |
| -------------------------------- | --------------- | ------------ | ------------------------ |
| **Initial voltage reference**    | Output          | pu           | **exciterID**/Vref0      |
| **Voltage reference increment**  | Input or Output | pu           | **exciterID**/pins/dVref |
| **Exciter output voltage (Efd)** | Output          | pu           | **exciterID**/pins/Efd   |

## 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     | pu                | **VsourceID**/vMag       |
| **Internal voltage angle**     | Input     | Degree            | **VsourceID**/vAng       |
| **Internal resistance**        | Input     | pu (network base) | **VsourceID**/resistance |
| **Internal reac­tance**        | Input     | pu (network base) | **VsourceID**/reactance  |
| **Injected current magnitude** | Output    | pu                | **VsourceID**/Imag       |
| **Injected current angle**     | Output    | Degree            | **VsourceID**/Iang       |
| **Active power output**        | Output    | pu (network base) | **VsourceID**/Pout       |
| **Reactive power output**      | Output    | pu (network base) | **VsourceID**/Qout       |

## 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 | pu (network base)                           | **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 | pu (network base) | **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                  |
| **Three-phase-to-ground fault status**   | Input or Output | <p>1 = Active<br>0 = Inactive</p>           | **lineID**/faulty                  |
| **Line fault location from sending bus** | Input or Output | 0 < Value < 1                               | **lineID**/fault\_distance\_factor |
| **Sending-end current magnitude**        | Output          | pu (RMS, network base)                      | **lineID**/Imag0                   |
| **Sending-end current angle**            | Output          | Degree                                      | **lineID**/Iang0                   |
| **Receiving-end current magnitude**      | Output          | pu (RMS, network base)                      | **lineID**/Imag1                   |
| **Receiving-end current angle**          | Output          | Degree                                      | **lineID**/Iang1                   |
| **Sending-end active power**             | Output          | pu (network base)                           | **lineID**/P0                      |
| **Sending-end reactive power**           | Output          | pu (network base)                           | **lineID**/Q0                      |
| **Receiving-end active power**           | Output          | pu (network base)                           | **lineID**/P1                      |
| **Receiving-end reactive power**         | Output          | pu (network base)                           | **lineID**/Q1                      |
| **Active power loss**                    | Output          | pu (network base)                           | **lineID**/PL                      |
| **Reactive power loss**                  | Output          | pu (network base)                           | **lineID**/QL                      |
| **Line resistance**                      | Input or Output | pu (network base)                           | **lineID**/resistance              |
| **Line reactance**                       | Input or Output | pu (network base)                           | **lineID**/reactance               |
| **Line capacitance**                     | Input or Output | pu (network base)                           | **lineID**/capacitance             |

Applying a fault to a line creates a three-phase-to-ground fault at a specified location along the line. The fault location is defined by the `fault_distance_factor` pin, where a value between `0` and `1` represents the relative distance from the sending bus.A value of `0` places the fault at the sending end, while a value of `1` places it at the receiving end. When the `fault_distance_factor` pin is not connected, the default value of `0.5` is used, placing the fault at the midpoint of the line.

## Load

### Standard load

| Pin Description                  | Direction       | Value / Unit                                | Pin Identifier    |
| -------------------------------- | --------------- | ------------------------------------------- | ----------------- |
| **Load service status**          | Input or Output | <p>1 = In service<br>0 = Out of service</p> | **loadID**/status |
| **Load active power setpoint**   | Input           | MW                                          | **loadID**/P      |
| **Load reactive power setpoint** | Input           | MVAr                                        | **loadID**/Q      |
| **Load output active power**     | Output          | pu (network base)                           | **loadID**/Pout   |
| **Load output reactive power**   | Output          | pu (network base)                           | **loadID**/Qout   |
| **Load current magnitude**       | Output          | pu (network base)                           | **loadID**/Imag   |
| **Load current angle**           | Output          | Degree                                      | **loadID**/Iang   |

### Dynamic load

| Pin Description            | Direction       | Value / Unit                                | Pin Identifier    |
| -------------------------- | --------------- | ------------------------------------------- | ----------------- |
| **Load service status**    | Input or Output | <p>1 = In service<br>0 = Out of service</p> | **loadID**/status |
| **Load active power**      | Input or Output | MW                                          | **loadID**/P      |
| **Load reactive power**    | Input or Output | MVAr                                        | **loadID**/Q      |
| **Load current magnitude** | Output          | pu (network base)                           | **loadID**/Imag   |
| **Load current angle**     | Output          | Degree                                      | **loadID**/Iang   |

## Shunt

| Pin Description             | Direction       | Value / Unit                             | Pin Identifier     |
| --------------------------- | --------------- | ---------------------------------------- | ------------------ |
| **Shunt status**            | Input or Output | <p>0 = Disconnected<br>1 = Connected</p> | **shuntID**/status |
| **Shunt current magnitude** | Output          | pu (network base)                        | **shuntID**/Imag   |
| **Shunt current angle**     | Output          | Degree                                   | **shuntID**/Iang   |
| **Shunt active power**      | Input           | kW                                       | **shuntID**/P      |
| **Shunt reactive power**    | Input           | kVAr                                     | **shuntID**/Q      |

## Switch

| Pin Description              | Direction       | Value / Unit                  | Pin Identifier      |
| ---------------------------- | --------------- | ----------------------------- | ------------------- |
| **Switch or breaker 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            |
| ------------------------------------------------- | --------------- | ---------------------- | ------------------------- |
| **Transformer tap ratio of winding&#x20;*****j*** | Input or Output | pu                     | **transformerID**/rW*j*   |
| **Current magnitude of winding&#x20;*****j***     | Output          | pu (RMS, network base) | **transformerID**/Imag*j* |
| **Current angle of winding&#x20;*****j***         | Output          | Degree                 | **transformerID**/Iang*j* |

In the table above, ***j*** is used to distinguish signals associated with each transformer winding:

* `0`: Primary
* `1`: Secondary
* `2`: Tertiary

## 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-01** 39-bus transmission system to calculate Thevenin equivalent impedances.

1. Add a `ZTH_MP` probe to the **Probes** worksheet with the probe ID `calc`.
2. In the **Bus** field, list the buses for which impedance calculations will be performed (for example: buses 4, 5, 6, 7, and 8).

   <figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-79955d125c6dbbb1f31da38912a1ecf1f80d9a83%2Feph-excel-probes.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_z2_5/resistance` outputs the Thevenin resistance between bus indexes `2` and `5`.
* `calc_z2_2/resistance` outputs the Thevenin resistance between bus index `2` and ground.
* The corresponding reactance values are obtained using the same identifiers with `/reactance`.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-4d61f4848898234737dfe857cc64691e1ad196cf%2Feph-excel-probes-pins.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/rt-lab/model-and-simulation/phasor-domain-with-ephasorsim/configure-ephasorsim-block-ports/positive-sequence-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.
