Group recorder

group recorder - Record data to a stream

Synopsis
module tape; object group_recorder { name "recorder-name"; parent "target-object-name"; group "target-object-name"; property "target-property-name"; file "output-file-name"; interval sampling-interval; limit sampling-limit; flush_interval -1; // strict boolean; print_units boolean; complex_part enumeration; }

Remarks
The group recorder can collect a recording of ONLY ONE property from a class or a group of similar objects. For instance, it can be used to record the voltages of every meter in the system as a time series. The values of the measured_energy variable of every meter object in a GLM are recorded into a file, named as "meter.csv", at 3600-second intervals.

object group_recorder { name MeterCorder; parent meter; group "class=meter"; property measured_real_energy; file meter.csv; interval 3600; limit 1000; }

The group_recorder places a timestamp in the first column of every row it emits. By default the timestamp is formatted using the ISO format (i.e., yyyy-mm-dd HH:MM:SS TZ). However, if the value of the dateformat global variable is not ISO, then the alternative date/time formatting rules will apply as follows:


 * #set dateformat=US : The timestamp will be formatted as mm-dd-yyyy HH:MM:SS[.SSSSSS].


 * #set dateformat=EURO : The timestamp will be formatted as dd-mm-yyyy HH:MM:SS[.SSSSSS].

Examples
Example 01: Three group_recorder objects are used to record the Phase A, B, and C voltages of all loads into three files. A MATLAB script that parses and plots the voltages of all loads is available in this GitHub repository.

object group_recorder { name loads_voltages_A_recorder; group "class=load"; property voltage_A; file loads_volts_A.csv; interval 1; limit 10000000; }

object group_recorder { name loads_voltages_B_recorder; group "class=load"; property voltage_B; file loads_volts_B.csv; interval 1; limit 10000000; }

object group_recorder { name loads_voltages_C_recorder; group "class=load"; property voltage_C; file loads_volts_C.csv; interval 1; limit 10000000; }

Caution: It is possible to have the voltages recorded as magnitude and angle (e.g., +7003.99-2.25958d) in the csv file. In this case, the MATLAB script in that GitHub repository needs to be modified to process the string "+7003.99-2.25958d".

1) Note that this is not controllable by users through property settings. Users may have a single csv file, in which the recorded voltages have a mix of two formats (i.e., the magnitude and angle format: "+7003.99-2.25958d", and the real and imaginary format: "+2465.49-1430.37j"). This bug will be fixed in future.

2) The property "complex_part" can be used to record the magnitude of a phase voltage. See Example 02, of which the output file can be parsed by the provided MATLAB script properly.

Example 02: A group_recorder that will watch the 'A' voltage of all meters and record the magnitude every 60 seconds.

object group_recorder { parent ThatNode; group "class=meter"; property voltage_A; interval 60; limit 1000; file ThatNode_kV.csv; complex_part MAG; }

Example 03: A group_recoder that measures real power through every transformer in a specific section of the circuit (through groupid) every 5 mins. object group_recorder { parent ThatTransformer; group "class=transformer"; property power_out; interval 300; limit 1000; file AllTransformers.csv; complex_part REAL; }

parent

 * object : Built-in property that specifies the object that the group_recorder childs to. Does not need to be specified.

property

 * string : Single property from the class to be recorded. Properties with units may be converted to other relevant units. Complex properties may be modified via the complex_parts enumeration.

file

 * string : By default, the name of the file to write the recorder output to. If left empty, the recorder will generate a file name based on the target object class and internal ID number.  The exact mode is dependent on the format of this string.  A simple file name will write text output to the specified file.  Other output modes are available with "mode:path", where mode may be "file", "odbc", "memory", or "plot".  The path for file and plot refer to a file name, to a global variable name for memory, and to a server login string for odbc.  See the Tape Database Output, Tape Memory Output, and Plotting Output sections for more details.

flush

 * number : By default the output buffer is flushed to disk when it is full (the size of the buffer is system specific). This default corresponds to the flush value -1.  If flush is set to 0, the buffer is flushed every time a record is written.  If flush is set to a value greater than 0, the buffer is flushed whenever the condition   is satisfied.

interval

 * integer : The frequency at which the recorder samples the specified properties, in seconds. A frequency of 0 indicates that they should be read & written every iteration (note, that each timestep often requires multiple iterations, so a frequency of zero may lead to multiple measurements in a timestep).  A frequency of -1 indicates that they should be read every timestep, but only written if one or more values change.  By default, this is TS_NEVER.

limit

 * integer : The number of rows to write to the output stream. A non-positive value puts no limit on the file size (use at your own risk).  By default, this is 0. The limit is only checked when output non-subsecond value.

group

 * string : Group definition string. Defines which class of device (required) and other information to create a group. See Finding_objects for more details.

flush_interval

 * integer : How often to "flush" the recorded material to the flat file - file flush interval (0 never, negative on samples)

strict

 * boolean : Causes the group_recorder to stop the simulation should there be a problem opening or writing with the group_recorder

print_units

 * boolean : flag to append units to each written value, if applicable

complex_parts

 * enumeration : Which part of the complex to record if a complex property is specified. Available settings: "NONE", "REAL", "IMAG", "MAG", "ANG_DEG", "ANG_RAD"

Caveats
The group_recorder attempts to read the value from the last iteration of a timestep, rather than the first iteration of a timestep. Normally the final value is more important than the initial or the intermediate values, for iterative solvers, but an interval of -1 can be used if necessary to record the value of a property with greater resolution.

The group_recorder cannot currently record the final value into a file, even though that value will be present in the output or dump XML file. This is a known quirk that cannot be resolved with the current structure of GridLAB-D, but is being worked on. All values written by various recorders at the same timestamp will be consistent between each other, however.