What is a GridLAB-D™ Model?

A GridLAB-D™ model can be stored in either GLM (GridLAB-D™ Model) or XML (Extensible Markup Language) files, often with other files around to help define simulation boundary conditions and provide needed supporting data. The names GLM and XML come from the extension used in the file name, .glm and .xml, respectively.

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

GLM files are not exactly like XML files. An XML file is a faithful representation of the exact model being simulated, while a GLM file can provide underlying information such as parametric values and statistical distributions for properties, as well as specifications for synthesizing populations of objects so that large models can be generated from relatively simple descriptions. GLM files also allow you to describe the behavior of objects in the simulation, whereas XML files cannot.

Consider a small example. Suppose we define a house, each instance of which has a floor_area, drawn from a normal distribution about a mean of 2500 square feet [sf] with a standard deviation of 250 sf. To instantiate the house object, both require the residential module to be added first. Compare the GLM object definition:

module residential;
object house {
  floor_area random.normal(2500,250);
};

with the XML code that might be generated after loading it:

<module>
  <residential/>
<module>
<house>
  <floor_area>2534.2 sf</floor_area>
</house>

The commands in this model are called directives. Directives are either simple one-liners like the module directives, or complex multi-line ones like the object directives. The first directive in this example instructs GridLAB-D™ to load the residential module. The second directive defines the house object, with a specific floor area.

The GLM file described the property floor_area as having a random value with a normal distribution. If you were to run GridLAB-D™ multiple times using this object description, then depending on how the random number generator is set up you might see a different value for the floor area each time. But overall, the values would have a mean 2500 sf with a standard deviation of 250 sf. 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 for the floor area. 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.

One thing you may have observed is that GridLAB-D™ doesn't do a great deal by itself. Without a model file or any modules, it becomes a big ""Hello World!" exercise. If a model file includes, but does not use, objects of a particular type, that functionality is never realized. Without some sort of action from GridLAB-D™, it looks much like a large blank monolith.

Model Terminology

The previous example introduced some very important concepts, which we touched on briefly in the tutorial overview. The first thing to recognize is that GridLAB-D™ functions much like a combination of a compiler and an operating system. It defines modules, classes, objects, inheritance hierarchy, and named variable types, then loads in the dynamic link libraries (DLLs in Windows or Shared Objects [SOs] in Linux) to extend its capabilities, links various objects together by name instead of address, contains PATH information, and handles object processing distribution and order. Though incomplete as an operating system, and while GridLAB-D™ is unable to write programs or scripted instructions, many similarities exist at deeper levels.

Model Components

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 larger GridLAB-D™ models that have been built contain well over 100,000 objects.
  • Variables are explicitly registered with the GridLAB-D™ core from within a class’s registration process. The property structure holds only the name of the property, its type, and an offset pointer to find the variable from the start of the object’s class block.

However, describing so many objects in detail can be an overwhelmingly difficult challenge. This is where the second notion comes in: a class.

• Classes are used to group objects according to similar properties and behaviors. GridLAB-D™ classes are similar to, but are not the C++ classes that are coded for them. The GridLAB-D™ core sees a class as a structure with a set of published properties, with some function pointers to the common routines, such as create, init, sync, and isa, then stores the name and instance size (in bytes) of the class. 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.

Accordingly, the C++ class definition for the house used above would look something like this

// class example
class house { 
  double floor_area[sf];
};

which tell GridLAB-D™ that the variable floor_area is a property of all houses and it is stored in units of sf (i.e., square feet). Note that it is not necessary to define the house class this way in the .glm model file because modules do this for us in a way that ensures everybody uses the same properties and behaviors (see below).

Example:
// This is a comment. We like comments

• Modules define many classes in a single quick and convenient directive. The largest building block for GridLAB-D™ is the module. These are DLLs that are loaded by the GridLAB-D™ core that use the core functions to register a set of classes, and a set of properties for each of those classes. The core has a small structure with handles to various parts for that DLL, including its name, the module interface functions such as init and check, and the classes registered with that module.

Loading a Model

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.

Once you're ready to use GridLAB-D™, you should check to see what version of GridLAB-D™ is installed:

host% gridlabd --version

GridLAB-D™ 5.3.0-20095

host%

Command Line Options

Sometimes you will have to enter what are called command options to get GridLAB-D™ to do something different than usual. To get a list of commonly used command options, you can enter the following:

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

To get detailed help on a particular topic, you can try the command --info:

host% gridlabd --info house
host%

which will open a web browser window on the page (or list of pages) related to the topic indicated. If your topic is multiworded you should use underscores _ or plus signs + instead of spaces:

host% gridlabd --info implicit_enduses
host%

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 describe 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

For a comprehensive list of command line options, please refer to Command Line Options in the reference section.

Creating Your First Model

The simplest GLM model you can create will contain only one object, will not process any time at all, and will record the state of only one property:

// Examples:1a.glm
module residential;
module tape;
object house {
  object recorder {
    property air_temperature;
    file "temperature.csv";
  };
}

Remember, your simulation will not function properly without using a clock.

clock {
  starttime '2000-01-01 00:00:00';
  stoptime '2001-01-01 00:00:00';
}

This example loads the residential module and the tape module. It then defines a single house with all the default properties. Within that house it defines a single recorder which records the air_temperature property of the house and stores that value in the file "temperature.csv".

Creating New Objects

The third and last directive in the above example is an object definition. Object directives must provide that class type so that GridLAB-D™ knows what kind of information you’d like to associate with an object. An object definition usually includes property values (see below), but sometimes it can also include nested objects.

The third entry includes a nested object. This nested object is the recorder. By nesting the recorder, it is associated with the house. This association is called a parent-child relationship. In this case, the house is the parent object and the recorder is the child object. Parent-child relationships are extremely important in GridLAB-D™ because they determine a hidden property of objects called the rank. Rank is used to establish things like the order in which time synchronization behaviors are run and whether they can be run simultaneously. This is critical to getting the correct results and enabling fast simulations running on high-performance computers.

Improving Your Model

The following section describes various ways to extend or improve your models. These include how to use date/time, how to disable and enable objects, referencing other objects, generating populations of objects, embedding context information in objects, using functional properties, performing calculations while loading and running models, and handling units.

Using Date and Time

Date and time specifications are used for many things in GridLAB-D™. Most importantly they are used to specify the starting and ending time of a simulation:

// Examples:1b.glm
clock {
  starttime '2000-01-01 00:00:00 UTC';
  stoptime '2001-01-01 00:00:00 UTC';
}
module residential;
module tape;
object house {
  object recorder {
    property air_temperature;
    file temperature.csv;
  };
}

which produces the following output:

2000-01-01 00:00:00 UTC,+69
2000-01-01 01:00:00 UTC,+69.9947
2000-01-01 02:00:00 UTC,+70.6269
2000-01-01 03:00:00 UTC,+71.1764
2000-01-01 04:00:00 UTC,+71.6754
2000-01-01 05:00:00 UTC,+72.1189
2000-01-01 06:00:00 UTC,+72.5266
2000-01-01 07:00:00 UTC,+72.927
...

Dates and times are usually specified using the ISO (International Standard Organization) standard format, which is YYYY-MM-DD HH:MM:SS ZZZ. (You can change the format of date/time values using the dateformat global variable).

If you omit the time zone specification, then the time zone indicated by the TZ environment variable will be used. If you wish to specify the timezone to use in the simulation, use the timezone directive:

// Examples:1c.glm
clock {
  timezone EST+5EDT;
  starttime '2000-01-01 00:00:00 UTC';
  stoptime '2001-01-01 00:00:00 UTC';
}
module residential;
module tape;
object house {
  object recorder {
    property air_temperature;
    file temperature.csv;
  };
}

which results in the following output:

2000-01-01 00:00:00 EST,+69
2000-01-01 01:00:00 EST,+69.9947
2000-01-01 02:00:00 EST,+70.6269
2000-01-01 03:00:00 EST,+71.1764
2000-01-01 04:00:00 EST,+71.6754
2000-01-01 05:00:00 EST,+72.1189
2000-01-01 06:00:00 EST,+72.5266
2000-01-01 07:00:00 EST,+72.927
2000-01-01 08:00:00 EST,+73.3376
2000-01-01 09:00:00 EST,+73.7618

Time zones are specified in the "tzinfo.txt" file that is installed with GridLAB-D™ under the share folder. The management of the GridLAB-D™ clock is explained further in the Simulation Time section.

Adding More Objects

Object blocks are used to define one or more instances of a class. The simplest form is a singleton object definition, such as

module residential;
object house {
  floorarea 2500 sf;
}

which will define an anonymous house of 2500 square feet.

If, however, you wish to define 10 such houses, then you can specify a count such as

module residential;
object house:..10 {
  floorarea 2500 sf;
}

If a functional value is used, then the functional value is evaluated separately for each instance created, so that

module residential;
object house {
  floorarea random.normal(2500,100) sf;
}

defines 10 separate houses, each with a different floor area, but with the floor area normally distributed about a mean of 2500 sf with a standard deviation of 100 sf.

If a mathematical expression is written within a set of parentheses, it will be processed at load time. Addition, subtraction, multiplication, division, exponential, and modulo operators are supported, as well as parenthetical nesting and unary math.h functions. The code

module residential;
object house {
  floorarea random.normal(2500,100) sf;
  ceilingheight random.normal(8,1) f;
  airvolume (this.floorarea * this.ceilingheight);
}

will generate a random value for the floor area and the ceiling height of a house and calculate the contained air volume.

Recording Information About an Object

The recorder class is one of two classes in the tape module that can gather information about objects as they change over time. Recorders can output data in a variety of formats, and the properties of a recorder object define what is gathered, how it is gathered, and where it is delivered to.

The recorder object gathers information from its parent object, in this case the house object. By specifying air_temperature, the recorder object is instructed to gather only the value of the air_temperature property of the house object. The property instructs the recorder to deliver the observed values to a file called "temperature.csv". Normally, a recorder object only delivers an observation to the file when the property changes, which is what we want in this case.

The output of a recorder object is normally in the form of a comma-separated 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 output 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 the file contains a complete time-series record of the changes in the observed value as the simulation advanced the clock.

Referencing Other Objects

In the above examples, the recorder object is nested within the house object. This is a convenient way to indicate that the recorder depends on the house object for the property it records. This implied relationship is the parent-child relation.

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

// Examples:1e.glm
clock {
  timezone EST+5EDT;
  starttime '2000-01-01 00:00:00';
  stoptime '2001-01-01 00:00:00';
}
module residential;
module tape;
object house {
  name MyHouse;
}
object recorder {
  parent MyHouse;
  property air_temperature;
  file temperature.csv;
  in '2000-04-01 00:00:00';
  out '2000-04-02 00:00:00';
};

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

The parent relationship has an impact on how behaviors like initialization and time synchronization are performed. Some objects reference other objects without using the parent relationship for that reason. This is done using an explicitly declared property of the object:

This is a mock-up example of how to/from properties can be set:

// Examples:1f.glm 
module powerflow;
class link {
  object from;
  object to;
}
object node {
  name Node1;
}
object node {
  name Node2;
}
object link {
  from Node1;
  to Node1;
}

Running GridLAB-D™

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. Recall the considerations about GLM vs. XML files discussed earlier on this page.

GridLAB-D™ can be run using the simple command line: gridlabd myfile.glm. Command line arguments, including options, are evaluated and executed in the order in which they appear.

Output is generated to stdout and stderr. Output redirection is controlled using the --redirect command line option.

If You’ve Just Installed GridLAB-D™

You may need to set up the system’s runtime environment. There are several files that you may have to adjust to accommodate the compilers and runtime libraries that are appropriate to your system. These should have been set automatically, but if you are experiencing trouble with the runtime environment, see the Installation Guide for details on how to make GridLAB-D™ work with your system.

If You’re a System Administrator

If there is more than one user for GridLAB-D™, you will probably have to set up the multiuser runtime support. You can skip this step, but this will require all users to have the same runtime environment, which may be undesirable in certain cases. When there are multiple users, it is quite likely they will need to have the ability to customize their individual GridLAB-D™ configurations. This is automatically supported by the "gridlabd.conf" runtime file, but several considerations must be taken into account when operating GridLAB-D™ this way.

By default, "gridlabd.conf" is located using the GLPATH environment variable and the search is always done by first looking in the current folder. If any users have a copy of this file in their search path or in the current directory, then they will not be consulting the host system’s standard configuration file. This can result in unpredictable and erratic behavior for different users.

Users may create a file "gridlabd-user.conf", where user is the user’s login name as specified by the USER environment variable. This file will be located and consulted when found. You may opt to create a static one for each user in the GridLAB-D™ directory that the user cannot edit. Or you can create configuration files for each user in directories they own and can edit. In the latter case you should be certain that their private directories are included in the GLPATH environment. On Linux systems, this can be done by adding

#setenv GLPATH=${GLPATH}:${HOME}/gridlabd

to the "gridlabd.conf" file. In Windows, the correct syntax uses a semicolon instead of a colon

#setenv GLPATH=${GLPATH};${HOME}/gridlabd

Running Your Model

Using an editor to run the file "house1.glm", run the following command from the host computer:

host% gridlabd house1.glm
host%

Note that you may see some warnings about the clock and voltages, but you can ignore those for now.

Now look at the output file:

host% more temperature.csv
1970-01-01 00:02:00 UTC,+69

The console output below the more command tells us that the temperature was read once at (shortly after) the default initial simulation time.

If you don’t get the expected result, make sure your GridLAB-D™ system is properly installed and that 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.

Generating Populations

One of the most important capabilities in GridLAB-D™ is the ability to study large populations of objects as they interact with each other. The challenge for modelers is quickly defining what that population looks like without having to explicitly define each and every object. This is made easy by using a multi-object definition, such as

object house:..5 {
  floor_area 2500 sf;
};

In this case, GridLAB-D™ will create 5 identical objects and will all run together.

Embedding Context Information

Object populations can create complications for other objects, such as recorders. Because the recorder is nested in the house definition, there are in fact 5 recorders created, all of which write to the same file. If left as-is, they will overwrite each other. To remedy the problem, context information can be embedded in the name of the output file, for instance: temperature{id}.csv, shown below:

// Examples:1g.glm
clock {
  timezone EST+5EDT;
  starttime '2000-01-01 00:00:00';
  stoptime '2001-01-01 00:00:00';
}
module residential;
module tape;
object house:..5 {
  object recorder {
    property air_temperature;
    file `temperature{id}.csv`;
    in '2000-04-01 00:00:00';
    out '2000-04-02 00:00:00';
  };
}

The result is that a different recorder file is used for each recorder. The recorders' internal id is used for each file name, thus allowing a separate file for each. You can enable embedded information from the context of an object by surrounding the value in back-quotes. When a value is defined this way, any part of the value which is in curly-braces is expanded from the context of the object.

Python API

The Python API provides three fundamental functions for interacting with the GridLAB-D™ engine: 1. Controlling simulation time 2. Reading object parameter values 3. Writing object parameter values

The combination of these three items allows the API to be used for simple tasks such as running one or more GridLAB-D™ models as well as more complex tasks such as writing simulation results to a database or implementing a custom controller that changes an object parameter values (say, an inverter output power) in response to the state of the model (say, the total load on the feeder). Additionally, being Python, it is possible to integrate GridLAB-D™ alongside any other Python library to use GridLAB-D™ as part of a larger integrated tool.

A more extensive introduction and explanation of the Python API including examples is provided in the Python API section of the Modeling Reference.

Functional Values

Sometimes it is necessary to examine the behavior of multiple objects that are not quite the same. When we want to create different objects with different properties we use a functional property, such as:

object house:..5 {
  floor_area random.uniform(1500,2500);
};

Functionals are values that are determined when the object is created. There are a number of supported functionals, most of which are random number generators of different types. In this case, the floor area property will be randomly sampled 5 times from a uniform distribution of values between 1500 and 2500.

Performing Calculations

Often objects have values that are correlated with each other, rather than independently distributed. For example, by default the air volume of a house is the ceiling height times the floor area. However, if you want to explicitly calculate a different volume based on floor area you can use an equation, as shown in the following example:

object house:..5 {
  floor_area random.uniform(1500,2500);
  air_volume (10*$floor_area);
};

Calculated values are always enclosed in parenthese and are an important way to established correlated relationships when large populations of objects are defined.

The following math functions are supported:

• sin
• cos
• tan
• abs
• sqrt
• acos
• asin
• atan
• log
• floor
• ceil

Variable references take the form:

$variable-name

or

this.variable-name

Only references to local properties or global variables are supported and they must already be defined to be used. If the variable is not defined, its creation default value is used. If the calculation ends up setting the property to the creation default value, it most likely will end up assuming the initialization default value.

Example Calculation

clock {
  timezone GMT0GMT;
  starttime '2015-05-20 00:00:00';
  stoptime '2015-05-21 00:00:00';
}
module residential;
module tape;
object house:..5 {
  floor_area random.uniform(1500,2500);
  air_volume (10*ceil($floor_area+10));
  object recorder {
    property floor_area,air_volume;
    file `data_{id}.csv`;
  };
}

Handling Units

Every real- or complex-valued property should have units associated with it. All recognized units are defined in the unit file "unitfile.txt". For example, the house’s floor_area property could be defined as

class house {
  double floor_area[sf];
}

which indicates that the property has a square-foot unit. When a property has a unit associated with it, any use of the property can include a compatible unit, and when it does, the value given will be converted automatically. For example,

object house {
  floor_area 125 m^2;
}

would convert the value from 125 \(m^2\) to square-feet when loading the model.

Unit conversion is performed automatically, but only when the units are compatible, meaning that they represent the same underlying fundamental quantity, but with different scales. This means that GridLAB-D™ will automatically convert \(ft\) to \(m\), or \(ft^2\) or \(sf\) to \(m^2\), but it cannot convert \(ft\) to \(cm^2\) because they are fundamentally incompatible.

When a unit is declared in a class’s property, but not specified in an object’s definition, it is assumed that the value defined uses the declared unit. Therefore floorarea 2500; is the same as floor_area 2500 sf;. The only difference is that if the default unit were to be changed, then the latter definition would continue to work as expected, while the former would behave differently.

For a comprehensive look at units in GridLAB-D™, refer to the units page of the documentation.

Providing Input

GridLAB-D™ provides a number of methods for inputting data into the system. The simplest of these uses an external file with a series of values, each associated with a timestamp. This is called a "player" file and there are more details about using them in the Player documentation.

Some objects that are modeled in GridLAB-D™ have very regular operational patterns and rather than specifying these patterns as a repeating series of values for all time, it is possible to define a series of operational transition points instead. These are called "schedules" and the details on defining them can be found in the Schedules and Loadshapes tutorial. A common application of a schedule is a "loadshape", a means interpretting the values defined by a schedule to realize more complex operation patterns such as pulsed or modulated values. These are not commonly used but provide considerable freedom that would be hard to realize without falling back to an exhaustive player file; further documentation can be found on the Loadshape page.

All of the above methods also support simple mathematical operations to modify the value provided by the player file, schedule, or loadshape before applying it to the object property. This is called a "transform" and allows the use of a linear function where the value provided is an operand in the function. These are commonly used to allow, say, the value provided by a single schedule to be used to be define the power of a load for both a small and large load. Further details on the use and implementation of transforms can be found on the Data Transforms page.

Lastly, the Python API provides a programmatic means of assigning object parameter values in an arbitrary manner and opens the door to any number of ways to changing the behavior of objects in a GridLAB-D™ model. The documentation on the use of the Python API can be found in the Python API section.

GridLAB-D™ Output Files

GridLAB-D™ can output results in one of two ways.

• Using the -o myfile.xml command line option to generate an instance of the model at the end of simulation.
• Using 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 the Tape module page. A brief overview of how to use the recorder object is provided below.

GridLAB-D™ provides a number of ways to generate output from simulations. The basic concept is that of a data logger. The recorder is hooked up to an object property and makes a copy of the value every so often and writes it to a file. What object the recorder looks at and how often it writes is determined by how you set up the recorder. For example

object recorder {
  parent MyHouse;
  property air_temperature;
  file "temperature.csv";
};

instructs the recorder to observe the air_temperature property of the MyHouse object and send any changed observations to the file "temperature.csv".

There are additional settings that you can provide to control the behavior of the recorder. To limit the length of the recording, for example:

object recorder {
  parent MyHouse;
  property air_temperature;
  file "temperature.csv";
  limit 1000;
};

The limit 1000 setting prevents the recorder from making more than 1000 observations.

To change the sampling interval, for example:

  object recorder {
  parent MyHouse;
  property air_temperature;
  file "temperature.csv";
  limit 1000;
  interval 300;
};

The interval 300 setting instructs the recorder to look at the internal air temperature of the house every 5 minutes (remember that GridLAB-D™'s default unit of time is seconds).

Summary

We have seen some of the basic features of GridLAB-D™ and covered how you can utilize them to model a simple system. At this point you are ready to explore the various modules in GridLAB-D™ and get familiar with the classes and properties they implement.

References

• [1] RT Guttromson, DP Chassin, SE Widergren, "Residential energy resource models for distribution feeder simulation", IEEE PES GM, 2003, DOI: \http://dx.doi.org/10.1109/PES.2003.1267145"http://dx.doi.org/10.1109/PES.2003.1267145>