Collector

Collectors are different from recorders in that they aggregate multiple object properties into a single value. They do not use the parent property but instead use the group property to form a collection of objects over which the aggregate is taken.

module tape;
object collector {
name collector-name;
group class=class-name;
property aggregator(property)[,...];
file "file-name";
flush -1;
TODO:  // other properties may not be documented
}

Properties

  • group: The group property specifies the grouping rule for creating the collection. Groups may be specified using any registered property of the object, such as class, size, parent, id, or rank. For example:

    group "class=triplex_meter AND groupie=Residential"

  • property: The property to aggregate over the group. Must be in the form aggregator(property), where the aggregator is one of min, max, count, avg, std, mean, var, mbe, kur, sum, prod, skew, or gamma. If a | is used instead of parentheses the absolute value of the property is used. Multiple aggregates may be specified as a comma-separated list.

    If the property is a complex number, it must be specified in the form

    property.part

    where part is real, imag (imaginary), mag (magnitude), ang (angle in degrees), or arg (angle in radians).

    For example, a collector over all water heater objects might aggregate the power property using

    count(power),min(power),max(power),std(power)

    which would print the number of water heaters, the minimum power used by any one water heater, the maximum power used, and the standard deviation of the power used by the set of water heaters.

    Note: As of revision 3320, kur and skew remain unimplemented.

  • file: The path to the output CSV file. If omitted, the file name is automatically derived from the group specification with disallowed characters replaced by underscores and the .txt extension appended.

  • interval: The recording interval in seconds. 0 = record on every simulation pass; -1 = record only when the aggregated value changes; >0 = record at the specified periodic interval.

  • limit: The maximum number of samples to write. Once the limit is reached the collector stops recording. 0 (default) means no limit.

  • trigger: An optional conditional expression that must be satisfied before the collector opens its output file and begins recording. The expression takes the form <op><value> where <op> is <, =, or >. Recording begins only when the comparison against the current aggregated value is true.

  • flush: Controls how often the output buffer is flushed to disk. -1 (default) flushes when the system buffer is full. 0 flushes every time a record is written. A value greater than 0 flushes whenever clock mod flush == 0.

Example

object collector {
group "class=triplex_meter AND groupie=Residential"
property max(measured_voltage_1);
file max_houe_voltage.csv;
}
  • Collections
  • Recorder