There are three assets that make up the scenario modeler:
- The electricity baseline (i.e., ElectricityLCI
- The grid mixer and TRACI impacts (i.e., Grid Mix Explorer v.4.2)
- The additional air and water impacts (i.e., elci-to-rfm, elci-to-traci, and elcaware)
The scenario modeler ideally links these three assets together and provides customization with respect to:
- static EIA Annual Energy Outlook scenario or user-defined custom technology mix percentages
- scalability as new technologies come online
- variable temporal resolutions (e.g., annual average down to monthly mix profiles)
- regionaliation (e.g., national down to balancing authority mix profiles)
The output of scenario modeler are the inputs into elci-to-rfm, elci-to-traci, and elcaware.
The unofficial fourth asset is the visualization framework, which should be flexible enough to visualize the impact outputs (e.g., AQI, TRACI, and water scarcity) of the scenario modeler.
For more information on elci-scenario-modeler Python package, see the documentation (e.g., './docs').
├── docs/ <- Sphinx documentation files.
│ ├── (build/)
│ │ └── (html/) <- Rendered html files (generated by Sphinx).
│ ├── source/ <- Documentation source files.
│ │ The files 'modules.rst' and
│ │ 'grid_mixer*.rst' were created using
│ │ `sphinx-apidoc` command. The remaining
│ │ reStructuredText files were manually
│ │ created.
│ ├── make.bat <- Windows batch file for running 'make' command
│ └── Makefile <- Makefile for other OS's.
│ To build the HTML from source, run `make html`
│ from this directory. The output will go to a new
│ untracked folder, 'build/', which includes a
│ subdirectory 'html/'.
│
├── grid_mixer/ <- Source code for this package.
│ ├── __init__.py <- Makes this a Python package
│ ├── data_manager.py <- Provides the base functionality for a
│ │ data manager class.
│ ├── eia_utils.py <- Extends the functionality of EIA's
│ │ data tools (e.g., API for AEO)
│ ├── elci_utils.py <- Takes 'the best of' electricityLCI
│ │ and extends upon it for reuse.
│ ├── fleet.py <- Provides the Fleet class, a model for
│ │ customizing scenarios for analysis.
│ ├── global_conf.py <- Provides the configuration class with
│ │ access to user-defined parameters via
│ │ a YAML file.
│ ├── grid_mix_data.py <- Provides extended functionality
│ │ for the data manager class.
│ ├── grid_mixer.py <- The scenario-modeler main class.
│ ├── misc_utils.py <- This module provides miscellaneous
│ │ utility functions that may be used by
│ │ all classes.
│ └── mix_manager.py <- Provides a database-esque management
│ class for optimized data organization.
│
├── inputs/ <- The default location for input data files.
│ │ Individual data file and folder names are defined
│ │ in the configuration file. Examples provided here
│ │ in parentheses are for known required files, which,
│ │ if not found, are generated during the first run
│ │ of the program and can be found in the 'outputs/'
│ │ directory.
│ │
│ ├── emmr_crosswalk.csv <- Plant ID to EMM region code mapping
│ │ provided by AEO2022 model (received
│ │ upon request) and used to update the
│ │ facility metadata. For EMMR naming,
│ │ see 'get_region_dict' in eia_utils.py.
│ └── (elci_inventory/)
│ └── (eLCI_plant_upstream.csv.zip)
│
├── (outputs/) <- The default folder for exporting data files.
│ (auto-generated if absent)
│
├── resources/ <- Resource directory.
│ ├── facility_template.xlsx <- Excel workbook template for custom
│ │ facility inventory and metadata.
│ ├── m.ipynb <- Jupyter notebook on spatial translation
│ │ from EMM region to BA areas.
│ └── template_parser.py <- Parser to create data files and
│ configuration file from Excel template
│
├── config.yaml <- The scenario-modeler package's default
│ configuration file, written in YAML format.
├── LICENSE <- Package licensing information; CC0 1.0
│ https://creativecommons.org/publicdomain/zero/1.0/
├── main.py <- Stand alone script that walks through
│ all the processes of the model.
│ IF YOU ARE RUNNING THIS MODEL, THIS
│ IS THE SCRIPT YOU SHOULD START WITH.
├── README.md <- The top-level README.
└── setup.py <- Makes package pip installable (`pip install -e .`).
(see Installation section for troubleshooting)
- Clone the repository
git clone https://github.com/NETL-RIC/elci-scenario-modeler.git- Create a new Python environment
Using conda:
conda create -n mixer -y python=3.12Using virtualenv:
mkvirtualenv -p /usr/local/bin/python3.12 mixer- Activate your virtual environment
Conda
conda activate mixer
activate mixerVirtualenv
workon mixer- Check your packages (should be pretty empty)
pip listYou should see something like the following:
Package Version
---------- -------
pip 24.1.1
setuptools 70.2.0
wheel 0.43.0
- Install dependencies
Get LCIAFMT, which includes numpy, pandas, fedelemflowlist, PyYAML, requests, openpyxl, etc.
pip install git+https://github.com/USEPA/LCIAformatter.git#egg=lciafmtGet the development branch of ElectricityLCI
pip install git+https://github.com/USEPA/ElectricityLCI.git@development#egg=electricitylciInstallation and general user manual are now available in the documentation located in the 'docs/source' directory. To generate the HTML version of the documentation, follow the Sphinx-specific instructions below.
To install the dependencies to run this package, in a Python (virtual) environment run the following from the same directory where the "setup.py" file is located:
pip install -e .NOTE: this package is updated for ElectricityLCI version 2. If you are trying to run with ElectricityLCI version 1.0.1, see instructions below.
Troubleshooting
- Create new virtual environment
$ conda create -n lca python=3.11-
Download repositories from GitHub archives
-
Extract each zip folder.
-
Edit the setup.py script in ElectricityLCI
- Delete lines 14--15
- 'fedelemflowlist @ git+https://github.com/USEPA/Federal-LCA-Commons-Elementary-Flow-List@v1.0.2#egg=fedelemflowlist',
- 'StEWI @ git+https://github.com/USEPA/standardizedinventories@v0.9.3#egg=StEWI',
- Save setup.py
- Delete lines 14--15
-
Install the dependencies above in order locally (note the folder paths below may be different depending on how and where you extract each zip folder).
cd fedelemflowlist-1.0.2\fedelemflowlist-1.0.2
pip install .
cd ..\..
cd standardizedinventories-0.9.3\standardizedinventories-0.9.3
pip install .
cd ..\..
cd ElectricityLCI-1.0.1\ElectricityLCI-1.0.1
pip install .Repeat the steps above for the optional lciafmt version 1.0.3.
Note that if you want to build the HTML-based documentation, also install the following:
pip install sphinx
pip install sphinxcontrib-bibtexThis Python package was developed and tested using Python 3.9.10 with the following package versions:
- numpy 1.21.5
- pandas 1.3.5
- PyYAML 6.0
- ElectricityLCI 1.0.1
- fedelemflowlist 1.0.8
- lciafmt 1.0.3 (optional for TRACI methods only)
The Sphinx documentation (e.g., HTML) was created (in part) by running the following commands from the './docs' directory.
Begin with Sphinx's quickstart:
sphinx-quickstartChoose to separate build and source. Define the project name, authors, and current release number.
The next command autogenerates the reStructuredText files based on the definitions provided in the Python models found one folder level higher than 'docs' (i.e., files imported within the __init__.py script).
sphinx-apidoc -M -f -e -o ./source ..The '-M' flag for sphinx-apidoc will move the module documentation to the top of the reading order (otherwise it appears at the bottom).
The '-f' flag for sphinx-apidoc will force the re-creation of the .rst files found in the ./docs/source directory.
The '-e' flag for sphinx-apidoc will create individual .rst files for each module.
The '-o' flag precedes the output directory for the autogenerated reStructured Text, which should point to the ./docs/source directory.
The important document that is created from running this command is the 'modules.rst' file. After the reStructuredText files are created, additional files and edits can be made.
For this project, the 'setup' and 'main' modules are removed from the 'modules.rst' TOC (along with their RST files from the repository). Additional documentation files, 'about.rst,' 'assessments.rst,' 'background.rst,' 'challenges.rst,' 'configuration.rst,' and 'references.rst' were created and added to the 'index.rst' TOC tree. Note that "modules" was also added to the originally generated "index.rst" under the main TOC section.
To render these source files to HTML, run the following command from the 'docs' directory:
make htmlThe 'make html' command evokes the Makefile, which will generate the html version of the source documentation in the ./docs/build/html directory.
Note that both sphinx (pip install sphinx) and make (e.g., Xcode command line tools) applications are required to run the above commands.
There is a batch file for Windows users.
This package's documentation was successfully compiled using Sphinx v.4.4.0 and GNU make v.3.81.
Sphinx documentation utilizes the reStructuredText markup language rather than Markdown.
For assistance with this style, see D. Goodger's reStructuredText Markup Specification.
For the handling of references, the Sphinx contributor's extension, sphinxcontrib-bibtex is used, which requires installation (e.g., using pip; see here).
The bibliography entries are located in a separate document formatted for BibTeX (i.e., refs.bib).
THe extension and its associated parameters should be added to the 'conf.py' script found in the ./docs/source directory.
A few notable reminders:
- Element blocks (e.g., paragraphs and lists) are left-aligned. When starting a new line, be sure to keep the new line aligned with the one above. This is tricky with lists as a tab typically exceeds the two or three spaces before the beginning of the text on the line with the asterisk, dash, or number.
2025-05-12
- Version 2.5 released (public)
2025-05-09
- Host scenario-modeler on NETL-RIC/elci-scenario-modeler
2022-12-07
- Version 2.0 released (non-public)
2022-04-15
- Version 1.1 released (non-public)
2022-04-05
- Add version 1.0 UML class diagram
- Simplify package installation instructions
2022-03-25
- Version 1.0.0 released (non-public)
2022-03-10
- Create Sphinx documentation (see './docs' folder) and moved bulk of background and configuration file info there
- Add Sphinx documentation generation and rendering help to the README
2022-01-06
- Change repository name from "elci_grid_mixer" to "scenario-modeler"