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.
Start a Simulation¶
Choose Simulations from the menu.
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 check mark to save the configuration.
Click the triangle (1) to start the simulation. Simulation Status (2) at the bottom of the screen will display the simulation log messages.
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.
Stop GridAPPS-D platform¶
For an orderly shutdown of the platform:
Use Ctrl+C to stop gridappsd from running
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. Six actions are available: Query_Model_names, Query, Query_Object, Query_Object_Types, Query_Model, and Put_Model
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 ?line_name ?subregion_name ?region_name WHERE {?line rdf:type cim:Line.?line cim:IdentifiedObject.name ?line_name.?line cim:Line.Region ?subregion.?subregion cim:IdentifiedObject.name ?subregion_name.?subregion cim:SubGeographicalRegion.Region ?region.?region cim: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": "_4F76A5F9-271D-9EB8-5E31-AA362D86F2C3",
"resultFormat": "JSON",
"filter": "?s cim:IdentifiedObject.name 'q14733'",
"objectType": "http://iec.ch/TC57/2012/CIM-schema-cim17#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¶
Not yet available 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
- 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
{
"requestType": "QUERY_OBJECT_IDS",
"resultFormat": "JSON",
"objectType": "......."
}
Example Response:
{
"objectIDs": ["_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"]
}
Query Object Dictionary By Type¶
Not yet available Returns details for either all objects of a particular type or a particular object based on the object Id in the same format as the model dictionary file.
Allowed parameters are:
- objectType – type of objects you wish to return details for.
- modelId (optional) - when specified it searches against that model, if empty it will search against all models
- objectID (optional) - 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_IDS",
"resultFormat": "JSON",
"objectType": "Capacitor. TODO what is cim type name......"
}
Example Response:
{
"name": "c83",
"mRID": "_8B8DB36D-CF7F-8C11-6C9C-E24B59C02366",
"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
},....
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 processes should publish their log messages with process status to Process Manager. These processes include applications, simulations, services, and test runs.
Topic:¶
Log message with process status should be published on the following topic. Process id should be attached to the topic name at the end.
goss.gridappsd.simulation.log.[simulation_id]
goss.gridappsd.service.log.[service_id]
goss.gridappsd.application.log.[app_id]
goss.gridappsd.test.log.[test_id]
Message structure:¶
{
"source": "",
"processId": "",
"timestamp": "",
"processStatus": "[STARTED|STOPPED|RUNNING|ERROR|PASSED|FAILED]",
"logMessage": "",
"logLevel": "[INFO|DEBUG|ERROR]",
"storeToDb": [true|false]
}
Receiving multiple logs:¶
User can either subscribe to individual process’s log by subscribing to topics mentioned above or receive all logs of a type by subscribing to following topics.
goss.gridappsd.simulation.log.*
goss.gridappsd.service.log.*
goss.gridappsd.application.log.*
goss.gridappsd.test.log.*
Similarly, to receive to all logs subscribe to following topic:
goss.gridappsd.*.log.*
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": "1248134400",
"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",
"measurement" : {
"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"
}
]
}
}
}
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
- 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":[]
}
- 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
- 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]