> 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/example-models/ehs-example-models/energy-example-models/future-grid-city.md).

# Future Grid City

## Description <a href="#description" id="description"></a>

The **Future Grid City** model illustrates the real-time simulation of a section of a three-phase low-voltage distribution network with distributed photovoltaic (PV) generation units, developed using Schematic Editor and solved using the eHS solver. The power network is simulated on FPGA, while a distribution transformer and low-voltage loads are simulated on CPU and connected to the FPGA simulation through a three-phase stubline interface.

Each PV generation unit consists of a two-stage transformer-less converter operating in open loop. Scaling Transformer components represent both series/parallel arrangements of PV modules and multiple identical converters operating in parallel, without explicitly simulating every unit.

This example comprises an RT-LAB project with a console to adjust grid voltage, load breakers, and simulation scenarios, and to monitor voltages and currents in real time.

## Detailed explanation

The RT-LAB model consists of a master subsystem (i.e. "sm\_master") and a console.

The **master subsystem** has

* a power network interface ("eHS\_SE\_SFunction\_Drivers")
* a CPU-based SmartPowerSimulation (SPS) distribution transformer and low-voltage loads
* a stubline interface to the FPGA simulation
* auxiliary subsystems for RMS/P/Q calculations ("RMS")
* scenario changes ("Scenario Settings")
* test execution
* result recording

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-9cdc161971514efdd997e9a7368f72ad13ab555b%2Ffigure-004.png?alt=media" alt=""><figcaption><p>sm_master in Model</p></figcaption></figure>

The **Console** is used to manually set boundary values, such as grid voltage, load breakers, and scenarios, during real-time simulation. Users can also monitor voltages and currents at different stages of the circuit.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-eabdd7f8ba9a025e6d868f4847922a1810a6330f%2Ffigure-005.png?alt=media" alt=""><figcaption><p>Console</p></figcaption></figure>

The **"eHS\_SE\_SFunction\_Drivers" solver** solves the power network built using Schematic Editor during real-time simulation. The circuit can be edited or viewed using the edit option in the solver block. The schematic includes the three-phase stubline interface to the CPU simulation, low-voltage loads, and PV-fed transformer-less inverters connected to the grid.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-0615807ababeada1324006d534063c7368a1370d%2Ffigure-006.png?alt=media" alt=""><figcaption><p>eHS model</p></figcaption></figure>

eFPGASIM allows multiple parameter sets for elements. In this example, the connection between the converters and the grid is changed by varying the resistances of `breaker_XY` and `freewheelXY`. Different current gain factors are also used to evaluate the impact of increasing distributed generation.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-8e3fc88cd6e93eb7e199d4ca2efa057b16b9e858%2Ffigure-007.png?alt=media" alt=""><figcaption><p>Breakers and inverter scaling using parameter sets</p></figcaption></figure>

When the model is compiled in Simulink, the configuration of the eHS solver is generated according to the Schematic Editor circuit characteristics. Elements are put into matrices and stored in .mat files that are transferred to the solver when the model is run from RT-LAB. Matrices are generated during model compilation in RT-LAB.

**Control of the PV converters** is implemented in open loop, with a CPU model simulation time step of 50 microseconds.

**Modulating waveforms** generated by the controller are converted to PWM via the OPAL-RT PWMO I/O block. The PWM pulses are fed back through digital loopback (internal or external) to control the eHS converters. Gating pulses are received through the simulator's digital inputs.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-c1656cc4538dbda54182920b5f04cd5161b6d61c%2Ffigure-008.png?alt=media" alt=""><figcaption><p>Gating pulses from Digital In channels</p></figcaption></figure>

The OPAL-RT hardware chassis and FPGA module must be selected in Schematic Editor before building the model. Go to **Simulation > Simulator Setup**, choose the simulator and firmware, and select **Use this setup** according to the simulation requirements.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-89b4cd8977b8c5ebc424e5062d6da9ba10046cb1%2Ffigure-009.png?alt=media" alt=""><figcaption><p>Simulator Setup and Solver Settings</p></figcaption></figure>

## Requirements <a href="#requirements" id="requirements"></a>

RT-LAB, Schematic Editor/Unified Database and the eHS Power Electronics Toolbox must be installed in order to successfully run this example project.

<details>

<summary><strong>OP5607 and OP5707 simulators</strong></summary>

In this configuration, an external Digital Output–to–Digital Input **loopback connection** must be used to control the gate signals. Connect a loopback cable from a digital output to the corresponding digital input on the simulator. This connection is required for the simulation to run successfully.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-c295d6b5e4702def97289d92b5756a5ab5359746%2FOP5607-OP5707-loopback.png?alt=media" alt=""><figcaption></figcaption></figure>

</details>

<details>

<summary><strong>OP4512 and OP4610 simulators</strong></summary>

When configured in **bi-directional mode**, the OP5369 card supports an internal Digital Output–to–Digital Input loopback. This allows a Digital Input assigned to a channel to directly read the signal generated by the Digital Output on the same channel.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-afa99eb09df0333f7f74ff01b5731e22fcf30a6d%2FOP4512-OP4610-loopback-interne.png?alt=media" alt=""><figcaption></figcaption></figure>

</details>

{% hint style="info" %}
If your IO Configuration contains bi-directional OP5369 card, you can always use its internal loopback capability.
{% endhint %}

## Simulation and results

The following procedure helps the user understand the functionality and linking between eFPGASIM, RT-LAB and Schematic Editor. A Hardware-in-the-loop based RT-LAB model illustrates the exchange of information between CPU and FPGA.

If eFPGASIM is installed, add the example project to RT-LAB by selecting **File>>New>>RT-LAB Project>>eFPGASIM>>Schematic\_Editor\_Workflow>>Energy>>Future Grid City**.

### Setup Parameters

This model must be run with both Hardware Synchronized and XHP modes enabled. The firmware used in this model is generated using RT-XSG and can be modified for another I/O hardware configuration. The CPU model simulation time step is set to 50 microseconds, and the variables required for the controller are defined in the "initializeExample.m" file, automatically loaded during simulation.

Digital loopback (internal or external) is used to transfer the gating pulses.

<details>

<summary><strong>S-function Workflow</strong></summary>

The **Mezzanine Option block** is an RT-LAB block used in the **S-Function workflow** to configure the settings of the I/O cards for each mezzanine. The available settings depend on the specific type of I/O card.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-f1b6053e49e0affae24fc2d39f5f8bcc8688cd6f%2Fboost-2levelinverter-exmodel-sfunction.png?alt=media" alt=""><figcaption></figcaption></figure>

</details>

<details>

<summary><strong>OpalBoard workflow</strong></summary>

[OPAL-RT Board](https://www.opal-rt.com/docs/rt-lab/configure-ios/analog-digital-and-sfp-ios/opal-rt-board-workflow.md) allow the configuration of I/O card settings for each mezzanine.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-2f4eed5a89d21acaca1e8426fce5331e36396a68%2Fboost-2levelinverter-exmodel-opalboard.png?alt=media" alt=""><figcaption></figcaption></figure>

If, for a given I/O mezzanine, this block is not used, then the corresponding settings will be kept at their default values. These default values are dependent on particularities of the bitstream, and they are not guaranteed to be exposed to the user loading their model. Further, the default values populating the Mezzanine Option block do not necessarily correspond to the default settings that will be seen if the Mezzanine Option block is not used.

Note that if a Mezzanine Option block is used, and the choice of mezzanine type is incorrect for the given slot, the model will still load and run. However, there will be errors in the load log in RT-LAB. For example, the following error is observed in the case that slot 1A on the simulator holds an OP5330-3, when we place a Mezzanine Option block that attempts to configure an OP5369 on slot 1A:

{% code overflow="wrap" lineNumbers="true" %}

```
Mezzanine configurator: OP5369 Threshold configuration.
ERROR: OPAL-RT Board: The threshold control register for slot 1A is in an unexpected state. Please reprogram the bitstream.
ERROR: Mezzanine configurator: Threshold configuration failed...
```

{% endcode %}

Further, as documented in the aforementioned RT-LAB page, the block outputs its status: a 0 in the case when the block’s settings have been correctly applied, and a -1 otherwise. For example, in the below model I incorrectly configured one block by giving it the wrong I/O card, and set the other correctly. The result when we load the model reflects this:

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-a4fe002fb70685f86d0a022ad92068069ae7264d%2Fehs-opalboard-block-workflow.png?alt=media" alt="" width="188"><figcaption></figcaption></figure>

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-635a0707a1e24ec9979ba91be578dae9fe0d6dac%2Fehs-opalborad-model-blocks.png?alt=media" alt=""><figcaption></figcaption></figure>

</details>

{% hint style="info" %}
In S-Function workflow, example models support any chassis. You can contextualize your example model by selecting the chassis in the Chassis selection block.
{% endhint %}

### Run the model

During real-time execution in the RT-LAB Dashboard, the following scenarios can be selected:

#### 1- Change PV generation penetration

The model allows the number of PV inverters represented by the Scaling Transformer to be varied: one inverter (pass-through), two balanced inverters, or different numbers of inverters per phase.

#### 2- Loss of phases

The model allows the following breaker configurations: normal operation (0); breaker A open, disconnecting inverters AB and CA (1); breaker B open, disconnecting inverters AB and BC (2); breaker C open, disconnecting inverters CA and BC (3); or breakers ABC open, disconnecting all inverters (4).


---

# 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/example-models/ehs-example-models/energy-example-models/future-grid-city.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.
