Using the PowerGrid Models API¶

1. Introduction to the PowerGrid Model API¶

The PowerGrid Models API is used to pull model information from the Blazegraph Database, inlcuding the names, mRIDs, measurements, and nominal values of power system equipment in the feeder (such as lines, loads, switches, transformers, and DERs).

In the Application Components diagram (explained in detail with sample code in GridAPPS-D Application Structure), the PowerGrid Models API is used for querying for the power system model and querying for model measurement MRIDs.

|power\_grid\_models\_usage.png|

2. API Syntax Overview¶

Application passes query to GridAPPS-D Platform

First, the application creates a query message for requesting information about the desired power system components in the format of a JSON string or equivalant Python dictionary object. The syntax of this message is explained in detail below.

The query is sent using gapps.get_response(topic, message) with a response expected back from the platform within the specified timeout period.

The application then passes the query through the PowerGrid Models API to the GridAPPS-D Platform, which publishes it to the goss.gridappsd.process.request.data.powergridmodel queue channel on the GOSS Message Bus. If the app is authenticated and authorized to pass queries, the query message is delivered to the data managers, which obtain the desired information from the Blazegraph Database.

GridAPPS-D Platform responds to Application query

The data managers then publish the response from the Blazegraph Database to the appropriate queue channel. The PowerGrid Models API then returns the desired information back to the application as a JSON message or equivalant Python dictionary object.

2.1. API Communication Channel¶

All queries passed to the PowerGrid Models API need to use the correct communication channel, which is obtained using the GridAPPS-D Topics library.

The PowerGrid Model API uses a /queue/ channel to pull power system model info from the the Blazegraph Database. The base static string used is goss.gridappsd.process.request.data.powergridmodel, which can be called using the .REQUEST_POWERGRID_DATA or .BLAZEGRAPH methods from the topics library.

When developing in python, it is recommended to use the .REQUEST_POWERGRID_DATA method. When using the STOMP client in GridAPPS-D VIZ, it is necessary to use the base static string.

[ ]:

from gridappsd import topics as t
topic = t.REQUEST_POWERGRID_DATA

2.2. Structure of a Query Message¶

Queries passed to PowerGrid Models API are formatted as python dictionaries or equivalent JSON scripts wrapped as a python string.

message = {
    "requestType": "INSERT QUERY HERE",
    "resultFormat": "JSON",
    "modelId": "OPTIONAL INSERT MODEL mRID HERE",
    "objectType": "OPTIONAL INSERT CIM CLASS HERE",
    "objectId": "OPTIONAL INSERT OBJECT mRID HERE",
    "filter": "OPTIONAL INSERT SPARQL FILTER HERE"
}

The components of the message are as follows:

"requestType": – Specifies the type of query. Available requestType are listed in the next section.
"resultFormat": – Specifies the format of the response, can be "JSON", "CSV", or "XML". (CAUTION: the PowerGridModel API uses the key resultFormat, while the Timeseries API uses the key reponseFormat. Using the wrong key for either API will result in a java.lang error.)
"modelID": – Optional. Used to filter the query to only one particular model whose mRID is specified. Be aware of spelling and capitalization differences between JSON query spelling "modelId" and Python Library spelling model_id.
"objectType": – Optional. Used to filter the query to only one CIM class of equipment. Speciying the objectID will override any values specified for objectType.
"objectID": – Optional. Used to filter the query to only one object whose mRID is specified. Specifying the objectID will override any values specified for objectType.
"filter": – Optional. Used to filter the query using a SPARQL filter. SPARQL queries are covered in the next lesson.

The usage of each of these message components are explained in detail with code block examples below.

Important: Be sure to pay attention to placement of commas ( , ) at the end of each JSON line. Commas are placed at the end of each line except the last line. Incorrect comma placement will result in a JsonSyntaxException.

All of the queries are passed to the PowerGrid Model API using the .get_response(topic, message) method for the GridAPPS-D platform connection variable.

2.3. Specifying the `requestType`¶

Below are the possible requestType strings that are used to specify the type of each query. Executable code block examples are provided for each of the requests in the subsections below.

The first group of requestType key-value pairs are for queries for information related to the entire model or a set of models, such as the model name, mRID, region, and substation:

"requestType": "QUERY_MODEL_NAMES" – Query for the list of all model name mRIDs
"requestType": "QUERY_MODEL_INFO" – Query for the dictionary of all details for all feeders in Blazegraph

The second group of requestType key-value pairs are for queries for a single object or a single class of objects withing a model, such as the object mRID, CIM attributes, or measurement points:

"requestType": "QUERY_OBJECT_TYPES" – Query for the types of CIM classes of objects in the model
"requestType": "QUERY_OBJECT_IDS" – Query for a list of all mRIDs for objects of a CIM class in the model
"requestType": "QUERY_OBJECT" – Query for CIM attributes of an object using its unique mRID
"requestType": "QUERY_OBJECT_DICT" – Query for the dictionary of all details for an object using either its *objectType* OR its *objectID*
"requestType": "QUERY_OBJECT_MEASUREMENTS" – Query for all measurement types and mRIDs for an object using either its *objectType* OR its *ObjectID*

The third group of requestType key-value pairs are for queries based on SPARQL filters or complete SPARQL queries. The structure of SPARQL was introduced in Lesson 1.7 (to be completed soon). Usage of these two requestType will covered separately in the next two lessons.

"requestType": "QUERY_MODEL" – Query for all part of a specified model, filtered by object type using a SPARQL filter.
"requestType": "QUERY" – Query using a complete SPARQL query.

3. Querying for Feeder Model Info¶

This section outlines the pre-built JSON queries that can be passed to the PowerGrid Model API to obtain mRIDs and other information for all models and feeders stored in the Blazegraph Database.

3.1. Query for mRIDs of all Models¶

This query obtains a list of all the model MRIDs stored in the Blazegraph database.

Query requestType:

"requestType": "QUERY_MODEL_NAMES"

Allowed parameters:

"resultFormat": – “XML” / “JSON” / “CSV” – Optional. Will return results as a list in the format selected.

[ ]:

message = {
    "requestType": "QUERY_MODEL_NAMES",
    "resultFormat": "JSON"
}

[ ]:

gapps.get_response(topic, message)

Return to Top

3.2. Query for Details Dictionary of all Models¶

This query returns a list of names and MRIDs for all models, substations, subregions, and regions for all available feeders stored in the Blazegraph database.

Query requestType:

"requestType": "QUERY_MODEL_INFO"

Allowed parameters:

"resultFormat": – “XML” / “JSON” / “CSV” – Will return results as a list in the format selected.

[ ]:

message = {
    "requestType": "QUERY_MODEL_INFO",
    "resultFormat": "JSON"
}

[ ]:

gapps.get_response(topic, message)

4. Querying for Object Info¶

This section outlines the pre-built JSON queries that can be passed to the PowerGrid Model API to obtain mRIDs and other information for a particular object or a class of objects for one or more feeders stored in the Blazegraph Database.

All of the examples in this section use the IEEE 13 node model. The python constructor %s is used for all queries to enable the code block to be cut and paste into any python script without needing to change the model mRID.

[ ]:

model_mrid = "_49AD8E07-3BF9-A4E2-CB8F-C3722F837B62" # IEEE 13 Node used for all example queries

4.1. Query for CIM Classes of Objects in Model¶

This query is used to query for a list of all the CIM XML classes of objects present in the Blazegraph for a particular model or all models in the database.

Query requestType is

"requestType": "QUERY_OBJECT_TYPES"

Allowed parameters are

"modelId": “model name mRID” – Optional. Searches only the particular model identified by the given unique mRID
"resultFormat": – “XML” / “JSON” / “CSV” – Will return results as a list in the format selected.

__1) Query entire Blazegraph database__ Omit the `"modelId"` parameter to search the entire blazegraph database.

[ ]:

message = {
    "requestType": "QUERY_OBJECT_TYPES",
    "resultFormat": "JSON"
}

[ ]:

gapps.get_response(topic, message)

2) Query for only a particular model

Specify the model MRID as a python string and pass it as a parameter to the method to return only the CIM classes of objects in that particular model.

Be aware of spelling and capitalization differences between JSON query spelling "modelId" and Python Library spelling model_id.

[ ]:

message = {
    "requestType": "QUERY_OBJECT_TYPES",
    "modelId": model_mrid,
    "resultFormat": "JSON"
}

[ ]:

gapps.get_response(topic, message)

4.2. Query for mRIDs of Objects in a Feeder¶

This query is used to obtain all the mRIDs of objects of a particular CIM class in the feeder.

Query responseType is

"requestType": "QUERY_OBJECT_IDS"

Allowed parameters are:

"modelId": “model name mRID” – When specified it searches against that model, if empty it will search against all models
"objectType": “CIM Class” – Optional. Specifies the type of objects you wish to return details for.
"resultFormat": – “XML” / “JSON” / “CSV” – Will return results as a list in the format selected.

Within a particular feeder, it is possible to query for objects of all the CIM classes obtained using "requestType": "QUERY_OBJECT_TYPES" (discussed above in Section 4.1). Note that the RDF URI is not included in the query, only the name of the class, such as "objectType": "ACLineSegment" or "objectType": "LoadBreakSwitch".

[ ]:

message = {
    "requestType": "QUERY_OBJECT_IDS",
    "resultFormat": "JSON",
    "modelId": model_mrid,
    "objectType": "LoadBreakSwitch"
}

[ ]:

response_obj = gapps.get_response(topic, message)

[ ]:

response_obj['data']

[ ]:

switch_mrids = response_obj['data']['objectIds']

4.3. Query for CIM Attributes of an Object¶

This query is used to obtain all the attributes and mRIDs of those attributes for a particular object whose mRID is specified.

Query responseType is

"requestType": "QUERY_OBJECT"

Allowed parameters are:

"modelId": “model name mRID” – When specified it searches against that model, if empty it will search against all models
"objectId": “object mRID” – Optional. Specifies the type of objects you wish to return details for.
"resultFormat": – “XML” / “JSON” / “CSV” – Will return results as a list in the format selected.

Within a particular feeder, it is possible to query for objects of all the CIM classes obtained using "requestType": "QUERY_OBJECT_TYPES" (discussed above in Section 4.1). Note that the RDF URI is not included in the query, only the name of the class, such as "objectType": "ACLineSegment" or "objectType": "LoadBreakSwitch".

[ ]:

object_mrid = "_2858B6C2-0886-4269-884C-06FA8B887319"
message = """
{
        "requestType": "QUERY_OBJECT",
        "resultFormat": "JSON",
        "modelId": "%s",
        "objectId": "%s"
}
""" % (model_mrid, object_mrid)

[ ]:

message = {
        "requestType": "QUERY_OBJECT",
        "resultFormat": "JSON",
        "objectId": "_4F76A5F9-271D-9EB8-5E31-AA362D86F2C3"
}

[ ]:

gapps.get_response(topic, message)

4.4. Query for Object Dictionary¶

This query returns a python dictionary of all the equipment attributes and mRIDs. The query can be for 1) all objects of a particular objectType or 2) for those connected to a particular object based on the objectId.

If neither objectType or objectId is provided, the query will provide all measurements belonging to the model. Query responseType is

"requestType": "QUERY_OBJECT_DICT"

Allowed parameters are:

"modelId": “model name mRID” – When specified it searches against that model, if empty it will search against all models
"objectId": “object mRID” – Optional. Specifies the type of objects you wish to return details for.
"objectType": “CIM Class” – Optional. Specifies the type of objects you wish to return details for.
"resultFormat": “XML” / “JSON” / “CSV” – Will return results as a list in the format selected.

Speciying the objectID will override any values specified for objectType.

Example 1: Querying for model dictionary for an ``”objectID”:``

[ ]:

message = {
    "modelId": model_mrid,
    "requestType": "QUERY_OBJECT_DICT",
    "resultFormat": "JSON",
    "objectId": switch_mrids[1]
}

gapps.get_response(topic, message)

Example 2: Querying for model dictionary for an ``”objectType”:``

[ ]:

message = {
    "modelId": model_mrid,
    "requestType": "QUERY_OBJECT_DICT",
    "resultFormat": "JSON",
    "objectType": "TransformerTank"
}

gapps.get_response(topic, message)

5. Querying for Object Measurements¶

5.1. Object mRIDs vs Measurement mRIDs¶

A key concept in GridAPPS-D and CIM XML power system models is the difference between the object mRID of a piece of equipment and multiple measurement mRIDs associated with its control settings and power flow values.

Measurements differ from the state variables (e.g. those obtained from State Estimator or a power flow calculation) in that the values are measured here and not calculated or estimated. Each Measurement is associated to a PowerSystemResource, and in GridAPPS-D for now, also a Terminal that belongs to the same PowerSystemResource. (Non-electrical measurements, for example weather, would not have the Terminal).

The measurementType is a string code from IEC 61850, with the following currently suppported:

PNV – Phase to Neutral Voltage
VA – Volt-Amperes (apparent power)
A – Amperes (current)
POS – Position for switches and transformer taps

Each measurement object has a name, mRID, and phases. In GridAPPS-D, each phase is measured individually so multi-phase codes like ABC should not be used.

Pos measurements will be discrete, for such things as tap position, switch position, or capacitor bank position.

The others will be Analog, with magnitude and optional angle in degrees.

Each MeasurementValue will have a timeStamp and mRID inherited from IdentifiedObject, so the values can be traced.

5.2. Querying for Measurements¶

This query returns details for the measurements within a model. The query can be for 1) all objects of a particular objectType or 2) for those connected to a particular object based on the objectId.

If neither objectType or objectId is provided, the query will provide all measurements belonging to the model. Query responseType is

"requestType": "QUERY_OBJECT_MEASUREMENTS"

Allowed parameters are:

"modelId": “model name mRID” – When specified it searches against that model, if empty it will search against all models
"objectId": “object mRID” – Optional. Specifies the type of objects you wish to return details for.
"objectType": “CIM Class” – Optional. Specifies the type of objects you wish to return details for.
"resultFormat": “XML” / “JSON” / “CSV” – Will return results as a list in the format selected.

Speciying the objectID will override any values specified for objectType.

Example 1: Querying for all measurements for an ``”objectID”:``

[ ]:

message = {
    "modelId": model_mrid,
    "requestType": "QUERY_OBJECT_MEASUREMENTS",
    "resultFormat": "JSON",
    "objectId": switch_mrids[1]
}

gapps.get_response(topic, message)

Example 2: Querying for all measurements for an ``”objectType”:``

[ ]:

message = {
    "modelId": model_mrid,
    "requestType": "QUERY_OBJECT_MEASUREMENTS",
    "resultFormat": "JSON",
    "objectType": "ACLineSegment"
}

gapps.get_response(topic, message)

5.3. Filtering Returned Data¶

After receiving the python dictionary of measurements, it will be necessary to parse it to inlcude just the desired set of measurements. This is done using the method presented in Parsing Returned Data

[ ]:

obj_msr_ACline = gapps.get_response(topic, message, timeout=10)

# Filter to just values for 'data' key
obj_msr_ACline = obj_msr_ACline['data']

# Chose specific measurement mrid. Screen out those whose type is not PNV. For example,
obj_msr_ACline = [k for k in obj_msr_ACline if k['type'] == 'Pos']

obj_msr_ACline

6. GridAPPSD-Python Shortcut Methods¶

A small number of simple PowerGrid Model API queries have pre-built Python functions that can be used without specifying the topic and a particular message.

6.1. Querying for mRIDs of all Models¶

The .query_model_names method is associated with the GridAPPSD connection object and returns a list of all the CIM XML classes of objects present in the Blazegraph for a particular model or all models in the database.

This method will return identical results to the python dictionary message explained above in Section 3.1

[ ]:

gapps.query_model_names()

6.2. Query for CIM Classes of Objects in Model¶

The .query_object_types method is associated with the GridAPPSD connection object and returns a list of all the CIM XML classes of objects present in the Blazegraph for a particular model or all models in the database.

This method will return identical results to the python dictionary message explained above in Section 4.1

Allowed parameters are

model_id (optional) - when specified, it searches only the particular model identified by the given unique mRID

1) Query entire Blazegraph database

Leave the arguments blank to search all models in the Blazegraph database

[ ]:

gapps.query_object_types()

2) Query for only a particular model

Specify the model MRID as a python string and pass it as a parameter to the method to return only the CIM classes of objects in that particular model

[ ]:

model_mrid = "_49AD8E07-3BF9-A4E2-CB8F-C3722F837B62" # IEEE 13 Node used for all example queries
gapps.query_object_types(model_mrid)

6.3. Query for CIM Attributes of an Object¶

The .query_object method is associated with the GridAPPSD connection object and returns a list of all the CIM XML classes of objects present in the Blazegraph for a particular model or all models in the database.

This method will return identical results to the python dictionary message explained above in Section 4.3

[ ]:

model_mrid = "_49AD8E07-3BF9-A4E2-CB8F-C3722F837B62" # IEEE 13 Node used for all example queries
object_mrid = "_2858B6C2-0886-4269-884C-06FA8B887319"

gapps.query_object(model_mrid, object_mrid)

7. Available Models in Default Installation¶

7.1. IEEE 13 Node Model¶

This is a very small distribution test feeder operating at 4.16 kV voltage level. It consists of a single voltage regulator at the substation, overhead and underground lines, shunt capacitor, and an in-line transformer. This feeder is relatively highly loaded and provides a good test of the convergence of the problem for a very unbalanced system.

This model is recommended for debugging as the model is small enough that issues can be traced by hand.

7.2. IEEE 123 Node Model¶

This models a medium-sized unbalanced distribution system operating at the nominal voltage of 4.16 kV. It consists of overhead and underground lines with single, two and three-phase laterals, along with step regulators and shunt capacitors for voltage regulation. The feeder model is characterized by the unbalanced loading having all combinations of load types (constant current, impedance, and power). It also includes a few switches to allow for the alternate paths for the power flow via feeder reconfiguration.

This model is recommended for initial app testing and debugging thorugh the first stages of development.

7.3. IEEE 123 Node Model with PV¶

7.4. IEEE 8500 Node Model¶

This is a relatively large and realistic radial distribution feeder consisting of MV and LV (secondary) circuits [21]. Unlike other test systems, this feeder also includes 120/240V center-tapped transformers that are commonly deployed in North American power distribution systems. Thus, it allows for users to interchange between the two versions of loading conditions: balanced (208 V) and unbalanced (120 V) in the secondary transformers. Voltage control is possible using a substation LTC transformer, as well as multiple poletop regulators and capacitor banks. The feeder was created to test scalability and convergence of power flow algorithms on a large unbalanced power distribution system.

Length: 170 km
Nominal voltage: 12.47 kV, 120/240V
Topology: radial
Service transformers: yes
Customers: 1177
Peak load: 11.1 MW
Normally-open switches: no

7.5. 9500 Node Test System¶

The 9500 Node Test System includes three radial distribution feeders with just over 12 MW of load, consisting of both medium voltage and low voltage equipment each supplied by a different distribution substation. The three distribution feeders are connected to each other through Normally-Open switches, which is representative of the way many utilities operate in North America. One feeder represents today’s grid with low penetration of customer-side renewables. The second represents a potential future grid with microgrids and 100% renewable penetration. The third has no customer resources, a district steam plant, and a utility-scale PV farm. All three feeders have customers connected by low-voltage secondary triplex lines.

Using the PowerGrid Models API¶

1. Introduction to the PowerGrid Model API¶

2. API Syntax Overview¶

2.1. API Communication Channel¶

2.2. Structure of a Query Message¶

2.3. Specifying the `requestType`¶

3. Querying for Feeder Model Info¶

3.1. Query for mRIDs of all Models¶

3.2. Query for Details Dictionary of all Models¶

4. Querying for Object Info¶

4.1. Query for CIM Classes of Objects in Model¶

4.2. Query for mRIDs of Objects in a Feeder¶

4.3. Query for CIM Attributes of an Object¶

4.4. Query for Object Dictionary¶

5. Querying for Object Measurements¶

5.1. Object mRIDs vs Measurement mRIDs¶

5.2. Querying for Measurements¶

5.3. Filtering Returned Data¶

6. GridAPPSD-Python Shortcut Methods¶

6.1. Querying for mRIDs of all Models¶

6.2. Query for CIM Classes of Objects in Model¶

6.3. Query for CIM Attributes of an Object¶

7. Available Models in Default Installation¶

7.1. IEEE 13 Node Model¶

7.2. IEEE 123 Node Model¶

7.3. IEEE 123 Node Model with PV¶

7.4. IEEE 8500 Node Model¶

7.5. 9500 Node Test System¶

7.6. PNNL Taxonomy Feeder¶

7.7. EPRI J1 Feeder¶

7.8. UAF Microgrid¶

Using the PowerGrid Models API¶

1. Introduction to the PowerGrid Model API¶

2. API Syntax Overview¶

2.1. API Communication Channel¶

2.2. Structure of a Query Message¶

2.3. Specifying the requestType¶

3. Querying for Feeder Model Info¶

3.1. Query for mRIDs of all Models¶

3.2. Query for Details Dictionary of all Models¶

4. Querying for Object Info¶

4.1. Query for CIM Classes of Objects in Model¶

4.2. Query for mRIDs of Objects in a Feeder¶

4.3. Query for CIM Attributes of an Object¶

4.4. Query for Object Dictionary¶

5. Querying for Object Measurements¶

5.1. Object mRIDs vs Measurement mRIDs¶

5.2. Querying for Measurements¶

5.3. Filtering Returned Data¶

6. GridAPPSD-Python Shortcut Methods¶

6.1. Querying for mRIDs of all Models¶

6.2. Query for CIM Classes of Objects in Model¶

6.3. Query for CIM Attributes of an Object¶

7. Available Models in Default Installation¶

7.1. IEEE 13 Node Model¶

7.2. IEEE 123 Node Model¶

7.3. IEEE 123 Node Model with PV¶

7.4. IEEE 8500 Node Model¶

7.5. 9500 Node Test System¶

7.6. PNNL Taxonomy Feeder¶

7.7. EPRI J1 Feeder¶

7.8. UAF Microgrid¶

2.3. Specifying the `requestType`¶