> 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/integrate-a-power-system-model-to-ephasorsim/include-fmu-components/integrate-fmus/pss-e-model.md).

# PSS/E Model

Integrating a custom FMU with a network imported from **PSS®E** requires a **YAML mapping file**.

## Introduction

When integrating a custom FMU with a network imported from **PSS®E**, **CYME**, or **PowerFactory**, ePHASORSIM must know:

* Which parameters are expected by the FMU.
* How those FMU parameters map to parameters available in the imported model.
* Which network buses should be connected to the FMU Power Pins.

This information is defined in a mapping file. The mapping file acts as a bridge between the imported model and the FMU by identifying the required data, mapping imported parameters to FMU parameters, and connecting FMU Power Pins (`bus0`, `bus1`, ..., `busN`) to the appropriate network buses.

## YAML mapping file

The YAML mapping files have three sections:

* The `filters` map selects components from the list of all parsed components.
* The `variables` map creates custom variables to help the process of mapping. Usually not required in the context of FMUs.
* The `mappings` map takes those selected components and creates an arbitrary number of blocks in the database.

The whole mapping process can be seen as a mapping from a list of components in the parser to a list of blocks in the database. We assume that every component in the list from the parser will be used during the mapping process. Unused elements will raise warnings.

{% hint style="info" %}
**Glossary:**

* **Block**: The representation of a component inside the Unified Database
* **Component**: An element in the output of the parser
  {% endhint %}

### Filters section

A filter can select multiple components from the list of parsed components. The first declared component is considered the **main** component, only this one is considered to be imported by the mapping file.

All the following components are subcomponents, which will be, if not imported as the main component of another filter, considered unimported and logged in the remaining components warning. Subcomponents are optional, whether a subcomponent could be found can be checked using the `sub_aliases` variable explained later.

So, this leads us to the following structure:

```
filters:
   # Required
   main: ...

   # Optional - don't need to be defined
   sub: ...
```

The `main` map accepts only one component definition, but the `sub` map can have many.

A component can be defined taking into account three steps: **Alias**, **Parsed Type**, and **Condition**:

1. **Alias**: A name for the matched component. This can be used in the following Python expressions to refer to this component. The alias includes Python expressions within the mapping file and all its expressions.
2. **Parsed Type**: The type of the parsed component as indicated by the parser.
3. **Condition** (optional): A condition to narrow the selection of the component beyond the type. This is a Python expression.

That being said, the **alias** will be the key in our definition, and the **parsed type** and **condition** will come as a list of maps to that **alias**:

```
filters:
main:
   COMP:
      - type: ElmComp
         if: "True"
```

In the example above, `COMP` is the alias for the component that has a parsed type of `ElmComp` and will be mapped only if the `if` condition is met.

*Note: the convention is to use \`\`COMP\`\` as the alias of the main component.*

**Example (Main component and Subcomponents)**

The same applies for defining a sub-component:

```
filters:
main:
   COMP:
      - type: ElmComp
        if: "True"

sub:
   NET:
      - type: General
        if: "some condition to be evaluated"

   OTHER_COMPONENT: ...
```

#### Other forms of defining components in filters

**Example (Short form)**

Since the condition is optional when defining a component, we can use the short form of definition. In the last example, we can see that *COMP* has **if** as True. So, we don’t need to set a condition here, this way we can use the short form of definition, where the alias can directly receive the parsed type as its value:

```
filters:
main:
   # short form
   COMP: ElmComp
sub:
   # standard definition
   NET:
      - type: General
        if: "some condition to be evaluated"
   OTHER_COMPONENT: ...
```

**Example (Multiple parsed types for the same component)**

If the desired component can be mapped to multiple types in the parser, we can use a special keyword called types which expects a list of possible types:

```
filters:
main:
   # Define multiple types for a single component
   COMP:
      - types:
         - ElmComp
         - ElmComp2
         - ElmComp3
        if: "True" # Optional

sub:
   # standard definition
   NET:
      - type: General
        if: "some condition to be evaluated"

   OTHER_COMPONENT: ...
```

### Variables section

Usually not required in the context of FMUs.

<details>

<summary>Variables section details (optional reference)</summary>

Some mappings have common subexpressions in the expression for a block’s different parameters. The `variables` section of a filter is intended to allow this kind of sharing among expressions.

The section for custom variables starts with a key containing the text `variables`. The definition of a custom variable also takes up three pieces of information:

1. **Alias**: A name for the custom variable. This can be used in the same manner as the alias of a Component Filter.
2. **Value**: A Python expression generating the value to be assigned.
3. **Condition** (optional): A Python expression that is checked *before* assigning its value. If this returns a falsy value, the assignment is omitted. An empty expression is always true.

The difference between the definition of the components and custom variables is that for variables we don’t define a **type** but instead a **value**.

**Example (Components and Custom Variables)**

```
variables:
   generator:
      # Notice that here we don't define a condition, since it's an optional field
      - value: COMP.pelm[0]
   hasGenerator:
      -  value: True
         if: generator is not None
   generatorName:
      -  value: generator.name
         if: hasGenerator
   nominalFrequency:
      -  value: NET.Frequency_Hz
         if: 'NET' in sub_aliases
```

Here additional generator/hasGenerator/generatorName/nominalFrequency variables are introduced for use in the map file.

**Example (Short form)**

In the same way as the components definition, we can have a short form when the **if** it’s not defined in a single value attribution:

```
variables:
   generator: COMP.pelm[0]
   hasGenerator:
      - value: True
        if: generator is not None
   generatorName:
      - value: generator.name
        if: hasGenerator
   nominalFrequency:
      - value: NET.Frequency_Hz
        if: 'NET' in sub_aliases
```

**Example (Multiple values in a single variable)**

The system also supports multiple value definitions for the same variable depending (or not) on a condition. But we should keep in mind that **the order matters** when the values are evaluated. This means that the last evaluated value to have a true condition is the value stored.

```
variables:
   generator: COMP.pelm[0]
   hasGenerator:
      - value: True
        if: generator is not None
   generatorName:
      - value: generator.name
        if: hasGenerator
      - value: 1
        if: "other condition"
      - value: False
        if: hasGenerator and another condition
   nominalFrequency:
      - value: NET.Frequency_Hz
        if: 'NET' in sub_aliases
```

#### sub\_aliases

The *sub\_aliases* variable, available in all Python expressions is special. It contains the names of all matched subcomponents as Python strings.

**Example (Components and Custom Variables using sub\_aliases)**

```
variables:
   generator: COMP.pelm[0]
   hasGenerator:
      - value: True
        if: generator is not None
   generatorName:
      - value: generator.name
        if: hasGenerator
      - value: 1
        if: "other condition"
      - value: False
        if: hasGenerator and another condition
   nominalFrequency:
      - value: NET.Frequency_Hz
        if: 'NET' in sub_aliases
```

Here *sub\_aliases* is used to check whether the NET component was found in the list of parsed components.

</details>

### Mapping section

#### Block mapping

Each Block Mapping is made up of multiple attributions. As we do for components, for blocks we can define a **type** and also a **condition** (**if**), followed by the other parameters definition. Each block expects a list of that information

First, we need to define:

1. **Alias**: A name for the block that is currently being instantiated. This could be used to access the defaults of attributes and to access previously applied attributes. It goes as the key for the other attributions
2. **Type**: The type of this block. This corresponds to the name of a block definition within the blockset that can be queried from the UDB.
3. **Condition** (optional): A Python expression. If this expression returns a falsy value, the current block will not be instantiated. It has access to all filtered components, custom variables and `sub_aliases`. An empty expression is always true.

#### Block attributes

A block has three groups of attributes. These are `block`, `params` and `ports`.

* `block`: Metadata for the whole block. `block.name` is a unique name that is used to identify this block in other tools.
* `parameters`: Electrical/Modeling parameters for this block. The parameters available for a type of block can be checked in the block library in the Unicon.
* `ports`: Ports are used to connect two components. The values are simple strings that are used to match two ports up during simulation.

Each attribute takes up 3 definitions, the same as the `custom variables`:

1. **Name**: The attribute name, e.g. `name` or `Kd`.
2. **Value**: A Python expression used to generate the value of the attribute. This has access to all filtered components, custom variables and `sub_aliases`.
3. **Condition**: A Python expression. If this expression returns a falsy value, this attribute assignment will be skipped. It has access to all filtered components, custom variables and `sub_aliases`. An empty expression is always true.

This way, we can define the mapping of a block:

**Example**

```
mappings:
   BLOCK_GENERATOR:
      -  type: SYNCHRONOUS MACHINE
         if: 'GENERATOR' in sub_aliases
         block:
            name:
               - value: functions.id("gen_", GENERATOR)
         parameters:
            D:
               - value: GENERATOR.dpu
         ports:
            n1:
               -  value: GENERATOR.n1
                  if: some condition
```

**Example (Short form)**

```
mappings:
   BLOCK_GENERATOR:
      -  type: SYNCHRONOUS MACHINE
         if: 'GENERATOR' in sub_aliases
         block:
            name: functions.id("gen_", GENERATOR)
         parameters:
            D: GENERATOR.dpu
         ports:
            n1:
               -  value: GENERATOR.n1
                  if: some condition
```

**Example (Multiple values to the same attribute)**

```
mappings:
   BLOCK_GENERATOR:
      - type: SYNCHRONOUS MACHINE
         if: 'GENERATOR' in sub_aliases
         block:
            name: functions.id("gen_", GENERATOR)
         parameters:
            D:
               -  value: GENERATOR.dpu
               -  value: GENERATOR.toto
                  if: any condition
         ports:
            n1:
               -  value: GENERATOR.n1
                  if: some condition
```

### Final example (Entire mapping file)

After all the explanation above, this is what a complete mapping file looks like:

```
version: 1.0.0

filters:
main:
   COMP: ElmComp

sub:
   NET: General

variables:
   generator: COMP.pelm[0]
   hasGenerator:
      -  value: True
         if: generator is not None
   generatorName:
      -  value: generator.name
         if: hasGenerator
   hasNominalFrequency:
      -  value: True
         if: "NET" in sub_aliases
      -  value: False
         if: "NET" in sub_aliases
   nominalFrequency:
      -  value: NET.Frequency_Hz
         if: hasNominalFrequency

mappings:
   BLOCK_GENERATOR:
      -  type: SYNCHRONOUS MACHINE
         if: 'GENERATOR' in sub_aliases
         block:
           name: functions.id("gen_", GENERATOR)
         parameters:
            D:
               - value: GENERATOR.dpu
               - value: GENERATOR.toto
                 if: any condition
         ports:
            n1:
               - value: GENERATOR.n1
                 if: some condition
```


---

# 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/integrate-a-power-system-model-to-ephasorsim/include-fmu-components/integrate-fmus/pss-e-model.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.
