> 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/integrate-a-power-system-model-to-ephasorsim/use-a-powerfactory-model/prepare-the-dgs-xml-file/network-component-mapping.md).

# Network Component Mapping

## Bus data

Bus data is imported from the **ElmTerm** section of the DGS-XML file and mapped to the ePHASORSIM **Bus** native library component.

| Parameter | Description                      |
| --------- | -------------------------------- |
| `uknom`   | Nominal Voltage: Line-Line in kV |

## Line data

Line data is imported from the **ElmLne** and **TypeLne** sections of the DGS-XML file and mapped to the ePHASORSIM **Line** native library component.

**Parameters from ElmLne section:**

| Parameter | Description                                    |
| --------- | ---------------------------------------------- |
| `dline`   | Length of line (km). Must be a positive value. |

**Parameters from TypeLne section:**

| Parameter | Description                                         |
| --------- | --------------------------------------------------- |
| `uline`   | Rated Voltage                                       |
| `sline`   | Rated Current                                       |
| `rline`   | Series resistance (Ω/km)                            |
| `xline`   | Series reactance (Ω/km)                             |
| `bline`   | Shunt Susceptance (uS/km)                           |
| `aohl`    | Line type. Only `ohl` (overhead line) is supported. |

## Load data

Load data is imported from the **ElmLod** and **TypLod** sections of the DGS-XML file and mapped to the ePHASORSIM **Load** native library component.

**Parameters from ElmLod section:**

| Parameter | Description                             |
| --------- | --------------------------------------- |
| `plini`   | Operating Point: Active Power in MW     |
| `qlini`   | Operating Point: Reactive Power in MVAr |
| `scale0`  | Scaling factor of operating point       |
| `u0`      | Operating point voltage (pu)            |

**Parameters from TypLod section:**

| Parameter                        | Description                                                                                |
| -------------------------------- | ------------------------------------------------------------------------------------------ |
| `Static`, `Dynamic`              | Percentage of static and dynamic load behavior. `Static + Dynamic` must equal `100`.       |
| `aP`, `bP`, `cP`                 | Weights of the voltage-dependence terms for active power. `aP + bP + cP` must equal `1`.   |
| `e_aP`, `e_bP`, `e_cP`           | Exponents of the voltage-dependence terms for active power.                                |
| `aQ`, `bQ`, `cQ`                 | Weights of the voltage-dependence terms for reactive power. `aQ + bQ + cQ` must equal `1`. |
| `e_aQ`, `e_bQ`, `e_cQ`           | Exponents of the voltage-dependence terms for reactive power.                              |
| `kpf`, `kqf`                     | Frequency sensitivity coefficients for active and reactive power.                          |
| `udmin`, `udmax`                 | Voltage limits. Typical values are in the range `[0.7, 1.3]` pu.                           |
| `t1`, `tpu`, `tqu`, `tpf`, `tqf` | Time constants for the voltage and frequency dependence of active and reactive power.      |

{% hint style="danger" %}

* For dynamic loads, only nonlinear voltage and linear frequency is supported.
* Only symmetrical `udmin/udmax` are supported (with regard to 1pu). In case of an unsymmetrical range of voltage (e.g \[0.7-1.2]), ePHASORSIM will create a symmetrical range based on `udmax` (i.e. \[0.8-1.2]).
* `u0` is only considered in the calculation when using dynamic loads.
  {% endhint %}

## Shunt data

Shunt data is imported from the **ElmShnt** section of the DGS-XML file and mapped to the ePHASORSIM **Shunt** native library component.

| Parameter | Description                                         |
| --------- | --------------------------------------------------- |
| `shtype`  | Shunt type: `1` = RL shunt, `2` = capacitive shunt. |
| `rrea`    | Resistance                                          |
| `xrea`    | Impedance                                           |
| `qcapn`   | Rated Capacitive Power                              |

## Switch data

Switch data is imported from the **StaSwitch** section of the DGS-XML file and mapped to the ePHASORSIM **Switch** native library component.

<table><thead><tr><th>Parameter</th><th width="229.111083984375">Description</th><th></th></tr></thead><tbody><tr><td><code>on_off</code></td><td>Switches inital status</td><td><code>1</code> for close<br><code>2</code> for open</td></tr></tbody></table>

## Transformer data

### Two-winding transformers

Two-winding transformer data is imported from the **ElmTr2** and **TypTr2** sections of the DGS-XML file and mapped to the ePHASORSIM **2WTransformer** native library component.

**Parameters from ElmTr2 section:**

| Parameter  | Description                       |
| ---------- | --------------------------------- |
| `nntap`    | Position for “Tap Changer 1”      |
| `rSbasepu` | Resistance on network Sbase (pu)  |
| `xSbasepu` | Reactance on network Sbase (pu)   |
| `bSbasepu` | Susceptance on network Sbase (pu) |

**Parameters from TypTr2 section:**

<table data-search="false"><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>strn</code></td><td>Rated power (MVA)</td></tr><tr><td><code>utrn_h</code></td><td>HV-Side rated voltage (kv)</td></tr><tr><td><code>utrn_l</code></td><td>LV-Side rated voltage (kv)</td></tr><tr><td><code>tr2cn_h</code></td><td>HV-Side vector group. Must be <code>YN</code> or <code>D</code>.</td></tr><tr><td><code>tr2cn_l</code></td><td>LV-Side vector group. Must be <code>YN</code> or <code>D</code>.</td></tr><tr><td><code>nt2ag</code></td><td>Phase shift vector group</td></tr><tr><td><code>dutap</code></td><td>Additional voltage per tap</td></tr><tr><td><code>phitr</code></td><td>Phase change per tap</td></tr><tr><td><code>nntap0</code></td><td>Neutral tap position</td></tr><tr><td><code>ntpmn</code></td><td>Minimum tap position</td></tr><tr><td><code>ntpmx</code></td><td>Maximum tap position</td></tr></tbody></table>

### Three-winding transformers

Three-winding transformer data is imported from the **ElmTr3** and **TypTr3** sections of the DGS-XML file and mapped to the ePHASORSIM **3WTransformer** native library component.

**Parameters from ElmTr3 section:**

<table data-search="false"><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>n3tap_h</code></td><td>Tap HV-Side: Act. Position in</td></tr><tr><td><code>n3tap_m</code></td><td>Tap MV-Side: Act. Position in</td></tr><tr><td><code>n3tap_l</code></td><td>Tap LV-Side: Act. Position in</td></tr><tr><td><code>rSbasepu_hm</code></td><td>Resistance between HV-MV in Net­work Sbase (pu)</td></tr><tr><td><code>rSbasepu_ml</code></td><td>Resistance between MV-LV in Net­work Sbase (pu)</td></tr><tr><td><code>rSbasepu_lh</code></td><td>Resistance between LV-HV in Net­work Sbase (pu)</td></tr><tr><td><code>xSbasepu_hm</code></td><td>Reactance between HV-MV in Net­work Sbase (pu)</td></tr><tr><td><code>xSbasepu_ml</code></td><td>Reactance between MV-LV in Net­work Sbase (pu)</td></tr><tr><td><code>xSbasepu_lh</code></td><td>Reactance between LV-HV in Network Sbase (pu)</td></tr><tr><td><code>bSbasepu</code></td><td>Susceptance in network Sbase (pu)</td></tr></tbody></table>

**Parameters from TypTr3 section:**

<table data-search="false"><thead><tr><th>Parameter</th><th></th></tr></thead><tbody><tr><td><code>strn3_h</code></td><td>Rated Power: HV-Side (MVA)</td></tr><tr><td><code>strn3_m</code></td><td>Rated Power: MV-Side (MVA)</td></tr><tr><td><code>strn3_l</code></td><td>Rated Power: LV-Side (MVA)</td></tr><tr><td><code>utrn3_h</code></td><td>HV-Side rated voltage (kv)</td></tr><tr><td><code>utrn3_m</code></td><td>MV-Side rated voltage (kv)</td></tr><tr><td><code>utrn3_l</code></td><td>LV-Side rated voltage (kv)</td></tr><tr><td><code>tr3cn_h</code></td><td>HV-Side vector group. Must be <code>YN</code> or <code>D</code>.</td></tr><tr><td><code>tr3cn_m</code></td><td>MV-Side vector group. Must be <code>YN</code> or <code>D</code>.</td></tr><tr><td><code>tr3cn_l</code></td><td>LV-Side vector group. Must be <code>YN</code> or <code>D</code>.</td></tr><tr><td><code>nt3ag_h</code></td><td>HV-side phase shift vector group</td></tr><tr><td><code>nt3ag_m</code></td><td>MV-side phase shift vector group</td></tr><tr><td><code>nt3ag_l</code></td><td>LV-side phase shift vector group</td></tr><tr><td><code>du3tp_h</code></td><td>Tap HV-Side: Add. Voltage per Tap</td></tr><tr><td><code>du3tp_m</code></td><td>Tap MV-Side: Add. Voltage per Tap</td></tr><tr><td><code>du3tp_l</code></td><td>Tap LV-Side: Add. Voltage per Tap</td></tr><tr><td><code>n3tp0_h</code></td><td>HV-Side: Neutral Position</td></tr><tr><td><code>n3tp0_m</code></td><td>MV-Side: Neutral Position</td></tr><tr><td><code>n3tp0_l</code></td><td>LV-Side: Neutral Position</td></tr><tr><td><code>i3loc</code></td><td>Magnetizing Impedance</td></tr></tbody></table>

## Machine data

Synchronous machine data is imported from the **ElmSym** and **TypSym** sections of the DGS-XML file and mapped to the ePHASORSIM **Synchronous Machine** native library component.

**Parameters from ElmSym section:**

<table data-search="false"><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>ngnum</code></td><td>Number of parallel Machines</td></tr><tr><td><code>pgini</code></td><td>Dispatch: Active Power in MW</td></tr><tr><td><code>qgini</code></td><td>Dispatch: Reactive Power in MVAr</td></tr><tr><td><code>usetp</code></td><td>Dispatch: Voltage in pu</td></tr><tr><td><code>q_min</code></td><td>Minimum reactive power operational Limits (pu)</td></tr><tr><td><code>q_max</code></td><td>Maximum reactive power operational Limits (pu)</td></tr><tr><td><code>ip_ctrl</code></td><td>Slack bus<br><code>0</code> = False<br><code>1</code>= True</td></tr><tr><td><code>i_mot</code></td><td>Must be <code>0</code> (generator).</td></tr><tr><td><code>phiini</code></td><td>Initial voltage angle (-180 to +180 degrees)</td></tr></tbody></table>

**Parameters from TypSym section:**

<table data-search="false"><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>sgn</code></td><td>Nominal apparent power (MVA)</td></tr><tr><td><code>ugn</code></td><td>Nominal voltage (kV)</td></tr><tr><td><code>iturbo</code></td><td>Rotor type<br><code>0</code> = Salient rotor<br><code>1</code> = Round rotor</td></tr><tr><td><code>rstr</code></td><td>Stator resistance (pu)</td></tr><tr><td><code>xd</code></td><td>d-axis reactance (pu)</td></tr><tr><td><code>xq</code></td><td>q-axis reactance (pu)</td></tr><tr><td><code>xds</code></td><td>d-axis transient reactance xd' (pu)</td></tr><tr><td><code>xqs</code></td><td>q-axis transient reactance xq' (pu)</td></tr><tr><td><code>xdss</code></td><td>d-axis sub-transient reactance (pu)</td></tr><tr><td><code>xqss</code></td><td>q-axis sub-transient reactance (pu)</td></tr><tr><td><code>h</code></td><td>Inertia constant H (s)</td></tr><tr><td><code>dpu</code></td><td><p>Turbine shaft friction torque coefficient</p><p>(Damping factor)</p></td></tr><tr><td><code>xl</code></td><td>Leakage reactance (pu)</td></tr><tr><td><code>tds0</code></td><td>d-axis transient time constant (s)</td></tr><tr><td><code>tqs0</code></td><td>q-axis transient time constant (s)</td></tr><tr><td><code>tdss0</code></td><td>d-axis sub-transient time constant (s)</td></tr><tr><td><code>tqss0</code></td><td>q-axis sub-transient time constant (s)</td></tr><tr><td><code>sg10</code></td><td>Saturation function value for 1 pu</td></tr><tr><td><code>sg12</code></td><td>Saturation function value for 1.2 pu</td></tr><tr><td><code>model_inp</code></td><td>Model type. Must be:<br><code>det</code> = Standard Model (equivalent to SynGenGENROU model)<br><code>cls</code> = Classical Mode (equivalent to ‘SynGenGENCLS’ model)</td></tr><tr><td><code>isat</code></td><td>Flux saturation<br><code>0</code> = Not Considered<br><code>1</code> = Considered</td></tr></tbody></table>

## Voltage source data

Voltage source data is imported from the **ElmVac** section of the DGS-XML file and mapped to the ePHASORSIM **Voltage Source** native library component.

| Parameter | Description                |
| --------- | -------------------------- |
| `phisetp` | Voltage angle offset (deg) |
| `usetp`   | Voltage magnitude (pu)     |
| `X1`      | Internal inductance (Ω)    |
| `R1`      | Internal resistance (Ω)    |

## Static generator data

Static generator is imported from the **ElmGenstat** section of the DGS-XML file. Depending on their PowerFactory configuration, the static generator components are mapped to different ePHASORSIM native library **Load** components. This mapping is determined by the selected load-flow controller and RMS model. The imported component determines which signals can be controlled through I/O pins.

| PowerFactory Configuration         | Imported Component and Available Control Signals                                                                                                                 | Notes                                                                                                                                   |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Const. Q + Current Source          | <p><strong>Constant Current Load</strong><br>Incoming signals: <code>P</code>, <code>Q</code></p>                                                                | Load-flow results may differ slightly because PowerFactory treats `P` and `Q` as fixed, while ePHASORSIM treats the current as fixed.   |
| Const. Q + Constant Impedance      | <p><strong>Constant Impedance Load</strong><br>Incoming signals: <code>P</code>, <code>Q</code></p>                                                              | Load-flow results may differ slightly because PowerFactory treats `P` and `Q` as fixed, while ePHASORSIM treats the impedance as fixed. |
| Const. Q + Constant Power          | <p><strong>Constant Power Load</strong><br>Incoming signals: <code>P</code>, <code>Q</code></p>                                                                  | —                                                                                                                                       |
| Const. V + Current Source          | <p><strong>Controllable Current Source</strong><br>Incoming signals: <code>P</code>, <code>Q</code> <strong>or</strong> <code>Imag</code>, <code>Iang</code></p> | Control either the power pair or the current pair, but not both.                                                                        |
| Const. V + Voltage Source          | <p><strong>Voltage Source</strong><br>Incoming signals: <code>Vmag</code>, <code>Vang</code>, <code>resistance</code>, <code>reactance</code></p>                | Always control both `Vmag` and `Vang`.                                                                                                  |
| Reference Machine + Voltage Source | <p><strong>Voltage Source</strong><br>Incoming signals: <code>Vmag</code>, <code>Vang</code>, <code>resistance</code>, <code>reactance</code></p>                | Acts as the system reference machine.                                                                                                   |
| Const. V + Constant Impedance      | <p><strong>Constant Impedance Load</strong><br>No dedicated control signals</p>                                                                                  | Supported, but uncommon. Results may not be reliable.                                                                                   |
| Const. V + Constant Power          | <p><strong>Constant Power Load</strong><br>No dedicated control signals</p>                                                                                      | Supported, but uncommon. Results may not be reliable.                                                                                   |

{% hint style="info" %}

* If the **Simulation RMS Model** is set to *According to connected input signals* (`iSimModel = 0`), the import defaults to a **Constant Current Load**. Select the desired RMS model explicitly to avoid unexpected import results.
* ePHASORSIM supports only the classical load-flow bus types (**PQ**, **PV**, and **Slack**). Other PowerFactory local-controller modes are not supported.
* Minimum operating-voltage thresholds are not supported.
* External station controllers and secondary load-flow controllers are not imported.
  {% endhint %}

**Parameters from ElmGenstat section:**

<table data-search="false"><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>ngnum</code></td><td>Number of parallel units (int)</td></tr><tr><td><code>model_inp</code></td><td>Dispatch: Input model<br>Must = <code>DEF</code></td></tr><tr><td><code>pgini</code></td><td>Dispatch: Active Power in MW</td></tr><tr><td><code>qgini</code></td><td>Dispatch: Reactive Power in MVAr</td></tr><tr><td><code>scale0</code></td><td>Dispatch: Scaling Factor</td></tr><tr><td><code>av_mode</code></td><td>Local Controller Mode<br>“Const. V” and “Const. Q”</td></tr><tr><td><code>iSimModel</code></td><td>Simulation RMS Model</td></tr><tr><td><code>cQ_min, cQ_max</code></td><td>Reactive power limits in case of “constant V” load flow controller (PV bus in MVAr)</td></tr><tr><td><code>usetp</code></td><td>Bus voltage magnitude in case of “Constant V” load flow controller (PV bus in pu)</td></tr><tr><td><code>phiini</code></td><td>Bus voltage angle when static generator is the “Reference Machine” (degrees)</td></tr><tr><td><code>uk, Pcu</code></td><td>Series Reactor (Only Considered for Voltage Source model)</td></tr></tbody></table>

### Use static generator external controllers

Composite-model controllers from PowerFactory are not imported into ePHASORSIM. To reproduce their behavior, implement the controller externally in Simulink or HYPERSIM and exchange signals with ePHASORSIM through I/O pins.

**Example: Controlling a static generator voltage source**

Consider a PowerFactory model where a controller regulates the voltage of a static generator through the voltage signals (`ur`, `ui`).

To reproduce this behavior in ePHASORSIM:

1. Configure the static generator as a **Voltage Source** in PowerFactory.
2. Implement the controller in Simulink or HYPERSIM.
3. Configure the controller outputs as voltage magnitude (`Vmag`) and voltage angle (`Vang`). If the controller uses another representation (for example, `dq` or real/imaginary components), convert the output signals to magnitude-angle form.
4. Define `Vmag` and `Vang` as **incoming signals** in the Excel Pins worksheet.
5. Connect the controller outputs to the corresponding ePHASORSIM input signals.
6. If the controller requires feedback from the network, define the required ePHASORSIM signals as **outgoing signals** and connect them to the controller inputs.

**Example: Static generator apparent power computation**

For the following parameter values:

* ngnum = 2
* scale0 = 1
* pgini = 15 MW
* qgini = 5 MVAr

ePHASORSIM imports the static generator as a negative constant-power load with an apparent power of:

$$
S\_{Load} = ngnum \cdot scale0 \left\[ (-1)\cdot pgini + (-1)\cdot j \cdot qgini \right] = 2 \times 1 \times \left\[ (-1)\times 15 + (-1)\times j \times 5 \right] = -30 - j10\ \text{MVA}
$$

Therefore, the apparent power is:

$$
\Rightarrow P\_{Load} = -30\ \text{MW}, \qquad Q\_{Load} = -10\ \text{MVAr}
$$


---

# 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/integrate-a-power-system-model-to-ephasorsim/use-a-powerfactory-model/prepare-the-dgs-xml-file/network-component-mapping.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.
