Grid Analysis Toolkit#

The Grid Analysis Toolkit, or GAT, is a python library for providing a simplified and intiuitive interface across multiple Production Cost Modeling and Capacity Expansion Modeling tools related to the Bulk Electrical System.

GAT is primarily built on top of pandas, numpy and matplotlib. GAT also requires h5py and tables to interface with the common Sienna and H5PLEXOS.jl outputs. Objects and functions are designed to return pandas dataframes or matplotlib axes to allow for further customization.

Installation#

GAT can be installed via pip.

pip install nlr-gat

(The distribution is named nlr-gat because gat on PyPI is an unrelated genomics package; the import package and CLI are still gat.)

Or from GitHub, optionally pinning a release:

pip install git+https://github.com/NatLabRockies/GridAnalysisToolkit

pip install git+https://github.com/NatLabRockies/GridAnalysisToolkit@v0.1.0

Motivation#

There are many Simulation tools for modeling the Bulk Electrical System, each of which formats the input configuration, and output simulation files differently. However, each tool is ultimately describing the electrical grid in some way. Each tool simulates, describes or parameterizes some or all of the following, usually in a timeseries format.

Generation by Generator Type
Load by electrical buses or area
Energy Storage Charging and Discharging
Transmission Flow
Generator capacities
Line and Transformer capacities
Renewable Generation Availability

GAT intends to provide a unified API to all these types of datasets, regardless of the underlying format used by the modeling tool. Furthermore, by providing a unified API, GAT provides additional calculations and datasets not always available in each modeling tool.

Variable Renewable Energy Curtailment
Transmission Loading as a percentage of capacity.
State of Charge
Native Load, Total Load and Net Load (if one is missing)

The power system modeler and/or analyst often needs to aggregate and simplify data for presentation. GAT provides power system specific plotting functions for the following:

Annual and Monthly System Dispatch
Annual Dispatch by Geographic Areas
Dispatch during Peak And Minimum Demand Time Periods
Curtailment by Technology
Transmission Load Duration Curves.

Finally, data analysis and visualization often requires customization to meet project needs. GAT maintains flexiblity by returning pandas dataframes or matplotlib axes that can be further modified to meet the users specific requirements. Each layer of the API is easily accessible if the higher level abstractions fail to meet your needs.

“The data API is too abstract, I just want to read the raw data” -> Use one of the parser objects.
“The data API doesn’t cover a dataset that I need” -> Use a parser object or the internal scenario parser object.
“I need plot multiple subplots, some of which aren’t covered by gat.quickplots” -> Mix and Match the quickplots and custom plots since quickplots returns matplotlib axes objects.
“I need to make a plot that uses the same color scheme, but is not covered by quickplots” -> The quickplots core plots provide the core styling for dispatch plot order and color scheme, and can be used for plotting multiple scenarios against each other.

Configuration#

While GAT provides default configurations for Sienna and other National Lab of the Rockies (NLR) tools, it is usually the case that some initial configuration is required to map generation types into something geared towards the audience of the modeler or analyst. Below is a diagram of the mapping flow from model specific generators and types to GAT presentation level types and colors.

image info

For example, in a model you may want to distinguish between 2-hour and 4-hour energy storage types, but would like to combine these into an overall storage type. In GAT, you would do this by mapping both the storage duration types to storage, and then assign a corresponding color in GAT’s color map. If you don’t want to configure the color map, you can map the generation types to a key in the color map, and use NLR’s default color scheme.

More details on configuring GAT can be found on the Configuring GAT page.

Scenario Objects#

Scenario Objects are designed to give you a holistic view of Production Cost Model or Capacity Expansion Model simulation. Each Scenario inherits from the BaseScenario by implementing model specific implementations for extracting raw data (e.g. generation or flow) and defining how generators or nodes map to technologies or geographic areas. Once implemented, each model specific object gains access to the base class methods found in BaseScenario. Furthermore, each scenario object implements a set of parsers for gathering model specific raw data, in the case that the bae methods are not sufficient.

BaseScenario

Initialize a scenario object with configuration, system data, and solution data.

sienna

Provides a scenario handler for the Sienna simulation platform.

plexos

reeds

ReEDS Scenario Object for interfacing with ReEDsScenario across various ReEDS specific CSV files.

multi

Provides a multi-scenario handler for comparing multiple scenarios.

egret

EGRET - Scenario Object for interfacing with EGRET JSON system and simulation data.

file_scenario

Parsers#

Parser Objects provide access to raw simulation and system data in the form of dataframes and simple data structures like dictionaries or lists, with minimal data transformation or manipulation.

It is often the case that Power System simulations are run in parallel across multiple compute nodes, resulting in multiple output files that represent one 8760. Parsers can take a list of h5 files and treat them as one simulation run. When this is the case, the timeseries data are combined by keeping the tail end of the preceding run skipping the head of the following run. This is handled automatically in the Sienna and Plexos parsers.

sienna

parsers

Functions for parsing PLEXOS h5 files to produce generation, availability, load and line flow datasets.

Plotting#

GAT provides capabilities for plotting generation stacks and transmission related plots. These are intended to do most of the heavy lifting in terms of stack order and color schemes, while maintaining the flexibility to adjust, modify and add to the created plots.

Reports (Experimental)#

GAT provides command-line reporting framework based on configuration files. You can initialize and run reporting configurations using commands like gat init single --help and gat run single --help. Reports are generated using a combination of functions found in the Scenario Plots with output saved to a directory or packaged into a powerpoint presentation. Users can override default parameters to tune plots to their needs as well as omit plots.

Users may also extend GAT with custom plots — see Custom plots and the reporting framework for the @plot_function decorator, the two-tier plot API, and a worked example.

Project Management CLI (v1.0)#

GAT v1.0 introduces a comprehensive project management system for organizing your analysis work. Projects are self-contained directories with YAML configuration files that can be shared across teams using git.

Key Features:

Initialize projects with standard directory structure
Add scenarios (Sienna, ReEDS, Plexos) via CLI
Share projects via git repositories
User-level project references for easy access
Support for palettes, pipelines, and notebooks

Quick Start:

# Create a new project
gat project init my-analysis --name "My Analysis"

# Add a scenario
gat project add-scenario sienna base_case \
    --system ../data/system.json \
    --simulation ../data/results.h5

# List projects
gat project list

Python API#

GAT provides a simple Python API for loading and working with projects, scenarios, and palettes in scripts and notebooks.