Roadmap

These subsections provide a suggested order of activities for different kinds of stakeholders approaching EMT model interoperability.

Users

This roadmap applies to stakeholders that primarily run EMT simulations. It’s also a good starting point for developers to become familiar with content of the open-source software.

1. Installation - Windows of the Python code and testing from the Quick Start - Windows are prerequisites.

2. Consider whether to download MATPOWER for the power flow examples. This is open-source software that runs in open-source Octave, or in MATLAB.

3. Consider whether to download ATP for the EMT examples. This is free-to-use, but has restrictive license terms. Utilities, researchers, and some consultants are generally able to license ATP, but generally not EMT tool developers.

   1. Contributors are invited to provide examples that run in other EMT simulators.

4. Run the five cases in Network Examples using the following scripts.

This batch file extracts all five examples to CIM RDF, with ATP and MATPOWER netlisting. It also solves four examples in MATPOWER:

@echo off
for /L %%i in (0,1,3) do (
    emthub-extract-case %%i
    python raw_to_rdf.py %%i
    python bps_make_mpow.py %%i
    python mpow.py %%i
    python ic_to_rdf.py %%i
    python cim_to_atp.py %%i
    )
emthub-extract-case 4
python create_smib_dll.py 4
python cim_to_atp.py 4
python cim_summary.py

The last command summarizes CIM class counts in each example.

This batch file runs all five examples in ATP. In this version, plots are saved in png format so the batch file continues uninterrupted:

@echo off
for /L %%i in (0,1,4) do (
    python atp.py %%i "run"
    python atp.py %%i "convert"
    python atp.py %%i "png"
    )

With a MATPOWER installation, you should obtain summary power flow output with bus voltages usually in the range 0.95 to 1.05 per-unit. However, the XfmrSat example has low initial voltage at the load end of the line. The WECC240 case has a few dozen overloaded branches. The SMIBDLL example initializes from zero, so MATPOWER is not used with it.

With an ATP installation, you should be able to match the outputs in Network Examples.

Profile Maintainers

This roadmap applies to stakeholders that primarily manage CIM UML and profiles. They do not necessarily run EMT simulations.

1. Users Roadmap is a pre-requisite.

2. The CIM UML, which includes version 18v15 of the Grid package, should be obtained from the CIM Users Group. Look for Draft CIM Model Releases and then a 48-MB zip file that includes Grid18v15 in the file name. Download that to your hard drive and unzip it.

3. A UML editing tool is suggested for exploring and extending the CIM UML. Chapter 10 of the CIM Modeling Guide provides advice on this topic.

4. To create and update profiles, document profiles, produce SQL data definition scripts, and check CIM RDF instance files against a profile, you need the open-source CIMTool.

These files, tools, and on-line documents provide the initial knowledge base to perform segments of the workflow shown below. In the upper left, the file CIM_Grid_18v15.xmi [1] has been reduced in size, by deleting the unnecesary (for EMT) Enterprise and Market packages. For CIMTool, it was also necessary to delete profile packages distributed within the base CIM file by the CIM Users Group. The three shaded files are key items maintained on the open-source software site for P3743:

1. Emtiop.xmi contains the CIM extensions for EMT, output from the UML editor and input to CIMTool. This file is relatively small and kept under version control. It should be possible to use this extension file with future versions of the base CIM. The format is a variant of xml.

2. emtiop.owl is the profile for EMT. This is created by selecting classes and attributes from the base CIM with extensions in CIMTool. You should check example CIM RDF instance files, some of them listed at the lower left, against the profile and resolve any errors.

3. emtiop.html documents the classes and attributes used in the profile for EMT. It is built automatically from CIMTool and included in this on-line documentation as part of CIM Extension and Profile.

For use with SQL implementations, CIMTool also produces emtiop.sql to define SQL tables. This doesn’t work for Python’s sqlite3 package; manual editing is necessary to add foreign keys at the same time as tables are created. This is not necessary if using CIM RDF implementations.

CIMTool stores its files in a “workspace” under its local installation. Any files imported into CIMTool will be copied into this workspace. Once the files are copied, it’s recommended to let CIMTool manage the workspace files itself. CIMTool began as an Eclipse plugin, and has since been more conveniently packaged as a standalone installation. The following steps illustrate a successful sequence of importing the schema, importing the profile from version control, and checking one of the example instance files against the profile.

1. Extract the Repository if you haven’t already.

2. Start CIMTool. Version 2.3.0 RC4 was used in this demonstration.

3. Use the File/New/CIMTool Project menu command.

4. On the page New CIMTool Project, name the project emtioptest. It will typically create the workspace in C:\CIMTool-2.3.0-RC4\workspace\emtioptest. Click Next >.

5. On the page Project Copyright Templates Configuration, select the option Do not include copyrights and click Next >.

6. On the page Import Initial Schema:

   • Browse to the CIM_Grid_18v15.xmi file containing the base CIM schema, which includes the Grid18v15 package.

   • Specify the Namespace URI as http://www.ucauig.org/ns# (check the Preference option if necessary).

   • Leave the During import merge shadow class extensions and Enable self-healing options checked (these may be grayed out).

   • Turn off the CIMTool Schema Model Validation Report.

   • The page should look similar to the screen shot below. Click Finish.

7. The Project Explorer should show the imported CIM base schema, as shown below.

8. Use either the archived CIM extensions in Emtiop.xmi, or export your own Emtiop.xmi from the UML editing tool (EA or an alternative). This same procedure was used to create the base CIM_Grid_18v15.xmi file.

   • In EA, select the <<CIMExtension>> Emtiop* pacakge in the Browser, Project tab on the left-hand side of the application.

   • Invoke the Export / Other Formats menu command from the Publish tab in the ribbon.

   • Select the UML 1.4 (XMI 1.2) export type.

   • Select only the Format XML Output and Exclude EA Extensions options. Your dialog should be similar to that shown below. Verify that the Package at the top is Emtiop. Verify that Filename shows your desired output file.

   • Click Export and then you may exit EA

9. The next step is to add the CIM extension xmi file to the base CIM xmi file in CIMTool.

10. Right-click on the Schema item under the emtioptest workspace in Project Explorer. Click Import on the pop-up menu and then select Import Schema, as shown below.

11. Click Next to bring up the Import Schema page, similar to item 6. Leave the options as before, but browse to Emtiop.xmi in your local copy of the GitHub repository. The page should be similar to the screen shot below. Then click Finish.

12. The Project Explorer and Project Browser should reflect the content of both xmi files, as shown below.

13. Right-click on the Profiles item under the emtioptest workspace in Project Explorer. Click Import on the pop-up menu and then select Import Profile. Click Next. This brings up the Import Profile page. Click Browse and navigate to the archived emtiop.owl file as shown below. Then click Finish.

14. This imports and verifies the profile against the loaded schema of base CIM with extensions. Correct any errors reported. These are generally caused by mismatches in different versions of the profile and CIM extension, which may require some iterations to resolve. The profile import should produce no errors before taking the next step.

15. Right-click on the Instances item under the emtioptest workspace in Project Explorer. Click Import on the pop-up menu and then select Import Model (CIM/XML file). Then click Next. This brings up the Import a Model page. Click Browse and navigate to one of the example CIM RDF files, in xml format, as shown below. [2] The Namespace URI should be left as shown. The correct check boxes for Project and Profile should be selected. Then click Next.

16. The Model Details page should have a proper Model file name filled in. If you are re-importing the same model in the process of fixing errors, select the check box to Replace existing model. For a first-time import of that model, the check box should be disabled. Click Finish.

17. This imports and verifies the network model against the profile, including CIM extensions. Any errors should be resolved before testing other network models, and before deploying any code. This may require iterations in the CIM extensions, the profile, and/or the code used to create the network model xml files from raw and dyr files.

From this point, please consult the CIMTool documentation and the CIM Modeling Guide for advice on how to proceed.

[1]

Instead of importing two separate xmi files to CIMTool, it is also possible to import one CIM_Grid_18v15_Emtiop.qea file. This combined qea file is not under version control; a developer would have to merge the two separate xmi files into a single qea file using the commercial UML editor. This approach can be more efficient in working on CIM extensions and profiles in a single workflow. At significant milestones, be sure to export Emtiop.xmi from the UML editor for version control. We keep two xmi files under version control because only the smaller Emtiop.xmi is expected to change frequently.

[2]

The example xml files were generated in the directory shown by completing the Users Roadmap in that directory.

Network Model Developers

This roadmap applies to stakeholders that primarily import CIM network models to an EMT simulator’s native format, i.e., EMT software developers.

1. Users Roadmap is a pre-requisite.

2. Examine the create_atp.py file that creates ATP netlists. This can be a starting point for implementing other CIM importers for EMT, even without having an ATP license.

   1. This script creates a file ending in _net.atp. That file syntax should be readable to developers familiar with EMT, even without ATP documentation. For more help, try this book. It has examples with segments of ATP input text.

   2. The script may be found in the GitHub repository: create_atp.py.

   3. The script may also be found in your local emthub package installation. From a Windows Command Prompt, type pip show emthub. That will return a Location of your local emthub installation. Then you may find the ATP netlisting script at Location\emthub\create_atp.py. Using this method, you can examine other script and data files from your local emthub installation.

3. Become generally familiar with the CIM Extension and Profile. This is a reference, not meant to read from beginning to end.

4. Become generally familiar with the Queries to CIM RDF. This is also a reference, not meant to read from beginning to end.

5. Develop and test the CIM-to-EMT conversion script for your own EMT simulator.

   1. Try testing the XfmrSat example first. It is the smallest example and has no generator dynamics.

   2. Try testing the IEEE39 example next. It includes one IBR plant and some other machine dynamics..

   3. Try testing the SMIBDLL example next. This adds the essential DLL interface to the baseline features already tested.

   4. Try testing IEEE118 and then WECC240. These are similar to but larger than IEEE39 and they add a few more types of network model components.

DLL Developers

Note

To be completed.

This roadmap applies to stakeholders that primarily build DLL models of IBR and other controllers. This includes IBR hardware vendors, their consultants, researchers, and EMT software developers who are building test cases.

1. Users Roadmap is a pre-requisite.

2. Run all five DLL Examples.

3. Talk about build tools (already addressed in the DLL examples), P3597 involvement, and testing in a SMIB with an EMT simulator.