Violation Recorder

The violation_recorder object monitors a GridLAB-D™ powerflow simulation and records voltage and thermal limit violations to output files. It scans powerflow objects (transformers, overhead lines, underground lines, triplex lines, nodes, meters, and inverters) each simulation timestep and writes timestamped violation records when configured thresholds are exceeded.

Two output files are produced:

• Log file (file): A CSV recording each violation event with timestamp, violation type, observed value, limits, object name, object type, phase, and a descriptive message.
• Summary file (summary): A CSV containing total violation counts per violation type and per object class at the end of the simulation.

Properties

Table 1: Violation Recorder Properties

Property	Type	Unit	Default	Description
file	char256	—	(auto-generated)	Output log file name. If omitted, defaults to violation_recorder-violation-log.csv.
summary	char256	—	(auto-generated)	Summary output file name. If omitted, defaults to violation_recorder-violation-summary.csv.
virtual_substation	char256	—	—	Name of the substation link object to monitor for reverse flow violations (VIOLATION4, VIOLATION5, VIOLATION8). If not specified, reverse flow and power factor violations are skipped.
interval	double	s	0	Recording interval. 0 = check every iteration; -1 = check on every commit timestep; >0 = check at the specified periodic interval.
flush_interval	double	s	0	File flush interval. 0 = never flush; <0 = flush every N samples (where N = absolute value); >0 = flush at the given time interval.
strict	bool	—	false	If true, the simulation halts on any file I/O error or if required objects cannot be found.
echo	bool	—	false	If true, violation messages are also written to the console output.
limit	int32	—	—	Maximum number of violation lines to write to the log file. The file is closed once the limit is reached.
violation_delay	int32	s	0	Number of seconds to skip at the start of the simulation before recording violations. Useful for allowing the system to reach a steady state.
xfrmr_thermal_limit_upper	double	pu	—	Upper per-unit thermal loading limit for transformers (VIOLATION1).
xfrmr_thermal_limit_lower	double	pu	—	Lower per-unit thermal loading limit for transformers (VIOLATION1).
line_thermal_limit_upper	double	pu	—	Upper per-unit thermal loading limit for overhead, underground, and triplex lines (VIOLATION1).
line_thermal_limit_lower	double	pu	—	Lower per-unit thermal loading limit for overhead, underground, and triplex lines (VIOLATION1).
node_instantaneous_voltage_limit_upper	double	pu	—	Upper per-unit instantaneous voltage limit for nodes and meters (VIOLATION2).
node_instantaneous_voltage_limit_lower	double	pu	—	Lower per-unit instantaneous voltage limit for nodes and meters (VIOLATION2).
node_continuous_voltage_limit_upper	double	pu	—	Upper per-unit continuous voltage limit for triplex nodes, triplex meters, and commercial meters (VIOLATION3).
node_continuous_voltage_limit_lower	double	pu	—	Lower per-unit continuous voltage limit for triplex nodes, triplex meters, and commercial meters (VIOLATION3).
node_continuous_voltage_interval	double	s	—	Duration a continuous voltage condition must persist before it is recorded as a violation (VIOLATION3).
secondary_dist_voltage_rise_upper_limit	double	pu	—	Upper per-unit voltage rise limit across the secondary distribution system (VIOLATION7).
secondary_dist_voltage_rise_lower_limit	double	pu	—	Lower per-unit voltage rise limit across the secondary distribution system (VIOLATION7).
substation_breaker_A_limit	double	A	—	Minimum trip current for the substation breaker on phase A, used for reverse flow checks (VIOLATION4, VIOLATION5).
substation_breaker_B_limit	double	A	—	Minimum trip current for the substation breaker on phase B (VIOLATION4, VIOLATION5).
substation_breaker_C_limit	double	A	—	Minimum trip current for the substation breaker on phase C (VIOLATION4, VIOLATION5).
substation_pf_lower_limit	double	pu	—	Minimum acceptable power factor at the substation (VIOLATION8).
inverter_v_chng_per_interval_upper_bound	double	pu	—	Upper bound on the per-unit voltage change at an inverter point of connection per interval (VIOLATION6).
inverter_v_chng_per_interval_lower_bound	double	pu	—	Lower bound on the per-unit voltage change at an inverter point of connection per interval (VIOLATION6).
inverter_v_chng_interval	double	s	—	Time interval over which inverter voltage change is measured (VIOLATION6).
violation_flag	set	—	—	Bit-field enabling specific violation checks. See Violation Types.

Violation Types

The violation_flag property is a bit-set that controls which checks are active. Multiple violations can be enabled simultaneously using the | operator in GLM.

Table 2: Violation Flags

Keyword	Bit Value	Description
VIOLATION0	0x00	No violations (default; disables all checks).
VIOLATION1	0x01	Device thermal limit: flags transformers, overhead lines, underground lines, and triplex lines whose per-unit loading exceeds the configured upper or lower thermal limits.
VIOLATION2	0x02	Instantaneous voltage: flags nodes, commercial meters, triplex nodes, and triplex meters whose per-unit voltage exceeds the instantaneous upper or lower bounds at any timestep.
VIOLATION3	0x04	Continuous voltage: flags triplex nodes, triplex meters, and commercial meters whose per-unit voltage remains outside the continuous bounds for longer than node_continuous_voltage_interval.
VIOLATION4	0x08	Reverse flow warning: flags the monitored substation link when reverse current exceeds 50% of the breaker trip limit on any phase.
VIOLATION5	0x10	Reverse flow violation: flags the monitored substation link when reverse current exceeds 75% of the breaker trip limit on any phase.
VIOLATION6	0x20	Inverter voltage change: flags inverters whose voltage change between consecutive inverter_v_chng_interval-spaced timesteps exceeds the configured per-interval bounds.
VIOLATION7	0x40	Secondary distribution voltage rise: flags triplex meters and commercial meters whose per-unit voltage rise across the secondary distribution system exceeds the configured limits.
VIOLATION8	0x80	Substation power factor: flags the substation when the computed power factor ( Re(power_in) / |power_in| ) falls below substation_pf_lower_limit.
ALLVIOLATIONS	0xFF	Enables all violation checks simultaneously.

Output Format

Log File

The log file is a CSV with a comment header followed by one row per violation event:

# file...... <filename>
# date...... <date>
# user...... <username>
# host...... <hostname>
# limit..... <limit>
# interval.. <interval>
# timestamp, violation, observation, upper_limit, lower_limit, object(s), object type(s), phase, message
<timestamp>,<VIOLATION#>,<observed_pu>,<upper_limit>,<lower_limit>,<object_name>,<class_name>,<phase>,<message>
...
# end of file

Summary File

The summary file is a CSV written at the end of the simulation (finalize) containing total violation counts and per-category breakdowns:

VIOLATION1 TOTAL,<count>
    TRANSFORMER (<n> of <total> transformers in violation),<count>
    OVERHEAD LINE (<n> of <total> lines in violation),<count>
    UNDERGROUND LINE (<n> of <total> lines in violation),<count>
    TRIPLEX LINE (<n> of <total> lines in violation),<count>
VIOLATION2 TOTAL,<count>
    NODE (<n> of <total> nodes in violation),<count>
    ...
...
VIOLATION8 TOTAL,<count>

Example

module tape;

object violation_recorder {
    file "violation_log.csv";
    summary "violation_summary.csv";
    virtual_substation "substation_link";
    interval 60;
    violation_delay 300;
    violation_flag VIOLATION1|VIOLATION2|VIOLATION3|VIOLATION8;
    xfrmr_thermal_limit_upper 1.0;
    xfrmr_thermal_limit_lower 0.0;
    line_thermal_limit_upper 1.0;
    line_thermal_limit_lower 0.0;
    node_instantaneous_voltage_limit_upper 1.1;
    node_instantaneous_voltage_limit_lower 0.9;
    node_continuous_voltage_limit_upper 1.05;
    node_continuous_voltage_limit_lower 0.95;
    node_continuous_voltage_interval 300;
    substation_pf_lower_limit 0.85;
    strict false;
    echo false;
}

Notes

• virtual_substation must name a link object (e.g., a transformer or line) whose flow_direction and current_out_A/B/C / power_in properties are readable. VIOLATION4, VIOLATION5, and VIOLATION8 are silently skipped if this property is unset or the object cannot be found.
• All voltage and thermal values are compared in per-unit after dividing by the object's nominal_voltage or continuous_rating. A normalization_value of 0 or 1 causes the raw value to be used directly.
• The first simulation timestep is excluded from dynamic (VIOLATION6) checks; continuous (VIOLATION3) checks can trigger on the first timestep.
• File output is buffered; use flush_interval to control how frequently data is written to disk during long simulations.

Related Concepts

• Tape