Simulation Options

This page outlines the different ways to run GridLAB-D™, using either the command line or server mode. The various command line options available to users are described, with look-up tables provided for easy reference.

Installation Notes

* For installation instructions, refer to the [Installation Guide](../../2.0%20-%20New%20Users/2.1%20-%20Installation%20Guide.md).

• 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.

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.

NppExec

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 options are supported

The following command-line processes can be called

host% gridlabd --libinfo|-L module_name

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:

• global property read uses the syntax <http://localhost/xml/property-name>.

• write uses the syntax <http://localhost/xml/property-name=value>.

• object property read uses the syntax <http://localhost/xml/object-nameproperty-name>.

• write uses the syntax <http://localhost/xml/object-name/property-name=value>.

• 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.

http://server:port/java/filename.jar

http://server:port/octave/filename.m

To 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.

Control

When operating in server mode, GridLAB-D™ accepts main loop state control messages from HTTP clients connected on the server's port. All control messages are in the form of HTTP 1.1 requests with the standard query format:

 http://server :port /control/command

The following control actions are recognized:

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

Exit Codes

The GridLAB-D™ core solver and most GridLAB-D™ modules use the following exit code:

• -1 exec failed
• 0 success
• 1 bad command line
• 2 environment startup failed
• 3 test failed
• 4 user rejected terms of use
• 5 simulation did not complete as desired
• 6 initialization failed
• 7 process control error
• 8 server killed
• 9 I/O error
• 127 shell failure
• 128-254 signal received (low order bits are signal number)
• 255 exception caught