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

With the platform running, use curl to load the file into Blazegraph.

curl -s -D- -H 'Content-Type: application/xml' --upload-file 'model.xml' -X POST 'http://localhost:8889/bigdata/sparql'

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": "_C1C3E687-6FFD-C753-582B-632A27E28507",
    "p_fraction": "0.0",
    "simulation_id": "12345",
    "z_fraction": "0.0",
    "simulation_broker_host": "localhost",
    "simulation_name": "ieee8500",
    "simulation_duration": "60",
    "simulation_start_time": "1518958800",
    "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": "_C1C3E687-6FFD-C753-582B-632A27E28507",
    "load_scaling_factor": "1.0",
    "schedule_name": "ieeezipload",
    "p_fraction": "0.0"
  }
}

Response:

object regulator_configuration {
name "rcon_reg1a";
connect_type WYE_WYE;
      Control MANUAL; // LINE_DROP_COMP;
.......

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": "_C1C3E687-6FFD-C753-582B-632A27E28507"
  }
}

Response: :: {“feeders”:[

{“name”:”ieee123”,
“mRID”:”_C1C3E687-6FFD-C753-582B-632A27E28507”, “substation”:”IEEE123”, “substationID”:”_FE44B314-385E-C2BF-3983-3A10C6060022”, “subregion”:”Medium”, “subregionID”:”_1CD7D2EE-3C91-3248-5662-A43EFEFAC224”, “region”:”IEEE”, “regionID”:”_73C512BD-7249-4F50-50DA-D93849B89C43”, “swing_nodes”:[ {“name”:”source”,”bus”:”150”,”phases”:”ABC”,”nominal_voltage”:2401.8,”x1”:100.0,”y1”:1500.0} ], “synchronousmachines”:[ ], “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":"_C1C3E687-6FFD-C753-582B-632A27E28507"}
 }

Response:

{"feeders":[
      {"name":"ieee123",
      "mRID":"_C1C3E687-6FFD-C753-582B-632A27E28507",
      "substation":"IEEE123",
      "substationID":"_FE44B314-385E-C2BF-3983-3A10C6060022",
      "subregion":"Medium",
      "subregionID":"_1CD7D2EE-3C91-3248-5662-A43EFEFAC224",
      "region":"IEEE",
      "regionID":"_73C512BD-7249-4F50-50DA-D93849B89C43",
      "synchronousmachines":[
      ],
      "capacitors":[
      {"name":"c83","mRID":"_232DD3A8-9A3C-4053-B972-8A5EB49FD980","CN1":"83","phases":"ABC","kvar_A":200.0,"kvar_B":200.0,"kvar_C":200.0,"nominalVoltage":4160.0,"nomU":4160.0,"phaseConnection":"Y","grounded":true,"enabled":false,"mode":null,"targetValue":0.0,"targetDeadband":0.0,"aVRDelay":0.0,"monitoredName":null,"monitoredClass":null,"monitoredBus":null,"monitoredPhase":null},
      {"name":"c88a","mRID":"_9A74DCDC-EA5A-476B-9B99-B4FB90DC37E3","CN1":"88","phases":"A","kvar_A":50.0,"kvar_B":0.0,"kvar_C":0.0,"nominalVoltage":4160.0,"nomU":2402.0,"phaseConnection":"Y","grounded":true,"enabled":false,"mode":null,"targetValue":0.0,"targetDeadband":0.0,"aVRDelay":0.0,"monitoredName":null,

.......
]
}]}

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":"_C1C3E687-6FFD-C753-582B-632A27E28507"}
 }

Response:

{"feeders":[

{“name”:”test9500new”,”mRID”:”_AAE94E4A-2465-6F5E-37B1-3E72183A4E44”,”substationName”:”ThreeSubs”,”substationID”:”_40485321-9B2C-1B8C-EC33-39D2F7948163”,”subregionName”:”Large”,”subregionID”:”_A1170111-942A-6ABD-D325-C64886DC4D7D”,”regionName”:”IEEE”,”regionID”:”_73C512BD-7249-4F50-50DA-D93849B89C43”}, {“name”:”ieee123”,”mRID”:”_C1C3E687-6FFD-C753-582B-632A27E28507”,”substationName”:”IEEE123”,”substationID”:”_FE44B314-385E-C2BF-3983-3A10C6060022”,”subregionName”:”Medium”,”subregionID”:”_1CD7D2EE-3C91-3248-5662-A43EFEFAC224”,”regionName”:”IEEE”,”regionID”:”_73C512BD-7249-4F50-50DA-D93849B89C43”},

]}

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":"GridLAB-D Simulation Output",
  "parameters":{"model_id":"_C1C3E687-6FFD-C753-582B-632A27E28507"}
 }

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 all OpenDSS configuration files

Generates all configuration files necessary to run a sumulation using the OpenDSS 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": "DSS All",
  "parameters": {
    "load_scaling_factor": "1.0",
    "i_fraction": "1.0",
    "model_id": "_C1C3E687-6FFD-C753-582B-632A27E28507",
    "p_fraction": "0.0",
    "simulation_id": "12345",
    "z_fraction": "0.0",
    "simulation_broker_host": "localhost",
    "simulation_name": "ieee8500",
    "simulation_duration": "60",
    "simulation_start_time": "1518958800",
    "solver_method": "NR",
    "schedule_name": "ieeezipload",
    "simulation_broker_port": "61616",
    "directory": "/tmp/dsssimulation/"
  }
}

Response: <directory where files have been stored>

Request OpenDSS Base File

Generates the main GLM file required by the OpenDSS 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": "DSS Base",
  "parameters": {
    "i_fraction": "1.0",
    "z_fraction": "0.0",
    "model_id": "_C1C3E687-6FFD-C753-582B-632A27E28507",
    "load_scaling_factor": "1.0",
    "schedule_name": "ieeezipload",
    "p_fraction": "0.0"
  }
}

Response:

clear
new Circuit.source phases=3 bus1=150 basekv=4.160 pu=1.00000 angle=0.00000 r0=0.00000 x0=0.00010 r1=0.00000 x1=0.00010
new Linecode.11 nphases=1 units=mi rmatrix=[1.32920 ] xmatrix=[1.34750 ] cmatrix=[11.9873 ]
new Linecode.1 nphases=3 units=mi rmatrix=[0.457600 | 0.156000 0.466600 | 0.153500 0.158000 0.461500 ] xmatrix=[1.07800 | 0.501700 1.04820 | 0.384900 0.423600 1.06510 ] cmatrix=[15.0567 | -4.85904 15.8641 | -1.85195 -3.08879 14.3156 ]


.......

Request OpenDSS Coordinates File

Generates the symbols file with XY coordinates used by the OpenDSS simulator

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

Request: goss.gridappsd.process.request.config

{
  "configurationType": "DSS Coordinate",
  "parameters": {
    "model_id": "_C1C3E687-6FFD-C753-582B-632A27E28507"
  }
}

Response:

88,2950.0,1300.0 89,2775.0,1125.0 197,3525.0,2200.0 110,4275.0,3050.0 111,4275.0,3625.0 112,4275.0,2925.0 113,4800.0,2925.0 114,5125.0,2925.0 90,2775.0,900.0 61s,3175.0,1300.0 91,2550.0,1125.0 92,2550.0,825.0 93,2325.0,1125.0 94,2325.0,850.0 95,2025.0,1125.0 96,2025.0,925.0 97,3525.0,2100.0 98,3800.0,2100.0 10,1450.0,2150.0 99,4350.0,2100.0 11,950.0,2150.0

Request YBus Export Configuration file

Generates file containing ybus configuration for the given model or simulation.

Request: goss.gridappsd.process.request.config

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

If requested for a simulation then simulation id is mandatory. Otherwise use model_id as mentioned next.

{
"configurationType": "YBus Export",
"parameters": {
  "model_id": "_C1C3E687-6FFD-C753-582B-632A27E28507"
            }
    }

Additional paramters can be provided with model_id as mentioned in next request.

  {
  "configurationType": "YBus Export",
  "parameters": {
    "i_fraction": "1.0",
    "z_fraction": "0.0",
    "model_id": "_C1C3E687-6FFD-C753-582B-632A27E28507",
    "load_scaling_factor": "1.0",
    "schedule_name": "ieeezipload",
    "p_fraction": "0.0"
  }
}

Response:

{
      "yParse": [
          "Row,Col,G,B",
          "1,1,517.6253721,-539.2591296",
          "2,1,-3.438703156,9.070554234",
          "3,1,-5.837170999,11.07061383",
          "4,1,-500,500",
          "84,1,-9.232329792,20.56428834",
          "85,1,1.801223903,-4.751238599",
          "86,1,3.057563114,-5.798887966"
          ..........
              ],
              "nodeList": [
                "\"97.1\"",
                "\"97.2\"",
              ..........
              ],
              "summary": [
                 "DateTime, .......
              ]
      }

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",
                "model_state":{
                        "synchronousmachines":[
                                {"name":"diesel590","p":100.000,"q":140.000},
                                {"name":"diesel620","p":150.000,"q":500.000}
                        ],
                        "switches":[
                                {"name":"2002200004641085_sw","open":true},
                                {"name":"2002200004868472_sw","open":true},
                                {"name":"l9407_48332_sw","open":true},
                                {"name":"tsw568613_sw","open":false}
                        ]
            }
        }
},

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" : "1357048800",
        "measurements" : {
            "123a456b-789c-012d-345e-678f901a234b":{
                                "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": "[STARTING|STARTED|STOPPED|RUNNING|ERROR|CLOSED|COMPLETE]",
        "logMessage": "",
        "logLevel": "[INFO|DEBUG|ERROR]",
        "storeToDb": [true|false]
}

Send Input to Simulation

Topic:

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

Example Message:

{
  "command": "update",
  "input": {
      "simulation_id": "123456",
      "message": {
          "timestamp": 1357048800,
          "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
              }
              ]
              }
      }
}

Pause Simulation

Topic:

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

Example Message:

{
    "command": "pause"
}

Resume Simulation

Topic:

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

Example Message:

{
    "command": "resume"
}

Resume and Pause the Simulation after a Specified Number of Seconds

Topic:

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

Example Message:

{
    "command": "resumePauseAt",
    "input": {
        "pauseIn": 10
    }
}

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": [ { "Diffuse": 2.5305959999999996,
                "AvgWindSpeed": 0,
                "TowerRH": 70.65,
                "long": "105.18 W",
                "MST": "08:00",
                "TowerDryBulbTemp": 16.124,
                "DATE": "1/1/2013",
                "DirectCH1": 0.08549150370000001,
                "GlobalCM22": 2.53962588,
                "AvgWindDirection": 0,
                "time": 1357048800,
                "place": "Solar Radiation Research Laboratory",
                "lat": "39.74 N" },
        { "Diffuse": 2.6431350599999996,
                "AvgWindSpeed": 0,
                "TowerRH": 70.41,
                "long": "105.18 W",
                "MST": "08:01",
                "TowerDryBulbTemp": 15.908,
                "DATE": "1/1/2013",
                "DirectCH1": 0.045951777299999996,
                "GlobalCM22": 2.6501118499999996,
                "AvgWindDirection": 0,
                "time": 1357048860,
                "place": "Solar Radiation Research Laboratory",
                "lat": "39.74 N" } ],
  "responseComplete": true,
  "id": "1998314042" }

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] or [array of string values]
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"}

{"queryMeasurement":"simulation",
"queryFilter":{"simulation_id":"1743450224",
"measurement_mrid":["_01625641-d9ae-4c34-8302-69a9620ec69d","_ffd6abc7-159d-4f6d-868b-7bf7b087ab85"]},
"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]

Query Historical Sensor Service Data

A docker image is available that containes the pre-populated historical data generated from sensor service for 9500 node model. It containes data with following details:

  • Start time: Saturday, July 13, 2013 8:00:02 AM (1373727602)
  • End time: Friday, July 19, 2013 3:12:23 PM (1374271943).
  • Simulation Id: 890162203

Follow these steps to access historical data:

  1. Clone gridappsd-docker repo
  2. Change the influxdb image in docker-compose.yml file to gridappsd/influxdb:historical
  3. Execure ./run.sh -t <release tag>
  4. Use Query Sensor Service Data API to request data.

Services

Sensor Simulator Service The GridAPPSD’s Sensor Simulator simulates real devices based upon the magnitude of “prestine” simulated values. Currently the sensor service supports angle and magnitude measurements.

‘_GridAPPS-D DNP3 Service <https://gridappsd-dnp3.readthedocs.io/en/develop/>’__ The GridAPPS-D DNP3 Service integrates GridAPPS-D with DNP3 based commercial tools to enable the CIM and DNP3 data exchange of the devices.

Hosting Application

Supported Application or Service Types

  • Python
  • EXE

Hosting Application

Developers can create application using GridAPPS-D API and use following instruction to host it with the platform. Applications run in their own Docker contianer. For example of an application working with GridAPPS-D, please see: https://github.com/GRIDAPPSD/gridappsd-sample-app.

1. Create proper folder structure for the application

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

.
└── gridappsd-sample_app
    ├── sample-app
    │   ├── [application exe or pythod code]
    ├── requirements.txt
    ├── sample_app.config
    ├── Dockerfile
    └── setup.py

Where,

  • gridappsd-sample-app is a folder and name of the application.
  • sample-app is a folder that contains the application’s source/build code.
  • requirements.txt is required for Python based application and lists all the pre-requisite packages.
  • sample_app.config is a file used by GridAPPS-D to launch the application from inside application container. More details are provided in Step 2.
  • Dockerfile contains all the commands to assemble a Docker image for the application. More details are provided in Step 3.
  • setup.py is build script file for python based applications.

2. Create config file for application

Config file is used by GridAPPS-D platform to register and launch the application. Here is the config file example using gridappsd-sample-app:

{
    "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":["gridappsd-state-estimator"],
    "multiple_instances":false
}

Where,

  • id is the name of the application and should match the name of the config file.
  • description is a string that describes the application.
  • creator is the organization/developer name
  • inputs is the list of input topics application is listening to. For future use. Leave it as in the example for now.
  • outputs is the list of input topics application is publishing to. For future use. Leave it as in the example for now.
  • options are the run time arguments required by the application. Available options are: (i) simulationId: Unique identifier for the simulation, (ii) request: Simulation request sent by the user.
  • type defines the type fo the application which can be PYTHON or EXE.
  • execution_path is the path of the main file that starts the application relative to the top-most folder. In this example it would be the path relative to gridappsd-sample-app folder.
  • launch_on_startup is true if application needs to be started as the platform starts and false if application needs to be started with a simulation.
  • prereqs is list of GridAPPS-D services that need to be started before starting the application. Leave it as empty list [] if no such services are required. Services such as FNCS and FNCS-GOSS-BRIDGE are started by default with a simuolation so not needed to be specified here.
  • multiple_instances is true if multiple instances of this application can be started for a single simulation otherwise false.

3. Create Dockerfile for application

Copy Dockerfile from https://github.com/GRIDAPPSD/gridappsd-sample-app/blob/master/Dockerfile. In the file replace gridappsd-sample with your applcation name and sample_app.config with the name of the config file of your application. You can add more commands in the file if needed for your application.

4. Build the Docker container for application

docker build --network=host -t sample-app .

Where,

  • sample-app is the image name. Change it to your application name.

5. Clone gridappsd-docker repository

Clone this repository outside any application folder.

git clone https://github.com/GRIDAPPSD/gridappsd-docker.git

6. Add application to platform

In order to add your application to the GridAPPS-D platform you will need to modify the docker-compose.yml file included in the gridappsd-docker repository. Add the following to the file:

sample_app:
image: sample_app
environment:
  GRIDAPPSD_URI: tcp://gridappsd:61613
depends_on:
  - gridappsd

Use image name from step 4 instead of sample_app in line 1 and 2.

7. Start platform and application container

cd gridappsd-docker
./run.sh

This script starts application container along with platform. Application container has built-in code that allows application to register with GridAPPS-D platform when it starts.

8. Verify that application container is running

Use following command to list all Docker container which should include application container with running status.

docker ps -a

Optional - You can go inside the application container to check its content.

docker exec -it sample_app bash

Where,

  • sample_app is the name of the container. Replace it with your application container name.

Execute exit to get out of the application container.

9. Varify that application is hosted correctly

  • Go to http://localhost:8080
  • Login with default user credetials already provided in login screen.
  • Press Menu on the top-left corner
  • Press Configure New Simulation menu item
  • Go to Application Configuration tab
  • Look for the application name in the drop down box.

If your application is available in that drop down box then application is hosted correctly with the platform.

For next step see documentation under Using GridAPPS-D –> Start a Simulation

Hosting Service

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

1. Create proper folder structure for the service.

Following is the recommended structure for services working with gridappsd using gridappsd-state-estimator as an example:

       .
       └── gridappsd-state-estimator
           ├── state-estimator
           │   ├── [service exe or pythod code]
           ├── requirements.txt
           ├── state-estimator.config
           └── setup.py

- **gridappsd-state-estimator** is a folder and name of the service.
- **state-estimator** is a folder that contains the service's source/build code.
- **requirements.txt** is required for Python based service and lists all the pre-requisite packages.
- **state-estimator.config** is a file used by GridAPPS-D to launch the service from inside GridAPPS-D container. More details are provided in Step 2.
- **setup.py** is build script file for python based applications.

2. Create config file for service

Config file is used by GridAPPS-D platform to register and launch the service. Here is the config file example using gridappsd-state-estimator:

::
{

“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)”,”(request)”], “execution_path”:”services/gridappsd-state-estimator/state-estimator/bin/state-estimator”, “type”:”EXE”, “launch_on_startup”:false, “prereqs”:[], “multiple_instances”:true, “environmentVariables”:[], “user_input”: {

“use-sensors-for-estimates”: {
“help”: “Use measurements from the sensor-simulator service, if the sensor-simulator is configured, to generate state estimates rather than using simulation measurements”, “help_example”: false, “default_value”: true, “type”: “bool”

}

}

}

Where,

  • id is the name of the service and should match the name of the config file.
  • description is a string that describes the service.
  • creator is the organization/developer name
  • inputs is the list of input topics service is listening to. For future use. Leave it as in the example for now.
  • outputs is the list of input topics service is publishing to. For future use. Leave it as in the example for now.
  • options are the run time arguments required by the service. Available options are: (i) simulationId: Unique identifier for the simulation, (ii) request: Simulation request sent by the user.
  • type defines the type fo the service which can be PYTHON or EXE.
  • execution_path is the path of the main file that starts the service relative to the top-most folder. In this example it would be the path relative to gridappsd-sample-app folder.
  • launch_on_startup is true if service needs to be started as the platform starts and false if service needs to be started with a simulation.
  • prereqs is list of GridAPPS-D services that need to be started before starting the service. Leave it as empty list [] if no such services are required. Services such as FNCS and FNCS-GOSS-BRIDGE are started by default with a simuolation so not needed to be specified here.
  • multiple_instances is true if multiple instances of this service can be started for a single simulation otherwise false.

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 service or service to platform

In order to add your service/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 service and config file. Adding these lines will mount the service/service on the container’s filesystem when the container is started.

For service:

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

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

For service:

#    volumes:
#      - ~/git/gridappsd-sample-app/sample_app:/gridappsd/services/sample_app
#      - ~/git/gridappsd-sample-app/sample_app/sample_app.config:/gridappsd/services/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 service.

Currently a service will be started by the platform only if it is a requirement for an service as described in the service 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 service (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.