CIMantic Graphs is an open-source library for for creating, parsing, and editing CIM power system models using in-memory knowledge graphs to reduce the burden and learning curve associated with using the Common Information Model.
Key features:
- Single API method to obtain data for any CIM class. No more custom database queries.
- Single API method to obtain data for EMS node-breaker transmission models, bus-branch planning models, and distribution feeder models.
- Singe API method for both centralized and distributed architectures.
- Support for multiple databases and query languages with no changes to upper-level graph data or API calls. Only need to change host/port specified in ConnectionParameters data object.
- Ability to create CIM models "from scratch".
- Open-source data engineering tool for management of CIM models.
- Knowledge graph approach based on semantic understanding of CIM.
- Object-oriented data structure with enforcement of CIM Schema.
- Data profiles generated directly from Enterprise Architect UML.
- Support for custom profiles using CIMTool or Schema Composer.
- Support for direct creation / editing / parsing of CIM XML, JSON-LD.
- API support for centralized/distributed transmission + distribution models.
CIM-Graph requires a python version >=3.8 and <4. No testing has been done with other versions.
Support is currently offered for opening XML, JSON-LD, and CSV files
Support is currently offered for GridAPPS-D, Blazegraph, Neo4J, GraphDB, and json-formatted MySQL databases. More databases will be added in the future.
pip install cim-graph
The CIM-Graph library supports multiple CIM profiles, which can be exported using CIMtool or Enterprise Architect Schema Composer as a .xsd data profile. The data profiles are ingested using the xsdata python library and saved in the cimgraph/data_profile directory.
When importing the library, the CIM profile must be specified using the gridappsd-python constructor or directly as
import cimgraph.data_profile.rc4_2021 as cim
or by using importlib
:
import importlib
cim_profile = 'rc4_2021'
cim = importlib.import_module('cimgraph.data_profile.' + cim_profile)
The CIM-Graph library supports multiple databases. The ConnectionParameters specify how to read the CIM model:
Required arguments:
cim_profile
: This specifies the specific version of CIM to be used, based on the available python data profiles loaded into the library
Optional arguments:
namespace
: CIM namespace, default is"http://iec.ch/TC57/CIM100#"
iec61970-301
: Serialization version. Versions 7(default) and below userdf:ID=
. Version 8 usesrdf:about=urn:uuid:
url
: URL at which the database can be reached via TCP/IP or other connectionhost
: Database host addressport
: Database host portdatabase
: Database nameusername
: Database usernamepassword
: Database passwordfilename
: Filename for importing CIM models from an XML file
Note that not all parameters are required. Each database connection uses a subset of these arguments depending on the requirements of the database connection driver.
The CIM-Graph library creates object instances populated with the attributes of mRID
for all nodes, terminals, and conducting equipment in the centralized netork or each distributed area. All other attributes are None
or []
by default until queried for using .get_all_edges(cim.ClassName)
.
from cimgraph.models import NodeBreakerModel
geo_region_id = "_EE4C60AE-550D-4599-92F4-022DF3118B3C" #Maple 10 bus
geo_region = cim.GeographicalRegion(mRID = geo_region_id)
network = NodeBreakerModel(connection=database, container=geo_region, distributed=True)
from cimgraph.models import BusBranchModel
model_mrid = "1783D2A8-1204-4781-A0B4-7A73A2FA6038" #IEEE 118 Bus"
container = cim.ConnectivityNodeContainer(mRID = model_mrid)
network = BusBranchModel(connection=database, container=container, distributed=False)
from cimgraph.models import FeederModel
feeder_mrid = "49AD8E07-3BF9-A4E2-CB8F-C3722F837B62"
feeder = cim.Feeder(mRID = feeder_mrid)
network = FeederModel(connection=database, container=feeder, distributed=False)
If the distributed
flag is set to False
, then all equipment are contained within a single knowledge graph. If set to True
, a DistributedArea
graph model is created for each topological area inside the power system model.
network = FeederModel(connection=rdf, container=feeder, distributed=True)
for switch_area in network.distributed_areas:
switch_area.get_all_edges(cim.ACLineSegement)
for secondary_area in switch_area.distributed_areas:
secondary_area.get_all_edges(cim.ACLineSegement)
If an application is built using the GridAPPS-D Context Manager and Field Interface in gridappsd-python, initialization of the FeederModel
and DistributedArea
graphs is performed automatically.
Internally, the GridAPPS-D Context Manager initializes distributed areas as dist_network = FeederModel(connection=gapps, container=feeder, distributed=True, topology_message=topo_msg)
.
The CIM power system model can then be parsed by invoking the .get_all_edges(cim.ClassName)
method. The method populates all available attributes of the given class and creates default instances of all associated class object instances that are one association away in the CIM UML. Associated default instances are only populated with mRID
attribute. The .get_all_edges
method must be invoked in sequential order following the inheritance hierarchy in the CIM UML, starting with the particular equiment class (e.g. ACLineSegment) and then each child class inheriting from the previous class.
The Python object instances can be accessed using the graph
dictionary of each distributed area class instance. The typed catalog is organized by the class type and then mRID of each object. The attributes of each class can be accessed directly or through any associated class. These two calls are equivalent:
bus_name = network.graph[cim.ConnectivityNode][node_mrid].name
bus_name = network.graph[cim.ACLineSegment][line_mrid].Terminals[0].ConnectivityNode.name
Note that all classes and attributes are case sensitive and follow the CIM UML conventions for each class.
Printing of CIM objects using default print()
is not supported. All instances of all given CIM class can be printed .pprint(cim.ClassName)
method:
network.pprint(cim.ACLineSegment)
All instances of all given CIM class can also be exported as JSON text using the .__dumps__(cim.ClassName)
method of the distributed area classes:
json_dump = network.__dumps__(cim.ACLineSegment)
Additional examples of usage are available on ReadTheDocs.
This software was created under a project sponsored by the U.S. Department of Energy’s Office of Electricity, an agency of the United States Government. Neither the United States Government nor the United States Department of Energy, nor Battelle, nor any of their employees, nor any jurisdiction or organization that has cooperated in the development of these materials, makes any warranty, express or implied, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness or any information, apparatus, product, software, or process disclosed, or represents that its use would not infringe privately owned rights.
Reference herein to any specific commercial product, process, or service by trade name, trademark, manufacturer, or otherwise does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or any agency thereof, or Battelle Memorial Institute. The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or any agency thereof.
PACIFIC NORTHWEST NATIONAL LABORATORY
operated by
BATTELLE
for the
UNITED STATES DEPARTMENT OF ENERGY
under Contract DE-AC05-76RL01830