User's Manual

1.0 About GridLAB-D

Version:
1.0 Allston, release in January 2008 includes the main GridLAB core, a powerflow module based on Kirsten's forward-backsweep method, and a residential module based on the equivalent thermal parameters (ETP) method. This is a limited release for the partners that will help produce the Version 1.1 release.

1.1 Buckley, release April 2008, includes java module link and additional objects in existing modules.

2.0 Installation

2.1 Windows installation

Todo:
Describe Windows installation method. (doxygen, high priority) (ticket #153)

2.2 Linux installation

To build the Linux version, download the source code to a folder of your choosing and type make install. This will install GridLAB-D in the /usr/local folder and make it available for use by all users.

3.0 Running GridLAB-D

GridLAB-D is run from the command-line using the following syntax: 
	gridlabd.exe options filename ...
The valid options are listed is the Command-line Arguments. A list of parameters can also be displayed by using the –-help command-line parameter.

The filename parameter is the name of one or more model definition input files to load. By convention, model definition input files are given the extension .glm (see Model Definition).

4.0 Model Definition

This section describes the modeling language used by GridLAB-D to define power and load models. The model definition is stored in a file with an extension of .glm. There are three main declaration blocks that may be defined in a model definition file:

Of these, only module and object declarations are required. Additionally a class block may be provided to enforce modeling consistency.

Comments within the model file are introduced using a hash (#) character. All text between a hash mark and the end of a line is ignored.

A number of sample model definition files are included with the GridLAB-D distribution.

4.1 Clock definition

The clock is used to specify the simulation start time and the clock resolution. The clock declaration typically looks like this: 
clock {
	tick double;
	timestamp [int64[s|m|h|d] | 'timestamp'];
	timezone std[+|-]hh[:mm[:ss]][dst];
}

If unspecified, the clock is initialized to zero, which starts the clock on Jan 1, 1970 GMT.

Multiple clock blocks may be specified. The effect of each clock is to set the initial clock value of any object subsequently defined to the timestamp given. This can be used to create an initially unsynchronized model and should be used with great caution.

4.2 Module block

The modules block loads and configures modules that will be used in the simulation and allows exposed properties of those modules to be set. The currently supported GridLAB-D modules include:

Additional modules may be added. The module names correspond to .dll names (Windows) or .so (Linux) that are distributed with GridLAB-D.

A module declaration typically looks like this: 

module module_name {
	property value;
}

Where property is a variable supported by that module and value is the value to which the property should be initialized at the start of the simulation. Property values must be one of the defined formats outlined in Section 4.4, Properties.

Modules can be declared without initializing any properties by omitting the bracketed section above and adding a semi-colon after the module name. The following example shows what a modules section might look like: 

# modules
module gauss_method {
	acceleration_factor 1.4;
	convergence_limit 0.001;
}
module tape;
module climate;
module commercial;

4.3 Objects

A model consists of instantiations of objects that are supported by the modules listed. For example, the power flow model might define as a series of node, link, capbank, fuse and regulator objects. The residential model may be defined as a series of residences, refrigerators, and water heaters. This section describes the format of the object definitions. See Sections __ through __ for specific objects and their properties supported by each module.

Todo:
provide detailed object property sections for users. (doxygen, high priority) (ticket #154)
An object definition is required for each object created. An object declaration might look like this: 
object <class>:<int> {
	[root | parent [<class>:<int> | <object.name>];
	clock [<int64>[s|m|h|d] | '<timestamp>'];
	latitute <latitude>;
	longitude <longitude>;
	in '<timestamp>';
	out '<timestamp>';
	name <string>;
	...
}

<class>:<int> refers to an object by specifying a class supported by one of the modules included in the modules section of the module definition file. The <int> id is a positive 32-bit integer that must be unique for the entire model, but not necessarily sequential. The object id can be specified as a range, such as 12..18 to construct multiple objects in a series. If the first number is left out, then the second number is used as a count of how many objects are created. For example, an id of ..19 will construct 19 separate objects.

Properties for different objects are described in subsequent sections. However, some properties are attributes of all objects. These attribute properties include:

The parent property can be specified as <class>:*, which has the effect of using the first as-yet childless object with that name. This is typically used in conjunction with multiple object ids (see above). For example, the following declaration will create one node object, 10 office objects, and 10 recorder objects. The office objects will all have the same parent (node:1) but the recorder objects will each have a different parent (office:1 through office:10). Once the office objects are assigned as parents to the recorder objects, the office:* nomenclature cannot be used to assign those same office objects as parents to other objects (i.e. they are no longer unreferenced). 

object node:1 {
	type 3;
	name "Feeder";
}

object office:1..10 {
	parent Feeder;
}
object recorder:..10 {
	parent office:*;
}

Additional properties that are supported by each object can be set. For the specific properties that are supported by an object, see Section ___ or consult the documentation for that module.

Todo:
provide a link to the documentation for the properties of each module (doxygen, high priority) (ticket #155)

4.4 Properties

This section describes the properties supported by the version 1.0 GridLAB-D modules and their corresponding objects. Property values can be specified as a number, a string, a date and time, or a functional. The value set must match the property type as defined by the module:

When an enumeration or set is defined, the module that defines it must specify what the keywords are and what internal numbers they correspond to.

An illustrative example of an enumeration is: 

    typedef enum {ITEM0=0, ITEM1=1, ITEM2=2} ITEMS;
    enumeration item;
    gl_publish(oclass,
        PT_enumeration, "item", PADDR(item),
            PT_KEYWORD,"ITEM0", ITEM0,
            PT_KEYWORD,"ITEM1", ITEM1,
            PT_KEYWORD,"ITEM2", ITEM2,
        NULL);

An example of a set is: 

    #define NO_OPTIONS  0x00
    #define OPTION_1    0x01
    #define OPTION_2    0x02
    #define OPTION_3    0x04
    #define ALL_OPTIONS 0x07
    set options;
    gl_publish(oclass,
        PT_enumeration, "options", PADDR(options),
            // keywords should be published in order of decreasing complexity
            PT_KEYWORD,"ALL_OPTIONS", ALL_OPTIONS,
            PT_KEYWORD,"OPTION_1", OPTION_1,
            PT_KEYWORD,"OPTION_2", OPTION_2,
            PT_KEYWORD,"OPTION_3", OPTION_3,
            PT_KEYWORD,"NO_OPTIONS", NO_OPTIONS,
        NULL);

See the section on Random numbers for more information.

5.0 Distribution Network Module

This section describes the objects and properties supported by the powerflow module. The powerflow module is the basic unbalanced 3-phase flow modeling and simulation module for GridLAB-D. It defines two generic objects, the link and the node objects. Together these two object types are necessary to create power flow networks. It also supports the following more specific objects types used in power systems. Among the node objects are:

A network can only be defined using only objects derived from link and node objects. A network can be defined using the abstract link and node objects. However, such a network could not exhibit any of the particular behaviors that are intrinsic to the more specific object types.

Be aware that some object properties are defined per-unit, which means that they are in relation to a reference value for the entire network, or for the part of the network to which they belong. All MVA values are in relation to the network mvabase property. Voltages are in relation to the root node's voltage, which varies over time. When voltage regulars or transformers intercede between the node and the root node, then their voltage becomes the voltage base.

6.0 Residential Module

This section defines the objects and properties supported by the residential module.

6.1 House Object Properties

Each house object supports the following properties that define its behavior.

6.2 Lights Object Properties

Each lights object supports the following properties that define its behavior.

6.3 Refrigerator Object Properties

6.4 Washer Object Properties

6.5 Range Object Properties

Todo:
complete the residential module user documentation (ticket 155)

7.0 Commercial Module

The commercial module is not supported in GridLAB-D Version 1.1 but is planned for future versions.

Todo:
complete the commercial building module user documentation (ticket 155)

8.0 Tape Module

This section defines the objects and properties supported by the tape module.

8.1 Player Object Properties

<<<<<<< .mine • property (string32) - the published name of the property whose values are written from the tape • file (string1024) - a name for locating the file, global object, or database with the player data • filetype (string8) - defines what media to use for the player (file, memory, odbc) • loop (int32) - how many times to play this file =======

8.2 Shaper Object Properties

<<<<<<< .mine • property (string32) - the published name of the property whose values are written from the tape • file (string1024) - a name for locating the file, global object, or database with the shaper data • filetype (string8) - defines what media to use for the shaper (file, memory, odbc) • group (string256) - the find statement that determines which objects to shape values on • magnitude (double) • events (double) =======

8.3 Recorder Object Properties

<<<<<<< .mine • property (string1024) - the published name of the property whose values are written to the tape • file (string1024) - a name for locating the file, global object, or database for the recorder data • trigger (string32) - the condition to write values on, such as ">40" or "=TRIPPED" • interval (int64) - how frequently to write the value of the aggregate (-1 == on every sync call) • limit (int32) - the maximum number of lines to write =======

8.4 Collector Object Properties

• property (string1024) - the published name of the property whose values are written to the tape • file (string 1024) - a name for locating the file, global object, or database for the collector data • trigger (string32) - the condition to write values on, such as ">40" or "=TRIPPED" • interval (int64) - how frequently to write the value of the aggregate (-1 == on every sync call) • group (string256) - defines the aggregate group (see aggregations) • limit (int32) - the maximum number of lines to write

Todo:
complete the tape module user documentation (ticket 155)

9.0 Climate Module

Note: this module needs work. It will export variables eventually. You can create more than one climate object, but there is no benefit from doing so.

Todo:
complete the climate module user documentation (ticket 155)

10.0 Troubleshooting

Todo:
write troubleshooting section (doxygen, high priority) (ticket #157)
GridLAB-DTM Version 1.0
An open-source project initiated by the US Department of Energy