> 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/control-interfaces/cigre-interface.md).

# CIGRÉ Interface

## Description

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

**CIGRÉ Interface block**, located in the **Control Interfaces** library, integrates manufacturer controller code into HYPERSIM based on the **IEEE/CIGRÉ B4.82 API**. The controller must be provided as a Windows 64-bit DLL that follows the working group’s interface. HYPERSIM packages the selected controller as a User-Coded Model (UCM) inside the model’s \_hyp folder.

<details>

<summary>For instructions and requirements related to DLL integration, see the IEEE/CIGRÉ DLL Modeling Method – Manual.</summary>

{% file src="/files/J0qA2QXvblgXizbJHp7e" %}

</details>

### Real-Time Container

The new **Real-time Container** allows Windows 64-bit DLLs to executed *as-is* on our real-time simulators environment without any recompilation of the controller's source code. This feature requires the **BlackBox Interface Tools** to be properly installed on the target. For installation instructions, see [Tools](https://www.opal-rt.com/docs/hypersim/model-and-simulation/prepare-the-simulation/set-simulation-parameters/target-manager.md#tools) in the **Target Manager** documentation.

## Create and configure the CIGRÉ block

An example model [CIGRÉ integrator](https://www.opal-rt.com/docs/hypersim/examples/how-to/cigre-integrator.md) is available. In the example folder "C:\OPAL-RT\HYPERSIM\\\<HYPERSIM-version>\Windows\demo\How To\CIGRE\_Integrator", the **CigreIntegrator.hypcigre** file could be used for testing purposes.

### Create the CIGRÉ block

Adding a new **CIGRÉ Interface** block to the schematic inserts an **empty placeholder block**. At this stage, no CIGRÉ controller is associated with the block, and therefore no controller information is included in the netlist.

{% hint style="danger" %}
A CIGRÉ controller available only in **Linux format** must be recompiled for Windows before it can be integrated and executed in HYPERSIM.
{% endhint %}

Double-click the empty block to open its parameter dialog box. From this dialog, you can select the CIGRÉ controller to associate with the interface block, after which the corresponding controller data will be included in the netlist.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-e1e8f41749f05b9f6416cd39d64995a3f3548d84%2Fcigre-interface-.png?alt=media" alt="" width="345"><figcaption></figcaption></figure>

Select the **CIGRÉ controller unit file** then click on Import button.

* A **.hypcigre file** is a JSON formatted file describing a HYPERSIM CIGRÉ project. It is created by pressing the hyperlink in the dialog box.
* A **.cigre file** is a ZIP archive containing an exported HYPERSIM CIGRÉ project. It can be created either from the hypcigre configuration interface or by right-clicking a **CIGRÉ controller** in the schematic and selecting the export option.

HYPERSIM will implement the CIGRÉ as a [User-Coded Model (UCM)](https://www.opal-rt.com/docs/hypersim/model-and-simulation/import-models-from-external-software-or-code/create-user-coded-models-ucm.md). The various files and settings will be packaged inside the \_hyp folder of the model.

When a **.cigre file is selected**, its contents must be extracted into a **new empty folder**. This process recreates the original hypcigre project and automatically links it to the newly created CIGRÉ controller instance. Once the file is selected, click **Import** and specify a destination folder.

{% hint style="info" %}
Since the files mentioned in the CIGRÉ configuration menu are packaged inside a custom format, editing the files on disk (updating the main library or any of its dependencies) will not affect existing blocks
{% endhint %}

### Define and update parameters

To open the **CIGRÉ Generator** window, right-click the block and select **Edit Unit** from the **CIGRÉ** menu.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-889708f94e54929938fb54011cca7d787853932b%2Fcigre-generator-general.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

<table><thead><tr><th width="200">Command</th><th>Description</th></tr></thead><tbody><tr><td><strong>Export</strong></td><td>Allows users to export the project as a .cigre file.</td></tr><tr><td><strong>Save</strong></td><td>Saves the latest changes.<br>After modifying a CIGRÉ configuration, the changes must be reloaded into the model. To do so, right-click the CIGRÉ block and select <strong>CIGRÉ > Reload Unit</strong>.</td></tr><tr><td><strong>Cancel</strong></td><td>Closes the window without saving any changes</td></tr></tbody></table>

The **General** page displays general information about the CIGRÉ controller. It is non editable.

#### **Packaging pages**

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-a450d2b85f2b46e21f21f0f271b056047b0abd7b%2Fcigre-generator-packaging.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

The **Packaging** pages allows to select the files which are required for runtime simulation.

While the **Windows main DLL library** is required, it does not need to be specified if the model is intended to run exclusively on **real-time target environments**.

Providing the **Linux package** is optional. When provided, it is used to execute the CIGRÉ controller in real time on **Linux targets**. If it is not provided, the Windows DLL can be executed on Linux targets through the **Real-Time Container**, provided that the [**BlackBox Interface Tools**](https://www.opal-rt.com/docs/hypersim/model-and-simulation/prepare-the-simulation/set-simulation-parameters/target-manager.md#tools) are installed.

<table><thead><tr><th width="200">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Main Library</strong></td><td><p>Specifies the path to the library which respects the CIGRÉ standard, to be executed during the simulation.</p><ul><li><strong>Windows</strong> : It must be a 64 bit “dll” and <strong>must be provided</strong>. While the mathematical implementation is not required if the CIGRÉ is only required on real time simulations, the windows library is used to extract the parameters, inputs and outputs of the CIGRÉ.</li><li><strong>Linux</strong> : It must be a 64 bit “so” library. This library is optional.</li></ul></td></tr><tr><td><strong>Runtime dependencies</strong></td><td><p>The list of files which will be required for the correct execution of the CIGRÉ library during simulation.</p><p>By default, all files will be put next to the main library of the architecture. However, a relative path can be defined, in case a hierarchy of file is required by the implementation of the CIGRÉ library.</p></td></tr></tbody></table>

#### Execution page

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-962392e2e9d1903b37655624129ee4e9d5c271ab%2Fcigre-generator-execution.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

The **Execution** page is used to configure HYPERSIM settings that determine how the CIGRÉ controller is executed during simulation.

<table><thead><tr><th width="200">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Execution time (s)</strong></td><td><p>Specifies the execution time for the CIGRÉ during a single time step. It will be used during the task mapping.</p><p>Note : The value entered represents the execution time before adjusting for the target’s processor performance</p></td></tr></tbody></table>

#### Summary page

This section is non editable. It displays all information available via the CIGRÉ main Windows DLL.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-03f64e32cada48544865552112bcc18c55296012%2Fcigre-generator-summary.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

### Update configuration and portability

When the hypcigre file is written, every path to a file is transformed to support relative pathing following the [**portability guidelines**](https://github.com/Opal-RT-Technologies/product-docs-hypersim/tree/release-2026.4/model-and-simulation/project-import-and-export/README.md).

Since the hypcigre is not related to a HYPERSIM model but to the CIGRÉ controller, keywords related to the HYPERSIM model are not applicable. Additionally, the keyword **${HYP\_CIGRE\_PARENT}** refers to the folder containing the hypcigre.

The generated UCM stores a relative path to the internal hypcigre project. To view this reference, open the **Attributes** dialog box and inspect the **HyModelProp** field.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-14222b59fc572749ef23c239e4297e85c880386e%2Fcigre-attributes-path.png?alt=media" alt=""><figcaption></figcaption></figure>

## Mask parameters

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-08f98a7edf60eb194981ebb2c786fe586c1c724b%2Fcigre-block-parameter.png?alt=media" alt=""><figcaption></figcaption></figure>

Any additional parameters defined in the CIGRÉ interface will be visible in this form, and configurable as any UCM. However, the CIGRÉ instance has a several additional parameters.

### Sample time

<table><thead><tr><th width="200">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Base sample time</strong></td><td>Sample time defined by the CIGRÉ controller.</td></tr><tr><td><strong>User-defined sample time</strong></td><td><p>Overrides the sample time.</p><ul><li>If set to 0, the controller executes at the simulation time step.</li><li>If set to a smaller value than the simulation time step, the controller executes multiple times per step. For example, with a 50 us simulation step and a 10 us sample time, the controller runs 5 times per step and repeats the input values.</li><li>If set to a larger value than the simulation time step, the controller executes every N steps. For example, with a 50 us simulation step and a 200 us sample time, it runs every 4 steps.</li></ul><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><h3><strong>Current limitation</strong></h3><p>even when the controller sample time is slower than the simulation time step, the simulation waits for the controller to finish before advancing to the next step.</p></div></td></tr></tbody></table>

### Real-Time Container Options

<table><thead><tr><th width="200">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Always use .DLL when available</strong></td><td><p>Forces the use of the Windows DLL through the Real-Time Container, even when a Linux version of the CIGRÉ controller is available.</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><h3><strong>Information</strong></h3><p>If only a Windows 64-bit version of the CIGRÉ controller is available, the Real-Time Container is always used to run it.</p></div></td></tr><tr><td><strong>Real-Time Container Core</strong></td><td><p>Selects the processor core to be used by the Real-Time Container. If set to -1, the first available core is used.</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><h3><strong>Information</strong></h3><p>This parameter has no effect if the Real-Time Container is not used to run that CIGRÉ controller.</p></div></td></tr></tbody></table>

## Inputs

<table><thead><tr><th width="200">Input</th><th>Description</th></tr></thead><tbody><tr><td><strong>Defined by the CIGRÉ controller</strong></td><td>Inputs are discovered from the Windows DLL via the IEEE/CIGRÉ B4.82 API and vary by implementation.</td></tr></tbody></table>

## Outputs

<table><thead><tr><th width="200">Output</th><th>Description</th></tr></thead><tbody><tr><td><strong>Defined by the CIGRÉ controller</strong></td><td>Outputs are discovered from the Windows DLL via the IEEE/CIGRÉ B4.82 API and vary by implementation.</td></tr></tbody></table>


---

# 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/control-interfaces/cigre-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.
