Using GridAPPS-D

Start GridAPPS-D platform

Connect to the running GridAPPS-D container

user@foo>docker exec -it gridappsddocker_gridappsd_1 bash

Now we are inside the executing container. Start the platform.

root@737c30c82df7:/gridappsd# ./run-docker.sh

Open your browser to http://localhost:8080/ and click the menu button.

home-image

Start a Simulation

Choose Simulations from the menu.

menu-image

To run a demo simulation keep the selected and entered values as it is. Otherwise select/enter Powergrid, Simulation and Application configuration values. Click the submit button to save the configuration.

config-image
config-image
config-image

Click the triangle to start the simulation.

start-image

The demo simulation runs 2 minutes of load variations with the sample-app controlling capacitor banks on the IEEE 8500-node test system [CIT2]. Most of Figure 1 is devoted to a map layout view of the test circuit, with updated labels for capacitor banks and voltage regulators. On the right-hand side, strip chart plots of the phase ABC voltages at capacitors and regulators, phase ABC substation power levels, and phase ABC regulator taps are continually updated. Capacitor bank labels on the circuit map view change between OPEN and CLOSED to show the bank status as load varies and the VVO application issues control commands. While GridAPPS-D runs the demo, GridLAB-D [CIT8] simulates power system operation and exchanges information with the sample-app using GOSS [CIT6] and FNCS [CIT7].

Following image shows the demo simulation output of the sample-app running on the IEEE 8500-node test system. Simulation Status at the bottom of the screen will display the simulation log messages. The simulation can be paused or stopped using the play and stop button.

rc3_overview_image0

Stop GridAPPS-D platform

For an orderly shutdown of the platform:

Use Ctrl+C to stop gridappsd from running

Adding Events

Communication outage and fault events can be added using the Test Configuration page

Select the CommOutage radio button for adding Communication Outage Events

config-image

Select the Fault radio button for adding Fault Events

config-image

Added events can be viewed in a tabular format on the right side of the page

config-image

The added events for a simulation can be seen in the events view

config-image

Uploading Model into Blazegraph

Go to http://localhost:8889/bigdata for the Blazegraph Workbench. Go to the Update tab and use the browse option to choose the file to be uploaded. Click on Update to upload the file into Blazegraph.

blazegraph_upload-image

Once the model is uploaded to Blazegraph, the new model will be shown in the Simulation Configuration Form in the visualization under the line name dropdown. If the Viz app was already open, you will need to restart the browser to see the new model(This is due to caching).

blazegraph_model_viz-image

Inserting Measurements into Blazegraph

Clone the Powergrid-Models repository

git clone https://github.com/GRIDAPPSD/Powergrid-Models.git

Install the required python module

pip install SPARQLWrapper

Modify the Powergrid-Models/Meas/constants.py file. Change the blazegraph_url to “http://localhost:8889/bigdata/sparql”.

Create a temporary directory for the measurements files

mkdir tmp
cd tmp

List the feeder and feeder id

python3 ../Powergrid-Models/Meas/ListFeeders.py

Generate the measurements file using the feeder and feeder id from the previous step

python3 ../Powergrid-Models/Meas/ListMeasureables.py ieee123pv _E407CBB6-8C8D-9BC9-589C-AB83FBF0826D

Load the measurements into Blazegraph

for f in `ls -1 *txt`; do
  python3 ../Powergrid-Models/Meas/InsertMeasurements.py $f
done

Using Platform API

Applications and services can use either publish/subscribe mechanism or Python API to interact with GridAPPS-D platform.

Publish/Subscribe mechanism can be implemented using any of the language bindings for ActiveMQ messaging framework.

Python API wraps the publish/subscribe messaging and makes the interaction easier for Python apps/services. For more information on Python API and how to use it, look at https://github.com/GRIDAPPSD/gridappsd-python and https://github.com/GRIDAPPSD/gridappsd-sample-app.

Following sections describe the messaging APIs and the corresponding Python API function to interact with platform. Where no Python API function is mentioned, following generic functions can be used.

send(self, topic, message)
get_response(self, topic, message, timeout=5)
subscribe(self, topic, callback, id=None)

Powergrid Model API

The Powergrid Model Data Manager API allows you to query the powergrid model data store.

Query Request Queue

Query request should be sent on following queue: goss.gridappsd.process.request.data.powergridmodel

Query Model Info

Returns list of names/ids for models, substations, subregions, and regions for all available feeders.

Allowed parameter is:

  • Result Format – XML/JSON/CSV, Will return results as a list in the format selected.

Example Request:

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

Example Response for result format JSON:

{
        "models": [{
                "modelName": "ieee123",
                "modelId": "_C1C3E687-6FFD-C753-582B-632A27E28507",
                "stationName": "ieee123_Substation",
                "stationId": "_FE44B314-385E-C2BF-3983-3A10C6060022",
                "subRegionName": "large",
                "subRegionId": "_1CD7D2EE-3C91-3248-5662-A43EFEFAC224",
                "regionName": "ieee",
                "regionId": "_24809814-4EC6-29D2-B509-7F8BFB646437"
}, .......

Query Model Names

Returns list of names for all available models.

Allowed parameter is:

  • Result Format – XML/JSON/CSV, Will return results as a list in the format selected.

Example Request: goss.gridappsd.process.request.data.powergridmodel

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

Example Response for result format JSON:

{
        "modelNames": ["_49AD8E07-3BF9-A4E2-CB8F-C3722F837B62",
        "_4F76A5F9-271D-9EB8-5E31-AA362D86F2C3",
        "_5B816B93-7A5F-B64C-8460-47C17D6E4B0F",
        "_67AB291F-DCCD-31B7-B499-338206B9828F",
        "_9CE150A8-8CC5-A0F9-B67E-BBD8C79D3095",
        "_C1C3E687-6FFD-C753-582B-632A27E28507"]
}

Python API function:

query_model_names(self, model_id=None)

Query

Returns results from a generic SPARQL query against one or all models.

Allowed parameters are:

  • modelId (optional) - when specified it searches against that model, if empty it will search against all models
  • queryString - SPARQL query, for more information see https://www.w3.org/TR/rdf-sparql-query/ See below for example.
  • resultFormat – XML/JSON , The format you wish the result to be returned in. Can be either JSON or XML. Will return result bindings based on the select part of the query string. See below for example.

Example Request: goss.gridappsd.process.request.data.powergridmodel

{
        "requestType": "QUERY",
        "resultFormat": "JSON",
        "queryString": "select ?feeder_name ?subregion_name ?region_name WHERE {?line r:type c:Feeder.?line c:IdentifiedObject.name  ?feeder_name.?line c:Feeder.NormalEnergizingSubstation ?substation.?substation r:type c:Substation.?substation c:Substation.Region ?subregion.?subregion  c:IdentifiedObject.name  ?subregion_name .?subregion c:SubGeographicalRegion.Region  ?region . ?region   c:IdentifiedObject.name  ?region_name}"
}

Example Response:

{
"head": {
         "vars": [ "line_name" , "subregion_name" , "region_name" ]
 } ,
"results": {
        "bindings": [
         {
                "line_name": { "type": "literal" , "value": "ieee8500" } ,
                "subregion_name": { "type": "literal" , "value": "ieee8500_SubRegion" },
                "region_name": { "type": "literal" , "value": "ieee8500_Region" }
          }
          ]
}
}

Python API function:

query_data(self, query, database_type=POWERGRID_MODEL, timeout=30)

Query Object

Returns details for a particular object based on the object Id.

Allowed parameters are:

  • modelId (optional) - when specified it searches against that model, if empty it will search against all models
  • objectID – mrid of the object you wish to return details for.
  • resultFormat – XML/JSON , Will return result bindings based on the select part of the query string.

Example Request: goss.gridappsd.process.request.data.powergridmodel

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

Example Response:

{
  "head": {
    "vars": [ "property" , "value" ]
  } ,
  "results": {
    "bindings": [
      {
        "property": { "type": "uri" , "value": "http://iec.ch/TC57/2012/CIM-schema-cim17#Feeder.NormalEnergizingSubstation" } ,
        "value": { "type": "uri" , "value": "http://localhost:9999/blazegraph/namespace/kb/sparql#_F1E8E479-5FA0-4BFF-8173-B375D25B0AA2" }
      } ,
      {
        "property": { "type": "uri" , "value": "http://iec.ch/TC57/2012/CIM-schema-cim17#IdentifiedObject.mRID" } ,
        "value": { "type": "literal" , "value": "_4F76A5F9-271D-9EB8-5E31-AA362D86F2C3" }
      } ,
      {
        "property": { "type": "uri" , "value": "http://iec.ch/TC57/2012/CIM-schema-cim17#IdentifiedObject.name" } ,
        "value": { "type": "literal" , "value": "ieee8500" }
      } ,
      {
        "property": { "type": "uri" , "value": "http://iec.ch/TC57/2012/CIM-schema-cim17#PowerSystemResource.Location" } ,
        "value": { "type": "uri" , "value": "http://localhost:9999/blazegraph/namespace/kb/sparql#_AD650B25-8A04-EA09-95D4-4F78DD0A05E7" }
      } ,
      {
        "property": { "type": "uri" , "value": "http://www.w3.org/1999/02/22-rdf-syntax-ns#type" } ,
        "value": { "type": "uri" , "value": "http://iec.ch/TC57/2012/CIM-schema-cim17#Feeder" }
      }
    ]
  }
}

Python API function:

query_object(self, object_id, model_id=None):

Query Object Types

Returns the available object types in the model

Allowed parameters are:

  • modelId (optional) - when specified it searches against that model, if empty it will search against all models
  • resultFormat – XML/JSON /CSV, Will return results as a list in the format selected.

Example Request: goss.gridappsd.process.request.data.powergridmodel

{
        "requestType": "QUERY_OBJECT_TYPES",
        "modelId": "_4F76A5F9-271D-9EB8-5E31-AA362D86F2C3",
        "resultFormat": "JSON"
}

Example Response:

{
        "objectTypes": ["http://iec.ch/TC57/2012/CIM-schema-cim17#ConnectivityNode",
        "http://iec.ch/TC57/2012/CIM-schema-cim17#TransformerTank",
        "http://iec.ch/TC57/2012/CIM-schema-cim17#PowerTransformer",
        "http://iec.ch/TC57/2012/CIM-schema-cim17#LinearShuntCompensator",
        "http://iec.ch/TC57/2012/CIM-schema-cim17#EnergySource",
        "http://iec.ch/TC57/2012/CIM-schema-cim17#ACLineSegment",
        "http://iec.ch/TC57/2012/CIM-schema-cim17#LoadBreakSwitch",
        "http://iec.ch/TC57/2012/CIM-schema-cim17#EnergyConsumer"]
}

Python API function:

query_object_types(self, model_id=None)

Query Model

Returns all or part of the specified model. Can be filtered by object type

Allowed parameters are:

  • modelId - when specified it searches against that model, if empty it will search against all models
  • objectType (optional) – type of objects you wish to return details for.
  • filter – SPARQL formatted filter string
  • resultFormat – XML/JSON, Will return result in the format selected.

Example Request: goss.gridappsd.process.request.data.powergridmodel

{
        "requestType": "QUERY_MODEL",
        "modelId": "_49AD8E07-3BF9-A4E2-CB8F-C3722F837B62",
        "resultFormat": "JSON",
        "filter": "?s cim:IdentifiedObject.name '650z'",
        "objectType": "http://iec.ch/TC57/CIM100#ConnectivityNode"
}

Example Response:

[{
        "id": "_0F9BF9EE-B900-71C2-B892-0287A875A158",
        "http://iec.ch/TC57/2012/CIM-schema-cim17#ConnectivityNode.ConnectivityNodeContainer": "_4F76A5F9-271D-9EB8-5E31-AA362D86F2C3",
        "http://iec.ch/TC57/2012/CIM-schema-cim17#ConnectivityNode.TopologicalNode": "_AE5EDB3A-9177-AEA6-78EF-3DDBA4557D94",
        "http://iec.ch/TC57/2012/CIM-schema-cim17#IdentifiedObject.mRID": "_0F9BF9EE-B900-71C2-B892-0287A875A158",
        "http://iec.ch/TC57/2012/CIM-schema-cim17#IdentifiedObject.name": "q14733",
        "http://www.w3.org/1999/02/22-rdf-syntax-ns#type": "http://iec.ch/TC57/2012/CIM-schema-cim17#ConnectivityNode"
}]

Query Object Ids

Returns details for a particular object based on the object Id.

Allowed parameters are:

  • modelId - when specified it searches against that model, if empty it will search against all models
  • objectType (optional) – type of objects you wish to return details for.
  • resultFormat – XML/JSON/CSV , Will return result bindings based on the select part of the query string.

Example Request: goss.gridappsd.process.request.data.powergridmodel

{
        "modelId": "_4F76A5F9-271D-9EB8-5E31-AA362D86F2C3",
        "requestType": "QUERY_OBJECT_IDS",
        "resultFormat": "JSON",
        "objectType": "LoadBreakSwitch"
}

Example Response:

{
  "objectIds": [
        "_0D2157F2-CD4D-9F68-9212-F663C472AF1C",
        "_18D43D9E-36D1-3A2C-AC8F-439232FC1EE2",
        "_323C2BDB-69AA-A10C-CEC5-628C77B83268",
        "_D7AA7B55-E700-F1E8-B3EB-CB2FB07F8A37",
        .......
  ]
}

Query Object Dictionary

Returns details for either all objects of a particular type or a particular object based on the object Id. Either the object type or id is required, but not both.

Allowed parameters are:

  • modelId - model that you wish to return objects from.
  • objectType (not required if objectId is set) – type of object you wish to return details for.
  • objectId (not required if objectType is set) - mrid of the object you wish to return details for, if set this will override objectType.
  • resultFormat – XML/JSON , Will return result bindings based on the select part of the query string.

Example Request: goss.gridappsd.process.request.data.powergridmodel

{
        "modelId": "_4F76A5F9-271D-9EB8-5E31-AA362D86F2C3",
        "requestType": "QUERY_OBJECT_DICT",
        "resultFormat": "JSON",
        "objectType": "LinearShuntCompensator",
        "objectId": "_EF2FF8C1-A6A6-4771-ADDD-A371AD929D5B"
}

Example Response:

{
 [
   {
        "id": "_2199D08B-9352-2085-102F-6B207E0BEBA3",
        "ConductingEquipment.BaseVoltage": "_C0A00494-BB68-7476-57E3-9741545AE287",
        "Equipment.EquipmentContainer": "_4F76A5F9-271D-9EB8-5E31-AA362D86F2C3",
        "IdentifiedObject.mRID": "_2199D08B-9352-2085-102F-6B207E0BEBA3",
        "IdentifiedObject.name": "capbank0a",
        "PowerSystemResource.Location": "_19B9D45D-F556-01D4-8094-3AE64D5E63A0",
        "LinearShuntCompensator.b0PerSection": "100",
        "LinearShuntCompensator.bPerSection": "0.0077160494",
        "LinearShuntCompensator.g0PerSection": "0",
        "LinearShuntCompensator.gPerSection": "0",
        "ShuntCompensator.aVRDelay": "100",
        "ShuntCompensator.grounded": "true",
        "ShuntCompensator.maximumSections": "1",
        "ShuntCompensator.nomU": "7200",
        "ShuntCompensator.normalSections": "1",
        "ShuntCompensator.phaseConnection": "PhaseShuntConnectionKind.Y",
        "type": "LinearShuntCompensator"
   },....
 ]
}

Query Object Measurements

Returns details for measurements within a model, can be for all objects of a particular type or for those connected to a particular object based on the objectId. If neither objectType or objectId is provided it will provide all measurements belonging to the model.

Allowed parameters are:

  • modelId - model that you wish to return measurements from.
  • objectType (optional) – type of object you wish to return measurements for.
  • objectId (optional) - mrid of the object you wish to return measurements for. If set this will override objectType.
  • resultFormat – XML/JSON , Will return result bindings based on the select part of the query string.

Example Request: goss.gridappsd.process.request.data.powergridmodel

{
        "modelId": "_4F76A5F9-271D-9EB8-5E31-AA362D86F2C3",
        "requestType": "QUERY_OBJECT_MEASUREMENTS",
        "resultFormat": "JSON",
        "objectType": "LinearShuntCompensator",
        "objectId": "_2199D08B-9352-2085-102F-6B207E0BEBA3"
}

Example Response:

  [
{
      "measid": "_59d526ff-32c0-4947-ab58-45f283636786",
      "type": "PNV",
      "class": "Analog",
      "name": "ACLineSegment_ln5532752-2_Voltage",
      "bus": "m1047534",
      "phases": "A",
      "eqtype": "ACLineSegment",
      "eqname": "ln5532752-2",
      "eqid": "_7A02B3B0-2746-EB24-45A5-C3FBA8ACB88E",
      "trmid": "_6B5B889C-E7E1-3444-CC63-7A589AC0DA8F"
  },....
   ]

Put Model

Note

Future Capability. Not yet available.

Inserts a new model into the model repository. This could validate model format during insertion Keep cim/model version in mind

Allowed parameters are:

  • modelId – id to store the new model under, or update existing model
  • modelContent – expects either RDF/XML or JSON formatted powergrid model
  • inputFormat – XML/JSON

Configuration File API

Request all GridLAB-D configuration files

Generates all configuration files necessary to run a sumulation using the GridLAB-D simulator. Returns the diretory where all of the configuration files are stored.

  • Required: configurationType, parameters[model_id,directory,simulationname,simulation_start_time,simulation_duration,simulation_id,simulation_broker_host,simulation_broker_port]
  • Optional: parameters[i_fraction, p_fraction, z_fraction, load_scaling_factor, schedule_name,solver_method]

Request: goss.gridappsd.process.request.config

{
  "configurationType": "GridLAB-D All",
  "parameters": {
    "load_scaling_factor": "1.0",
    "i_fraction": "1.0",
    "model_id": "_4F76A5F9-271D-9EB8-5E31-AA362D86F2C3",
    "p_fraction": "0.0",
    "simulation_id": "12345",
    "z_fraction": "0.0",
    "simulation_broker_host": "localhost",
    "simulation_name": "ieee8500",
    "simulation_duration": "60",
    "simulation_start_time": "2018-02-18 00:00:00",
    "solver_method": "NR",
    "schedule_name": "ieeezipload",
    "simulation_broker_port": "61616",
    "directory": "/tmp/gridlabdsimulation/"
  }
}

Response: <directory where files have been stored>

Request GridLAB-D Base File

Generates the main GLM file required by the GridLAB-D simulator

  • Required: configurationType, parameters[model_id]
  • Optional: parameters[simulation_id, i_fraction, p_fraction, z_fraction, load_scaling_factor, schedule_name]

Request: goss.gridappsd.process.request.config

{
  "configurationType": "GridLAB-D Base GLM",
  "parameters": {
    "i_fraction": "1.0",
    "z_fraction": "0.0",
    "model_id": "_4F76A5F9-271D-9EB8-5E31-AA362D86F2C3",
    "load_scaling_factor": "1.0",
    "schedule_name": "ieeezipload",
    "p_fraction": "0.0"
  }
}

Response:

object regulator_configuration {
  name "rcon_VREG4";
  connect_type WYE_WYE;
  Control MANUAL; // OUTPUT_VOLTAGE;
.......

Request GridLAB-D Symbols File

Generates the symbols file with XY coordinates used by the GridLAB-D simulator

  • Required: configurationType, parameters[model_id]
  • Optional: parameters[simulation_id]

Request: goss.gridappsd.process.request.config

{
  "configurationType": "GridLAB-D Symbols",
  "parameters": {
    "model_id": "_4F76A5F9-271D-9EB8-5E31-AA362D86F2C3"
  }
}

Response:

{"feeder":[
{"swing_nodes":[
{"name":"source","bus":"sourcebus","phases":"ABC",
  "nominal_voltage":66395.3,"x1":1693780.0,"y1":1.22775777570982E7}
]},
{"capacitors":[
.......

Request CIM Dictionary file

Generates a dictionary file which maps between the mrid identifiers used by the CIM model and the other names of model objects used by simulators.

  • Required: configurationType, parameters[model_id]
  • Optional: parameters[simulation_id]

Request: goss.gridappsd.process.request.config

{
  "configurationType":"CIM Dictionary",
  "parameters":{"model_id":"_4F76A5F9-271D-9EB8-5E31-AA362D86F2C3"}
 }

Response:

{"feeders":[
{"name":"ieee8500",
"mRID":"_4F76A5F9-271D-9EB8-5E31-AA362D86F2C3",
"substation":"ieee8500_Substation",
"substationID":"_F1E8E479-5FA0-4BFF-8173-B375D25B0AA2",
"subregion":"large",
"subregionID":"_A1170111-942A-6ABD-D325-C64886DC4D7D",
"region":"ieee",
"regionID":"_6F10E278-12DC-9CBB-D2D9-D09582538F8A",
"capacitors":[
{"name":"capbank0a","mRID":"_A5866105-A527-F682-C982-69807C0E088B","CN1":"r42246","phases":"A","kvar_A":400.0,"kvar_B":0.0,"kvar_C":0.0,"nominalVoltage":12470.0,"nomU":7200.0,"phaseConnection":"Y","grounded":true,"enabled":true,"mode":"reactivePower","targetValue":-50000.0,"targetDeadband":-500000.0,"aVRDelay":100.0,"monitoredName":"cap_3a","monitoredClass":"ACLineSegment","monitoredBus":"q16642","monitoredPhase":"A"},
.......
],
"regulators":[
{"bankName":"FEEDER_REG","size":"3","bankPhases":"ABC","tankName":["feeder_rega","feeder_regb","feeder_regc"],"endNumber":[2,2,2],"endPhase":["A","B","C"],"rtcName":["feeder_rega","feeder_regb","feeder_regc"],"mRID":["_330E7EDE-2C70-8F72-B183-AA4BA3C5E221","_0EBF840D-7BE9-0D81-03A0-315D617ECA27","_BBB3984D-2A67-7E15-0763-635C5B06A348"],"monitoredPhase":["A","B","C"],"TapChanger.tculControlMode":["volt","volt","volt"],"highStep":[32,32,32],"lowStep":[0,0,0],"neutralStep":[16,16,16],"normalStep":[16,16,16],"TapChanger.controlEnabled":[true,true,true],"lineDropCompensation":[false,false,false],"ltcFlag":[true,true,true],"RegulatingControl.enabled":[true,true,true],"RegulatingControl.discrete":[true,true,true],"RegulatingControl.mode":["voltage","voltage","voltage"],"step":[1.0125,1.0125,1.0063],"targetValue":[126.5000,126.5000,126.5000],"targetDeadband":[2.0000,2.0000,2.0000],"limitVoltage":[0.0000,0.0000,0.0000],"stepVoltageIncrement":[0.6250,0.6250,0.6250],"neutralU":[7200.0000,7200.0000,7200.0000],"initialDelay":[15.0000,15.0000,15.0000],"subsequentDelay":[2.0000,2.0000,2.0000],"lineDropR":[0.0000,0.0000,0.0000],"lineDropX":[0.0000,0.0000,0.0000],"reverseLineDropR":[0.0000,0.0000,0.0000],"reverseLineDropX":[0.0000,0.0000,0.0000],"ctRating":[300.0000,300.0000,300.0000],"ctRatio":[1500.0000,1500.0000,1500.0000],"ptRatio":[60.0000,60.0000,60.0000]},
.......
],
"solarpanels":[
],
"batteries":[
],
"switches":[
{"name":"2002200004641085_sw","mRID":"_F5E6D212-C700-C94A-ED54-E00E8230C19C","CN1":"q14734","CN2":"d5587291-3_int","phases":"ABC","nominalVoltage":12470.0,"normalOpen":false},
.......
],
"measurements":[
  {"name":"RatioTapChanger_VREG2","mRID":"02b818b7-fab3-4529-b3b3-fa7cb026eab9","ConductingEquipment_mRID":"_39BD981D-C57D-49E9-1209-9DF79B93A9EA","Terminal_mRID":"_4082AE8B-FAF3-34A9-26A6-6769C16CF78D","measurementType":"Pos","phases":"A","MeasurementClass":"Discrete","ConductingEquipment_type":"PowerTransformer","ConductingEquipment_name":"VREG2","ConnectivityNode":"190-8593"},
{"name":"PowerTransformer_hvmv_sub_Power","mRID":"034241b0-c4f9-4f83-9b65-5dcbeab6b029","ConductingEquipment_mRID":"_B32F64E3-AAD3-FA3F-254B-CF74D12DA290","Terminal_mRID":"_ECDEEB50-1B94-9B13-A797-DED1326D80A5","measurementType":"VA","phases":"B","MeasurementClass":"Analog","ConductingEquipment_type":"PowerTransformer","ConductingEquipment_name":"hvmv_sub","ConnectivityNode":"hvmv_sub_hsb"},

.......
]
}]}

Request CIM Feeder Index file

Generates a list of the feeders available powergrid model data store

  • Required: configurationType, parameters[model_id]
  • Optional: parameters[simulation_id]

Request: goss.gridappsd.process.request.config

{
  "configurationType":"CIM Feeder Index",
  "parameters":{"model_id":"_4F76A5F9-271D-9EB8-5E31-AA362D86F2C3"}
 }

Response:

{"feeders":[
{"name":"ieee123","mRID":"_C1C3E687-6FFD-C753-582B-632A27E28507","substationName":"ieee123_Substation","substationID":"_FE44B314-385E-C2BF-3983-3A10C6060022","subregionName":"large","subregionID":"_1CD7D2EE-3C91-3248-5662-A43EFEFAC224","regionName":"ieee","regionID":"_24809814-4EC6-29D2-B509-7F8BFB646437"},
{"name":"ieee13nodecktassets","mRID":"_5B816B93-7A5F-B64C-8460-47C17D6E4B0F","substationName":"ieee13nodecktassets_Substation","substationID":"_D5B23536-54A7-984E-78F2-B136E9B6380E","subregionName":"test","subregionID":"_C43D4535-5786-01CD-C3C4-69AAC7945AD2","regionName":"ieee","regionID":"_85D8A951-64F2-4787-C922-4AE0AA99A874"},
.......
]}

Request Simulation Output Configuration file

Generates file containing objects and properties with measurements avilable in the selected model

  • Required: configurationType, parameters[model_id]
  • Optional: parameters[simulation_id]

Request: goss.gridappsd.process.request.config

{
  "configurationType":"CIM Feeder Index",
  "parameters":{"model_id":"_4F76A5F9-271D-9EB8-5E31-AA362D86F2C3"}
 }

Response:

{
  "cap_capbank0a": [
    "switchA",
    "shunt_A",
    "voltage_A"
  ],

  "cap_capbank1b": [
    "switchB",
    "voltage_B",
    "shunt_B"
  ],
  "cap_capbank2c": [
    "voltage_C",
    "switchC",
    "shunt_C"
  ],
  "cap_capbank0b": [
    "voltage_B",
    "switchB",
    "shunt_B"
  ],.......

Request YBus Export Configuration file

Generates file containing ybus configuration for the selected simulation. Simulation must be running.

  • Required: configurationType, parameters[simulation_id]

Request: goss.gridappsd.process.request.config

{
  "configurationType":"YBus Export",
  "parameters":{"simulation_id":"12345"}
  }

Response:

{
  yParseFilePath":"/tmp/gridappsd_tmp/1129698954/base_ysparse.csv",
  "nodeListFilePath":"/tmp/gridappsd_tmp/1129698954/base_nodelist.csv",
  "summaryFilePath":"/tmp/gridappsd_tmp/1129698954/base_summary.csv"
}

Logging API

All applications and services should publish their log messages using using paltform;s log API.

Publishing Logs:

Log messages should be published on the following topic. Simulation id should be attached to the topic at the end.

goss.gridappsd.simulation.log.[simulation_id]

Message structure for publishing logs :

{
        "source": "",
        "processId": "",
        "timestamp": "long",
        "processStatus": "[STARTED|STOPPED|RUNNING|ERROR|PASSED|FAILED]",
        "logMessage": "",
        "logLevel": "[INFO|DEBUG|ERROR]",
        "storeToDb": [true|false]
}

where,

source is the filename publishing log message.

processId is the simulation id.

timestamp is in epoch format.

storeToDb is true if you want to store this message in log database for later.

Subscribing to Logs:

For the currently running simulation, subcribe to following topic with simulation id appended at the end to receive real time logs:

goss.gridappsd.simulation.log.[simulation_id]

Querying Logs:

Query request should be sent at following topic:

goss.gridappsd.process.request.data.log

User can query log data by sending either custom SQL query string or using query filters.

  1. Custom query string:

Logs are stored in MySQL database in a table named log with following columns: source, processId,timestamp, processStatus, logMessage, logLevel. User can create custom SQL query string to get log data:

{"query":"select * from log"}

Custom query response:

{ "data": [
        { "process_id": "", "process_status": "RUNNING", "log_level": "INFO", "log_message": "Starting gov.pnnl.goss.gridappsd.app.AppManagerImpl", "id": "1", "source": "gov.pnnl.goss.gridappsd.app.AppManagerImpl", "timestamp": "2018-11-14 21:51:11.0", "username": "system" },
        { "process_id": "", "process_status": "RUNNING", "log_level": "INFO", "log_message": "Found 0 applications", "id": "2", "source": "gov.pnnl.goss.gridappsd.app.AppManagerImpl", "timestamp": "2018-11-14 21:51:14.0", "username": "system" },
], "responseComplete": true, "id": "1792453601" }
  1. Query filters:

An example for query filters are

{
        "source": "ProcessEvent",
        "processId": "12345678",
        "processStatus": "DEBUG",
        "logLevel": "DEBUG"
}

For more details on log message filter look at ‘Publishing Logs’ section.

Custom query response:

{ "data": [
        { "process_id": "414798372", "process_status": "RUNNING", "log_level": "DEBUG", "log_message": "New rewuest received", "id": "8", "source": "ProcessEvent", "timestamp": "2018-11-14 21:51:29.0", "username": "system" },
        { "process_id": "", "process_status": "RUNNING", "log_level": "DEBUG", "log_message": "Running application", "id": "2", "source": "ProcessEvent", "timestamp": "2018-11-14 21:51:30.0", "username": "system" },
], "responseComplete": true, "id": "1792453601" }

Simulation API

Start a Simulation

Returns simulation id.

Queue:

goss.gridappsd.process.request.simulation

Example Request:

{

power_system_config: the CIM model to be used in the simulation

"power_system_config": {
        "GeographicalRegion_name": "ieee8500nodecktassets_Region",
        "SubGeographicalRegion_name": "ieee8500nodecktassets_SubRegion",
        "Line_name": "ieee8500"
},

simulation_config: the paramaters used by the simulation

"simulation_config": {
        "start_time": "2009-07-21 00:00:00",
        "duration": "120",
        "simulator": "GridLAB-D",
        "timestep_frequency": "1000",
        "timestep_increment": "1000",
        "simulation_name": "ieee8500",
        "power_flow_solver_method": "NR",

simulation_output: the objects and fields to be returned by the simulation

"simulation_output": {
        "output_objects": [{
                "name": "rcon_FEEDER_REG",
                "properties": ["connect_type",
                "Control",
                "control_level",
                "PT_phase",
                "band_center",
                "band_width",
                "dwell_time",
                "raise_taps",
                "lower_taps",
                "regulation"]
        },
        .....]
},

model creation config: the paramaters used to generate the input file for the simulation

        "model_creation_config": {
                "load_scaling_factor": "1",
                "schedule_name": "ieeezipload",
                "z_fraction": "0",
                "i_fraction": "1",
                "p_fraction": "0"
        }
},

application config: inputs to any other applications that should run as part of the simluation, in this case the voltvar application

"application_config": {
        "applications": [{
                "name": "vvo",
                "config_string": "{\"static_inputs\": {\"ieee8500\" : {\"control_method\": \"ACTIVE\", \"capacitor_delay\": 60, \"regulator_delay\": 60, \"desired_pf\": 0.99, \"d_max\": 0.9, \"d_min\": 0.1,\"substation_link\": \"xf_hvmv_sub\",\"regulator_list\": [\"reg_FEEDER_REG\", \"reg_VREG2\", \"reg_VREG3\", \"reg_VREG4\"],\"regulator_configuration_list\": [\"rcon_FEEDER_REG\", \"rcon_VREG2\", \"rcon_VREG3\", \"rcon_VREG4\"],\"capacitor_list\": [\"cap_capbank0a\",\"cap_capbank0b\", \"cap_capbank0c\", \"cap_capbank1a\", \"cap_capbank1b\", \"cap_capbank1c\", \"cap_capbank2a\", \"cap_capbank2b\", \"cap_capbank2c\", \"cap_capbank3\"], \"voltage_measurements\": [\"nd_l2955047,1\", \"nd_l3160107,1\", \"nd_l2673313,2\", \"nd_l2876814,2\", \"nd_m1047574,3\", \"nd_l3254238,4\"],       \"maximum_voltages\": 7500, \"minimum_voltages\": 6500,\"max_vdrop\": 5200,\"high_load_deadband\": 100,\"desired_voltages\": 7000,   \"low_load_deadband\": 100,\"pf_phase\": \"ABC\"}}}"
        }]
}

Subscribe to Simulation Output

Topic:

/topic/goss.gridappsd.simulation.output.[simulation_id]

Where simulation_id is response from start simulation API.

Example Message:

{
        "simulation_id" : "12ae2345",
    "message" : {
        "timestamp" : "YYYY-MM-DDThh:mm:ss.sssZ",
        "measurements" : [{
            "measurement_mrid" : "123a456b-789c-012d-345e-678f901a234b"
            "magnitude" : 3410.456,
            "angle" : -123.456
        }]
    }
}

Subscribe to Simulation Logs

Topic:

/topic/goss.gridappsd.simulation.log.[simulation_id]

Where simulation_id is response from start simulation API.

Example Message:

{
        "source": "",
        "processId": "",
        "timestamp": "",
        "processStatus": "[STARTED|STOPPED|RUNNING|ERROR|PASSED|FAILED]",
        "logMessage": "",
        "logLevel": "[INFO|DEBUG|ERROR]",
        "storeToDb": [true|false]
}

Send Input to Simulation

Topic:

/topic/goss.gridappsd.fncs.input

Example Message:

{
        "simulation_id" : "12ae2345",
    "message" : {
        "timestamp" : "2018-01-08T13:27:00.000Z",
        "difference_mrid" : "123a456b-789c-012d-345e-678f901a235c"
        "reverse_differences" : [
                        {
                                "object" : "61A547FB-9F68-5635-BB4C-F7F537FD824E",
                        "attribute" : "ShuntCompensator.sections",
                        "value" : "1"
                },
                        {
                                "object" : "E3CA4CD4-B0D4-9A83-3E2F-18AC5F1B55BA",
                        "attribute" : "ShuntCompensator.sections",
                        "value" : "0"
                }
                ]
        "forward_differences" : [
                        {
                                "object" : "61A547FB-9F68-5635-BB4C-F7F537FD824E",
                        "attribute" : "ShuntCompensator.sections",
                        "value" : "0"
                },
                        {
                                "object" : "E3CA4CD4-B0D4-9A83-3E2F-18AC5F1B55BA",
                        "attribute" : "ShuntCompensator.sections",
                        "value" : "1"
                }
                ]
        }
        }
}

Timeseries API

The Timeseries Data API allows you to query the timeseries data such as weather, simulation output and input.

Query Request Queue

Query request should be sent on following queue: goss.gridappsd.process.request.data.timeseries

Query Weather data

The weather data is based on exported data collected from the Solar Radiation Research Laboratory (39.74N,105.18W,1829 meter elevation) January - December 2013. The original dataset was based in Mountain Standard Time (MST).

The original column names included engineering units, but could not be included on the import. Below is a mapping between the exported column headers and the fields in the Influx database management system.

Original Exported Data                      Influx Measurement Field Key       Field Type
------------------------------------        ----------------------------       ----------
DATE (MM/DD/YYYY)                           DATE                               String
MST                                         MST                                String
Global CM22 (vent/cor) [W/ft^2]             GlobalCM22                         Float
Direct CH1 [W/ft^2]                         DirectCH1                          Float
Diffuse CM22 (vent/cor) [W/ft^2]            Diffuse                            Float
Tower Dry Bulb Temp [deg F]                 TowerDryBulbTemp                   Float
Tower RH [%]                                TowerRH                            Float
Avg Wind Speed @ 42ft [MPH]                 AvgWindSpeed                       Float
Avg Wind Direction @ 42ft [deg from N]      AvgWindDirection                   Float

Original Exported Data                      Influx Measurement Tag             Type
------------------------------------        ----------------------------       ----------
n/a                                         lat                                String
n/a                                         long                               String
n/a                                         place                              String

Influx database details:

Database name: “proven”, Measurement name: “weather”

Example Request:

{"queryMeasurement":"weather",
"queryFilter":{"startTime":"1357048800000000",
                        "endTime":"1357048860000000"},
"responseFormat":"JSON"}

Example Response for result format JSON:

{ "data": { "measurements": [ { "name": "weather",
  "points": [ { "row": { "entry": [
                                { "key": "Diffuse","value": "-0.006386875" },
                                { "key": "AvgWindSpeed","value": "0.0" },
                                { "key": "TowerRH", "value": "86.8" },
                        { "key": "long", "value": "\"105.18 W\"" },
                        { "key": "MST","value": "00:00" },
                        { "key": "TowerDryBulbTemp","value": "13.316" },
                        { "key": "DATE", "value": "1/1/2013" },
                        { "key": "DirectCH1", "value": "-0.0402521765" },
                        { "key": "GlobalCM22", "value": "-0.037676152399999996" },
                        { "key": "AvgWindDirection", "value": "0.0" },
                        { "key": "time", "value": "1357048800" },
                        { "key": "place", "value": "\"Solar Radiation Research Laboratory\"" },
                    { "key": "lat", "value": "\"39.74 N\"" } ] } },
                  { "row": { "entry": [
                        { "key": "Diffuse","value": "-0.005538233499999999" },
                { "key": "AvgWindSpeed", "value": "0.0" },
                { "key": "TowerRH", "value": "86.9" },
                { "key": "long", "value": "\"105.18 W\"" },
                { "key": "MST", "value": "00:01" },
                { "key": "TowerDryBulbTemp", "value": "13.406" },
                { "key": "DATE", "value": "1/1/2013" },
                { "key": "DirectCH1", "value": "-0.0395396335" },
                { "key": "GlobalCM22", "value": "-0.0369521827" },
                { "key": "AvgWindDirection", "value": "0.0" },
                { "key": "time", "value": "1357048860" },
                { "key": "place", "value": "\"Solar Radiation Research Laboratory\"" },
                { "key": "lat", "value": "\"39.74 N\"" } ] } } ] } ] },
  "responseComplete": true, "id": "1111869534" }

Allowed values for queryFilter are:

startTime[epoch number]
endTime[epoch number]
AvgWindDirection[number]
AvgWindSpeed[number]
Diffuse[number]
DirectCH1[number]
GlobalCM22[number]
MST[number]
TowerDryBulbTemp[number]
TowerRH[number]
lat[string]
long[string]
place[string]

Query Simulation Data

Returns simulation input or output data based on query filters

Example Request:

{"queryMeasurement": "simulation",
"queryFilter": {"simulation_id": "582881157"},
"responseFormat": "JSON"}

Example Response for result format JSON:

{
"data": { "measurements": [{ "name": "simulation",
                "points": [{ "row": { "entry": [
                        { "key": "hasMeasurementDifference", "value": "FORWARD" },
                        { "key": "hasSimulationMessageType", "value": "INPUT" },
                        { "key": "difference_mrid", "value": "c65d4ba9-8689-4838-970c-2983b54ed2e6" },
                        { "key": "simulation_id", "value": "582881157" },
                        { "key": "time", "value": "1562614884" },
                        { "key": "attribute", "value": "ShuntCompensator.sections" },
                        { "key": "value", "value": "0.0" },
                        { "key": "object","value": "_5405BE1A-BC86-5452-CBF2-BD1BA8984093" }]}},
                { "row": { "entry": [
                        { "key": "hasMeasurementDifference", "value": "FORWARD" },
                        { "key": "hasSimulationMessageType", "value": "INPUT" },
                        { "key": "difference_mrid", "value": "c65d4ba9-8689-4838-970c-2983b54ed2e6" },
                        { "key": "simulation_id", "value": "582881157" },
                        { "key": "time", "value": "1562614884" },
                        { "key": "attribute", "value": "ShuntCompensator.sections" },
                        { "key": "value", "value": "0.0" },
                        { "key": "object", "value": "_8D0EAC3F-AD56-C5A6-ED03-863DBB4A8C5F"}]}}
"responseComplete": true,
"id": "1927836780" }

Allowed values for queryFilter are:

Both input and output message type:
starttime [number]
endtime [number]
measurement_mrid [string]
simulation_id [string]
hasSimulationMessageType ["OUTPUT" | "INPUT"]

Ouput message type:
angle [number]
magnitude [number]

Input Message type:
hasMeasurementDifference  ["FORWARD"  | "REVERSE"]
attribute [string]
difference_mrid [string]
object [string]
value [number]

Please find some sample requests with various query filters

{"queryMeasurement": "simulation",
"queryFilter": {"simulation_id": "582881157", "hasSimulationMessageType": "INPUT"},
"responseFormat": "JSON"}

{"queryMeasurement": "simulation",
"queryFilter": {"simulation_id": "582881157", "angle": 23.706919634782313},
"responseFormat": "JSON"}

Query Sensor Service Data

Returns output of sensor sensor service.

Example Request:

{"queryMeasurement": "gridappsd-sensor-simulator",
"queryFilter": {"simulation_id": "582881157"},
"responseFormat": "JSON"}

Example Response for result format JSON:

{
        "data": {
        "measurements": [
                {
                "name": "gridappsd-sensor-simulator",
                "points": [
                        {
                                "row": {
                                "entry": [
                                        {
                                                "key": "instance_id",
                                                "value": "gridappsd-sensor-simulator-1564186315783"
                                        },
                                        {
                                                "key": "hasSimulationMessageType",
                                                "value": "OUTPUT"
                                        },
                                        {
                                                "key": "measurement_mrid",
                                                "value": "_0009caa4-23ef-41b9-9db7-624f3f47460c"
                                        },
                                        {
                                                "key": "angle",
                                                "value": "-152.44531328865978"
                                        },
                                        {
                                                "key": "magnitude",
                                                "value": "2470.4939175057075"
                                        },
                                        {
                                                "key": "simulation_id",
                                                "value": "1512566584"
                                        },
                                        {
                                                "key": "time",
                                                "value": "1564186297"
                                        }
                                        ]
                                        }
                        },.........]}]
        },
        "responseComplete": true,
        "id": "597021681"
}

Allowed values for queryFilter are:

starttime [number]
endtime [number]
measurement_mrid [string]
simulation_id [string]
instance_id
angle [number]
magnitude [number]
value [number]

Hosting Application or Service

Supported Application or Service Types

  • Python
  • EXE

Hosting Application or Service

Developers can create application and services using GridAPPS-D API and use following instruction to host it with the platform. For example of application and service working with GridAPPS-D, please see: https://github.com/GRIDAPPSD/gridappsd-sample-app and https://github.com/GRIDAPPSD/gridappsd-state-estimator

  1. Create proper folder structure for the application or service.

Following is the recommended structure for applications or services working with gridappsd using sample-app as an example:

For application:

.
├── README.md
└── my_app
    ├── app
    │   ├── [application exe or pythod code]
    ├── requirements.txt
    ├── my_app.config
    └── setup.py

For service:

.
├── README.md
└── my_service
    ├── service
    │   ├── [service exe or pythod code]
    ├── requirements.txt
    ├── my_service.config
    └── setup.py

Where config file is used by GridAPPS-D to launch the application or service from inside the gridappsd container.

Example config for application:

{
    "id":"sample_app",
    "description":"GridAPPS-D Sample Application app",
    "creator":"PNNL",
    "inputs":[],
    "outputs":[],
    "options": ["(simulationId)"],
    "type":"PYTHON",
    "execution_path": "sample_app/runsample.py",
    "launch_on_startup":false,
    "prereqs":["fncs","fncsgossbridge"],
    "multiple_instances":true
}

Example config for service:

{
        "id":"state-estimator",
        "description":"State Estimator",
        "creator":"PNNL",
        "inputs":["/topic/goss.gridappsd.fncs.output","/topic/goss.gridappsd.se.input"],
        "outputs":["/topic/goss.gridappsd.se.requests","/topic/goss.gridappsd.se.system_state"],
        "static_args":["(simulationId)"],
        "execution_path":"service/bin/state-estimator.out",
        "type":"EXE",
        "launch_on_startup":false,
        "prereqs":[],
        "multiple_instances":true,
        "environmentVariables":[]
}
  1. Clone the repository https://github.com/GRIDAPPSD/gridappsd-docker (refered to as gridappsd-docker repository) next to this repository (they should both have the same parent folder)
.
├── gridappsd-docker
└── gridappsd-sample-app
  1. Add application or service to platform

In order to add your application/service to the container you will need to modify the docker-compose.yml file included in the gridappsd-docker repository. Under the gridappsd service there is an example volumes leaf that is commented out. Uncomment and modify these lines to add the path for your application and config file. Adding these lines will mount the application/service on the container’s filesystem when the container is started.

For application:

#    volumes:
#      - ~/git/gridappsd-sample-app/sample_app:/gridappsd/applications/sample_app
#      - ~/git/gridappsd-sample-app/sample_app/sample_app.config:/gridappsd/applications/sample_app.config

    volumes:
      - ~/git/[my_app_directory]/[my_app]:/gridappsd/applications/[my_app]
      - ~/git/[my_app_directory]/[my_app]/[my_app.config]:/gridappsd/applications/[my_app.config]

For service:

#    volumes:
#      - ~/git/gridappsd-sample-app/sample_app:/gridappsd/applications/sample_app
#      - ~/git/gridappsd-sample-app/sample_app/sample_app.config:/gridappsd/applications/sample_app.config

    volumes:
      - ~/git/[my_service_directory]/[my_service]:/gridappsd/services/[my_service]
      - ~/git/[my_service_directory]/[my_service]/[my_service.config]:/gridappsd/services/[my_service.config]

How to start a service

Note: This process will be simplified in future releases so user could start a service through API and UI for a simulation with or without an application.

Currently a service will be started by the platform only if it is a requirement for an application as described in the application config file under prereqs key. By default gridappsd-sensor-service and gridappsd-voltage-violation services are available in GridAPPS-D docker container.

In order to start a service with an application (sample app in this example) follow these steps:

1. Go into sample app container by executing

docker exec -it gridappsddocker_sample_app_1 bash

2. Inside sample app container execute following commands

apt-get update

apt-get install vim

4. Edit sample_app.config and add service id to the prereqs as shown below:

"prereqs":["gridappsd-sensor-simulator"]

Note: Service id should match the value of “id” in service config file.

  1. Exit sample app container

6. Restart sample app docker container by executing

docker restart gridappsddocker_sample_app_1

7. Go into GridAPPS-D docker container by executing

docker exec -it gridappsddocker_gridappsd_1 bash

8. Start platform by executing :

./run-gridappsd.sh

Now when you start a simulation with sample app the service defined in prereqs will start as well.