> 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/library-blocks-reference/network-interfaces/ephasorsim-interface.md).

# ePHASORSIM Interface

## Description

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-3f67298ca7a76fb167d760d5197c567ceecfafd1%2Fimage%20(1104).png?alt=media" alt="" width="162"><figcaption></figcaption></figure>

The **ePHASORSIM Interface** block, located in the **Network Interface** library, runs real-time phasor-domain simulations of large power systems within HYPERSIM. It supports transient stability and steady-state studies, integrates tightly with HYPERSIM for co-simulation with EMT models, and offers model import from Excel, PSS/E, and PowerFactory formats. The CYME import format is not supported.

{% hint style="danger" %}
**Some features require a specific license key**. They are identified with a lock and key icon .
{% endhint %}

<details>

<summary><strong>More information on licensing</strong></summary>

The table below describes each license keys that may be used to unlock ePHASORSIM’s powerful features.

| **Licence key**                    | **Feature**                                                                                                                                                     |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EPHASOR_RT`                       | Enables ePHASORSIM on a real-time target.                                                                                                                       |
| `EPHASOR_NRT`                      | Enables ePHASORSIM offline (on Windows host).                                                                                                                   |
| `EPHASOR_NUM_POWERSYSTEM_NODES`    | Maximum size of a power system (in number of nodes) that can be simulated by ePHASORSIM.                                                                        |
| `EPHASOR_INPUTFORMAT_PSSE`         | Enables ePHASORSIM’s PSS/E data file input feature.                                                                                                             |
| `EPHASOR_INPUTFORMAT_POWERFACTORY` | Enables ePHASORSIM’s PowerFactory data file input feature.                                                                                                      |
| `EPHASOR_FEATURE_POWERFLOW`        | <p>Enables power-flow computation on the host<br>(Even though the target uses the results of the power-flow, the target’s license doesn’t contain this key)</p> |

| **Parallel processing**         | **Feature**                                                                                                                                                                                                                                 |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EPHASOR_NUM_CORES`             | <p>Maximum number of cores that can be used for simulation on a Linux target.<br>(If this key is set to a number strictly higher than 1, <code>EPHASOR\_PARALLELIZE\_GENUNITS</code> is enabled.)</p>                                       |
| `EPHASOR_PARALLELIZE_GENUNITS`  | <p>Enables parallel computation for generator units in the embedded library and FMUs (machines and their controllers).<br>(If this key is set, <code>EPHASOR\_NUM\_CORES</code> is set to a number strictly higher than 1)</p>              |
| `EPHASOR_PARTITION_POWERSYSTEM` | <p>Enables partitioning of the power system: when the power system is partitioned, the network’s nodal equations are computed in parallel.<br>(If this key is enabled, <code>EPHASOR\_PARALLELIZE\_GENUNITS</code> is enabled as well.)</p> |

</details>

{% hint style="danger" %}
To use the ePHASORSIM Interface, **enable Dashboard** in Preferences.
{% endhint %}

## Mask parameters

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-09e88fbcdd123879bd6f164c7eb8a9ad9c66840b%2Fephasorsim.jpg?alt=media" alt=""><figcaption></figcaption></figure>

{% tabs %}
{% tab title="Excel import format" %}

| **Parameter**                      | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Import format files**            | Power system model (\*.xlsx)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **External components (optional)** | <p>Specify external components to include in the simulation.<br>Details on including FMUs are in \[Phasor-Domain with ePHASORSIM}(./../model-and-simulation/README ) section.<br><strong>Select Folder</strong>: Import external components that interact with the grid (e.g., renewable sources, control devices).</p>                                                                                                                                                                                                                          |
| T**ime Step**                      | Set the simulation time step(s)The time step defines the phasor solve rate and accuracy (For example 0.01 s).                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **Number of cores**                | Sets the number of CPU cores used for parallel computation. Each thread runs on a distinct core. A value of 1 disables parallelization.                                                                                                                                                                                                                                                                                                                                                                                                          |
| **Number of partitions**           | <p>Reserved for future use to improve parallelization. The only valid value is 1.License keys required:</p><ul><li>EPHASOR\_PARTITION\_POWERSYSTEM</li><li>EPHASOR\_PARALLELIZE\_GENUNITS</li></ul>                                                                                                                                                                                                                                                                                                                                              |
| **Timeout for sync client**        | Advanced setting to extend initialization time for signal acquisition synchronization, useful for large models. Expert setting; it is recommended to keep the default value.                                                                                                                                                                                                                                                                                                                                                                     |
| **Calculate load flow**            | Initializes bus voltages for a steady-state start. Disable if load flow results are already included in the import files.                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **Max iterations**                 | Maximum Newton–Raphson iterations for load flow convergence. Typical value: 100.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **Tolerance**                      | Convergence tolerance for load flow (per-unit mismatch). Example: 1.0000e-8.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **Initialization mode**            | <p>Select the Newton–Raphson starting point:</p><ul><li><strong>From Input Data</strong>: Uses bus voltages provided in the input files. Best when input includes valid load flow results.</li><li><strong>Flat Start</strong>: Initializes PQ buses to Vmag = 1 pu, Vang = 0 deg; PV and Slack angles set to 0 deg with original magnitudes.</li><li><strong>Smart Start</strong>: Starts from Flat Start, runs one linear load flow iteration to improve initial conditions for better convergence on large or challenging networks.</li></ul> |
| {% endtab %}                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

{% tab title="PSS/E import format" %}

| **Parameter**                         | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Import format files**               | <ul><li>I/O pins file (<em>.xlsx)</em></li><li><em>DYR file (</em>.dyr)</li><li>RAW file (\*.raw)</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **External components (optional)**    | <p>Specify external components to include in the simulation.<br><strong>Select Folder</strong>: Import external components that interact with the grid (e.g., renewable sources, control devices).</p>                                                                                                                                                                                                                                                                                                                                           |
| **Mappings (required conditionally)** | <p>Required when external components are included and the import format is PSS/E or Powerfactory. The mappings file specification is in the ePHASORSIM documentation (.yaml FMU Specification).<br><strong>Select File</strong>: Provide the component identifier to external component mapping.</p>                                                                                                                                                                                                                                             |
| **Time Step**                         | Set the simulation time step(s)The time step defines the phasor solve rate and accuracy (For example 0.01 s).                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **Number of cores**                   | Sets the number of CPU cores used for parallel computation. Each thread runs on a distinct core. A value of 1 disables parallelization.                                                                                                                                                                                                                                                                                                                                                                                                          |
| **Number of partitions**              | <p>Reserved for future use to improve parallelization. The only valid value is 1.License keys required:</p><ul><li>EPHASOR\_PARTITION\_POWERSYSTEM</li><li>EPHASOR\_PARALLELIZE\_GENUNITS</li></ul>                                                                                                                                                                                                                                                                                                                                              |
| **Timeout for sync client**           | Advanced setting to extend initialization time for signal acquisition synchronization, useful for large models. Expert setting; it is recommended to keep the default value.                                                                                                                                                                                                                                                                                                                                                                     |
| **Calculate load flow**               | Initializes bus voltages for a steady-state start. Disable if load flow results are already included in the import files.                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **Max iterations**                    | Maximum Newton–Raphson iterations for load flow convergence. Typical value: 100.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **Tolerance**                         | Convergence tolerance for load flow (per-unit mismatch). Example: 1.0000e-8.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **Initialization mode**               | <p>Select the Newton–Raphson starting point:</p><ul><li><strong>From Input Data</strong>: Uses bus voltages provided in the input files. Best when input includes valid load flow results.</li><li><strong>Flat Start</strong>: Initializes PQ buses to Vmag = 1 pu, Vang = 0 deg; PV and Slack angles set to 0 deg with original magnitudes.</li><li><strong>Smart Start</strong>: Starts from Flat Start, runs one linear load flow iteration to improve initial conditions for better convergence on large or challenging networks.</li></ul> |
| {% endtab %}                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

{% tab title="Powerfactory import factory" %}

| **Parameter**                         | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Import format files**               | <ul><li>I/O pins file (<em>.xlsx)</em></li><li><em>DGS file (</em>.xml)</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| **Import switches**                   | <p>Filter switch components when importing a Powerfactory model :</p><ul><li><strong>All switches</strong> : All switches are imported.</li><li><strong>No switch</strong> : All switches are excluded.</li><li><strong>Switches with events only</strong> : Only switches associated with events in the original model are imported.</li></ul>                                                                                                                                                                                                  |
| **External components (optional)**    | <p>Specify external components to include in the simulation.<br><strong>Select Folder</strong>: Import external components that interact with the grid (e.g., renewable sources, control devices).</p>                                                                                                                                                                                                                                                                                                                                           |
| **Mappings (required conditionally)** | <p>Required when external components are included and the import format is PSS/E or Powerfactory. The mappings file specification is in the ePHASORSIM documentation (.yaml FMU Specification).<br><strong>Select File</strong>: Provide the component identifier to external component mapping.</p>                                                                                                                                                                                                                                             |
| **Time Step**                         | Set the simulation time step(s)The time step defines the phasor solve rate and accuracy (For example 0.01 s).                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **Number of cores**                   | Sets the number of CPU cores used for parallel computation. Each thread runs on a distinct core. A value of 1 disables parallelization.                                                                                                                                                                                                                                                                                                                                                                                                          |
| **Number of partitions**              | <p>Reserved for future use to improve parallelization. The only valid value is 1.License keys required:</p><ul><li>EPHASOR\_PARTITION\_POWERSYSTEM</li><li>EPHASOR\_PARALLELIZE\_GENUNITS</li></ul>                                                                                                                                                                                                                                                                                                                                              |
| **Timeout for sync client**           | Advanced setting to extend initialization time for signal acquisition synchronization, useful for large models. Expert setting; it is recommended to keep the default value.                                                                                                                                                                                                                                                                                                                                                                     |
| **Calculate load flow**               | Initializes bus voltages for a steady-state start. Disable if load flow results are already included in the import files.                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **Max iterations**                    | Maximum Newton–Raphson iterations for load flow convergence. Typical value: 100.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **Tolerance**                         | Convergence tolerance for load flow (per-unit mismatch). Example: 1.0000e-8.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **Initialization mode**               | <p>Select the Newton–Raphson starting point:</p><ul><li><strong>From Input Data</strong>: Uses bus voltages provided in the input files. Best when input includes valid load flow results.</li><li><strong>Flat Start</strong>: Initializes PQ buses to Vmag = 1 pu, Vang = 0 deg; PV and Slack angles set to 0 deg with original magnitudes.</li><li><strong>Smart Start</strong>: Starts from Flat Start, runs one linear load flow iteration to improve initial conditions for better convergence on large or challenging networks.</li></ul> |
| {% endtab %}                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| {% endtabs %}                         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

{% hint style="danger" %}
After a successful Create, changes to the import source files are not propagated. **To apply source changes, create a new block and reconnect signals**.
{% endhint %}

## Inputs

This block has no inputs.

## Outputs

This block has no outputs.

## Characteristics and limitations

The ePHASORSIM interface is still in its early development stages and comes with some limitations. These limitations are listed here, and will be subject to changes in the upcoming HYPERSIM versions as the development continues.

* Computational cores used by the parallelization are not visible and cannot be modified by HYPERSIM's Task Mapper.
* The user cannot visualize load flow results.
* The ePHASORSIM python API is not supported with this integration.
* The use of user defined components is supported through the external components field in the model configuration view, however the FMUCreator, used to generate those external components, is currently only available with RT-LAB.


---

# 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/library-blocks-reference/network-interfaces/ephasorsim-interface.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.
