From GridLAB-D Wiki
Jump to: navigation, search

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.

See also