diff --git a/CHANGELOG.md b/CHANGELOG.md index 201e5f9e9..f1cec9631 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,7 @@ # Changelog ## Unreleased +- Updated README and docs intro page with expanded H2I description, reorganized sections, and streamlined installation instructions [PR 677](https://github.com/NatLabRockies/H2Integrate/pull/677) - Update energy conversion ratio in H2 SMR model [PR 606](https://github.com/NatLabRockies/H2Integrate/pull/606) - Update iron models and examples [PR 601](https://github.com/NatLabRockies/H2Integrate/pull/601) - Remove outdated iron files diff --git a/README.md b/README.md index b0f594115..33bc4a961 100644 --- a/README.md +++ b/README.md @@ -4,18 +4,55 @@ ![CI Tests](https://github.com/NatLabRockies/H2Integrate/actions/workflows/ci.yml/badge.svg) [![image](https://img.shields.io/pypi/pyversions/H2Integrate.svg)](https://pypi.python.org/pypi/H2Integrate) [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) -[![DOI:10.5281/zenodo.17903150](https://zenodo.org/badge/DOI/10.5281/zenodo.17903149.svg)](https://zenodo.org/records/17903149) +[![DOI 10.5281/zenodo.17903150](https://zenodo.org/badge/DOI/10.5281/zenodo.17903150.svg)](https://zenodo.org/records/17903150) -[![DOI 10.1088/1742-6596/2767/8/082019](https://img.shields.io/badge/DOI-10.1088%2F1742--6596%2F2767%2F8%2F082019-brightgreen?link=[https://doi.org/10.1088/1742-6596/2767/8/082019](https://doi.org/10.1088/1742-6596/2767/8/082019))](https://iopscience.iop.org/article/10.1088/1742-6596/2767/8/082019/pdf) -[![DOI 10.1088/1742-6596/2767/6/062017](https://img.shields.io/badge/DOI-10.1088%2F1742--6596%2F2767%2F6%2F062017-brightgreen?link=[https://doi.org/10.1088/1742-6596/2767/6/062017](https://doi.org/10.1088/1742-6596/2767/6/062017))](https://iopscience.iop.org/article/10.1088/1742-6596/2767/6/062017/pdf) -[![DOI 10.21203/rs.3.rs-4326648/v1](https://img.shields.io/badge/DOI-10.21203%2Frs.3.rs--4326648%2Fv1-brightgreen?link=[https://doi.org/10.21203/rs.3.rs-4326648/v1](https://doi.org/10.21203/rs.3.rs-4326648/v1))](https://assets-eu.researchsquare.com/files/rs-4326648/v1_covered_338a5071-b74b-4ecd-9d2a-859e8d988b5c.pdf?c=1716199726) +H2Integrate (H2I) is an open-source Python package for hybrid energy systems engineering design and technoeconomic analysis. +It models hybrid systems, especially hybrid energy plants that produce electricity, hydrogen, ammonia, steel, and other products, to perform optimization and scenario analysis. -H2Integrate is an open-source Python package for modeling and designing hybrid energy systems producing electricity, hydrogen, ammonia, steel, and other products. +## Installation -Note: The current version of H2Integrate is under active development and may be missing features that existed previously. H2Integrate v0.2.0 is the last version that uses the prior framework. +The recommended installation method is via pip from PyPI, which will install the latest stable release of H2Integrate and its dependencies: + +```bash +pip install h2integrate +``` + +For installing from source, development setup, and additional installation options, see the [full installation instructions](https://h2integrate.readthedocs.io/en/latest/getting_started/install.html). + +## What H2Integrate Does + +H2Integrate is both a **hybrid systems engineering design tool** and a **technoeconomic analysis (TEA) tool**. It significantly expands beyond generalized tools by offering: + +- **Detailed equipment-level modeling** with a wide range of subsystem variation options +- **High-resolution, location-specific resource data** for site-dependent performance modeling +- **Cost inputs settable by the user** with examples based on the [Annual Technology Baseline (ATB)](https://atb.nlr.gov/) +- **Optimization and scenario analysis** to explore design trade-offs across hybrid plant configurations + +### Available Technologies + +H2I includes models for a broad set of energy generation, conversion, and storage technologies. +This is a non-exhaustive list, and the library of available technologies is actively expanding: + +- **Electricity generation**: solar PV, wind, wave, tidal, natural gas combined cycle (NGCC), natural gas combustion turbines (NGCT), nuclear, grid +- **Hydrogen production**: PEM electrolysis, NG-SMR +- **Energy storage**: Li-ion batteries, long-duration energy storage (LDES), pumped storage hydropower (PSH) +- **Fuel cells**: H2 PEM fuel cells +- **Industrial processes**: ammonia synthesis, iron ore reduction, steel production, and more + +## Getting Started + +See the [Getting Started guide](https://h2integrate.readthedocs.io/en/latest/intro.html) for an introduction to H2Integrate. +The [Examples folder](./examples/) contain Jupyter notebooks, Python scripts, and sample YAML files for common usage scenarios. + +## Publications + +For a full list of publications, see the [Publications section in the documentation](https://h2integrate.readthedocs.io/en/latest/intro.html#publications). +Note: H2Integrate was previously known as GreenHEART, and some publications may refer to it by that name. ## Software Citation +If you use H2I or any of its components in your work, please cite this in your publications using the following BibTeX: + ```bibtex @software{brunik_2025_17903150, author = {Brunik, Kaitlin and @@ -50,197 +87,6 @@ Note: The current version of H2Integrate is under active development and may be } ``` -## Publications where H2Integrate has been used - -For more context about H2Integrate and to see analyses that have been performed using the tool, please see some of these publications. -PDFs are available in the linked titles. - -### Nationwide techno-economic analysis of clean hydrogen production powered by a hybrid renewable energy plant for over 50,000 locations in the United States. - -The levelized cost of hydrogen is calculated for varying technology costs, and tax credits to -explore cost sensitivities independent of plant design, performance, and site selection. Our -findings suggest that strategies for cost reduction include selecting sites with abundant wind -resources, complementary wind and solar resources, and optimizing the sizing of wind and solar -assets to maximize the hybrid plant capacity factor. - -Grant, E., et al. "[Hybrid power plant design for low-carbon hydrogen in the United States.](https://iopscience.iop.org/article/10.1088/1742-6596/2767/8/082019/pdf)" Journal of Physics: Conference Series. Vol. 2767. No. 8. IOP Publishing, 2024. - -### Exploring the role of producing low-carbon hydrogen using water electrolysis powered by offshore wind in facilitating the United States’ transition to a net-zero emissions economy by 2050. - -Conducting a regional techno-economic analysis at four U.S. coastal sites, the study evaluates two -energy transmission configurations and examines associated costs for the years 2025, 2030, and 2035. -The results highlight that locations using fixed-bottom technology may achieve cost-competitive -water electrolysis hydrogen production by 2030 through leveraging geologic hydrogen storage and -federal policy incentives. - -Brunik, K., et al. "[Potential for large-scale deployment of offshore wind-to-hydrogen systems in the United States.](https://iopscience.iop.org/article/10.1088/1742-6596/2767/6/062017/pdf)" Journal of Physics: Conference Series. Vol. 2767. No. 6. IOP Publishing, 2024. - -### Examining how tightly-coupled gigawatt-scale wind- and solar-sourced H2 depends on the ability to store and deliver otherwise-curtailed H2 during times of shortages. - -Modeling results suggest that the levelized cost of storage is highly spatially heterogeneous, with -minor impact on the cost of H2 in the Midwest, and potentially significant impact in areas with -emerging H2 economies such as Central California and the Southeast. While TOL/MCH may be the -cheapest aboveground bulk storage solution evaluated, upfront capital costs, modest energy -efficiency, reliance on critical materials, and greenhouse gas emissions from heating remain -concerns. - -Breunig, Hanna, et al. "[Hydrogen Storage Materials Could Meet Requirements for GW-Scale Seasonal Storage and Green Steel.](https://assets-eu.researchsquare.com/files/rs-4326648/v1_covered_338a5071-b74b-4ecd-9d2a-859e8d988b5c.pdf?c=1716199726)" (2024). - -### DOE Hydrogen Program review presentation of H2Integrate - -King, J. and Hammond, S. "[Integrated Modeling, TEA, and Reference Design for Renewable Hydrogen to Green Steel and Ammonia - GreenHEART](https://www.hydrogen.energy.gov/docs/hydrogenprogramlibraries/pdfs/review24/sdi001_king_2024_o.pdf?sfvrsn=a800ca84_3)" (2024). - -## Software requirements - -- Python version 3.11, 3.12 64-bit -- Other versions may still work, but have not been extensively tested at this time - -## Installing from Package Repositories - -```bash -pip install h2integrate -``` - -> [!NOTE] -> If using the Ard models `h2integrate[ard]`, see the source installation instructions (item 3) for -> creating a conda environment with WISDEM installed through conda, not pip as it can cause issues -> on some machines. - -## Installing from Source - -### Easiest approach (recommended) - -1. Using Git, navigate to a local target directory and clone repository: - - ```bash - git clone https://github.com/NatLabRockies/H2Integrate.git - ``` - -2. Navigate to `H2Integrate` - - ```bash - cd H2Integrate - ``` - -3. Create a conda environment and install H2Integrate and all its dependencies. Please read the - following two notes about modified installation steps. - - 1. If on a Unix machine, uncomment line 8 in `environment.yml` to install Cbc. Windows - users will need to manually install from . - 2. If you plan to use Ard, you may need to uncomment line 9 in `environment.yml` to ensure WISDEM (an Ard - dependency) is installed from conda to avoid installation issues with some systems. - - ```bash - conda env create -f environment.yml - ``` - -An additional step can be added if additional dependencies are required, or you plan to use this -environment for development work. - -- Pass `-e` for an editable developer install -- Use one of the extra flags as needed: - - `gis`: adds the iron mapping tools. - - `ard`: adds the Ard-based wind models. - - `extras`: installs all extra analysis tool dependencies, e.g., `ard` or `gis`. - - `develop`: adds developer and documentation tools. - - `examples`: allows you to use the Jupyter Notebooks and all examples (includes `ard` and `gis`). - - `all` simplifies adding all the dependencies. - -This looks like the following for a developer installation: - -```bash -pip install -e ".[all]" -``` - -### Customizable - -1. Using Git, navigate to a local target directory and clone repository: - - ```bash - git clone https://github.com/NatLabRockies/H2Integrate.git - ``` - -2. Navigate to `H2Integrate` - - ```bash - cd H2Integrate - ``` - -3. Create a new virtual environment and change to it. Using Conda Python 3.11 (choose your favorite - supported version) and naming it 'h2integrate' (choose your desired name): - - ```bash - conda create --name h2integrate python=3.11 -y - conda activate h2integrate - ``` - -4. Install H2Integrate and its dependencies: - - ```bash - conda install -y -c conda-forge glpk coin-or-cbc>=2.10.12 - ``` - - - If you want to just use H2Integrate: - - ```bash - pip install . - ``` - - - If you want to work with the examples: - - ```bash - pip install ".[examples]" - ``` - - - If you also want development dependencies for running tests and building docs: - - ```bash - pip install -e ".[develop]" - ``` - - Please be sure to also install the pre-commit hooks if contributing code back to the main - repository via the following. This enables a series of automated formatting and code linting - (style and correctness checking) to ensure the code is stylistically consistent. - - ```bash - pre-commit install - ``` - - If a check (or multiple) fails (commit is blocked), and reformatting was done, then restage - (`git add`) your files and commit them again to see if all issues were resolved without user - intervention. If changes are required follow the suggested fix, or resolve the stated - issue(s). Restaging and committing may take multiple attempts steps if errors are unaddressed - or insufficiently addressed. Please see [pre-commit](https://pre-commit.com/), - [ruff](https://docs.astral.sh/ruff/), or [isort](https://pycqa.github.io/isort/) for more - information. - - - In one step, all dependencies can be installed as: - - ```bash - pip install -e ".[all]" - ``` - -5. The functions which download resource data require an NLR API key. Obtain a key from: - - [https://developer.nlr.gov/signup/](https://developer.nlr.gov/signup/) - -6. To set up the `NLR_API_KEY` and `NLR_API_EMAIL` required for resource downloads, follow the steps - outlined in [this doc page](https://h2integrate.readthedocs.io/en/latest/getting_started/environment_variables.html). - -7. Verify setup by running tests: - - ```bash - pytest - ``` - -## Getting Started - -The [Examples](./examples/) contain Jupyter notebooks and sample YAML files for common usage -scenarios in H2Integrate. These are actively maintained and updated to demonstrate H2Integrate's -capabilities. For full details on simulation options and other features, documentation is -forthcoming. - ## Contributing -Interested in improving H2Integrate? Please see the [Contributor's Guide](./docs/CONTRIBUTING.md) -section for more information. +Interested in improving H2Integrate? Please see the [Contributor's Guide](./docs/CONTRIBUTING.md) for more information. diff --git a/docs/getting_started/install.md b/docs/getting_started/install.md index 235c0babf..4dcba6c06 100644 --- a/docs/getting_started/install.md +++ b/docs/getting_started/install.md @@ -2,7 +2,7 @@ ## Install H2Integrate via PyPI -If you just want to use H2Integrate and aren't developing new models, you can install it from PyPI using pip: +If you just want to use H2Integrate and aren't developing new models, you should install it from PyPI using pip: ```bash pip install h2integrate diff --git a/docs/intro.md b/docs/intro.md index de798f43c..356a53451 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -4,57 +4,19 @@ ![CI Tests](https://github.com/NatLabRockies/H2Integrate/actions/workflows/ci.yml/badge.svg) [![image](https://img.shields.io/pypi/pyversions/h2integrate.svg)](https://pypi.python.org/pypi/h2integrate) [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) -[![DOI:10.5281/zenodo.17903150](https://zenodo.org/badge/DOI/10.5281/zenodo.17903149.svg)](https://zenodo.org/records/17903149) +[![DOI 10.5281/zenodo.17903150](https://zenodo.org/badge/DOI/10.5281/zenodo.17903150.svg)](https://zenodo.org/records/17903150) -H2Integrate is an open-source Python package for modeling and designing hybrid energy systems producing electricity, hydrogen, ammonia, steel, and other products. +H2Integrate (H2I) is an open-source Python package for hybrid systems engineering design and technoeconomic analysis. +It models and optimizes hybrid energy plants that produce electricity, hydrogen, ammonia, steel, and other products, using high-resolution location-specific resource data to perform optimization and scenario analysis. Browse the example workflows in the GitHub repository: https://github.com/NatLabRockies/H2Integrate/tree/main/examples -```{note} -H2Integrate is under active development and may be missing features that existed in previous versions. H2Integrate v0.2.0 is the last version that uses the prior framework. -``` - -If you use this software in your work, please cite using the following BibTeX: - -```bibtex -@software{brunik_2025_17903150, - author = {Brunik, Kaitlin and - Grant, Elenya and - Thomas, Jared and - Starke, Genevieve M and - Martin, Jonathan and - Ramos, Dakota and - Koleva, Mariya and - Reznicek, Evan and - Hammond, Rob and - Stanislawski, Brooke and - Kiefer, Charlie and - Irmas, Cameron and - Vijayshankar, Sanjana and - Riccobono, Nicholas and - Frontin, Cory and - Clark, Caitlyn and - Barker, Aaron and - Gupta, Abhineet and - Kee, Benjamin (Jamie) and - King, Jennifer and - Jasa, John and - Bay, Christopher}, - title = {H2Integrate: Holistic Hybrids Optimization and Design Tool}, - month = dec, - year = 2025, - publisher = {Zenodo}, - version = {0.4.0}, - doi = {10.5281/zenodo.17903150}, - url = {https://doi.org/10.5281/zenodo.17903150}, -} -``` - ## What is H2Integrate? -H2Integrate is designed to be flexible and extensible, allowing users to create their own components and models for various energy systems. -The tool currently includes renewable energy generation (wind, solar, wave, tidal), battery storage, hydrogen, ammonia, methanol, and steel technologies. -Other elements such as desalination systems, pipelines, compressors, and storage systems can also be included as developed by users. +H2Integrate is designed to be flexible and extensible, allowing users to create their own components and models for various hybrid systems. +The tool currently includes renewable energy generation (land-based wind, offshore wind, solar PV, wave, tidal), conventional generation (natural gas combined cycle, combustion turbines, grid electricity), hydrogen production (PEM electrolysis, NG-SMR), energy storage (Li-ion batteries, long-duration energy storage, pumped storage hydropower), fuel cells, and industrial processes (ammonia synthesis, iron ore reduction, steel production, methanol, and more). +Other elements can also be included as developed by users. +H2Integrate is continually expanding to serve additional hybrid applications -- if you're interested in seeing what's being actively developed, please see the [current pull requests in the GitHub repository](https://github.com/NatLabRockies/H2Integrate/pulls). Some modeling capabilities in H2Integrate are provided by integrating existing tools, such as [HOPP](https://github.com/NatLabRockies/HOPP), [PySAM](https://github.com/NatLabRockies/pysam), [ORBIT](https://github.com/NLRWindSystems/ORBIT), and [ProFAST](https://github.com/NatLabRockies/ProFAST). The H2Integrate tool is built on top of [NASA's OpenMDAO framework](https://github.com/OpenMDAO/OpenMDAO/), which provides a powerful and flexible environment for modeling and optimization. @@ -103,5 +65,74 @@ Like REopt, SAM also does not model loads or end-uses but accepts timeseries dat H2Integrate goes into more component-level details than those tools, especially in terms of nonlinear physics-based modeling and design. +```{note} +H2Integrate was previously known as GreenHEART, and some publications or references may refer to it by that name. +``` + +## Publications + +For more context about H2Integrate and analyses performed using the tool, see the publications below. +PDFs are available in the linked titles. + + +### Techno-economic analysis of low-carbon hydrogen production pathways for decarbonizing steel and ammonia production + +Reznicek, E.P., et al. "[Techno-economic analysis of low-carbon hydrogen production pathways for decarbonizing steel and ammonia production.](https://www.cell.com/cell-reports-sustainability/pdfExtended/S2949-7906(25)00034-5)" Cell Reports Sustainability. Vol. 2. No. 4. Elsevier, 2025. + +### Nationwide techno-economic analysis of clean hydrogen production powered by a hybrid renewable energy plant for over 50,000 locations in the United States + +Grant, E., et al. "[Hybrid power plant design for low-carbon hydrogen in the United States.](https://iopscience.iop.org/article/10.1088/1742-6596/2767/8/082019/pdf)" Journal of Physics: Conference Series. Vol. 2767. No. 8. IOP Publishing, 2024. + +### Exploring the role of producing low-carbon hydrogen using water electrolysis powered by offshore wind in facilitating the United States' transition to a net-zero emissions economy by 2050 + +Brunik, K., et al. "[Potential for large-scale deployment of offshore wind-to-hydrogen systems in the United States.](https://iopscience.iop.org/article/10.1088/1742-6596/2767/6/062017/pdf)" Journal of Physics: Conference Series. Vol. 2767. No. 6. IOP Publishing, 2024. + +### Examining how tightly-coupled gigawatt-scale wind- and solar-sourced H2 depends on the ability to store and deliver otherwise-curtailed H2 during times of shortages + + +Breunig, Hanna, et al. "[Hydrogen Storage Materials Could Meet Requirements for GW-Scale Seasonal Storage and Green Steel.](https://assets-eu.researchsquare.com/files/rs-4326648/v1_covered_338a5071-b74b-4ecd-9d2a-859e8d988b5c.pdf?c=1716199726)" (2024). + +### DOE Hydrogen Program review presentation of H2Integrate + +King, J. and Hammond, S. "[Integrated Modeling, TEA, and Reference Design for Renewable Hydrogen to Green Steel and Ammonia - GreenHEART](https://www.hydrogen.energy.gov/docs/hydrogenprogramlibraries/pdfs/review24/sdi001_king_2024_o.pdf?sfvrsn=a800ca84_3)" (2024). + +## Software Citation + +If you use this software in your work, please cite using the following BibTeX: + +```bibtex +@software{brunik_2025_17903150, + author = {Brunik, Kaitlin and + Grant, Elenya and + Thomas, Jared and + Starke, Genevieve M and + Martin, Jonathan and + Ramos, Dakota and + Koleva, Mariya and + Reznicek, Evan and + Hammond, Rob and + Stanislawski, Brooke and + Kiefer, Charlie and + Irmas, Cameron and + Vijayshankar, Sanjana and + Riccobono, Nicholas and + Frontin, Cory and + Clark, Caitlyn and + Barker, Aaron and + Gupta, Abhineet and + Kee, Benjamin (Jamie) and + King, Jennifer and + Jasa, John and + Bay, Christopher}, + title = {H2Integrate: Holistic Hybrids Optimization and Design Tool}, + month = dec, + year = 2025, + publisher = {Zenodo}, + version = {0.4.0}, + doi = {10.5281/zenodo.17903150}, + url = {https://doi.org/10.5281/zenodo.17903150}, +} +``` + ```{tableofcontents} ```