ReEDS

Regional Energy Deployment System (ReEDS) Model

This GitHub repository contains the source code for NLR's ReEDS model.

The ReEDS model source code is available at no cost from the National Laboratory of the Rockies.

The ReEDS model can be downloaded or cloned from https://github.com/ReEDS-Model/ReEDS.

If you want to use the latest stable version of ReEDS, download or check out the latest stable release here.

For more information about the model, see the ReEDS Documentation.

ReEDS training videos are available on the NLR Learning YouTube channel.

Introduction

ReEDS is a capacity planning and dispatch model for the U.S. electricity system.

As NLR's flagship long-term power sector model, ReEDS has served as the primary analytic tool for many studies of electricity sector research questions.

Example model results are available in the Scenario Viewer.

Quick-start guide

The ReEDS model is written in Python, GAMS, and Julia.

Python and Julia are free, open-source languages.

GAMS requires a software license from the vendor.

A step-by-step guide for getting started with ReEDS is available here, and a quick-start guide for advanced users is outlined below.

1. Install UV and Python

Install UV:

curl -LsSf https://astral.sh/uv/install.sh | sh

Restart your terminal, then install Python 3.11:

uv python install 3.11

2. Set up GAMS

1. Install GAMS: https://www.gams.com/download/
2. Obtain a combined GAMS/CPLEX license: https://www.gams.com/sales/licensing/

Small ReEDS systems have been solved using the open-source COIN-OR solver as described here, but this capability is not actively maintained.

Other commercial solvers have also been successfully applied to ReEDS, but setup details and some solver tuning are specific to the CPLEX solver.

Ensure the gams executable is available on your PATH:

gams

GAMS typically installs directly into the top level directory, with a version number. A typical way to add gams to your user PATH variable in powershell is:

$currentPath = [Environment]::GetEnvironmentVariable("Path","User") #This gets the PATH Environment variable at the user scope
$addPath = 'C:/GAMS/53' # or wherever your gams install is
[Environment]::SetEnvironmentVariable("Path","$addPath;$currentPath","User")

3. Install Julia

Install Julia using juliaup:

curl -fsSL https://install.julialang.org | sh

Install the required Julia version:

juliaup add 1.12.1
juliaup default 1.12.1

Verify:

julia --version

4. Set up the ReEDS environment

Clone the repository:

git clone https://github.com/ReEDS-Model/ReEDS.git
cd ReEDS

Pin Python 3.11 for the project:

uv python pin 3.11

Create the UV-managed Python environment:

uv sync --extra dev

Instantiate the Julia environment:

julia --project=. instantiate.jl

Link large data files from shared folder, so we each don't store separate instances of this ~95GB of input data. Note you cannot do this in git bash as there are some type of strange permission issues, so use powershell:

New-Item -ItemType Junction -Path ".\inputs\remote" -Target "C:\Users\Public\Documents\reeds_data\remote"

Several large data files are hosted remotely. These files are downloaded automatically as needed during a ReEDS run, but the command above finishes all internet-requiring steps up front.

Additional details on remote files and other topics can be found in the user guide.

4.5 Optional PowerShell setup-and-run command (run_cepm.ps1)

Once you've cloned the repository, you can use the optional PowerShell helper run_cepm.ps1 to ensure supporting software is up to date and then immediately run runreeds.py:

.\run_cepm.ps1

This script performs the following steps in order:

1. Verifies GAMS is on PATH, checks GAMS license status, and prints a detected version string.
2. Verifies Julia is on PATH and checks that the version is 1.12.1.
3. Sets ReEDS environment variables for the current PowerShell session.
4. Checks that Python is pinned to 3.11 and runs uv python pin 3.11 if needed.
5. Runs uv sync --extra dev.
6. Instantiates Julia dependencies only when needed: a fast offline check (Pkg.instantiate without a registry update) skips the work when the environment is already current, and only falls back to the full julia --project=. instantiate.jl (which updates the registry) if dependencies changed or are missing.
7. Checks environment.yml against pyproject.toml and prints a non-fatal warning if they have drifted beyond the known-accepted allowlist (see CEPM/UV_MAMBA_GUIDE.md).
8. Forwards all arguments to runreeds.py.
9. Sends a best-effort ntfy.sh notification (topic rmi-cepm-run-batch-finished) before runreeds.py is launched and once it returns (on fail or success), so you can be alerted when a long-running batch finishes. Subscribe to the topic in the ntfy app or at https://ntfy.sh/rmi-cepm-run-batch-finished. A failed or offline notification is ignored. A failed or offline notification is ignored. Note: ntfy.sh topics are public; avoid including sensitive information in notifications.

Passing -y (or --skip-setup / --bypass) skips Step 5 (uv sync --extra dev) and Step 6 (Julia instantiation). All other checks and setup steps still run, and remaining arguments are still passed to runreeds.py

Two more bootstrap-only options: -q (or --quiet) disables the ntfy.sh notifications, and -u <name> (or --user <name>) includes <name> as the username in the notification messages (omitted when not given). All other arguments are forwarded to runreeds.py.

.\run_cepm.ps1 -y -b v20250314_main -c test
.\run_cepm.ps1 --bypass -b v20250314_main -c test

5. Run ReEDS

ReEDS currently expects Conda-style environment variables. When using UV, set these variables before running ReEDS or ideally in your dotenv file, so you don't ahve to do this before every run.

export CONDA_DEFAULT_ENV=reeds2
export CONDA_PREFIX="$PWD/.venv"

For interactive setup:

uv run python runreeds.py

For one-line operation:

uv run python runreeds.py -b v20260605 -c cepm

In this example, v20260605 is the prefix for this batch of cases, and cepm is the suffix of the cases file, in this case cases_cepm.csv, located in the root of the repository. For the batch prefix, we should follow the convention vYYYYMMDD, and note that the case ID from the cases file will be appended to the batch prefix for file naming purposes (e.g., WECC_county_100by2050).

Run the following for information on other optional command-line arguments:

uv run python runreeds.py -h

PowerShell users can run setup + launch in one command with run_cepm.ps1:

.\run_cepm.ps1 -b v20250314_main -c test

Troubleshooting

GAMS is not found

Confirm that GAMS is available on your PATH:

gams

If this fails, update your shell PATH to include the GAMS installation directory.

Julia setup fails

Re-run:

julia --project=. instantiate.jl

Python environment issues

Recreate the UV environment:

rm -rf .venv uv.lock
uv sync --extra dev

CONDA_DEFAULT_ENV error

When running with UV, set:

export CONDA_DEFAULT_ENV=reeds2
export CONDA_PREFIX="$PWD/.venv"

Then rerun the command with uv run.

Contact Us

If you have comments and/or questions, contact the ReEDS team at ReEDS.Inquiries@nlr.gov or post a question on the discussion pages.