Metrics collector writer

=Overview= This document describes GridLAB-D implementation of metrics_collector_writer. metrics_collector_writer class is created as part of the project Transactive Energy Simulation Platform. metrics_collector_writer is used together with metrics_collector to collect the aggregated values from metrics_collector, and writes the intermediate metrics to Javascript Object Notation (JSON) files during the simulation at each predefined time interval. This saves considerable disk space and processing time over the handling of multiple CSV files. Python, and other languages, have library functions optimized to quickly load JSON files.

Inputs
In order to record and aggregate the simulation data in each time interval, both metrics_collector and metrics_collector_writer need to be used. The time interval defined in glm file for metrics_collector_writer should be the same with the ones defined for all metrics_collector objects. metrics_collector is attached to each object from which the simulation data are recorded. metrics_collector_writer should be defined before defining all the metrics_collector objects in the glm file (this is important so that metrics_collector_writer will wait till all metrics_collector objects have done aggregation for each time period).

Outputs
In addition, prefix of output file names can be defined in glm file for metrics_collector_writer. If not given the prefix, then file will be named by metrics_collector_writer based on its id in GridLAB-D. There are 6 output files generated by metrics_collector_writer, based on the data recorded by metrics_collector objects attached to triplex_meter/meter, house/water heater, inverter, capacitor, regulator and swing-bus meter/substation node respectively. The aggregated data from house and water heater are written into one output file, aggregated data from meter and triplex meter are written into the same output file.

For example, if the filename is given as "metrics_collector_output.json" in glm file, then the output files will be:


 * "house_metrics_collector_output.json"
 * "inverter_metrics_collector_output.json"
 * "capacitor_metrics_collector_output.json"
 * "regulator_metrics_collector_output.json"
 * "substation_metrics_collector_output.json"
 * "billing_meter_metrics_collector_output.json"

Metadata is also written into each output file, indicating the names of the aggregated values based on their indices, as seen in the below example from an inverter output file. "Metadata" : { "reactive_power_avg" : { "index" : 5, "units" : "VAR" },     "reactive_power_max" : { "index" : 4, "units" : "VAR" },     "reactive_power_min" : { "index" : 3, "units" : "VAR" },     "real_power_avg" : { "index" : 2, "units" : "W" },     "real_power_max" : { "index" : 1, "units" : "W" },     "real_power_min" : { "index" : 0, "units" : "W" }  }

At each time interval, metrics_collector_writer the loops through each metrics_collector object, identify the parent type this metrics_collector object is attached to, and write the aggregated data from each metrics_collector object to the corresponding output file of the same parent type. If, for example, metrics_collector objects are only attached to inverter objects, the values in each time interval in output files for the other objects are all null. Below shows an example from an inverter output file at time 32100 seconds since starting of the simulation. The starting time of the simulation is also given in each output file. "32100" : {     "inverters" : [ {           977.98732248746251,            977.98732248746637,            977.98732248746637,            0.0,            0.0,            0.0         }      ]   }

= Synopsis = Below example shows how metrics_collector_writer is defined in glm file. User needs to define the time interval in seconds for metrics_collector_writer. The prefix of output file names can also be defined, or default names will be used. object metrics_collector_writer { interval 300; // in seconds filename metrics_collector_output.json; };

= See also =
 * Tape (module)
 * metrics_collector