Finding an equilibrium solution among several modules requires exchanging information that is common between modules and/or having modules access information contained in another module. The Prototype chooses to find an equilibrium solution through this integrator module.
The essential common information that modules exchange is related to prices and quantities, which have to coincide among the modules for an equilibrium. Modules might exchange other information, such as updated marginal costs and discount rates, but mathematically, there's two types of variables exchanged between modules:
-
Primal Variables, or those that explicitly are defined within the problem, and exist as unknowns that the problem solves for. This mostly include quantities.
-
Dual Variables, or those outputs available once the problem is solved but are not explicitly defined in the problem formulation. Examples of this are prices that are calculated from multipliers or shadow prices of market clearing conditions in individual modules.
The Prototype shows generalizable methods to exchange both these pieces of information under two different methods to solve for an equilibrium. While the Prototype only displays specific examples, they are programmed in a generalized way so that modules can exchange any primal and dual variables within modules. The "Primal" and "Dual" terminology is borrowed from mathematical optimization but can apply to any module depending on how the variables are defined. Note that any parameters could be exchanged as primal variables.
This module provides computational methods to integrate the sectoral modules and solve for equilibrium. The module exchanges prices (Dual Variables) and quantities (Primal Variables) as in the figure below until values converge.
The prototype has two different methods to solve for equilibrium, the iterative Gauss-Seidel and the unified single optimization method.
Mathematically, if both methods converge, the point they converge to is guaranteed to be an equilibrium. In our integrator methods, the Hydrogen demand is a primal variable, and in the unified optimization method, is coded as a variable that is shared in the overall problem. The Hydrogen price and Electricity price are dual variables and are only available after the optimization has been solved. The problem needs to be resolved with the updated dual variables until it converges. Other primal and dual variables that are common between modules can be coded by the methodology presented here.
A Gauss-Seidel iteration method mimics the current NEMS algorithm in a basic manner. The modules are solved iteratively with variables from other modules fixed as parameters until all modules converge. The unified single optimization method combines all modules into a single optimization problem and then iterates over dual variables until the values of the dual variables converge.
A unified single optimization method that combines all modules into a single optimization problem and then iterates over dual variables until the values of the dual variables converge.
The majority of the options for integrating and solving modules rely upon a configuration file located in the integrator folder: run_config.toml. This file contains settings shared across modules as well as settings specific to each module.
These switches specify whether a module will be included in a run.
| Switch | Description | Values |
|---|---|---|
| electricity | electricity module | false = Off true = On |
| hydrogen | hydrogen module | false = Off true = On |
| residential | residential module | false = Off true = On |
| Switch | Description | Values | Notes |
|---|---|---|---|
| force_10 | Forces 10 iterations to occur when running combo solves |
false = Off true = On |
Only allows for true/false options, does not impact H2 or elec modes |
| tol | Tolerance setting for iterative solves | Represents the acceptable percent difference in objective values between iterative solves needed to achieve convergence | |
| max_iter | Maximum number of iterations allowed | If tolerance criteria is not met, iterative solves will stop +1 solve after max_iter | |
| sw_temporal | Temporal resolution (inter-annual) switch |
default = 16 representative (rep) days and 4 rep hours d8h12 = 8 rep days and 12 rep hours d4h24 = 4 rep days and 24 rep hours |
Temporal switch to select different prespecified temporal resolutions. Advanced users can also specify their own temporal resolution by creating their own “cw_s_day” and “cw_hr” files in the “src\integrator\input\temporal_mapping” directory. See more details below in the temporal settings section |
The model runs a number of representative days (self-looping) with a number of periods (hour-several hours) per representative day. Any number of aggregated representative days can be used, but there must be at least 1 per season. The representative days and hours use a weighted average of inputs where necessary.
| Temporality | File | Description |
|---|---|---|
| Hours | cw_hr.csv | Contains the representative hour mapping crosswalk |
| Days | cw_s_day.csv | Contains the representative hour mapping crosswalk |
| Years | sw_year.csv | Contains the representative year mapping switches |
This model currently has 25 regions. Turning on and off certain regions allows only specific regions to be run.
| Regionality | File | Description |
|---|---|---|
| Regions | sw_reg.csv | Contains the representative region mapping switches |
Note: Hydrogen data currently has hydrogen production in Region 7 (only) for demonstration. Simple modifications to the data could expand this. Most of the instantiations of the Hydrogen model use the 'single_region' data folder in the H2 module
For more details about the module-specific settings provided in the configuration file, navigate to the model READMEs (e.g. Electricity, Residential, Hydrogen).
Navigate to the docs README for details on code documentation, as well as instructions for locally compliling Sphinx to generate an html version of the documenation.