Introduction to GridLAB-D: How to Simulate Power Grids from Scratch
The modernization of the electrical grid requires advanced simulation tools. Traditional power flow software often struggles with high penetrations of distributed energy resources (DERs), smart appliances, and time-varying retail electricity rates.
GridLAB-D, developed by the U.S. Department of Energy at the Pacific Northwest National Laboratory (PNNL), solves this problem. It is an open-source, agent-based simulation environment that models power distribution systems from the substation down to individual household appliances.
This article introduces you to GridLAB-D, explains its unique architecture, and guides you through building your very first power grid simulation from scratch. What is GridLAB-D?
Unlike conventional power flow simulators that use static, snapshot-based calculations, GridLAB-D uses an agent-based, time-series approach.
In GridLAB-D, every component of the distribution network—a transformer, a residential house, a photovoltaic (PV) inverter, or a water heater—is treated as an independent object (an agent) with its own state and behavior. The software solves the power flow equations while simultaneously updating the thermodynamic states of houses and the behavioral patterns of consumers at every time step. Key Features
Coupled Simulations: It integrates power flow solvers with thermodynamic models of buildings and market mechanisms.
High Time Resolution: It simulates sub-second dynamics up to multi-year horizons.
Scalability: It can model thousands of individual homes and physical assets simultaneously.
Open Source: It has an active community modifying and expanding its capabilities for modern research. GridLAB-D Core Architecture
GridLAB-D models are written in GridLAB-D Core Language (GLM) files. A typical GLM file consists of four primary building blocks:
Directives and Global Variables: These set up the simulation environment, defines the start and stop times, and establish configuration parameters.
Modules: Software packages that contain the class definitions for specific types of equipment. The most common modules are powerflow, residential, and climate.
Objects: Individual instances of classes defined within the modules. For example, a specific node, line, or house.
Recorders/Collectors: Tools used to sample data from objects during the simulation and save the output to CSV files for analysis. Step-by-Step: Writing Your First Simulation
Let’s build a simple simulation: a distribution transformer feeding a single residential house with an air conditioner over a 24-hour period. Step 1: Install GridLAB-D
Before writing code, ensure GridLAB-D is installed on your machine. You can build it from source via GitHub or download pre-compiled binaries for Windows, macOS, or Linux through the official GridLAB-D repository or package managers like Homebrew. Step 2: Set Up the Simulation Environment
Create a new text file named simple_grid.glm. Open it in any text editor and begin by defining the simulation clock and loading the necessary modules.
#set minimum_timestep=60; clock { timezone EST+5EDT; starttime ‘2026-07-15 00:00:00’; stoptime ‘2026-07-16 00:00:00’; } module powerflow; module residential; module tape; Use code with caution.
clock: Tells the simulator to run exactly a 24-hour simulation starting July 15, 2026.
module powerflow: Loads the tools required to calculate voltages, currents, and power metrics.
module residential: Loads models for houses, appliances, and thermal dynamics. module tape: Loads recording tools to export data. Step 3: Define the Power Flow Infrastructure
Next, define the electrical node representing the low-voltage side of a transformer and the triplex (split-phase) line connecting it to the home.
object triplex_meter { name main_transformer_meter; phases AS; nominal_voltage 120.0; } object triplex_line { name service_drop; phases AS; from main_transformer_meter; to house_meter; length 100 ft; configuration object triplex_line_configuration { conductor_1 object triplex_line_conductor { resistance 0.48; }; conductor_2 object triplex_line_conductor { resistance 0.48; }; conductor_N object triplex_line_conductor { resistance 0.48; }; insulation_thickness 0.08; }; } object triplex_meter { name house_meter; phases AS; nominal_voltage 120.0; } Use code with caution. Step 4: Model the Smart House
Now, attach a physical house to the house_meter. We will give the house basic structural characteristics and add an air conditioner that reacts to internal temperatures.
object house { name residential_home; parent house_meter; floor_area 2000 sf; thermal_integrity_level GOOD; cooling_setpoint 72.0; heating_setpoint 68.0; air_temperature 70.0; object airconditioner { type TWO_STAGE; control_mode THERMOSTATIC; }; } Use code with caution.
Because GridLAB-D solves the thermal equations of the house, the air conditioner will automatically cycle on and off based on how quickly the house heats up. Step 5: Capture the Data
To see how much power the house consumes throughout the day, add a recorder object to track the real power consumption at the meter.
object recorder { parent house_meter; property measured_real_power; interval 300; file load_profile.csv; } Use code with caution.
This captures the power data every 5 minutes (300 seconds) and saves it to a clean spreadsheet. Running the Simulation and Analyzing Results
To execute your model, open your command terminal, navigate to the folder containing your file, and run: gridlabd simple_grid.glm Use code with caution.
Once complete, a file named load_profile.csv will appear in your directory. Opening this file in Python or Excel reveals a dynamic, time-varying load profile. You will see spikes in power demand whenever the air conditioner turns on to cool the house, creating a realistic power consumption signature rather than a flat, estimated average. Advancing to Complex Models
Once you master this basic structure, you can expand GridLAB-D simulations into highly sophisticated grid architectures:
Real Weather Data: Replace static indoor temperatures by importing real Typical Meteorological Year (TMY3) weather files to drive heating and cooling behaviors based on real climate history.
Renewable Integration: Add triplex_inverter and solar objects to model residential rooftop solar adoption and its localized impacts on voltage stability.
Feeder Models: Import massive, IEEE-standard distribution test feeders (such as the IEEE 13-node or 123-node feeders) to simulate entire utility territories.
GridLAB-D bridges the gap between power systems engineering and building science. By mastering its object-oriented architecture, you gain the ability to accurately test how tomorrow’s technologies will impact today’s electrical infrastructure. To help you continue building out this simulation, tell me:
Leave a Reply