From GridLAB-D Wiki
Jump to: navigation, search

 TODO:  This page needs to be converted to use headings instead of a wikitable.


GridLAB-D is a flexible agent-based simulator that can model the behavior of many objects over time. The simulator looks for changes in objects that affect other objects and keeps track of the evolution of these objects over time. GridLAB-D will continue advancing the clock and allowing objects to update themselves until all the object report that they are at equilibrium and the clock need not be advanced further. This is very important to understand and is often one of the least understood aspect of GridLAB-D.


GridLAB-D uses modules to define classes of objects. Each class must be defined in a module. Modules can either be static, meaning they are implemented in a .dll library (.so in Linux, .dylib in Mac OS X), or they can be dynamic, meaning they are compiled and linked at runtime. Classes define which properties are allowed in objects, and how behaviors are implemented. Objects are instances of classes, so each object can have its own value for each property, but GridLAB-D will make every attempt to keep the objects synchronized with each other as time advances.


GridLAB-D Input Files
GridLAB-D uses either GLM (GridLAB-D Model) or XML (Extensible Markup Language) as input files:
.glm files are used primarily to synthesize populations of objects and encode object behavior
.xml files are used to represent instances of .glm files and exchange data with other software systems.

In general .xml files will work best with static modules that can be loaded from pre-existing libraries (.so files in Linux), while .glm files do not require static modules. In other words, we will describe models using the .glm file format and reserve .xml for two main functions:

  1. viewing output results,
  2. exchanging data with other tools.

Consider a simple example. We need to define an object of a class we call myexample, each instance of which has a single real number we call myvalue, where the number has a normal distribution with mean of 100 and standard deviation of 1. Compare the GLM object definition

 // GLM object example  
 object myexample {
   myvalue random.normal(100,1);
 };

with the XML code that might be generated after loading it

 <myexample>
   <myvalue>108.2</myvalue>
 </myexample>

The GLM file described the property myvalue as having a random value. If you were to run GridLAB-D multiple times using this object description, each time you would see a different value, but overall the values would have a mean of 100 and standard deviation of 1. In contrast the XML file simply describes one realization of that object and each time you load the XML you will get the same value. The information about randomness is lost in the XML file, but repeatability of the results is gained. Therefore, you should exercise care and use the appropriate type of files depending on the task you need to accomplish. In general, model exchange will require XML files and stochastic (or Monte Carlo) studies will require GLM files.



GridLAB-D Output Files

GridLAB-D can output result one of two ways:

  • use the -o myfile.xml command line option to generate an instance of the model at the end of simulation. For more information on .xml output, see the XML Data Files page.
  • use the tape module's recorder and collector objects to generate a time-series of particular values or aggregate values over the entire model. For more information on this see Tape Module Guide page.


Terminology

In practice, GridLAB-D concerns itself with modeling in the context of GLM files, using objects, the class of each of those objects, and the DLL modules that registered those classes:

  • Objects describe specific instances of a thing that can respond to and/or act on other objects. A simulation can contain very many objects. It is not uncommon to see a model that contains thousands of objects. Some of the large GridLAB-D models have been built that contain well over 100,000 objects.
  • Classes are used to group object according to similar properties and behavior. In general we define a class of objects that are similar in structure, but we instantiate objects that exhibit specific properties. For example, according to the Department of Motor Vehicles a person has a name, birth date, height, weight, age, eye and hair color all of which are associated with their driver's license number. This collection of information is the same for all drivers. So a person is a class. John Q Smith, born on May, 1968, who is 6'2", 200 lbs, 32 years old, brown hair and brown eyes and has driver's license number "SMITHJQ325KE" is an instance of that class.
  • Modules define many classes in a single quick and convenient directive. Modules are not like class definitions that you give as a directive because they are not compiled when GridLAB-D is run. Instead, developers package a collection of classes and distribute a dynamic link library (as a .dll file in Windows or .so file in Linux). Static modules must be loaded before the classes they define can be used or modified (i.e. use module name;)

Module blocks may include additional information, such as assignments of the values for module globals and specification of the version number. To set a module global variable, simply include the name and value in the module block, such as

 module MyModule {
   MyStringGlobal "value";
   MyEnumGlobal A;
   MyDoubleGlobal 1.2 ft/s;
 }

To enforce verification of the module's version information, simply include the desired version in the module block:

 module MyModule {
   major 2;
   minor 1;
 }

If the version loaded is not version 2.0 or greater, an error will be displayed and the loader will stop. The minor and build numbers can also be specified, if necessary.

Class blocks are used to create, modify, or verify class definitions. If a class is already defined in a static module, then a class block either modifies or verifies the definition provided by the module. Consider the following example

 module MyModule;
 
 class MyClass {
   char32 svalue;
   enum {A=0,B=1,C=2} evalue;
   double dvalue[W];
 }

If the properties svalue, evalue, and dvalue are already defined as specified, the class block will load successfully. However, if there are any differences between the class block and the module's definition of the class, then the loader will attempt to address the discrepancy as follows:

  1. If the class defines a property differently than the module, then the loader will fail.
  2. If the class defines a property that the module does not define, then the loader will extend the module's definition of the class to include this new property.
  3. If the class is not defined by any loaded module, then the class is defined as a new class, and the properties are added to that new class. In this case, you may also include C++ code for the behaviors that static modules normally provide. See below for more information on runtime classes.




Commands The machine where GridLAB-D is installed is called the host computer. To use GridLAB-D you have several options:
  • log in directly on the host computer,
  • use a client application on your computer to connect to a server computer that hosts the simulation,
  • run a simple web browser that serves a web-based client application that in turn connects to the simulation either on the web-server or to a third computer that hosts the simulation.

To see what version of GridLAB-D is installed, type:

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

host% 

Note
The host% refers the command shell prompt, which indicates that you are logged in on the host computer where GridLAB-D is installed. It will probably look different on your computer—on Windows machines it’s usually C:\> and sometimes it’s simply $ on Unix machines.

To get a list of commonly used command lines options, you can enter the following:

host% gridlabd –-help
Syntax: gridlabd [OPTIONS ...] <file> ...
Options:
(...lots of helpful output...)

The command line options are used to alter the mode of operation of GridLAB-D. The normal setting for a mode of operation is called the default, and command line options are one way to override those defaults. For example, GridLAB-D can be instructed to describing everything it is doing using the verbose mode:

host% gridlabd --verbose
GridLAB-D Version 2.00.654 (Diablo)
Copyright (C) 2004-2008
Battelle Memorial Institute
All Rights Reserved
    ... starting up batch environment
    ... initializing objects...
    ... creating index 0
    ... creating index 1
    ... creating index 2
    ... shuffled -10 lists in index 0
    ... shuffled -10 lists in index 1
    ... shuffled -10 lists in index 2
    ... detected 8 processor(s)
    ... using 1 helper thread(s)
    ... simulation at steady state at INIT
    ... shutdown complete
    ... elapsed runtime 0 seconds



Models handling

This section describes how to create a GridLAB-D model and examine the output it produces when it is loaded and run.
A GridLAB-D model can be stored in either GLM or XML files, often with other files around to help define simulation boundary conditions and provide needed supporting data. In your editor type the following (or copy it from the website):

// file: examples/metronome1.glm
class metronome {
        double bpm; // beats per minute
        int16 count; // beats left
        enumeration {TIC=0, TOC=1} side;
        timestamp last_t;
        intrinsic create (object parent) { 
                last_t = gl_globalclock; 
                return SUCCESS;
        };
        intrinsic sync (TIMESTAMP t0, TIMESTAMP t1) {
                TIMESTAMP next_t = (TIMESTAMP)(last_t + 60/bpm);
                if (t1==next_t) {
                        side = (side==TIC) ? TOC : TIC;
                        last_t = next_t;
                        count--;
                }
                return count>0 ? (TIMESTAMP)(last_t + 60/bpm) : TS_NEVER;
        };
};
module tape; // loads the tape module
object metronome {
        bpm 60;
        count 10;
        object recorder {
                property side;
                file "metronome1.csv";
        };
};

Explanation of the model file:

  • The class metronome is defined and contains six directives that provided two types of information about the class:
    • the first four are properties (he beats per minute (bpm), the number of beats (count), the current beat (side) and the time of the last beat (last_t))
    • the last two entries are behaviors (create and sync behavior). Create behavior is run whenever an object is created, while synchronization behavior is called when the simulation clock changes or an inconsistency between two or more objects is observed.
  • The directive module tape loads the tape module. This is a data collection and tape playing module. The module implementation is found by searching the current folder, the folder where the gridlabd executable was found, and the folders specified in GLPATH environment, in that order. The first instance of a dynamic link library matching the module name (with extension .dll in Windows or .so in Linux) is used.
  • An object definition always includes property values, but sometimes it can also include nested objects. In this example, only two of the metronome class’s properties are set: the bpm property is set to 60 and the count property is set to 10. The third entry is the nested object - a recorder. By nesting the recorder, a parent-child relationship is established (the metronome is the parent object and the recorder is the child object). By specifying property side, the recorder object is instructed to gather only the value of the side property of the metronome object. The file property instructs the recorder to deliver the observed values of side to a file called "metronome1.csv".
Note
The output of a recorder object is normally in the form of comma-separate value file (CSV). This is the format that many programs and applications use to exchange simple tables of column-row oriented data. GridLAB-D will always outputs the date and time of the observation (in simulation time), followed by the observed value(s). Each observation event is placed in a separate row, so that they file is a complete time-series record of the changes in the observed value as the simulation advanced the clock.


To run your first metronome simulation, type the following (GridLAB-D always assumes that you are using GLM files):

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.

On most systems, you will see extra information about the recording output before the data. Each piece of information is preceded by a ‘#’ character to indicate that it is not part of the recording itself but simply meta-information to describe the recording. In the above example, the recorder object is nested within the metronome object. This is a convenient way to indicate that the recorder depends on the metronome for the property it records. This implied relationship is the parent-child relation.

Another way to specify such a relationship is the give the metronome a name and reference it from the recorder, as in

object metronome {
        name MyMetronome;
        bpm 60;
        count 10;
};

object recorder {
        parent MyMetronome;
        property side;
        file "metronome.csv";
};

In this case, the recorder is explicitly referring to the metronome as its parent by name. It is using this mechanism that you can link objects together across multiple model files.

The parent relationship has an impact on how sync calls are made, so often it’s not appropriate to use it. If you want to reference an object without using the parent relationship, then you can explicitly declare an object in the class definition:

class metronome {
        object room; // the room in which the metronome is located
        // ... rest of class declaration
};
class room {
        // ... rest of room declaration
};
object room {
        name MyRoom; // the name of the room
        // ... rest of room definition
};
object metronome {
        room MyRoom; // reference to the room
        // ... rest of metronome definition
};



Date and time

Date and time specifications are used for a lot of things in GridLAB-D. Dates and times are always specified using the ISO (International Standard Organization) standard format, which is "YYYY-MM-DD HH:MM:SS ZZZ". If you omit the time zone specification, then the current time zone is used.

Time zones are specified in the time zone file timezone.txt file that is installed with the system in the etc folder. GridLAB-D does not use the operating system’s time zone specifications for several reasons:

  • some operating systems don’t recognize time zone that are historical but no longer used,
  • the simulation often needs to run the simulation in a different time zone than that used by the host computer,
  • the ability to use alternate time zone rules is essential to understand the energy use implication of altering the time zone rules, something which policymakers have an interest in and sometimes ask.

GridLAB-D can address these questions only if the rules for the simulation are different from the rules on the computer on which the simulation is running.

Let us consider the following example:

clock {
        timezone PST+8PDT;
        timestamp '2000-01-01 00:00:00';
}

The simulation started on January 1, 2000 at midnight, as specified by the timestamp statement in the clock directive and the timezone directive caused the simulation to operate in the Pacific time zone (which is 8 hours west of GMT) and with daylight savings time enabled.



Disabling and enabling objects

It is possible to have an object come into existence at a pre-determined date and time, and have it cease to exist at some time later. Each object has a pair of built-in property called in and out that determine when the object enters service and when to go out of service.

In the following example, we modify metronome1.glm to illustrate how the in property functions. The bold text indicates what has been added or changed, and strikeout indicates what has been removed.

// file: examples/metronome12.glm
clock {
        timezone PST+8PDT;
        timestamp '2000-01-01 00:00:00';
}
class metronome {
        double bpm; // beats per minute
        int16 count; // beats left
        enumeration {TIC=0, TOC=1} side;
        timestamp last_t;
        intrinsic create (object parent) { 
                last_t = gl_globalclock; 
                return SUCCESS;
        };
        intrinsic sync (TIMESTAMP t0, TIMESTAMP t1) {
                if (last_t==0) last_t = gl_globalclock;
                TIMESTAMP next_t = (TIMESTAMP)(last_t + 60/bpm);
                if (t1==next_t) {
                        side = (side==TIC) ? TOC : TIC;
                        last_t = next_t;
                        count--;
                }
                return count>0 ? (TIMESTAMP)(last_t + 60/bpm) : TS_NEVER;
        };
};

module tape;
object metronome {
        in '2000-02-01 09:15:00 PST';
        bpm 60;
        count 10;
        object recorder {
                property side;
                file "metronome12.csv";
        };
};

Running metronome2.glm give the following result:

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

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


The addition of the in directive in the metronome object caused the simulation to delay updates of the metronome until it was turned on February 1st at 9:00 AM. From that point on the simulation worked as before.

You will note one important change in the way the metronome is created and run. The initial value of last_t is no longer set in the create function. This way the sync function could use it to detect that the object is being synchronized for the first time after being brought into service and set last_t appropriately. This is a common practice. If we had left last_t’s initialization in create, the simulation would have an inappropriate value for last_t when sync was called and the algorithm for determining next_t would have to take into consideration the possibility that last_t is very much older than the current clock time.



Comments Comments begin with a // sign. All text between the // and the end of the line is ignored by the parser.

It is important to note that the parser in GridLAB-D is quite primitive and may in certain circumstance be confused by // appearing in other contexts, such as a URL not enclosed in a quotes.



Macros The .glm loader allows the use of macros to control the behavior of the parser and to a limited extent also the behavior of GridLAB-D. Macros are lines that begin with a '#' sign. The following macros are available:
  • #define name=value is used to define a global variable. This allows the creation of a new global variable, in contrast to the #set macro which requires the global variable already exist.
  • #set name=value is used to set a global variable. For a list of defined global variables, see the [Doxygen Documentation].
  • #undef is used to remove the definition of a global variable.
  • #if[[n]def] <expression>
    ...
    [#else
    ... ]
    #endif is used to conditionally process a block of text in the .glm. For #ifdef and #ifndef the expression is simply the name of a global variable. When #if is used, the expression is a conditional test in the form of name op value where the operator op is one of <, >, &lt=, >=, ==, or !=.
  • #include file is used to include text from file in the loaded text.
  • #print name is used to display the value of the global variable <name> at the moment it is encountered by the loader.
  • #ifexist file is used to determine whether a file exists
  • #include file is used to include another file during the parser load
  • #setenv name=string is used to set an environment variable
  • #binpath path sets the path for binary searches (compiler PATH environment)
  • #libpath path sets the path for library seaches (compiler GLPATH environment)
  • #incpath path sets the path for include file searches (compiler INCLUDE environment)
  • #error message triggers a parser error condition
  • #warning message triggers a parser warning condition