> 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/include-fmu-components/integrate-fmus/pss-e-model/example.md).

# Example

## Mapping file syntax <a href="#yaml-specification-syntax" id="yaml-specification-syntax"></a>

The `.yaml` mapping file syntax is displayed on the right of the PSS/E example `CSTCNT.yaml` below. In this example, the PSS/E `FACTS_DEVICE` with its DYR component `CSTCNT` is mapped to a custom FMU named `CSTCNT`.

{% hint style="info" %}
Further below, the PSS/E input parameters and OpenModelica parameters are also shown to illustrate how the mappings between the third-party data and Modelica-based FMU match.
{% endhint %}

{% hint style="info" %}
Information on the `.yaml` specification in a broader context extending beyond the FMU Specification in ePHASORSIM is available at [.yaml Appendix](https://opal-rt.atlassian.net/wiki/spaces/PEUD/pages/1404667018).

However please note that in the FMU Specification context, it is sufficient to start from examples and adapt them to the FMU at hand.
{% endhint %}

{% columns %}
{% column %}

```
version: 1.0.0
filters:
  main:
    COMP: FACTS_DEVICE
  sub:
    CSTCNT:
      - type: CSTCNT
        if: CSTCNT.FACTSNAME == COMP.uid.split("_")[-1]
    BUS:
      - type: BUS
        if: BUS.I == COMP.I
mappings:
  DB_COMP:
    - type: Subsystem
      if: '"CSTCNT" in ListSubAlias and len(ListSubAlias) == 2'
      block:
        name: f"facts_{COMP.uid}"
      parameters:
        fmuModelIdentifier: '"CSTCNT"'
        IB: CSTCNT.M
        T1: CSTCNT.J
        T2: CSTCNT.J_1
        T3: CSTCNT.J_2
        T4: CSTCNT.J_3
        K: CSTCNT.J_4
        Droop: CSTCNT.J_5
        Vmax: CSTCNT.J_6
        Vmin: CSTCNT.J_7
        ICMAX: CSTCNT.J_8
        ILMAX: CSTCNT.J_9
        Vcutout: CSTCNT.J_10
        Elimit: CSTCNT.J_11
        Xt: CSTCNT.J_12
        Acc: CSTCNT.J_13
        P_gen: COMP.PDES
        Q_gen: COMP.VSMX
        Qmax: COMP.SHMX
        Qmin: -COMP.SHMX
        SB: COMP.RMPCT
        Vt_abs: BUS.VM
        Vt_ang: BUS.VA
        ZSOURCE_RE: COMP.VTMN
        fn: fBase
      ports:
        bus0: f"bus_{BUS.I}"
```

{% endcolumn %}

{% column %}
Under the `filters` section, we configure which data from the third-party input model we filter for the mapping at hand:

* the `main` key is required to define the **type** of component we fetch from the third-party input data
  * once filtered from the input data, the component is named with the **alias** `COMP`
  * this **alias** is later available when we proceed to the `mappings` below
  * in the example, the **alias** `COMP` contains the `FACTS_DEVICE` parameters from the .raw file
* the `sub` key is optional and defines to which subcomponents we want to have accessto in addition to the main component
  * `CSTCNT` and `BUS` are fetched from the input .dyr and .raw files according to specific `if` conditions and instantiated in `CSTCNT` and `BUS` **aliases** respectively

***

Under the `mappings` section, we reuse the aliases from the `filters` section to map the parameters to the target Modelica-based FMU.

The `if` condition can be used to restrict the mapping to a given condition.

For example, here we only proceed with the mapping if we found an instance of a `CSTCNT` subcomponent and two instances of `sub` components in the list of subcomponents (named `ListSubAlias`)

The **alias** `DB_COMP` and **type** `Subsystem` must remain unchanged.

Under the `parameters` section, the Modelica-based FMU parameters are mapped one by one by to the third-party component parameters via their respective component **aliases**.

The parameter `fmuModelIdentifier` is required and **must match exactly** the name of the Modelica-based FMU.

Under the `ports` section, the Modelica-based FMU ports are mapped to the third-party buses. The ports must be named `bus0`, `bus1`, …, `busN`.
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column %}
**PSS/E component parameters:**

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-77493dc5ccc0a2c1e3d2ce0e38ed5e7692269ffa%2Feph-fmu-psse-modelica-example.png?alt=media" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column %}
**Modelica-based FMU parameters:**

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-5663fdb57a2c73020ac5ce1605f69723029c2688%2Feph-fmu-psse-example.png?alt=media" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}


---

# 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/include-fmu-components/integrate-fmus/pss-e-model/example.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.
