Skip to content

Updating the readme and intro doc page ahead of v0.8 release #677

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
johnjasa wants to merge 3 commits into
base: develop
Choose a base branch
from
+121 −238
Open

Updating the readme and intro doc page ahead of v0.8 release #677

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1626d21
Updating the readme
johnjasa Apr 15, 2026
b4a0360
Updated intro.md and changelog
johnjasa Apr 15, 2026
517eb4b
Minor readme updates
johnjasa Apr 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down
268 changes: 75 additions & 193 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,58 +4,53 @@
![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 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:

## Software Citation

```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},
}
```bash
pip install h2integrate
```

## Publications where H2Integrate has been used
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)
- **Optimization and scenario analysis** to explore design trade-offs across hybrid plant configurations

### Available Technologies

For more context about H2Integrate and to see analyses that have been performed using the tool, please see some of these publications.
H2I includes models for a broad set of energy generation, conversion, and storage technologies:

- **Renewable generation**: land-based wind, offshore wind, solar PV, wave, tidal
- **Conventional generation**: natural gas combined cycle (NGCC), natural gas combustion turbines (NGCT), grid electricity
- **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 and sample YAML files for common usage scenarios.

## Publications

For more context about H2Integrate and analyses performed using the tool, see the publications below.
PDFs are available in the linked titles.
Note: H2Integrate was previously known as GreenHEART, and some publications may refer to it by that name.

### Nationwide techno-economic analysis of clean hydrogen production powered by a hybrid renewable energy plant for over 50,000 locations in the United States.
### 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
Expand All @@ -65,7 +60,7 @@ 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.
### 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.
Expand All @@ -75,7 +70,7 @@ 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.
### 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
Expand All @@ -90,157 +85,44 @@ Breunig, Hanna, et al. "[Hydrogen Storage Materials Could Meet Requirements for

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 <https://github.com/coin-or/Cbc>.
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.
## Software Citation

This looks like the following for a developer installation:
If you use H2I or any of its components in your work, please cite this in your publications using the following BibTeX:

```bash
pip install -e ".[all]"
```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},
}
```

### 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.
2 changes: 1 addition & 1 deletion docs/getting_started/install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading
Loading