Copyright (c) 2017-2021, Battelle Memorial Institute
This is a tool set for translating electric power distribution system models between various formats, using the IEC Standard 61970/61968 Common Information Model (CIM) as the "Hub". Requirements
The CIM data is stored in an open-source triple-store called Blazegraph. Python 3 scripts depend on SPARQLWrapper. The Java code uses OpenJDK 11 and builds with Apache Maven.
Please make sure that GIT LFS is installed before checking out or cloning this repository.
CIMHub requires Docker for the database engine, and it runs on Linux (best), Windows or Mac OS X. Some of the converters to OpenDSS may only work on Windows, in cases where the input file comes from a Windows-only database.
Blazegraph requires Java 8, which is no longer widely available for new installations. Blazegraph isn't compatible with Java 9 or newer versions. Therefore, we recommend using Blazegraph in a Docker container:
This example converts two versions of the IEEE 13-Bus case from OpenDSS to CIM and GridLAB-D, without writing code. One version uses phase impedance matrices for line segments. The other version, labeled "Assets", uses wire and spacing data for the line segments, and transformer code data for the transformers.
The example script may produce error messages upon first invocation, because the Blazegraph engine doesn't start immediately. However, the example does complete successfully. You may re-run the example starting from step 2. You may also wish to modify docker-compose.yml so that it mounts a local directory inside the converter, for transferring your own files between the host and Docker.
To convert your own circuits from OpenDSS to CIM and GridLAB-D, follow the IEEE 13-Bus example described above, with some changes:
If you don't have an OpenDSS model, see the converters provided in this repository.
Usage and options for java gov.pnnl.gridappsd.cimhub.CIMImporter [options] output_root
-q={queries file} // optional file with CIM namespace and component queries (defaults to CIM100)
-s={mRID} // select one feeder by CIM mRID; selects all feeders if not specified
-o={glm|dss|both|idx|cim|csv} // output format; defaults to glm; currently cim supports only CIM14
-l={0..1} // load scaling factor; defaults to 1
-f={50|60} // system frequency; defaults to 60
-n={schedule_name} // root filename for scheduled ZIP loads (defaults to none), valid only for -o=glm
-z={0..1} // constant Z portion (defaults to 0 for CIM-defined LoadResponseCharacteristic)
-i={0..1} // constant I portion (defaults to 0 for CIM-defined LoadResponseCharacteristic)
-p={0..1} // constant P portion (defaults to 0 for CIM-defined LoadResponseCharacteristic)
-r={0..1} // determine ZIP load fraction based on given xml file or randomized fractions
-h={0..1} // determine if house load objects should be added to supplement EnergyConsumers
-x={0, 1} // indicate whether for glm, the model will be called with a fault_check already created
-t={0, 1} // request timing of top-level methods and SPARQL queries, requires -o=both for methods
-u={http://localhost:8889/bigdata/namespace/kb/sparql} // blazegraph uri (if connecting over HTTP); defaults to http://localhost:8889/bigdata/namespace/kb/sparql
The output format options are:
-o=cim
creates a CIM14 model from CIM100-o=csv
creates a set of comma-delimited text files from CIM100-o=dss
creates an OpenDSS model from CIM100-o=glm
creates a GridLAB-D model from CIM 100-o=both
creates both OpenDSS and GridLAB-D models from CIM100 -o=idx
creates a JSON index of all Feeders in the triple-store. Use this to obtain valid mRID values for the -s optionIf you will need both OpenDSS and GridLAB-D files, the -o=both
option is much more efficient than generating them individually,
because over 90% of the execution time is taken up with SPARQL queries that are common to both.
It could be more convenient to run only Blazegraph in a Docker container, writing code and queries on the host.
You can also run the IEEE 13-bus example conversions from the host Terminal.
Step 2 provides a dummy argument so that the example script will select a different URL for Blazegraph. When querying from the host, the URL contains localhost:8889 but when querying from a Docker terminal, the URL contains blazegraph:8080, which is valid only on the internal network that Docker creates. Also, with a dummy argument, the example will try to run GridLAB-D on the converted example models. This will fail unless you have GridLAB-D installed on the host. If you do have GridLAB-D, tail test*.csv to check the results.
In order to develop Python code for the CIM, it should suffice to pip3 install sparqlwrapper and then use existing Python code under ./utils for guidance.
In order to modify the CIMHub Java code, you will need to install Apache Maven and then use mvn clean install.
In order to build the cimhub docker container, use the ./build.sh script. However, that script assumes that opendsscmd and liblinenoise have been built in sibling directories to this one. When finished, an authorized developer can push the new image to DockerHub, e.g., docker push gridappsd/cimhub:0.0.1
If working on the platform:
mvn clean install
from this repository to ensure you have the latest, branch-compatible CIMHubThe actively maintained directories are:
converters
CYMDist and Synergi conversion to OpenDSSdoc
description of the CIM support in OpenDSSexample
test CIMHub on the IEEE 13-bus modelhelics
illustration of a CIM-defined link between transmission and distribution simulators under HELICSieee9500
CIM, OpenDSS, GridLAB-D and CSV versions of the IEEE 9500-node test feedermodel_output_tests
scratch directory for model output tst resultssrc
Java source for CIMHubutils
Python source, bash scripts and supporting data filesTo run the Python code, you may need to adjust the Blazegraph URL and CIM Namespace in cimhubconfig.json
Unused code or data from the Powergrid-Models repository is now in archive