From GridLAB-D Wiki
Jump to: navigation, search

Hassayampa (Version 3.0) is the latest release of GridLAB-D.


Now supported fully on multiple platforms
  • Windows (32/64)
  • Linux (32/64): Redhat, Fedora, Ubuntu, etc.
  • Mac (64 only)
New modules
  • Transmission grids
  • Communications
  • Controls
  • Optimizers
  • Matpower Integration (Optimal Power Flow)
Key new capabilities
  • Multithreading supported
  • Matlab Link
  • Graphic User Interface API available

New Command options

Working directory

The working directory can be controlled directly from the command line.

Command line
host% gridlabd -W|--workdir path
  • Takes effect immediately (can be used several times)
  • Does not affect parent shell/process

Platform validation

Validation can now be done using the gridlabd command itself. The python script is obsolete as of Hassayampa (Version 3.0).

Command line
host% gridlabd --validate [...]
  • Runs GLM files in autotest folders in the working folder.
  • Options before --validate are used by validate job
  • Options after --validate are passed to each run
  • Output report goes to validate.txt

Job control

Job are collections of GLM files that must be run together.

Command line
host% gridlabd --job [...]
  • Runs GLM files in the working folder.
  • Options before --job are used by job controller
  • Options after --job are passed to each run


Multi-threaded support is significantly enhanced.

Command line
host% gridlabd -T|--threadcount number
#set threadcount=number
  • Use in GLM discouraged but sometimes necessary
  • Threadcount = 0 means use all available processors
  • Most core loops are now multithreaded
  • Module programmer’s caveat:
  • Module object locking is now mandatory (PC_AUTOLOCK)
  • Although R/W locks are distinct there is no difference yet

Process control

A process control window is now available.

Command line
host% gridlabd --pcontrol
  • Uses a “curses” interface (new in C++ Programmer's API)
  • Show which gridlabd jobs are using which processors
  • Allows you to “kill” a job by sending it an interrupt signal (looks like you hit Ctrl-C).
  • In most cases a killed job will stop and shutdown normally.

Sanitizing models

Models can be sanitized by obfuscating names and positions so that proprietary or sensitive utility data can be protected.

Command line
host% gridlabd --sanitize
  • Modifies object headers in memory from that point on
  • Options include:
    • Changing obfuscated name prefix (sanitize_prefix)
    • Limited sanitizing to name or location only (sanitize)
    • Choosing index file format & name (sanitize_index)

New help options

Advanced help features make getting information easier.

Examples of objects
Command line: gridlabd --example module:class
  • Outputs the default values for all properties
Topic info/help
Command line: gridlabd --info keyword
  • Opens a browser and searches online wikis for topic

GLM Syntax Enhancements

Timezone/city support

Locale names can be used instead of timezone specs. Locale names are listed in tzinfo.txt. Format of locale is CC/SS/City.

clock {
  timezone US/WA/Yakima;
  • City name alone can be used
    • Caveat: ambiguity is not detected or resolved
  • Foreign countries are now supported
  • Start and end time defaults
  • Simulation start and end time now have default values.
    • The default start time is now 1/1/2000 0:00:00 local time
    • The default end time is one year after the start time

Random variables

Random variables change value periodically.

Declaration (runtime class)
class my_class {
  random my_variable;
object my_class {
  my_variable "type:dist(args,...); refresh:dt; min:value; max:value; state:seed";

Double and complex arrays

Double and complex array data are now supported

GLM syntax
double_array “var00 … var0M ; … ; var N0 … varNM”;
complex_array “var00 … var0M ; … ; var N0 … varNM”;

Variables may be

  • Numbers (double or complex)
  • Properties of other objects (i.e.,
  • Globals (i.e., name)

New C++ API supports many (in-place) vector/matrix ops

External transforms

External functions may be use to implement transforms.

GLM transform definition
extern "C" library_name:function_name_1[,function_name_2[,...]]; 
extern "C" library_name:function_name_1[,function_name_2[,...]] { /* C code */ }
GLM transform usage
object my_class {
  property function_name(arg1,arg2,...,argN);

The first form links an external library you compile separately. The second form links a runtime library created from the code you provide.

The function calling convention is similar to Matlab’s MX convention, e.g.,

int function(nrhs, prhs, nlhs, plhs)

General purpose asserts

Assert now support a general purpose assert object than can examine any property type. Comparison operations are based on property type.

class assert {
	enumeration {NONE=3, FALSE=2, TRUE=1} status;
	char1024 target;
	char32 part;
	enumeration {outside=7, inside=6, !==3, >==2, >=5, <==1, <=4, ===0} relation;
	char1024 value;
	char1024 within;
	char1024 lower;
	char1024 upper;

External application link

Link directives establish a synchronization link between GridLAB-D and an external application.

GLM directive
link control-file;

Link directives are application specific, e.g., Matlab:


Scripts allow modelers to run external commands before, during, and after a simulation.

GLM directive
script [on_{create,init,sync,term}] command; 
  • Without on_* script is run immediately during load
  • With on_* script is run when the event occurs
  • If the command returns a non-zero exit code, the simulation stops and returns that exit-code

Note: The #system macro ignores the exit code but saves it in the return_code global variable.


Multiple GridLAB-D models can be loosely coupled and run as a single simulation.

GLM syntax
instance hostname {
  model slave.glm;
  cacheid id; 
  mode connection-mode;
  execdir dir;
  return_port port-num;
  local-object:property -> remote-object:property; 
  local-object:property <- remote-object:property; 


Checkpoints are now supported.

#set checkpoint_file=“savefile”
#set checkpoint_keepall=FALSE
#set checkpoint_interval=3600 
#set checkpoint_type=WALL
  • Checkpoint interval can be wall or sim clock interval
  • Checkpoint images can be very large files
  • Checkpoint images loaded using --stream command option

Modules introductions/upgrades

Residential appliances

A general residential appliance model is now available

object appliance {
	durations “array”;
	transitions “array|matrix”;
	powers|currents|impedances|heatgains “array”;
  • Durations/transitions define a general state machine
  • Transition is probability of state change during duration
  • Powers, etc. define updates to enduse data.












Classes are compatible with tape module classes. Module directives establish default connection. Database object allows multiple server connections:

module mysql;
object database {
	// (...mysql connection info goes here)
	on_init file-name;
	on_sync file-name;
	on_term file-name;
	sync_interval seconds; 

Programmers’ Tools

Object heartbeat

An object heartbeat allows it receive a regular opportunity to post synchronization requests time without using a sync call.

  • New object header property
  • Value is a time interval (in seconds).
  • Causes EXPORT TIMESTAMP heartbeat_class(OBJECT *obj) to be called at the specified time interval
  • The return value is considered for the next sync time

Property/global access control

Properties can be hidden from users (PA_HIDDEN)

Enhanced initialization sequence

Deferred initialization is now permitted. Initialization sequence is controlled by a global

#set init_sequence=sequence_type
Sequence types

Exit codes

All gridlabd exit codes are harmonized

  • 0-126 normal exit codes
  • 127 shell error (usually command not found)
  • 128-255 exception/signal exit codes
  • -1 system error (usually memory error or wait error)

Validate and job rely on these codes to control runs

C++ programmer’s API

Implemented in gridlabd.h. Many new classes are implemented by the Module API, notably:

“Curses” API

Implements basic curses library functions on all platforms, including Windows. Can be used either in core or in modules

#include “console.h” // core usage

- or –

#define CONSOLE
#include “gridlabd.h” // module usage

Limited curses functionality available on Windows. For details, see any curses manual. Examples: setup, debug, pcontrol


Running gridlabd without a GLM starts web GUI. Browser loaded if gridlabd.htm is found in GRIDLABD path. Server mode starts and browser connects to server. Only API — gridlabd.htm is not distributed with gridlabd download from SourceForge.

General solvers API

Requires definition of a solver data structure. Allows solvers to be initialized and feature/parameters to be set. Solver can be called repeatedly and it is re-entrant. See

See also