GAT - Grid Analysis Toolkit

A toolkit for wrangling data for Bulk Grid Dispatch and Transmission Analysis.

GAT aims to provide simplified access to PCM and CEM results in a standard format while also allowing raw data access to underlying datasets specific to the model.

For plotting, GAT defaults to standard National Lab of the Rockies (NLR) color schemes and standard styles while allowing customization.

[!WARNING] GAT's public API is still evolving. Expect breaking changes between releases before v1.0 — pin an exact version (e.g. nlr-gat==0.1.0) if you need stability.

[!WARNING] Support for PLEXOS solution files produced by H5PLEXOS.jl (.h5) will be removed in v0.2.0. Load native PLEXOS Solution.zip files through the DuckDB-backed engine instead: install with pip install "nlr-gat[plexos]" and pass the .zip path directly to PlexosScenario — backend selection is automatic.

Installation

It is recommended to create a virtual environment for installing GAT.

In your desired directory, run one of the following.

python -m venv .venv

python3 -m venv .venv

Then activate your virtual environment by running.

. .venv/bin/activate on MacOS or Linux

or .venv/Scripts/Activate on Windows. If you are having trouble activating the virtual environment on Windows, you may need to update your execution policy. More can be read here.

Install the latest release from PyPI:

pip install nlr-gat

Note: the distribution is named nlr-gat because gat on PyPI is an unrelated genomics package. The import package and CLI are still gat, which also means nlr-gat cannot share an environment with that genomics package.

Choosing extras

The bare install above pulls in only the format-agnostic core — no scenario handler is usable yet. Each simulation/model format has its own extra, so you only install the (often large, native-code) dependencies you actually need:

Combine as needed, e.g.:

pip install "nlr-gat[sienna,plots]"

pip install "nlr-gat[plexos,server]"

pip install "nlr-gat[all]"

Or install from GitHub — the latest, a specific release, or a branch:

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

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

pip install git+https://github.com/NatLabRockies/GridAnalysisToolkit@{branch_name}

Documentation

The latest stable documentation lives at natlabrockies.github.io/GridAnalysisToolkit. The example gallery is a good starting point for visual capability.

Highest-traffic doc pages (also readable directly in the repo):

• Quickstart: scenarios and palettes
• Python API: gat.load(...)
• Sienna scaling and raw dataset access
• Custom plots and the reporting framework
• v1 architecture & migration pattern
• Legacy scenario handler deprecation
• Migrating from v0.x to v1.0
• Changelog

Example data

example_data/ is gitignored — the binaries are too large to track in-tree. Sienna fixtures regenerate via make sienna-fixture-v4 (requires Docker; see docker/sienna/README.md). For Plexos (pip install nlr-gat[plexos]), point the GAT_PLEXOS_FIXTURE environment variable at a directory of .h5 solution files of your own, or GAT_PLEXOS_ZIP_FIXTURE at a native PLEXOS Solution.zip.

Contributing

If you wish to contribute to the development of GAT, please clone the repo and install the dev dependencies as follows.

git clone https://github.com/NatLabRockies/GridAnalysisToolkit.git

cd GridAnalysisToolkit

Follow the instructions for creating a virtual environment above, then:

pip install -e ".[dev]"

When you are ready, please open a pull request for review.

If you plan to contribute to documentation, install the documentation dependencies as well.

pip install -e ".[dev,doc]"

Commit messages and PR titles should follow Conventional Commits (feat: ..., fix: ..., docs: ..., etc.) — releases are generated automatically from these (see .github/workflows/release.yml).

Building the documentation

After installing the doc dependencies:

cd docs && sphinx-build -b html source build/html

Review documentation changes locally:

open build/html/index.html

Software Record and Disclaimer

GAT is developed by the National Lab of the Rockies (NLR) and released under software record SWR-25-41 "GAT (Grid Analysis Toolkit)".

See DISCLAIMER.md for the full disclaimer.