Group Recorder

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.

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; //  New in 3.1! 
strict boolean;
print_units boolean;
complex_part enumeration;
}

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].

Properties

Table 1: Group Recorder Properties

Property	Type	Description
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 clock mod flush == 0 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"

Examples

Example 1: Record Phases

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;
}

Example 2: Voltage

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 3: Real Power

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;
}

Related Concepts

• collector
• Tape (module)
• recorder