Model Debugging

The debug option produces all the debugging output from GridLAB-D™. It is managed by the global variable debug, which is by default FALSE.

GLM

The debugger is started when the -debugger command-line option is used. It can also be started by including the line:

# GLM

To enable debug mode use the directive

#set debug=1

To disable debug mode use the directive

#set debug=0

Command line

To toggle debug mode use the option

host% gridlabd --debug

To enable debug mode use the option

host% gridlabd -D debug=1

To disable debug mode use the option

host% gridlabd -D debug=0

in the GLM file. The debugger supports two methods of interrupting the simulation.

The debugger option enables the debugger in GridLAB-D™. To enable the debugger use the command option

host% gridlabd --debugger

1. Breakpoints halt the simulator and start the debugger whenever a situation arises that matches the breakpoint criterion. For example, a breakpoint on the bottom-up pass will stop the simulation every time an object sync is called during a bottom-up pass.

2. Watchpoints are different from breakpoints in that the debugger is only stopped when the value being watched changes. For example, a watchpoint on node:12 voltage would only stop the simulation when the voltage of node:12 is changed. In contrast, a breakpoint on node:12 would stop each time node:12 is sync'd.

While the debugger is running help will print a list of all the available commands.

Getting started

To start the debugger you must include the -debugger option on the command-line. Note that while the debugger is running, the system will only operate in single-threaded mode.

Each time the debugger stops to prompt for input, it displays the current simulation time and simulator status. The status include which pass is currently running (see PASSCONFIG), which rank is being processed, which object is about to be updated, and which iteration is being run (if the time has not advanced yet).

DEBUG: time 2000-01-01 00:00:00 PST
DEBUG: pass BOTTOMUP, rank 0, object link:14, iteration 1
GLD>

Debugging commands may be abbreviated to the extent that they are unambiguous. For example b may be used instead of break, but wa must be used for watch to distinguish it from where.

Listing objects

To obtain a list of objects loaded, you may use the list command:

GLD> list
A-b---    2 INIT                     node:0           ROOT
A-b---    1 INIT                     node:1           node:0
A-b---    1 INIT                     node:2           node:0
A-b---    1 INIT                     node:3           node:0
A-b---    0 INIT                     link:4           node:1
A-b---    0 INIT                     link:5           node:2
A-b---    0 INIT                     link:6           node:2
A-b---    0 INIT                     link:7           node:3
A-b---    0 INIT                     link:8           node:3    
GLD>

You may limit the list to only the object of a particular class:

GLD> list node
A-b---    2 INIT                     node:0           ROOT
A-b---    1 INIT                     node:1           node:0
A-b---    1 INIT                     node:2           node:0
A-b---    1 INIT                     node:3           node:0
GLD>

1. The first column contains flags indicating the status of the object. In the first character:

First Character	Indicates that the object...
A	is active (operating)
P	is planned (not yet operating)
R	is retired (no longer operating) In the second character:
-	is not called on the PRETOPDOWN pass
t	has yet to be called on the PRETOPDOWN pass
T	has already been called on the PRETOPDOWN pass In the third character:
-	is not called on the BOTTOMUP pass
b	has yet to be called on the BOTTOMUP pass
B	has already been called on the BOTTOMUP pass In the fourth character:
-	is not called on the POSTTOPDOWN pass
t	that has yet to be called on the POSTTOPDOWN pass
T	that has already been called on the POSTTOPDOWN pass In the fifth character:
-	is unlocked
l	is locked In the sixth character:
-	the object's native PLC code is enabled
x	the object's native PLC code is disabled

1. The second field is the object's rank.
2. The third field is the object's internal clock (or INIT) if the object has not yet been sync'd.
3. The fourth field is the name (class:id) of the object.
4. The fifth field is the name of the object's parent (or ROOT) if is has none.

Printing values

To inspect the properties of an object, you can use the print command. With no option, the current object is printed:

GLD> print
DEBUG: object link:5 {
  parent = node:2
  rank = 0;
  clock = 0 (0);
  complex Y = +10-1j;
  complex I = +0+0j;
  double B = +0;
  object from = node:0;
  object to = node:2;
  }
GLD>

When an object name (class:id) is provided, that object is printed:

GLD> print node:0
DEBUG: object node:0 {
  root object
  rank = 2;
  clock = 0 (0);
  latitude = 49N12'34.0";
  longitude = 121W15'48.3";
  complex V = +1-0d;
  complex S = +0+0j;
  double G = +0;
  double B = +0;
  double Qmax_MVAR = +0;
  double Qmin_MVAR = +0;
  enumeration type = 3;
  int16 bus_id = 0;
  char32 name = Feeder;
  int16 flow_area_num = 1;
  complex Vobs = +0+0d;
  double Vstdev = +0;
  }
GLD>

Scripting commands

You can run a script containing debug commands using the script command:

GLD> sys copy con: test.scr
wa node:0
run
^Z
1 file(s) copied.
GLD> script test.scr
DEBUG: resuming simulation, Ctrl-C interrupts
DEBUG: watchpoint 0 stopped on object node:0
DEBUG: object node:0 {
  root object
  rank = 2;
  clock = 2000-01-01 00:00:00 PST (946713600);
  latitude = 49N12'34.0";
  longitude = 121W15'48.3";
  complex V = +1-0d;
  complex S = +0.522519+0.0522519j;
  double G = +0;
  double B = +0;
  double Qmax_MVAR = +0;
  double Qmin_MVAR = +0;
  enumeration type = 3;
  int16 bus_id = 0;
  char32 name = Feeder;
  int16 flow_area_num = 1;
  complex Vobs = +0+0d;
  double Vstdev = +0;
  }
DEBUG: watchpoint 1 stopped on object node:0
DEBUG: object node:0 {
  root object
  rank = 2;
  clock = 2000-01-01 00:00:00 PST (946713600);
  latitude = 49N12'34.0";
  longitude = 121W15'48.3";
  complex V = +1-0d;
  complex S = +0.522519+0.0522519j;
  double G = +0;
  double B = +0;
  double Qmax_MVAR = +0;
  double Qmin_MVAR = +0;
  enumeration type = 3;
  int16 bus_id = 0;
  char32 name = Feeder;
  int16 flow_area_num = 1;
  complex Vobs = +0+0d;
  double Vstdev = +0;
  }
DEBUG: time 2000-01-01 00:00:00 PST
DEBUG: pass BOTTOMUP, rank 2, object node:0, iteration 5
GLD>

GDB

When gdb is non-zero, runtime classes are built with debugging enabled and GridLAB-D™ is started inside the host platform's debugging environment. This is specifically to allow user to debug runtime classes.

The gdb option interacts in complex ways with debug, gdb_window, compile_once, and use_msvc. For details, see further documentation on working with MS Visual Studio 2005 in GridLAB-D™. To implement:

host% gridlabd -D gdb=0|1
host% gridlabd --define gdb=0|1
#set gdb=0|1

gdb_window controls the use of the source debugger window for runtime classes. When gdb_window is non-zero, runtime classes are built with debugging enabled and GridLAB-D™ is started inside the host platform's debugging environment using a debugging window. This is specifically to allow users to debug runtime classes using a debugging window. To implement:

host% gridlabd -D gdb_window=0|1
host% gridlabd --define gdb_window=0|1
#set gdb_window=0|1

Runtime Debugger

When the environment variable GRIDLABD_DEBUG is set, the script /usr/local/bin/gridlabd starts the specified debugger and opens the file /usr/local/bin/gridlabd.bin. This enables debugging of your code.

If you enable debugging using debug or by including -g in CXXFLAGS and LDFLAGS then you will be able to set a breakpoint in your runtime code. When the GRIDLABD_DEBUG environment variable is set, the C++ source file is not deleted after the runtime code is compiled. This file can be found in your temporary folder, which is specified by the tmp global variable.

/bin/bash$ export GRIDLABD_DEBUG=debugger

LDFLAGS

#setenv LDFLAGS=g++-command-line-options
/bin/bash$ export LDFLAGS=g++-command-line-options

The default C++ runtime class linker options are as follows:

• -shared: Generate a shared library (always included)
• -m32: Generate 32-bit code (always included on 32-bit GridLAB-D™ versions)
• -m64: Generate 64-bit code (always included on 64-bit GridLAB-D™ versions)
• -lstdc++: Use the standard C++ library (always included)

If debug output is enabled, the -g optional to enable linking with debugging symbols is added automatically. If you wish to enable debugging without debug output generated, you must add the -g option to both CXXFLAGS and LDFLAGS.

LDPOSTLINK

#setenv LDPOSTLINK=command

-or-

/bin/bash$ export LDPOSTLINK=command

Some operating systems require special commands to allow dynamic link or shared libraries to used after they are linked. For example, SELinux requires the following to load a runtime class after it is built and linked.

chcon -t textrel_shlib_t afile

To make this occur before the runtime module is loaded, use

/bin/bash$ export LDPOSTLINK=chcon -t textrel_shlib_t

to cause the command to be executed on every afile created by the runtime class compiler.