GridLAB-D™ Overview

GridLAB-D™ is a power system simulation tool used to model and analyze electric power distribution systems. It helps researchers, engineers, and utilities evaluate system performance and explore the benefits of modern grid technologies, including smart grid applications.

GridLAB-D™ incorporates advanced modeling techniques with high-performance simulation algorithms to represent detailed end use loads, distributed energy resources, three-phase unbalanced power flow, and retail market systems. Historically, the inability to accurately model and evaluate these complex systems has been a barrier to adoption of new technologies; GridLAB-D™ is designed to address this problem.

This tutorial is designed for users who have a basic understanding of electric distribution systems and want to begin using GridLAB-D™ in their work. It is not intended to be comprehensive in covering every model or parameter. Rather, this tutorial is intended to introduce the most commonly used features of the tool and help users build a practical foundation.

This tutorial contains and references many example GridLAB-D™ models and files. Readers are recommended to download a local copy of the Tutorial folder so example files are readily available while working through the exercises.

GridLAB-D™ Design

GridLAB-D™ is a flexible, agent-based, time-series simulator that can model the behavior of many interacting components (e.g., houses, distributed energy resources, and power systems controls) over time. Although users build models using .glm (GridLAB-D™ Model) files, the underlying simulation engine and modules are implemented in C++, which enables high performance and detailed physical modeling.

Each component in GridLAB-D™ is represented by an object that responds to changes in its local environment and to other objects in the system. A key concept in GridLAB-D™ is time advancement. At each simulation time step, GridLAB-D™ checks whether any objects need to update their state (i.e., modifying the state of a thermostat due to temperature changes or a battery due to power flow). The simulator continues advancing time and allows each object to update themselves at each time step. The simulation will only advance to the next time step if all objects reach an equilibrium or stable state. This event-driven simulation approach is central to how GridLAB-D™ works and is an important concept to understand.

Multi-Domain Models

GridLAB-D™ is commonly represented as a distribution system and/or smart grid simulator with more, very useful built-in classes than what you might find in a traditional distribution system simulator. GridLAB-D™ contains classes for many common distribution components (transformers, lines, voltage regulators, capacitors, ZIP loads,...). It also contains classes for solar PV, energy storage, residences with air-conditioners and water heaters, and weather. Though each of these classes have impacts on the operation of the distribution system, it is their behavior outside of the electrical system as modeled by GridLAB-D™ that is unique. A house with an air-conditioner is modeled to not only represent how much energy the air-conditioner uses when it is running but also how often it runs and for how long based on the indoor temperature, which is influenced by the thermodynamic properties of the house (how large it is, insulation properties, number of windows...) and the weather. These multi-domain interactions provide a capability not often seen in other distribution system simulators.

While GridLAB-D™ is commonly used to simulate distribution systems and smart grids in particular, there is no reason that it needs to be limited to these areas in scope. It is entirely possible to use the existing GridLAB-D™ framework to simulate vegetation growth, weather, or vehicle traffic patterns while simultaneously simulating an electrical distribution system.

Modules, Classes, Objects

GridLAB-D™ is organized using modules, classes, and objects.

  • Modules are used to group functionalities and define sets of object classes.

For example,

  • The power flow module defines electrical components such as lines, transformers, and meters.
  • The residential module contains the definitions of things such as the house model and appliances like the water heater, and zip load.

Most modules are written in C++ and are loaded automatically when referenced in a .glm file.

  • Classes define the properties and behavior of a specific type of component within a module. For example:

    • The house class (from the residential module) defines properties like floor area, insulation, and thermostat setpoint.
    • The meter class (from the power flow module) defines electrical measurement and billing behavior.
    • The battery class (from the generators module) defines charging, discharging, and state-of-charge behavior.

  • Objects are individual instances of classes that represent real components in the modeled system. For example:

    • A specific house at one address.
    • A single residential meter serving that house.
    • A particular rooftop solar system installed at that location.

While objects of the same class share behavior, each object can have different property values. Every object must belong to a class, and every class must be defined in a module.

The following example in Figure 1 illustrates this GridLAB-D™ parent-child hierarchy. The example includes a house with water heater, zip loads, EV charger, rooftop solar, and battery backup.

Module - Object - Parentage Hierarchy
Figure 1: Module - Object - Parentage Hierarchy

The house object, which is from the residential module, is a parent of the water heater, any zip loads, and the EV charger object, but is a child to its own meter. The solar and battery objects are a part of the generators module, and are children to their own meters, as they are able to exist as standalone generator objects and do not necessarily need to be attached to a house. All three meters are children to the same customer meter so that both the billing and the behavior of the solar and battery objects are take into account all the objects that make up this residence.

Classes are important because they define which properties are allowed in objects (i.e., a house can have windows and insulation, while an EV charger cannot). Classes also define how objects behave during simulations (i.e., the thermodynamics of how indoor air temperatures respond to weather and thermostat settings in homes, the thermodynamics of a house based on its insulation, thermostat setpoint, outside air temperature, and other relevant properties). Each class of objects must be defined in a module, and cannot exist without one.

Although every house object may have different property values, all house objects follow the same physical and control rules defined by the class. For example, every house on a street is not identical nor sets their thermostat to the same temperature; however, each house does obey the laws of thermodynamics.

During simulations, GridLAB-D™ will keep the objects' properties synchronized with each other as time advances to accurately model the behavior of each object with respect to time. Note also that modules can either be static, meaning they are implemented in a dynamic link library (e.g., .dll in Windows, .so in Linux, .dylib on Macs), or they can be dynamic, meaning they are compiled and linked at runtime. For most uses, this happens automatically and does not affect how .glm models are written or run.

Introduction to GridLAB-D™

If you're already competent with GridLAB-D™ and want skip straight to the details of runtime classes or high-performance simulation, then as an advanced user you can jump straight the list of Modules. However, we suggest that all beginners and most intermediate users continue through this tutorial.

GridLAB-D™ is the first (and so far only) environment for simulating highly-integrated modern energy systems. GridLAB-D™ is also an open-source system, meaning that the source code, which is the programming code that makes up GridLAB-D™, is freely available to anyone. People all over the world can add to GridLAB-D™, fix bugs, make improvements, or suggest optimizations, and they do. GridLAB-D™ has grown tremendously since the prototype implementation (called PDSS, short for Power Distribution System Simulator) was created at Pacific Northwest National Laboratory (PNNL) in 2002 [1].

Unlike proprietary simulation tools, where the source code is written by a few people and carefully guarded, open-source projects like GridLAB-D™ exclude no one who is interested in making a contribution. However, those contributions must be vetted and validated before being incorporated into the main code.

Another important advantage of the open-source model is the transparency of the implementation, which is necessary for building confidence in the accuracy of the results that come from using GridLAB-D™. While proprietary tools must be carefully validated using test cases, GridLAB-D™ has an advantage wherein validation can begin much sooner by ensuring that the implementation meets industry standards for quality and accuracy.

Understanding GridLAB-D™ Basics

GridLAB-D™ is an agent-based simulation environment specifically designed to model modern energy systems. It’s a program capable of tracking the simultaneous states of vast numbers of objects having a wide variety of properties and behaviors, and gathering information about their condition as time progresses in the simulation.

GridLAB-D™ simulates a system by computing a series of steady states, separated by state transitions. The simulation discovers when those state transitions occur by looking at each object to determine:

1) Its next proposed steady state solution.

2) Whether that state is consistent with the proposed steady states of all the other objects in the model.

3) How long that state is expected to last.

The details of how GridLAB-D™ works are left to a later discussion. All the tools needed for constructing and compiling models, debugging and running them in the simulator, and extracting results are either installed with GridLAB-D™ or are available as free downloads from open-source repositories. A quick reference for accessing help resources is provided below.

Runtime Help Resources

There are several options for getting assistance: To get a list of command options from the gridlabd runner:

gridlabd --help

To get a list of a module's classes and their properties:

gridlabd --modhelp modulename:classname

To get a list of global variables

gridlabd --globals

To get an example of an object:

gridlabd --example modulename:classname

To search online for a topic:

gridlabd --info topic

The GLBROWSER environment variable is used to specify the browser to use when the simulator is running. This feature is used by the --info and the GUI. The default browser is different on various platforms: Internet explorer (iexplore) for Windows systems; Firefox for Linux; and Safari for Mac OSX.

The --copyright command line option is used to display the GridLAB-D™ copyright. The copyright message is suppressed at startup when the file COPYRIGHT is found in one of the folders specified by the GLPATH environment variable. The version information is also displayed when the copyright is output.

gridlabd --copyright

References