DLL Examples

Warning

This section is not complete yet.

These projects build a supporting wrapper around the IEEE/Cigre specification for dynamic link libraries (DLLs), and three examples. They should be built in the following order.

1. First, install the compiler and Cmake from Visual Studio (find Build Tools for Visual Studio 2022 under Tools for Visual Studio 2022). Python is also used for plotting test results.

2. All DLL builds are performed in the x64 Native Tools Command Prompt for VS 2022, which is on the Windows Start Menu.

3. Build the wrapper project, as the following four examples depend on it.

4. Build and test the SCRX9 example, which is a self-contained static exciter DLL from Electranix.

5. Build and test the GFM_GFL_IBR example, which is a self-contained inverter-based resource (IBR) controller from EPRI.

6. Build and test the GFM_GFL_IBR2 example, which is version 2 of a self-contained IBR controller from EPRI.

7. Build and test the HWPV example, which is a data-driven IBR model from PNNL and UCF. This example is not self-contained; you will have to download and build a JSON support library, and sample data-driven model files.

8. Build and test the PPC example, which is a renewable plant controlller model (WECC REPCA) compiled with OpenModelica (a required download for this example).

The build instructions will produce 64-bit and 32-bit versions of all example DLLs, test harnesses, and support libraries. A 32-bit simulator, such as ATP, will need the 32-bit DLLs.

These five examples can be built and tested in Python. To run the DLL examples in ATP, follow the linking instructions after compiling and linking the DLLs. An ATP license is required for access to these linking instructions.

SCRX9

This is an example DLL for the IEEE/Cigre specification, a static exciter model for synchronous machines. Developed by Electranix.

Build Instructions - Windows

Follow these instructions to make 64-bit and 32-bit versions of the DLL:

1. Open the x64 Native Tools Command Prompt for VS 2022 from Windows Start Menu

2. From the SCRX9 project directory (rd /s build and rd /s build32 if they exist):

   1. md build

   2. md build32

   3. cmake -B build -A x64

   4. cmake -B build32 -A Win32

   5. cmake --build build --config Release or cmake --build build --config Debug

   6. cmake --install build

   7. cmake --build build32 --config Release` or ``cmake --build build32 --config Debug

   8. cmake --install build32

3. From the SCRX9/build and SCRX9/build32 directories, check the exported functions with no wrapper:

   1. dumpbin /exports release/SCRX9.dll or dumpbin /exports debug/SCRX9.dll

   2. release/test generates an output CSV file in the ../../bin directory

   3. From the ../bin directory, relative to SCRX9, check outputs with python plotdlltest.py

4. From the ../bin and ../bin32 directories, check the DLL wrapper:

   1. test_scrx9 should give the same results as release/test above

   2. Verify with python plotdlltest.py from the ../bin and ../bin32 directories relative to SCRX9

File Directory

• CMakeLists.txt generates the detailed build instructions

• SCRX9.c is the (nearly) unmodified example file from Garth Irwin of Electranix

• test.c is a test harness, mimicking the DLL import and calling functions of a simulation tool

• test_scrx9.c is a test harness, invoking the DLL through an EMTHub wrapper that supports all IEEE/Cigre DLLs

Results

GFM GFL v1

This is an example DLL for the IEEE/Cigre specification, implementing grid-forming (GFL) and grid-following (GFL) behaviors for inverter-based resources (IBR). Developed by EPRI.

Build Instructions - Windows

Follow these instructions to make 64-bit and 32-bit versions of the DLL:

1. Open the x64 Native Tools Command Prompt for VS 2022 from Windows Start Menu

2. From the GFM_GFL_IBR project directory (rd /s build and rd /s build32 if they exist):

   1. md build

   2. md build32

   3. cmake -B build -A x64

   4. cmake -B build32 -A Win32

   5. cmake --build build --config Release or cmake --build build --config Debug

   6. cmake --install build

   7. cmake --build build32 --config Release` or ``cmake --build build32 --config Debug

   8. cmake --install build32

3. From the ../bin and ../bin32 directories, check the DLL wrapper:

   1. test_ibr should produce an output ibr.csv file

   2. Verify with python plotdlltest.py ibr.csv

File Directory

• CMakeLists.txt generates the detailed build instructions

• GFM_GFL_IBR.c is the unmodified example file from Deepak Ramasubramanian of EPRI

• test_ibr.c is a test harness, mimicking the DLL import and calling functions of a simulation tool

Results

GFM GFL v2

This is an example DLL for the IEEE/Cigre specification, implementing grid-forming (GFL) and grid-following (GFL) behaviors for inverter-based resources (IBR). See EPRI Report. This is a newer version of the EPRI-developed IBR model presented in ../gfm_gfl_ibr.

Build Instructions - Windows

Follow these instructions to make 64-bit and 32-bit versions of the DLL:

1. Open the x64 Native Tools Command Prompt for VS 2022 from Windows Start Menu

2. From the GFM_GFL_IBR2 project directory (rd /s build and rd /s build32 if they exist):

   1. md build

   2. md build32

   3. cmake -B build -A x64

   4. cmake -B build32 -A Win32

   5. cmake --build build --config Release or cmake --build build --config Debug

   6. cmake --install build

   7. cmake --build build32 --config Release` or ``cmake --build build32 --config Debug

   8. cmake --install build32

3. From the ../bin and ../bin32 directories, check the DLL wrapper:

   1. test_ibr2 should produce an output ibr2.csv file

   2. Verify with python plotdlltest.py ibr2.csv

File Directory

• CMakeLists.txt generates the detailed build instructions

• gfm_gfl_ibr2.c is the unmodified example file from Vishal Verma of EPRI, OCR-scanned from the report downloadable from https://www.epri.com/research/products/3002028322

• test_ibr2.c is a test harness, mimicking the DLL import and calling functions of a simulation tool

Results

HWPV

This is an example DLL for the IEEE/Cigre specification, implementing generalized block diagram models for solar photovoltaic inverters. See pecblocks for more information.

Build Instructions - Windows

Follow these instructions to make 64-bit and 32-bit versions of the DLL:

1. Open the x64 Native Tools Command Prompt for VS 2022 from Windows Start Menu

2. Download and build the required JSON support library, into a sibling directory of EMTHub.

   1. From the parent directory of EMTHub, git clone https://github.com/akheron/jansson.git

   2. cd jansson

   3. md build

   4. md build32

   5. cmake -B build -A x64

   6. cmake -B build32 -A Win32

   7. cmake --build build --config Release

   8. cmake --build build32 --config Release

   9. copy build\lib\release\jansson.lib ..\emthub\dll\lib

   10. copy build32\lib\release\jansson.lib ..\emthub\dll\lib32

3. Clone the _pecblocks_ repository, into a sibling directory of _EMTHub_, for some example models:

   1. From the parent directory of EMTHub, git clone https://github.com/pnnl/pecblocks.git

   2. The generalized block diagram models are located in various json files under the examples directory. Some of these must be run at reduced power output, until new versions are trained with sensitivity optimization, as described in pecblocks documentation

4. From this _hwpv_ project directory (rd /s build and rd /s build32 if they exist):

   1. md build

   2. md build32

   3. cmake -B build -A x64

   4. cmake -B build32 -A Win32

   5. cmake --build build --config Release or cmake --build build --config Debug

   6. cmake --install build

   7. cmake --build build32 --config Release or cmake --build build32 --config Debug

   8. cmake --install build32

5. From the ../bin and ../bin32 directories, check the DLL wrapper:

   1. test_hwpv should produce an output hwpv.csv file

   2. Verify with python plotdlltest.py hwpv.csv

File Directory

• CMakeLists.txt generates the detailed build instructions

• hwpv.c implements forward evaluation of the trained generalized block diagram model

• test_hwpv.c is a test harness, mimicking the DLL import and calling functions of a simulation tool

Results

WECC REPCA1

This directory contains an IEEE/CIGRE DLL wrapper around an FMU exported from OpenIPSL’s REPCA1 plant controller implementation [1]. Other resources [2] and [3].

Limitations:

• Parameters are fixed at initialization

• Snapshots and states are unsupported

Prequisites:

• Compiler and Cmake as described above

• OpenModelica (Tested with version 1.26.3)

• Python 3 (Tested with version 3.14.3)

[1]

M. De Castro et al., “Version [OpenIPSL 2.0.0] - [iTesla Power Systems Library (iPSL): A Modelica library for phasor time-domain simulations],” SoftwareX, vol. 21, p. 101277, Feb. 2023, doi: 10.1016/j.softx.2022.101277.

[2]

“Inverter-Based Resources Power Plant Modeling and Validation Guideline.” WECC. [Online]. Available: https://www.wecc.org/sites/default/files/documents/meeting/2026/IBR%20Power%20Plant%20Modeling%20and%20Validation%20Guideline.pdf

[3]

“Model User Guide for Generic Renewable Energy Systems.” [Online]. Available: https://www.epri.com/research/products/000000003002027129

Build Instructions - Windows

Follow these instructions to make 64-bit and 32-bit versions of the DLL:

1. Open the x64 Native Tools Command Prompt for VS 2022 from Windows Start Menu.

2. From the repository root:

   1. Checkout git submodule OpenIPSL from its git repository: git submodule update --init --recursive

   2. Regenerate the FMU build files (default as-tested path to omc.exe is shown): python dll\ppc\fmu\generate_fmu_build.py --omc-cmd "c:\program files\openmodelica1.26.3-64bit\bin\omc.exe"

   3. Remove build and build32 if they already exist.

   4. md build

   5. md build32

   6. cmake -S dll\ppc -B build -A x64

   7. cmake -S dll\ppc -B build32 -A Win32

   8. cmake --build build --config Release or cmake --build build --config Debug

   9. cmake --install build

   10. cmake --build build32 --config Release or cmake --build build32 --config Debug

   11. cmake --install build32

3. From the build and build32 directories, check the exported functions:

   1. dumpbin /exports Release\PPC.dll or dumpbin /exports Debug\PPC.dll

   2. Release\TEST_PPC.exe generates CSV output for the wrapper-based harness

   3. python ..\dll\bin\plotdlltest.py ppc_voltage_step.csv plots one of the CSV output files

4. From the installed output directories:

   1. x64 installs to dllbin

   2. Win32 installs to dllbin32

   3. TEST_PPC.exe can also be run from those installed directories

The tests write CSV outputs for the configured scenarios.

File Directory

• fmu/PPC.mo: wrapper model around OpenIPSL.Electrical.Renewables.PSSE.PlantController.REPCA1

• fmu/export_fmu.mos: OpenModelica FMU export script

• fmu/generate_fmu_build.py: regenerates dll/ppc/CMakeLists.txt after FMU export

• PPC.c: IEEE/CIGRE DLL wrapper around the exported FMU

• test_ppc.c: test harness using DLLWrapper

Results

Licenses

IEEE: Contributions as per IEEE Open Source Apache 2.0 CLA for P3743 WG EMTIOP

OpenIPSL: license as per open-source license in repository source (https://github.com/OpenIPSL/OpenIPSL.git):

BSD 3-Clause License

Copyright (c) 2016-2026 Luigi Vanfretti, ALSETLab (formerly SmarTS Lab) and contributors. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

• Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.