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; // New in 3.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; }
Properties
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"
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.