Hassayampa (Version 3.0) is the latest release of GridLAB-D.
Highlights
- 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-threading
Multi-threaded support is significantly enhanced.
- Command line
host% gridlabd -T|--threadcount number
- GLM
#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.
- Example
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; }
- Instantiation
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., name.property)
- 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.
- Definition
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
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.
Multi-run
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
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.
Powerworld
TODO:
Control
TODO:
Optimize
TODO:
Communications
TODO:
Debug
TODO:
Mysql
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
- CREATION (default, as prior to Hassayampa (Version 3.0))
- DEFERRED
- BOTTOMUP
- TOPDOWN
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
GUI API
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
- Solver API
- How to create a solver
- Technical manuals
- USE_GLSOLVERS