A publish and subscribe mechanism is utilized for clients and applications to communicate with the GridAPPS-D platform. The next sections describe the topics and expected message formats for starting a simulation, receiving data from a simulation, and interacting with an ongoing simulation.

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"
                }
                ]
        }
        }
}

Input/Output Topics

The FNCS Bridge input and output topics are the main driver behind controlling the simulation and subscribing to the latest data from the simulation. FNCS Bridge listens for input on topic goss/gridappsd/fncs/input and publishes responses on topic goss/gridappsd/fncs/output

Applications that wish to interact with the simulation can do so by subscribing to to the output topic and publishing commands to the input topic.

Each message should contain a command field, this specifies the operation that is either sent to teh input topic or responded to on the output topic. The available values for the command field are isInitialized, nextTimeStep, update, and stop. These are each described in more depth below.

  • isInitialized

    goss/gridappsd/fncs/input - Checks to see if the simulator is initialized, meaning that it has established a connection to both GOSS and the simulator. This command takes no other parameters.

    {"command": "isInitialized"}

    goss/gridappsd/fncs/output - Returns simulator initializtion status (true/false) and any initialization messages.

    {"command": "isInitialized", "response":<true/false>, "output":"Any messages from simulator regarding initialization"}
  • nextTimeStep

    goss/gridappsd/fncs/input - Increments the simulator to the specified timestep, in a typical real-time simulation it will be incremented once per second. The only parameter is the current time in seconds (after the start of the simulation), this command will initiate the next time step in the simulator.

    {"command": "nextTimeStep", "currentTime":<seconds from start of simulation>}

    goss/gridappsd/fncs/output - Returns the current state of the objects and properties in the simulator, which objects and properties are specified by the simluation output. The is the output that applications will wish to subscribe to. The visualization application subscribes to this output to display the latest capacitor and regulator state. The volt-var optimization application subscribes to this output when managing voltage levels within the simulation

    {"command": "nextTimeStep", "output": "{\"ieee8500\":{\"cap_capbank0a\":{\"capacitor_A\":400000.0,\"control\":\"MANUAL\",\"control_level\":\"BANK\",\"dwell_time\":100.0,\"phases\":\"AN\",\"phases_connected\":\"NA\",\"pt_phase\":\"A\",\"switchA\":\"CLOSED\"},\"cap_capbank0b\":{\"capacitor_B\":400000.0,\"control\":\"MANUAL\",\"control_level\":\"BANK\",\"dwell_time\":101.0,\"phases\":\"BN\",\"phases_connected\":\"NB\",\"pt_phase\":\"B\",\"switchB\":\"CLOSED\"},\"cap_capbank0c\":{\"capacitor_C\":400000.0,\"control\":\"MANUAL\",\"control_level\":\"BANK\",\"dwell_time\":102.0,\"phases\":\"CN\",\"phases_connected\":\"NC\",\"pt_phase\":\"C\",\"switchC\":\"CLOSED\"},\"cap_capbank1a\":{\"capacitor_A\":300000.0,\"control\":\"MANUAL\",\"control_level\":\"BANK\",\"dwell_time\":100.0,\"phases\":\"AN\",\"phases_connected\":\"NA\",\"pt_phase\":\"A\",\"switchA\":\"CLOSED\"},\"cap_capbank1b\":{\"capacitor_B\":300000.0,\"control\":\"MANUAL\",\"control_level\":\"BANK\",\"dwell_time\":101.0,\"phases\":\"BN\",\"phases_connected\":\"NB\",\"pt_phase\":\"B\",\"switchB\":\"CLOSED\"},\"cap_capbank1c\":{\"capacitor_C\":300000.0,\"control\":\"MANUAL\",\"control_level\":\"BANK\",\"dwell_time\":102.0,\"phases\":\"CN\",\"phases_connected\":\"NC\",\"pt_phase\":\"C\",\"switchC\":\"CLOSED\"},\"cap_capbank2a\":{\"capacitor_A\":300000.0,\"control\":\"MANUAL\",\"control_level\":\"BANK\",\"dwell_time\":100.0,\"phases\":\"AN\",\"phases_connected\":\"NA\",\"pt_phase\":\"A\",\"switchA\":\"CLOSED\"},\"cap_capbank2b\":{\"capacitor_B\":300000.0,\"control\":\"MANUAL\",\"control_level\":\"BANK\",\"dwell_time\":101.0,\"phases\":\"BN\",\"phases_connected\":\"NB\",\"pt_phase\":\"B\",\"switchB\":\"CLOSED\"},\"cap_capbank2c\":{\"capacitor_C\":300000.0,\"control\":\"MANUAL\",\"control_level\":\"BANK\",\"dwell_time\":102.0,\"phases\":\"CN\",\"phases_connected\":\"NC\",\"pt_phase\":\"C\",\"switchC\":\"CLOSED\"},\"cap_capbank3\":{\"capacitor_A\":300000.0,\"capacitor_B\":300000.0,\"capacitor_C\":300000.0,\"control\":\"MANUAL\",\"control_level\":\"INDIVIDUAL\",\"dwell_time\":0.0,\"phases\":\"ABCN\",\"phases_connected\":\"NCBA\",\"pt_phase\":\"\",\"switchA\":\"CLOSED\",\"switchB\":\"CLOSED\",\"switchC\":\"CLOSED\"},\"nd_190-7361\":{\"voltage_A\":\"6410.387411-4584.456974j V\",\"voltage_B\":\"-7198.592139-3270.308372j V\",\"voltage_C\":\"642.547265+7539.531175j V\"},\"nd_190-8581\":{\"voltage_A\":\"6485.244722-4692.686497j V\",\"voltage_B\":\"-7183.641237-3170.693324j V\",\"voltage_C\":\"544.875720+7443.341013j V\"},\"nd_190-8593\":{\"voltage_A\":\"6723.279162-5056.725836j V\",\"voltage_B\":\"-7494.205738-3101.034602j V\",\"voltage_C\":\"630.475857+7534.534977j V\"},\"nd__hvmv_sub_lsb\":{\"voltage_A\":\"6261.474438-3926.148203j V\",\"voltage_B\":\"-6529.409296-3466.545236j V\",\"voltage_C\":\"247.131622+7348.295282j V\"},\"nd_l2673313\":{\"voltage_A\":\"6569.522312-5003.052614j V\",\"voltage_B\":\"-7431.486583-3004.840139j V\",\"voltage_C\":\"644.553331+7464.115915j V\"},\"nd_l2876814\":{\"voltage_A\":\"6593.064915-5014.031801j V\",\"voltage_B\":\"-7430.572726-3003.995538j V\",\"voltage_C\":\"643.473396+7483.558765j V\"},\"nd_l2955047\":{\"voltage_A\":\"5850.305846-4217.166594j V\",\"voltage_B\":\"-6729.652722-2987.617376j V\",\"voltage_C\":\"535.302083+7395.127354j V\"},\"nd_l3160107\":{\"voltage_A\":\"5954.507575-4227.423005j V\",\"voltage_B\":\"-6662.357613-3055.346879j V\",\"voltage_C\":\"600.213657+7317.832960j V\"},\"nd_l3254238\":{\"voltage_A\":\"6271.490549-4631.254028j V\",\"voltage_B\":\"-7169.987847-3099.952683j V\",\"voltage_C\":\"751.609655+7519.062260j V\"},\"nd_m1047574\":{\"voltage_A\":\"6306.632406-4741.568924j V\",\"voltage_B\":\"-7214.626338-2987.055914j V\",\"voltage_C\":\"622.058711+7442.125124j V\"},\"rcon_FEEDER_REG\":{\"Control\":\"MANUAL\",\"PT_phase\":\"CBA\",\"band_center\":126.5,\"band_width\":2.0,\"connect_type\":\"WYE_WYE\",\"control_level\":\"INDIVIDUAL\",\"dwell_time\":15.0,\"lower_taps\":16,\"raise_taps\":16,\"regulation\":0.10000000000000001},\"rcon_VREG2\":{\"Control\":\"MANUAL\",\"PT_phase\":\"CBA\",\"band_center\":125.0,\"band_width\":2.0,\"connect_type\":\"WYE_WYE\",\"control_level\":\"INDIVIDUAL\",\"dwell_time\":15.0,\"lower_taps\":16,\"raise_taps\":16,\"regulation\":0.10000000000000001},\"rcon_VREG3\":{\"Control\":\"MANUAL\",\"PT_phase\":\"CBA\",\"band_center\":125.0,\"band_width\":2.0,\"connect_type\":\"WYE_WYE\",\"control_level\":\"INDIVIDUAL\",\"dwell_time\":15.0,\"lower_taps\":16,\"raise_taps\":16,\"regulation\":0.10000000000000001},\"rcon_VREG4\":{\"Control\":\"MANUAL\",\"PT_phase\":\"CBA\",\"band_center\":125.0,\"band_width\":2.0,\"connect_type\":\"WYE_WYE\",\"control_level\":\"INDIVIDUAL\",\"dwell_time\":15.0,\"lower_taps\":16,\"raise_taps\":16,\"regulation\":0.10000000000000001},\"reg_FEEDER_REG\":{\"configuration\":\"rcon_FEEDER_REG\",\"phases\":\"ABC\",\"tap_A\":2,\"tap_B\":2,\"tap_C\":1,\"to\":\"nd__hvmv_sub_lsb\"},\"reg_VREG2\":{\"configuration\":\"rcon_VREG2\",\"phases\":\"ABC\",\"tap_A\":10,\"tap_B\":6,\"tap_C\":2,\"to\":\"nd_190-8593\"},\"reg_VREG3\":{\"configuration\":\"rcon_VREG3\",\"phases\":\"ABC\",\"tap_A\":16,\"tap_B\":10,\"tap_C\":1,\"to\":\"nd_190-8581\"},\"reg_VREG4\":{\"configuration\":\"rcon_VREG4\",\"phases\":\"ABC\",\"tap_A\":12,\"tap_B\":12,\"tap_C\":5,\"to\":\"nd_190-7361\"},\"xf_hvmv_sub\":{\"power_in_A\":\"1739729.121744-774784.928874j VA\",\"power_in_B\":\"1659762.622236-785218.729252j VA\",\"power_in_C\":\"1709521.679116-849734.584017j VA\"}}}\n"}
  • update

    goss/gridappsd/fncs/input - Sends an update command which can change the capacitor and regulator status within the simulator, this is used by the volt-var optimization application. Parameters include a message field, which contains the simulation name and the desired values for the objects to be updated.

    {"command": "update", "message": {"ieee8500": {"reg_FEEDER_REG": {"tap_C": -3, "tap_B": -2, "tap_A": -1}, "reg_VREG4": {"tap_C": 1, "tap_B": 8, "tap_A": 8}, "reg_VREG2": {"tap_C": -1, "tap_B": 2, "tap_A": 6}, "reg_VREG3": {"tap_C": -3, "tap_B": 6, "tap_A": 12}}}}
  • stop

    goss/gridappsd/fncs/input - Stops the simulator and shuts down the bridge. No additional parameters are required

    {"command": "stop"}