/GenX

GenX: a configurable power system capacity expansion model for studying low-carbon energy futures. More details at : https://genx.mit.edu

Primary LanguageJuliaGNU General Public License v2.0GPL-2.0

GenX

GenX

Build Status Coverage Status

Dev ColPrac: Contributor's Guide on Collaborative Practices for Community Packages

Overview

GenX is a highly-configurable, open source electricity resource capacity expansion model that incorporates several state-of-the-art practices in electricity system planning to offer improved decision support for a changing electricity landscape.

The model was originally developed by Jesse D. Jenkins and Nestor A. Sepulveda at the Massachusetts Institute of Technology and is now jointly maintained by a team of contributors at the MIT Energy Initiative (led by Dharik Mallapragada) and the Princeton University ZERO Lab (led by Jenkins).

GenX is a constrained linear or mixed integer linear optimization model that determines the portfolio of electricity generation, storage, transmission, and demand-side resource investments and operational decisions to meet electricity demand in one or more future planning years at lowest cost, while subject to a variety of power system operational constraints, resource availability limits, and other imposed environmental, market design, and policy constraints.

GenX features a modular and transparent code structure developed in Julia + JuMP. The model is designed to be highly flexible and configurable for use in a variety of applications from academic research and technology evaluation to public policy and regulatory analysis and resource planning. Depending on the planning problem or question to be studied, GenX can be configured with varying levels of model resolution and scope, with regards to: (1) temporal resolution of time series data such as electricity demand and renewable energy availability; (2) power system operational detail and unit commitment constraints; and (3) geospatial resolution and transmission network representation. The model is also capable of representing a full range of conventional and novel electricity resources, including thermal generators, variable renewable resources (wind and solar), run-of-river, reservoir and pumped-storage hydroelectric generators, energy storage devices, demand-side flexibility, demand response, and several advanced technologies such as long-duration energy storage.

The 'main' branch is the current master branch of GenX. The various subdirectories are described below:

  1. src/ Contains the core GenX model code for reading inputs, model generation, solving and writing model outputs.

  2. Example_Systems/ Contains fully specified examples that users can use to test GenX and get familiar with its various features. Within this folder, we have two sets of examples:

  • RealSystemExample/, a detailed system representation based on ISO New England and including many different resources (upto 58)
  • SmallNewEngland/ , a simplified system consisting of 4 different resources per zone.

  1. docs/ Contains all the documentation pertaining to the model.

  2. GenXJulEnv Contains the .toml files related to setting up the Julia environment with all the specified package versions in julenv.jl.

Requirements

GenX currently exists in version 0.3.0 and runs only on Julia v1.6.x and v1.5.x series, where x>=0 and a minimum version of JuMP v0.21.x. There is also an older version of GenX, which is also currently maintained and runs on Julia 1.3.x and 1.4.x series (For those users who has previously cloned GenX, and has been running it successfully so far, and therefore might be unwilling to run it on the latest version of Julia: please look into the GitHub branch, old_version). It is currently setup to use one of the following open-source freely available solvers: A) Clp for linear programming (LP) problems and (B) Cbc for mixed integer linear programming (MILP) problems. (C) SCIP for faster solution of MILP problems. At this stage, we suggest users to prefer SCIP over Cbc, while solving MILP problem instances, because, the write outputs is much faster with SCIP. We also provide the option to use one of these two commercial solvers: D) Gurobi, and E) CPLEX. Note that using Gurobi and CPLEX requires a valid license on the host machine. There are two ways to run GenX with either type of solver options (open-source free or, licensed commercial) as detailed in the section, Running an Instance of GenX.

The file julenv.jl in the parent directory lists all of the packages and their versions needed to run GenX. You can see all of the packages installed in your Julia environment and their version numbers by running pkg> status on the package manager command line in the Jula REPL.

Documentation

Detailed documentation for GenX can be found here. It includes details of each of GenX's methods, required and optional input files, and outputs. Interested users may also want to browse through prior publications that have used GenX to understand the various features of the tool. Full publication list is available here.

Running an Instance of GenX

Download or clone the GenX repository on your machine in a directory named 'GenX'. Create this new directory in a location where you wish to store the GenXJulEnv environment.

The Run.jl file in each of the example sub-folders within Example_Systems/ provides an example of how to use GenX.jl for capacity expansion modeling. The following are the main steps performed in the Run.jl script:

  1. Establish path to environment setup files and GenX source files.
  2. Read in model settings GenX_Settings.yml from the example directory.
  3. Configure solver settings.
  4. Load the model inputs from the example directory and perform time-domain clustering if required.
  5. Generate a GenX model instance.
  6. Solve the model.
  7. Write the output files to a specified directory.

Here are step-by-step instructions for running Run.jl, following the two slightly different methods:

Method 1: Creating the Julia environment and installing dependencies from Project.toml file

  1. Start a terminal and navigate into the GenX folder.
  2. Type julia --project=. to start an instance of the julia kernal with the project set to the current folder. The . indicates the current folder.

If it's your first time running GenX (or, if you have pulled after some major upgrades/release/version) execute steps 3-6.

  1. Type ] to bring up the package system (GenX) pkg > prompt. This indicates that the GenX project was detected. If you see (@v1.6) pkg> as the prompt, then the project was not successfully set.
  2. Type instantiate from the (GenX) pkg prompt.
  3. Type st to check that the dependecies have been installed.
  4. Type the back key to come back to the julia> prompt.

Steps 3-6 can be skipped on subsequent runs. Execution of the entire sequence of the six steps is shown in Figure 1.

Creating the Julia environment and installing dependencies from Project.toml file from inside the GenX folder: Steps 1-6 Figure 1. Creating the Julia environment and installing dependencies from Project.toml file from inside the GenX folder: Steps 1-6

  1. Run the script by executing the command julia> include(“<path to your case>/Run.jl”). For example, in order to run the OneZone case within the Example_Systems/SmallNewEngland folder, type include("Example_Systems/SmallNewEngland/OneZone/Run.jl") from the julia> prompt.

Execution of step 7 should look like the figure below:

Creating the Julia environment and installing dependencies from Project.toml file from inside the GenX folder: Step 7 Figure 2. Creating the Julia environment and installing dependencies from Project.toml file from inside the GenX folder: Step 7

  1. After the script runs to completion, results will be written to a folder called “Results”, located in the same directory as Run.jl.

Method 2: Creating the Julia environment and installing the dependencies by building the Project.toml files by running activation script

  1. Start an instance of the Julia kernel.
  2. Make your present working directory to be where the Run.jl is located. To do this, you can use the Julia command julia> cd(“/path/to/directory/containing/file), using the actual pathname of the directory containing Run.jl. Note that all your inputs files should be in this directory in addition to Run.jl. Details about the required input files can be found in the documentation linked above or in the examples provided in the folder Example_Systems/. You can check your present working directory by running the command julia> pwd().
  3. Uncomment the following lines of code at the beginning of the Run.jl file (which is currently commented out): environment_path = "../../../package_activate.jl" include(environment_path)
  4. Run the script by executing the command julia> include(“Run.jl”).
  5. After the script runs to completion, results will be written to a folder called “Results”, also located in the same directory as Run.jl.

Note that if you have not already installed the required Julia packages, you are using a version of JuMP other than v0.21.4, or you do not have a valid Gurobi license on your host machine, you will receive an error message and Run.jl will not run to completion.

When using commercial solvers, Gurobi and CPLEX

If you want to use either of Gurobi or CPLEX solvers, instead or Clp or Cbc do the following:

  1. Open the Guide_to_Project.toml file within the GenX folder
  2. If you want to have only Gurobi (but, not CPLEX) solver, use the [deps] and the [compat] from underneath the header: [deps]/UUIDs to be used when not using CPLEX and the header [compat]/version numbers to be used when not using CPLEX respectively. If one the other hand, if you want to use CPLEX (along with Gurobi; you can delete the relevant lines of Gurobi, in case you don't want to use it) then use the [deps] and the [compat] from underneath the header: [deps]/UUIDs to be used when using CPLEX and the header [compat]/version numbers to be used when using CPLEX respectively, from the Guide_to_Project.toml file. Copy the corresponding lines and paste them in the Project.toml file. Alternatively, you can also copy only the [deps] and [compat] for just the commercial solvers and paste those at respective places in the Project.toml file.
  3. Uncomment the relevent using Gurobi and/or using CPLEX at the beginning of the GenX.jl file
  4. Set the appropriate solver in the genx_settings.yml file
  5. Make sure you have a valid license and the actual solvers for either of Gurobi or CPLEX installed on your machine

Note that if you have not already installed the required Julia packages, you are using a version of JuMP other than v0.21.4, or you do not have a valid Gurobi license on your host machine, you will receive an error message and Run.jl will not run to completion.

Running Modeling to Generate Alternatives with GenX

GenX includes a modeling to generate alternatives (MGA) package that can be used to automatically enumerate a diverse set of near cost-optimal solutions to electricity system planning problems. To use the MGA algorithm, user will need to perform the following tasks:

  1. Add a Resource_Type column in the Generators_data.csv file denoting the type of each technology.
  2. Add a MGA column in the Generators_data.csv file denoting the availability of the technology.
  3. Set the ModelingToGenerateAlternatives flag in the GenX_Settings.yml file to 1.
  4. Set the ModelingtoGenerateAlternativeSlack flag in the GenX_Settings.yml file to the desirable level of slack.
  5. Create a Rand_mga_objective_coefficients.csv file to provide random objective function coefficients for each MGA iteration. For each iteration, number of rows in the Rand_mga_objective_coefficients.csv file represents the number of distinct technology types while number of columns represent the number of model zones.
  6. Solve the model using Run.jl file.

Results from the MGA algorithm would be saved in MGA_max and MGA_min folders in the Example_Systems/ folder.

Limitations of the GenX Model

While the benefits of an openly available generation and transmission expansion model are high, many approximations have been made due to missing data or to manage computational tractability. The assumptions of the GenX model are listed below. It serves as a caveat to the user and as an encouragement to improve the approximations.

Time period

GenX makes the simplifying assumption that each time period contains n copies of a single, representative year. GenX optimizes generation and transmission capacity for just this characteristic year within each time period, assuming the results for different years in the same time period are identical. However, the GenX objective function accounts only for the cost of the final model time period.

Cost

The GenX objective function assumes that the cost of powerplants is specified in the unit of currency per unit of capacity. GenX also assumes that the capital cost of technologies is paid through loans.

Market

GenX is a bottom-up (technology-explicit), partial equilibrium model that assumes perfect markets for commodities. In other words, each commodity is produced such that the sum of producer and consumer surplus is maximized.

Technology

Behavioral response and acceptance of new technology are often modeled simplistically as a discount rate or by externally fixing the technology capacity. A higher, technology-specific discount rate represents consumer reluctance to accept newer technologies.

Uncertainty

Because each model realization assumes a particular state of the world based on the input values drawn, the parameter uncertainty is propagated through the model in the case of myopic model runs

Decision-making

GenX assumes rational decision making, with perfect information and perfect foresight, and simultaneously optimizes all decisions over the user-specified time horizon.

Demand

GenX assumes price-elastic demand segments that are represented using piece-wise approximation rather than an inverse demand curve to keep the model linear.

How to cite GenX

We recommend users of GenX to cite it in their academic publications and patent filings. Here's the text to put up as the citation for GenX: `MIT Energy Initiative and Princeton University ZERO lab. GenX: a configurable power system capacity expansion model for studying low-carbon energy futures n.d. https://github.com/GenXProject/GenX

pygenx: Python interface for GenX

Python users can now run GenX from a thin-python-wrapper interface, developed by Daniel Olsen. This tool is called pygenx and can be cloned from the github page: pygenx. It needs installation of Julia 1.3 and a clone of GenX repo along with your python installation.

Simple GenX Case Runner: For automated sequential batch run for GenX

It is now possible to run a list of GenX cases as separate batch jobs. Alternatively, they can also be run locally in sequence, as one job. It has been developed by Jacob Schwartz. This tool is called SimpleGenXCaseRunner and can be cloned from the github page: SimpleGenXCaseRunner

Bug and feature requests and contact info

If you would like to report a bug in the code or request a feature, please use our Issue Tracker. If you're unsure or have questions on how to use GenX that are not addressed by the above documentation, please reach out to Sambuddha Chakrabarti (sc87@princeton.edu), Jesse Jenkins (jdj2@princeton.edu) or Dharik Mallapragada (dharik@mit.edu).

GenX Team

GenX has been developed jointly by researchers at the MIT Energy Initiative and the ZERO lab at Princeton University. Key contributors include Nestor A. Sepulveda, Jesse D. Jenkins, Dharik S. Mallapragada, Aaron M. Schwartz, Neha S. Patankar, Qingyu Xu, Jack Morris, Sambuddha Chakrabarti.