NatLabRockies · RHammond2 · Apr 27, 2026 · Apr 27, 2026 · Apr 27, 2026 · Apr 27, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,7 @@
 # Changelog
 
 ## Unreleased
+
 - Change commodity in DRI and EAF model from pig iron to sponge iron based on likely carbon content [PR 670](https://github.com/NatLabRockies/H2Integrate/pull/670)
 - Bugfix for round-trip efficiency handling when calling `check_inputs` around `StoragePerformanceModel` [PR 684](https://github.com/NatLabRockies/H2Integrate/pull/684)
 - Bugfix. Include nuclear in electricity producing tech list and improve error message for zero-length electricity producing techs in model when electricity is specified as the commodity. [PR 685](https://github.com/NatLabRockies/H2Integrate/pull/685)
@@ -17,12 +18,20 @@
 - Add `{commodity}_set_point` as an input to hydrogen fuel cell model [PR 709](https://github.com/NatLabRockies/H2Integrate/pull/709)
 - Rename `n_control_window` to `n_control_window_hours` for unit clarity [PR 712](https://github.com/NatLabRockies/H2Integrate/pull/712)
 - Update N2 diagram for demand openloop control from static and outdated to dynamic and interactive [PR 714](https://github.com/NatLabRockies/H2Integrate/pull/714)
+- `feedstocks.py` has moved from `h2integrate/core/` to `h2_integrate/feedstocks`
+  [PR 719](https://github.com/NatLabRockies/H2Integrate/pull/719)
+- Creates the `EIANaturalGasFeedstockConfig` and `EIANaturalGasFeedstockCostModel` to load EIA
+  natural gas prices from file or to retrieve them from the EIA API. The model is able to retrieve
+  the US or any of the 50 states' annual or monthly values, which will be converted into an hourly timeseries. Additionally, a `EIANaturalGasFeedstockPerformanceConfig` and
+  `EIANaturalGasFeedstockPerformanceModel` are created to be compatible with the hard-coded
+  definitions from the cost model. [PR 719](https://github.com/NatLabRockies/H2Integrate/pull/719)
 - Added basic check of 4-length connections in `technology_interconnections` [PR 720](https://github.com/NatLabRockies/H2Integrate/pull/720)
 - Adds `H2IntegrateModel`, `load_yaml`, `write_yaml`, and `write_readable_yaml` as package-level imports [PR 728](https://github.com/NatLabRockies/H2Integrate/pull/728).
 - Update N2 diagram for Pyomo heuristic control from static image to dynamic and interactive embedded diagram [PR 726](https://github.com/NatLabRockies/H2Integrate/pull/726)
 - Added ability to use timeseries for finance calculations [PR 725](https://github.com/NatLabRockies/H2Integrate/pull/725)
 
 ## 0.8 [April 15, 2026]
+
 - 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)

diff --git a/docs/_static/class_hierarchy.html b/docs/_static/class_hierarchy.html
diff --git a/docs/api.md b/docs/api.md
@@ -8,6 +8,7 @@
    :recursive:
 
    core
+   feedstocks
    converters
    control
    finances

diff --git a/docs/technology_models/feedstocks.md b/docs/technology_models/feedstocks.md
@@ -32,6 +32,7 @@ technology_interconnections: [
 ```
 
 Where:
+
 - `name_of_feedstock_source`: Name of your feedstock source
 - `consuming_technology`: Technology that uses the feedstock
 - `commodity`: Type identifier (e.g., "natural_gas", "water", "electricity")
@@ -85,9 +86,66 @@ The `price` parameter is flexible - you can specify constant pricing with a sing
 ```
 
 ### Consumed Feedstock Outputs
+
 The feedstock model outputs cost and performance information about the consumed feedstock. The most notable outputs are:
 - `VarOpEx`: cost of the feedstock consumed (in `USD/yr`)
 - `total_{commodity}_consumed`: total feedstock consumed over simulation (in `commodity_amount_units`)
 - `annual_{commodity}_consumed`: annual feedstock consumed (in `commodity_amount_units/yr`)
 - `rated_{commodity}_production`: this is equal to the the `rated_capacity` of the feedstock model (in `commodity_rate_units`)
 - `capacity_factor`: ratio of the feedstock consumed to the maximum feedstock available
+
+## EIA Natural Gas Pricing
+
+A special case of the feedstock cost model `EIANaturalGasFeedstockCostModel` (see
+[the relevant API docs](https://h2integrate.readthedocs.io/en/latest/_autosummary/h2integrate.feedstocks.eia_ng_pricing.html)
+for complete details) exists to enable users to download data from the EIA API's natural gas price
+portal. Access to the wellhead, import, citygate, residential, commercial, industrial, electrical
+power, and exports price facets are supported for all 50 US states and the US as a whole, though
+it is best to see which data are
+[availble online in the EIA API documentation](https://www.eia.gov/opendata/browser/natural-gas/pri/sum)
+prior to using in an analysis.
+
+Users are expected to get an EIA API key from the
+[EIA Open Data portal](https://www.eia.gov/opendata/), or to download the data as as CSV file for
+the model to load.
+
+At present, the EIA natural gas cost model uses only a single year of price data (annual or monthly)
+and extrapolates it to an hourly timeseries automatically.
+
+### Configuring the EIA Cost Model
+
+Similar to the standard feedstock model, the following variables are able to be set by the user
+
+- `cost_year` (int): Dollar year for cost inputs
+- `annual_cost` (float, optional): Fixed cost per year in USD/year. Defaults to 0.0
+- `start_up_cost` (float, optional): One-time capital cost in USD. Defaults to 0.0
+
+Additionally, there are a few other settings that users will need to provide for the model to work
+that differ from the standard cost model.
+
+:::{important}
+If relying on site coordinate data (`latitude` and `longitude`), then the `reverse_geocoder` package
+is required, which can be pip installed directly or through the `gis` library extras.
+:::
+
+- `resource_year` (int): Which year to obtain the data from in the range [2001, 2026].
+- `monthly` (bool): If True, the monthly data are retrieved, otherwise the annual price is used.
+- location data options 1) use `state` or 2) use `latitude` and `longitude`:
+  - `state` (str): Full name of the state or two-letter state abbreviation, such as "United States" or
+    "US". Only the "US" or all 50 states will produce valid results. When `state` is provided, the
+    site coordinate data will be ignored.
+  - `latitude` (float): Latitude of the natural gas plant site. Only used when `state` is not
+    provided, and will be filled from the plant configuration's site data if not provided.
+  - `longitude` (float): Longitude of the natural gas plant site. Only used when `state` is not
+    provided, and will be filled from the plant configuration's site data if not provided.
+
+- `price_category` (str): One of "wellhead", "imports", "citygate", "residential", "commercial",
+  "industrial", "electrical_power", or "exports". Note that not all categories will return
+  state-level data.
+- `api_key_file` (str, optional): The file where the user's API key is stored. If storing in a file,
+  define it on its own line using the convention "EIA_API_KEY: xxxx", or have the API key defined as
+  an environment variable set as "EIA_API_KEY".
+
+- `commodity`: Set to "natural_gas" internally.
+- `commodity_rate_units`: Set to "MMBtu/h" internally.
+- `commodity_amount_units`: Set to "MMBtu" internally.
diff --git a/h2integrate/core/supported_models.py b/h2integrate/core/supported_models.py
@@ -1,6 +1,11 @@
+from h2integrate.feedstocks import (
+    FeedstockCostModel,
+    FeedstockPerformanceModel,
+    EIANaturalGasFeedstockCostModel,
+    EIANaturalGasFeedstockPerformanceModel,
+)
 from h2integrate.resource.river import RiverResource
 from h2integrate.resource.tidal import TidalResource
-from h2integrate.core.feedstocks import FeedstockCostModel, FeedstockPerformanceModel
 from h2integrate.transporters.pipe import PipePerformanceModel
 from h2integrate.transporters.cable import CablePerformanceModel
 from h2integrate.converters.grid.grid import GridCostModel, GridPerformanceModel
@@ -314,6 +319,8 @@
     # Feedstock
     "FeedstockPerformanceModel": FeedstockPerformanceModel,
     "FeedstockCostModel": FeedstockCostModel,
+    "EIANaturalGasFeedstockCostModel": EIANaturalGasFeedstockCostModel,
+    "EIANaturalGasFeedstockPerformanceModel": EIANaturalGasFeedstockPerformanceModel,
     # Grid
     "GridPerformanceModel": GridPerformanceModel,
     "GridCostModel": GridCostModel,

diff --git a/h2integrate/feedstocks/__init__.py b/h2integrate/feedstocks/__init__.py
@@ -0,0 +1,5 @@
+from h2integrate.feedstocks.feedstocks import FeedstockPerformanceModel, FeedstockCostModel
+from h2integrate.feedstocks.eia_ng_pricing import (
+    EIANaturalGasFeedstockCostModel,
+    EIANaturalGasFeedstockPerformanceModel,
+)