From GridLAB-D Wiki
Jump to: navigation, search

 DEPRECATED  The Metronome example is no longer supported.

Installation Notes

  • Note that minimally, the environment variable GLPATH should be set to the directory where GridLAB-D is installed.

If runtime classes are being used, please observe the following.

  • MinGW must be installed (MinGW does not work on 64-bit Windows at this time)
  • GridLAB-D uses the temporary folder HOMEDRIVE\HOMEPATH\Local Settings\Temp\gridlabd to store files associated with runtime classes (source files, object files). This will cause errors if this folder does not exist or you do not have permission to write to this folder. If a different directory is desired for temporary files, the environment variable GLTEMP can be created and its value set to the path to an existing temporary directory you can write to. Alternatively, to set the path to the temporary directory on a case by case basis, the following line of code may be added to each GLM file:
    #set tmp="path to temporary directory"
  • Note that there must be no spaces between "tmp" and "=" and also between "=" and the path.
  • Also note that it is best to enclose the path in double quotes.

Running Simulations

The GridLAB-D software can be run using the command-line or the server mode.

GridLAB-D Command-Line Tool

GridLAB-D takes the path to a GridLAB-D model file (GLM file) as input. For more information about creating GLM files refer to the guide to Creating GLM Files.

An example of the run of the metronome model is presented below:

host% gridlabd metronome1.glm 
GridLAB-D Version 2.00.654 (Diablo)
Copyright (C) 2004-2008
Battelle Memorial Institute
All Rights Reserved

host% more metronome1.csv 
1970-01-01 00:00:00,TIC
1970-01-01 00:00:01,TOC
1970-01-01 00:00:02,TIC
1970-01-01 00:00:03,TOC
1970-01-01 00:00:04,TIC
1970-01-01 00:00:05,TOC
1970-01-01 00:00:06,TIC
1970-01-01 00:00:07,TOC
1970-01-01 00:00:08,TIC
1970-01-01 00:00:09,TOC
1970-01-01 00:00:10,TIC

If you don’t get the expected result, make sure your GridLAB-D system is properly installed and make sure you didn’t make any typographic errors if you entered the code by hand. A useful tool for editing and running GLM files is Notepad++. This editor allows syntax highlighting for custom languages and also contains a plug-in called NppExec, reducing the process of running GridLAB-D on a GLM file to a few key presses.

Syntax Highlighting

The syntax highlighting rules for C++ work well for GLM files. To set the syntax highlighting language, click Language -> C -> C++. The current syntax highlighting rules are available in the SourceForge repository for the file gridlabd.syn. A more complete, custom set of syntax highlighting rules is being developed and will be available soon. To import these settings, click View -> User-Defined Dialogue.... In the Window that pops up, click Import... and select the file from above. To apply these settings to a file click Language -> GLM. Note that for files with the ".glm" extension, these syntax highlighting rules will be applied automatically.


The plug-in NppExec allows the user to run console commands from within Notepad++. To install this plug-in click Plugins -> Plugin Manager -> Show Plugin Manager. In the window that pops up, click on the Available tab and find the NppExec plug-in from the list. Click the check-box next to NppExec and then click Install. Once NppExec is installed click Plugins -> NppExec -> Execute. In the Execute... window, type the following command:

cmd /c cd "$(CURRENT_DIRECTORY)" && "gridlabd.exe" "$(FULL_CURRENT_PATH)"

This command will change to the directory of the currently opened file, then run GridLAB-D with the current file as input. Next, click Save..., type in "GridLAB-D" as the script name, and click Save again. To run the command on the currently opened file click OK. To subsequently run this command, simply click F6, select the correct script, and click OK. To run the same script that was previously run, simply click Ctrl + F6. GridLAB-D will be executed, with the current file as input and the output will be shown on a console window at the bottom of the Notepad++ window.

It is useful to define several such scripts, for example, to run GridLAB-D with verbose output:

cmd /c cd "$(CURRENT_DIRECTORY)" && "gridlabd.exe" -v "$(FULL_CURRENT_PATH)"

or to print profiling information:

cmd /c cd "$(CURRENT_DIRECTORY)" && "gridlabd.exe" --profile "$(FULL_CURRENT_PATH)"

or to redirect output:

cmd /c cd "$(CURRENT_DIRECTORY)" && "gridlabd.exe" --redirect all "$(FULL_CURRENT_PATH)"

Each of these commands can be saved and the appropriate command can be selected from the Plugins -> NppExec -> Execute... window.

To further speed things up, another option may be enabled which automatically saves the current file before executing the command. To toggle this option click Plugins -> NppExec -> Save all files on execute.

Command Line Arguments

The command-line argument module processes arguments as they are encountered.

The following command-line toggles are supported

  • --warn toggles the warning mode
  • --check toggles calls to module check functions
  • --debug toggles debug messages
  • --debugger enables the debugger and turns on debug messages
  • --dumpall toggles a complete model dump when the simulation exits
  • --quiet toggles all messages except error and fatal messages
  • --profile toggles performance profiling

The following command-line processes can be called

  • --license prints the software license
  • --dsttest performs a daylight saving time definitions in tzinfo.txt
  • --unitstest performs a test of the units in unitfile.txt
  • --randtest performs a test of the random number generators
  • --testall file performs module selftests of modules those listed in file
  • --test run the internal core self-test routines
  • --define define a global variable
  • --libinfo module prints information about the module
  • --xsd module[:object] prints the xsd of a module or object
  • --xsl creates the xsl for this version of gridlab-d
  • --kml=file output kml (Google Earth) file of model
  • --modhelp module[:class] output definition of class from module. All the classes from the specified module will be listed in alphabetical order if no class is given
  • --server runs in server mode (uses pidfile and redirects all output)
  • --pidfile[=filename] creates a process id file while GridLAB-D is running (default is
  • --redirect stream[:file] redirects output stream to file

The following system options may be changed

  • --threadcount n changes the number of thread to use during simulation (default is 0, meaning as many as useful)
  • --output file saves dump output to file (default is gridlabd.glm)
  • --environment app start the app as the processing environment (default is batch)
  • --xmlencoding num sets the XML encoding (8, 16, or 32)
  • --xmlstrict toggles XML to be strict
  • --relax allows implicit variable definition when assignments made

GridLAB-D Server Mode

The server mode was introduced in version 2.0 as a supporting feature of the Realtime server. Currently, the server mode is used in the gui development work. The implementation of server mode is done in core/server.c file.

The server mode allows a web-based application to access the global variable and properties of named objects.

To start GridLAB-D in server mode, simply include the command line argument --server, e.g.,

host% gridlabd modelname.glm --server

The port used in server mode is 6267 and was assigned by Internet Assigned Numbers Authority (IANA) in December 2010. . It can be change in a GLM file using the directive

#set server_portnum=6267

To get the value of a global variable, use the following query

host% wget http://host.domain/variable-name -q -O -

To get the value of an object property, use the following query

host% wget http://host.domain/object-name/property-name -q -O -

To set the value of an object property, use the following query

host% wget http://host.domain/object-name/property-name=value -q -O -

The value can include units (separate by a space) and they will be converted automatically. The value is read back after it is set to confirm that it was accepted (including unit conversion).

When server mode is used for running GridLAB-D, the following steps are performed:

  • start up server environment and the server
  • create a new socket
  • bind the socket to the server address
  • server listens to the port for connections
  • accept client request and get its address; functions that receive and send data from/to the client are included in this procedural step.
  • process client's request;
The client's request falls in one of the categories: "/xml/...", "/runtime/...","/gui/...", "/output/...", "/action/...", "/rt/...", "/perl/...", "/gnuplot/...", "/java/...", "/python/...", "/r/...", "/scilab/...", "/octave/...".
For instance, read and write any global or object property can be done as follows:
  • send the results back to the client.
  • shutdown server when done or connection lost.

Running server-side scripts of various types is also an available feature of GRIDLAB-D server mode. The general syntax is http://localhost/language/script-name, where language is r (extension .r), scilab (extension .sce), perl (extension .pl), python (extension .py), octave (extension .m), java (extension .jar), gnuplot(extension .plt). The set of available languages will be soon expended even more.
Retrieve output files, such as CSV files, is also available in GRIDLAB-D server mode by using the syntax http://localhost/output/filename.ext.
The work done for the gui capability enables generation of HTML code by using the syntax http://localhost/gui/pagename.ext.

All the features presented above are in early stages of development and under constinuous improvement. Example of concept tests are presented in core/test/gui_example.... The examples are not fully functional at this point because we are trying to understand the limitations of each on various platforms.

Level 1 Requirements

All Level 1 requirements require Project Manager approval to be adopted.

Platforms supported

The server mode shall be accessible on all the existent platforms (i.e., Windows, Linux, Mac).

Presentment encoding

The server mode layout shall be encoded so that it is driven by the GLM file. Ancillary files may be referenced by the GLM file.

Input entities

All server mode input entities functionality shall be implemented by the core.

Output entities


Client/server model

A client/server model over a TCP port registered with IANA is used.

Communication protocol

The server shall support HTTP 1.1 traffic according to RFC2616. All major clients conforming to HTTP 1.1 shall be supported.

Level 2 Requirements

Level 3 Requirements

Level 4 Requirements