From GridLAB-D Wiki
Jump to: navigation, search

 New in 4.1! 

Overview

The helics_msg object is part of the connection module. It allows GridLAB-D models to be run as federates in a HELICS co-simulation. In 4.1 the helics_msg object is available by default.

Enabling the helics_msg object

When building from source. HELICS is a third party library that can be downloaded and built from here. Once HELICS and its third party libraries, ZeroMQ and boost, have been built, the following options needs to be added to the configure step for compiling GridLAB-D.

--with-helics=<location to where HELICS and its third party libraries were installed>

“CXXFLAGS=-g -O2 -w -std=c++11”

Environment Considerations

The following environment variables must have the location to the HELICS library and its third party libraries, ZeroMQ and boost.

OS Environment Variable
Windows PATH
Mac DYLD_LIBRARY_PATH
Linux LD_LIBRARY_PATH

Helics_msg

The helics_msg object implements the HELICS library such that a single GridLAB-D model acts as a single HELICS federate. There can only be one instance of a helics_msg object per GridLAB-D model.

Default Helics_msg

A minimalist helics_msg could be created with

object helics_msg{
     name federate1;
     configure federate1Configuration.txt;
}

Helics_msg Parameters

Property Name Type Unit Description
name string none This is the name of the object in the GridLAB-D context. It is also the name of the HELICS federate. This means that all published property topics get prepended with this name like so: name/publish_topic
configure string none The name of the file used to configure the HELICS federate.

Configuration File Syntax

HELICS 1.X Library

The configuration file defines the publication and subscription topics as well as the broker location helics federate options. The file is a json file with the following schema

{
     “publications” : {
          “globals” : {
               <global property name> : <subtopic name>,
               …
          },
          <object name> : {
               <property name> : <subtopic name>,
               …
          },
          …
     },
     “subscriptions” : {
          “globals” : {
               <global property name> : <topic name>,
               …
          },
          <object name> : {
               <property name> : <topic name>,
               …
          },
          …
     },
     “endpoint publications” : {
          “globals” : {
               <global property name> : <destination endpoint name>,
               …
          },
          <object name> : {
               <property name> : < destination endpoint name >,
               …
          },
          …
     },
     “endpoint_subscriptions” : {
          “globals” : {
               <global property name> : <endpoint name>,
               …
          },
          <object name> : {
               <property name> : <endpoint name>,
               …
          },
          …
     },
     “core_init_string” : <string>,
     “core_name” : <string>,
     “core_type” : <string>,
     “broker_address” : <string>,
     “time_delta” : <double in seconds>,
     “input_delay” : <double in seconds>,
     “rttolerance” : <double in seconds>,
     “output_delay” : <double in seconds>,
     “period” : <double in seconds>,
     “offset” : <double in seconds>,
     “maximum_iterations” : <integer>,
     “separator” : <single character string>,
     “observer” : <boolean>,
     “rollback” : <boolean>,
     “only_update_on_change” : <boolean>,
     “only_transmit_on_change” : <boolean>,
     “source_only” : <boolean>,
     “uninterruptible” : <boolean>,
     “interruptible” : <boolean>,
     “forward_compute” : <boolean>,
     “real_time” : <boolean>,
     “delayed_update” : <boolean>
}

All of the keys found in the json schema are optional. The example below shows federate configuration that publishes a load, ties a subscription to a substation voltage, and creates an endpoint for the fixed price of a market object for other federates to write to.

{
     "publications" : {
          "network_node" : {
               "distribution_load" : "total_load"
          }
     },
     "subscriptions" : {
          "network_node" : {
               "positive_sequence_voltage" : "transmision_sim/b_2_voltage"
          }
     },
     "endpoint_subscriptions" : {
          "market_1" : {
               "fixed_price" : "fixed_price_endpoint"
          }
     },
     "core_init_string" : "1"
}

HELICS 2.X

The configuration file defines the publication and subscription topics as well as the broker location helics federate options. The file is a json file with the following schema

{
     "broker" : string, //The address of the broker to connect to if the core hasn't connected to a broker already
     "core_init_string" : string, //The core_init_string to use if we have to create the core.
     "core_name" : string, //The name of the core to connect to if it exists otherwise create a core with this name.
     "core_type" : string, //The type of core the federate should be connecting to.
     "input_delay" : double, //The time in seconds to delay recieved data.
     "log_level" : int, //The level of verbosity to output to the logs. valid levels are 1-3?
     "max_iterations" : int, //The maximum number of times the federate can reiterate?
     "name" : string, //The federate name.
     "offset" : int, //offset from the period
     "output_delay" double, //The time in seconds to delay sending data.
     "period" : double, //The unit is in seconds. define this if the federate must return only on a multiple of this value.
     "rt_lag" : double, //The amount of time in seconds the federate is allowed to lag real time before corrective action is taken.
     "rt_lead" : double, //The amount of time in seconds the federate is allowed to lead real time before corrective action is taken.
     "rt_tolerance" : double, //The time tolerance in seconds of the real time mode.
     "separator" : string, //The character used separate the federate name from the publication key in the creation of the publication topic.
     "time_delta" : double, //The minimum time delta a federate can return to process an unexpected message.
     "flags" : {
          "delayed_update" : bool, //delay between calling publish and actually publishing the value on the HELICS message bus.
          "forward_compute" : bool, 
          "interruptible" : bool, //Flag that indicates the federate can return earlier than it's requested time to return.
          "observer" : bool, //Flag that indicates that this federate does not publish anything.
          "only_transmit_on_change" : bool, //Flag for publications/endpoints that indicates that the federate should only send if the value is different than the previous sent value.
          "only_update_on_change" : bool, //Flag for subscriptions/endpoints that only update the federate subscription/endpoint if the value is different than the previous value.
          "realtime" : bool, //Flag that indicates that this federate needs to run in real time.
          "source_only": bool, //Flag that indicates that this federate doesn't recieve messages of any type but publishes/sends data only.
          "uninterruptible" : bool, //Flag that indicates that this federate can't return earlier than the it's requested time to return.
          "wait_for_current_tiume" : bool 
     },
     "endpoints" : [
          {
               "global" : bool, //Flag to indicate this endpoint ss a global enpoint which means the federate name will not be prepended to the endpoint name followed by the separator.
               "knownDestinations" : string or [strings], //The enpoint name(s) to send messages to from this endpoint.
               "knownSubscription" : string or [strings], //The publication(s) to subscribe this endpoint to.
               "name" : string, //The name of the endpoint
               "type" : string //The data type this endpoint sends and recieves.
               "info" : "{
                    \"object\" : <object_name> or \"global\", //Can contain a specific GridLAB-D object instance name or global if you want to publish a GridLAB-D global property.
                    \"property\" : <object_property_name> or <global_property_name>, //Contains the name of the GridLAB-D object property or GridLAB-D global property
               }",
          },
          ...
     ],
     "publications" : [
          {
               "global" : bool, //Flag to indicate this publication s s a global publication which means the federate name will not be prepended to the publication name followed by the separator.
               "key" : string, //The name of the publication.
               "type" : string, //the data type this publication publishes.
               "unit" : string //The units associated with the data.
               "info" : "{
                    \"object\" : <object_name> or \"global\", //Can contain a specific GridLAB-D object instance name or global if you want to publish a GridLAB-D global property.
                    \"property\" : <object_property_name> or <global_property_name>, //Contains the name of the GridLAB-D object property or GridLAB-D global property
               }",
          },
          ...
     ],
     "subscriptions" : [
          {
               "key" : string, //The name of the publication topic to subscribe to.
               "required" : bool, //Flag that if set the federate will throw an error is the publication doesn't exist.
               "type" : string //The data type this subscription holds.
               "info" : "{
                    \"object\" : <object_name> or \"global\", //Can contain a specific GridLAB-D object instance name or global if you want to publish a GridLAB-D global property.
                    \"property\" : <object_property_name> or <global_property_name>, //Contains the name of the GridLAB-D object property or GridLAB-D global property
               }",
          },
          ...
     ]
}

All of the keys found in the json schema are optional. The example below shows federate configuration that publishes a load, ties a subscription to a substation voltage, and creates an endpoint for the fixed price of a market object for other federates to write to.

{
     "name" : "fed1",
     "period" : 1.0,
     "publications" : [
          {
               "global" : false,
               "key" : "total_load",
               "type" : "complex",
               "unit" : "VA",
               "info" : "{
                    \"object\" : \"network_node\",
                    \"property\" : \"distribution_load\"
               }"
          }
     ],
     "subscriptions" : [
          {
               "key" : "transmission_sim/b_2_voltage",
               "type" : "complex",
               "unit" : "V",
               "info" : "{
                    \"object\" : \"network_node\",
                    \"property\" : \"positive_sequence_voltage\"
               }"
          }
     ],
     "endpoints" : [
          {
               "global" : false,
               "name" : "fixed_price_point",
               "type" : "double",
               "info" : "{
                    \"object\" : \"market_1\",
                    \"property\" : \"fixed_price\"
               }"
          }
     ]
}