Open basic version of EMPIRE in Pyomo.
The EMPIRE model and all additional files in the git repository are licensed under the MIT license. In short, that means you can use and change the code of EMPIRE. Furthermore, you can change the license in your redistribution but must mention the original author. We appreciate if you inform us about changes and send a merge request via git. For further information please read the LICENSE file, which contains the license text, or go to https://opensource.org/licenses/MIT
The EMPIRE model is available in the Python-based, open-source optimization modelling language Pyomo. Running the model thus requires some coding skills in Python. To run the model, make sure Python, Pyomo and a third-party solver (gurobi, FICO xpress, or CPLEX) is installed and loaded to the respective computer or cluster. More information on how to install Python and Pyomo can be found here: http://www.pyomo.org/installation. Other python package dependencies can be found in the file environment.yml.
To download, you need to install Git and clone the repository. Note that the repository makes use of Git Large File Storage (LFS) which also needs to be installed for input data-files to be downloaded when cloning the repository. Once both Git and Git LFS has been successfully installed, the model is downloaded to the desired directory.
EMPIRE consists of five programming scripts:
(1) run.py: The main script used to run EMPIRE. It links to all other scripts. This is the only script a user of EMPIRE needs to use and potentially modify.
(2) Empire.py: Contains the abstract formulation of EMPIRE in Pyomo. This script also contains code related to printing the results.
(3) scenario_random.py: Generates random operational scenarios as .tab-files through sampling.
(4) reader.py: Generates .tab-files input based on data provided in Excel workbooks.
(5) test_run.py: Same as the main run-script (run.py), but it is linked to a small test instance of EMPIRE that usually finishes in 1-2 min.
In the repository, the ‘Data handler’-folder contains the Excel workbooks that are used to store and modify input data. The workbooks are contained within folders representing instance-versions of EMPIRE, e.g. ‘europe_v50’. The ‘test’-folder contains input data for a small test-instance of EMPIRE. Within an instance-version in the ‘Data handler’-folder, there is a folder called ‘ScenarioData’ containing large data sets used to generate stochastic scenarios in EMPIRE. If EMPIRE is run with random scenario generation, representative time series are sampled once per scenario and season for each random input parameter.
The EMPIRE Model reads .tab-files, which provide all needed sets and input data. For editing and storing the data, excel-files are used. There are seven excel-files in total of which six contain indexed input data and one is to provide the indices/sets. The excel-files are sorted by the following categories: General data, generation data, country/node data, set/index data, transmission data, and storage data. These files contain multiple tables regarding for example investment costs and initial capacity.
For more details, please refer to the software documentation in the repository.
| Input name | Type | Default | Description |
|---|---|---|---|
| USE_TEMP_DIR | True/False | False | If true, all instance-files related to solving EMPIRE is stored in the directory defined by temp_dir (see below). This is useful when running a large instance of EMPIRE to avoid memory problems. |
| temp_dir | String | './' | The path to which temporary files will be stored if USE_TEMP_DIR = True; .lp-file is stored if WRITE_LP = True; and .plk-file is stored if PICKLE_INSTANCE = True. |
| version | String | 'europe_v50' | The name of the version to be run. Note that this is the folder-name containing input data in ‘Data handler’. |
| Horizon | Integer | 2060 | The last strategic (investment) period used in the optimization run. |
| NoOfScenarios | Integer | 3 | The number of scenarios in every investment period. |
| lengthRegSeason | Integer | 168 | The number of hours to use in a regular season for optimization of system operation in every investment period. |
| discountrate | Float | 0.05 | The discount rate. |
| WACC | Float | 0.05 | The weighted average cost of capital (WACC). |
| solver | String | "Xpress" | Specifies the solver. Options: “Xpress”, “Gurobi”, “CPLEX”. |
| scenariogeneration | True/False | True | If true, new operational scenarios will be generated. NB! If false, .tab-files or sampling key must be manually added to the ‘ScenarioData’-folder in the version. |
| fix_sample | True/False | False | If true, new operational scenarios will be generated. NB! If false, .tab-files or sampling key must be manually added to the ‘ScenarioData’-folder in the version. |
| EMISSION_CAP | True/False | True | If true, emissions in every scenario are capped according to the specified cap in ‘General.xlsx’. If false, the CO2-price specified in ‘General.xlsx’ applies. |
| IAMC_PRINT | True/False | True | If true, selected results are printed on the standard IAMC-format in addition to the normal EMPIRE print. |
| WRITE_LP | True/False | False | If true, the solver-file will be saved. Useful for debugging. |
| PICKLE_INSTANCE | True/False | False | If true, instance will be saved/pickled. Useful for printing alternative results. |
Note that building the instance in Pyomo for a base case of EMPIRE can take around 40 min. Therefore, it is good to run the ‘test_run.py’ first to confirm whether your computer or cluster connects to the preferred solver or not.
When all Pyomo and the preferred solver has been installed, the model is run by running the script ‘run.py’ in a Python interface. The code is run by using the following commands:
C:\Users\name> cd <path_to_folder>
C:\Users\name\path_to_folder> python run.py