Built-In Distribution Models

As we've demonstrated in this tutorial, GridLAB-D™ has the capability of representing very large distributions with a high degree of fidelity, replicating unique behaviors for each residence in the network and driving load as the weather changes throughout the day and year. This is a powerful capability that hinge on one crucial piece: the actual models that connect all these pieces together appropriately. So far, the example models we’ve been using have been relatively small in size with a handful of nodes, a few loads, and a bit of supporting infrastructure in the distribution system like voltage regulators and capacitors. A realistic distribution system would have hundreds, if not thousands of objects, each uniquely defined. Creating a model like this by hand would be a herculean effort.

Fortunately, the GridLAB-D™ developers have addressed this with what are called the Taxonomy Feeders. Found here, these models are the second secret weapon of GridLAB-D™, after the residential class. This collection of about two dozen models are the result of an extensive study in which models of actual distribution systems from across the United States were collected and analyzed. The results from this analysis was used to identify typical features of these distribution systems based on region and type of feeder and subsequently used to define these typical, taxonomy feeders. The report describing this analysis process and further details on the specific feeder models is called Modern Grid Initiative Distribution Taxonomy (Final Report).

The naming of the feeder models follows the form of:

• R - Region number. The regions are based on common weather patterns and are roughly defined in Figure 1.:
• xx.xx - Primary voltage of feeder in kV
• x - Serial number of feeder

For example, R5-12.47-1 is a model for a distribution feeder commonly found in the coastal SE portion of the United States. The main distribution voltage is 12.47 kV and this is serial number 1 of such models. Looking at the report, we see there are a total of five models.

In their stock form, these feeders are very useful for examining the powerflow in a distribution system; however, they come built with static loads. Through the use of schedules and players it is possible to create more realistic loading on the network but doing so would miss out on so much of the functionality GridLAB-D™ can endogenously produce using loads from the residential class. To fully realize this kind of model for a distribution system, the Transactive Energy Simulation Platform (TESP) developers have developed a python API that takes one or more of these taxonomy feeders and replaces the static loads with one or more residential loads of the appropriate size.

Feeder Generator API

The feeder generator API is defined in a script is called "gld_feeder_generator.py" and is found in the TESP distribution at .../tesp_support/api/gld_feeder_generator.py. Using the API requires a TESP installation, instructions for which are found here.

The TESP documentation describes how to use the feeder generator API in detail. To quickly get started with the API and populate your first feeder, run the "feeder_demo.py" script after customizing the user config file "feeder_config.json5". This will generate a populated feeder model called "test.glm", which can then be immediately run using GridLAB-D™.

The populated feeder models are large files, tens of thousands of lines long with lengthy (but hopefully self-explanatory) names for all the feeder objects. If further modification of the model is needed, dig into the feeder config file to dial in the location, customer classes, DER deployment levels, and more. Alternatively, with careful editing, the "gld_feeder_generator.py" API itself can be modified to change integral aspects of the population process.

Taxonomy Feeders

Note that the first feeder of each series is bold for ease of reading this table.

Table 1: Summary of Prototypical Feeders

Feeder	kV	kVA	Description
R1-12.47-1	12.5	7152	Moderate suburban and rural
R1-12.47-2	12.47	2836	Moderate suburban and light rural
R1-12.47-3	12.47	1362	Small urban center
R1-12.47-4	12.47	5334	Heavy suburban
R1-25.00-1	24.9	2105	Light rural
R2-12.47-1	12.47	6046	Light urban
R2-12.47-2	12.47	6098	Moderate suburban
R2-12.47-3	12.47	1411	Light suburban
R2-25.00-1	24.9	17021	Moderate urban
R2-35.00-1	34.5	8893	Light rural
R3-12.47-1	12.47	8417	Heavy urban
R3-12.47-2	12.47	4322	Moderate urban
R3-12.47-3	12.47	7880	Heavy suburban
R4-12.47-1	13.8	5530	Heavy urban with rural spur
R4-12.47-2	12.5	2218	Light suburban and moderate urban
R4-25.00-1	24.9	948	Light rural
R5-12.47-1	13.8	9430	Heavy suburban and moderate urban
R5-12.47-2	12.47	4500	Moderate suburban and heavy urban
R5-12.47-3	13.8	9200	Moderate rural
R5-12.47-4	12.47	7700	Moderate suburban and urban
R5-12.47-5	12.47	8700	Moderate suburban and light urban
R5-25.00-1	22.9	12050	Heavy suburban and moderate urban
R5-35.00-1	34.5	11800	Moderate suburban and light urban
GC-12.47-1	12.47	5200	Single large commercial or industrial

Other Sample Models

PG&E Models

As a part of a project PNNL completed with Pacific Gas and Electric (PG&E), a number of distribution system models were converted into GridLAB-D™ format. These models have been made available as a part of the GridLAB-D™ distribution and offer the same benefits as the taxonomy feeder models: they are constructed from real-world systems and thus have some degree of realism built into them.

The models are broken into two portions. The first is the primary model and it represents the distribution system up to the point of the individual distribution transformers. The loads are expressed as generic ZIP loads at this higher voltage and use schedules and schedule transforms to generate the changes in load level over time. There are twelve different primary-side distribution models available.

In conjuction with these primary models, a few secondary system models have also been assembled, these representing the loads attached to a single distribution transformer, typically multiple houses. A number of scenarios for this model have been created to examine the effects of new distribution system load such as transients due to variability in solar PV output and loading due to EV charging. These models use house objects as well as some of the more experimental models such as dishwashers, ranges, and clothes driers.

The models can be found here and can be downloaded from the GridLAB-D™ repository just like the Taxonomy Feeder models or the GridLAB-D™ source code. There are a number of "readme.txt" files that provide more details and clarification on the use of the models.

Auto-test Models

One slightly sneaky way to understand how a particular class or feature in GridLAB-D™ is to look at the simple models the GridLAB-D™ developers have written to test the functionality of the feature. These models are part of the auto-test functionality built into GridLAB-D™ that developers use to ensure that development or modification in one part of the code doesn't inadvertently break some other portion of functionality.

The first step, if you haven't already, is to download the source code from GitHub. Afer following that link, scroll down to the README if you are unfamiliar with how to clone a repository.

Next, you'll need to find the portion of the source code that contains the feature of interest; check the Modeling Reference section for a breakdown of each module's contents. Inside the module folder is another folder named "autotest" and inside this folder is a number of model files and their supporting data files (weather, players, schedules, etc.) needed to run those models.

Now the moment of truth: do any of these autotest models contain the particular feature needed? Examining the names of the model files should be helpful but the only way to know for sure is looking into the files themselves.

If you do happen to find a model that contains what you're looking for, it will be important to strip out any assert object and their related parameter statements. These objects are what makes these models autotests; the assert object forces GridLAB-D™ to compare the values of the specified parameters as they are generated in simulation to pre-recorded values in a player file. If they differ by more than a specified amount, the simulation crashes, alerting the developer that something is wrong. For educational purposes, there is no need for such a comparison to be made.

Note that there's no guarantee what you're looking for will be in an autotest. Not all features have autotests and those that do may or may not be helpful in getting your model to work. The nice thing about the autotests, though, is that they are guaranteed to run correctly, since they must pass as a part of the release process.

Training Course Models

There has been previous training on GridLAB-D™ provided by developers over the years. Not only are the presentations used in that training provided but the models used as demonstrations and in-class exercises are as well. Perusing through these examples may reveal a whole or partial model that is useful. The training materials can be found under the course page of the GridLAB-D™ repository. "Tutorial" is the name of the folder containing the models described in these pages. The other pages are named for specific events, formats, or audiences.