Feature: EIA Natural Gas Price Retrieval for Feedstocks

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,6 +18,16 @@
 - 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. [PR 719](https://github.com/NatLabRockies/H2Integrate/pull/719)
+- Creates a series of preprocessing tools for basic state name and abbreviation handling, and for
+  reverse geocoding coordinates to state data. [PR 719](https://github.com/NatLabRockies/H2Integrate/pull/719)
+- Creates a series of preprocessing tools for downloading EIA natural gas prices to monthly and
+  hourly timeseries that could be extended to other EIA API data in the future. [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)
@@ -26,6 +37,7 @@
 - Add `constant` pricing mode for Grid cost models, allowing an explicit scalar price configuration alongside `per_timestep` and `per_year` modes. [PR 764](https://github.com/NatLabRockies/H2Integrate/pull/764)
 
 ## 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)

docs/api.md

@@ -8,6 +8,7 @@
    :recursive:
 
    core
+   feedstocks
    converters
    control
    finances

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,73 @@ 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` exists to enable users
+to download data from the EIA API's natural gas price
+portal for a single site (see
+[the relevant API docs](https://h2integrate.readthedocs.io/en/latest/_autosummary/h2integrate.feedstocks.eia_ng_price.html)
+for complete details). Access to the wellhead, import, citygate, residential, commercial,
+industrial, electrical power, and exports price facets are supported for the US
+as a whole, though it is best to see which data are
+[available 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. For users that wish to download a large
+batch of data from the EIA, please see the EIA preprocessing tools in
+[`h2integrate/preprocess/eia.py`](https://github.com/NatLabRockies/H2Integrate/h2integrate/preprocess/eia.py).
+In particular, use the `get_eia_ng_data` function once an API has been created and saved to your
+environment variables or to a file.
+
+### 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".
+- `filename` (str, optional): Filename where the data should be loaded from if it exists or saved
+  to once it is downloaded.
+
+- `commodity`: Set to "natural_gas" internally.
+- `commodity_rate_units`: Set to "MMBtu/h" internally.
+- `commodity_amount_units`: Set to "MMBtu" internally.

h2integrate/core/h2integrate_model.py

@@ -624,9 +624,9 @@ def create_technology_models(self):
                             self.finance_models.append(finance_object)
 
         for tech_name, individual_tech_config in self.technology_config["technologies"].items():
-            cost_model = individual_tech_config.get("cost_model", {}).get("model")
+            cost_model = individual_tech_config.get("cost_model", {}).get("model", "")
 
-            if cost_model == "FeedstockCostModel":
+            if "FeedstockCostModel" in cost_model:
                 comp = self.supported_models[cost_model](
                     driver_config=self.driver_config,
                     plant_config=self.plant_config,
@@ -1146,11 +1146,11 @@ def connect_technologies(self):
                 # Get the performance model of the source_tech
                 source_tech_config = self.technology_config["technologies"].get(source_tech, {})
                 perf_model_name = source_tech_config.get("performance_model", {}).get("model")
-                cost_model_name = source_tech_config.get("cost_model", {}).get("model")
+                cost_model_name = source_tech_config.get("cost_model", {}).get("model", "")
 
                 # If the source is a feedstock, make sure to connect the amount of
                 # feedstock consumed from the technology back to the feedstock cost model
-                if cost_model_name == "FeedstockCostModel":
+                if "FeedstockCostModel" in cost_model_name:
                     self.plant.connect(
                         f"{dest_tech}.{transport_item}_consumed",
                         f"{source_tech}.{transport_item}_consumed",
@@ -1745,7 +1745,7 @@ def _check_tech_connections(self):
                     group = getattr(self.prob.model.plant, f"{tech_name}_source")
                 else:
                     group = getattr(self.prob.model.plant, tech_name)
-                    if model_name != "FeedstockCostModel":
+                    if "FeedstockCostModel" not in model_name:
                         group = getattr(group, model_name, None)
                         if group is None:
                             continue

h2integrate/core/supported_models.py

@@ -165,8 +165,9 @@ def copy(self):
         "PyomoRuleStorageMinOperatingCosts": "control.control_rules.storage.pyomo_storage_rule_min_operating_cost:PyomoRuleStorageMinOperatingCosts",
         "PyomoDispatchGenericConverterMinOperatingCosts": "control.control_rules.converters.generic_converter_min_operating_cost:PyomoDispatchGenericConverterMinOperatingCosts",
         # Feedstock
-        "FeedstockPerformanceModel": "core.feedstocks:FeedstockPerformanceModel",
-        "FeedstockCostModel": "core.feedstocks:FeedstockCostModel",
+        "FeedstockPerformanceModel": "feedstocks:FeedstockPerformanceModel",
+        "FeedstockCostModel": "feedstocks:FeedstockCostModel",
+        "EIANaturalGasFeedstockCostModel": "feedstocks:EIANaturalGasFeedstockCostModel",
         # Grid
         "GridPerformanceModel": "converters.grid.grid:GridPerformanceModel",
         "GridCostModel": "converters.grid.grid:GridCostModel",

h2integrate/feedstocks/__init__.py

@@ -0,0 +1,2 @@
+from h2integrate.feedstocks.feedstocks import FeedstockPerformanceModel, FeedstockCostModel
+from h2integrate.feedstocks.eia_ng_price import EIANaturalGasFeedstockCostModel

h2integrate/feedstocks/eia_ng_price.py

@@ -0,0 +1,174 @@
+import warnings
+from pathlib import Path
+from datetime import datetime
+
+import attrs
+import numpy as np
+import pandas as pd
+from attrs import field, define
+
+from h2integrate.preprocess import eia, geospatial
+from h2integrate.core.utilities import merge_shared_inputs
+from h2integrate.core.file_utils import get_path
+from h2integrate.core.validators import range_val
+from h2integrate.feedstocks.feedstocks import FeedstockCostModel
+from h2integrate.core.model_baseclasses import BaseConfig
+
+
+HOURS_PER_YEAR = 8760
+SECONDS_PER_HOUR = 3600
+CURRENT_YEAR = datetime.now().year
+
+default_price = pd.DataFrame(
+    np.zeros(8760, dtype=float).reshape(-1, 1),
+    columns=["price"],
+    index=pd.date_range("2001-01-01", "2001-12-31 23:00:00", freq="h"),
+)
+
+
+@define
+class EIANaturalGasFeedstockConfig(BaseConfig):
+    """EIA Industrial Natural Gas Pricing API configuration and downloader for the US and all 50 US
+    states, in $/MCF, converted to $/MMBtu. Please see
+    https://www.eia.gov/opendata/browser/natural-gas/pri/sum for further details about data
+    availability.
+
+    Args:
+        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.
+        resource_year (int): The YYYY-format year whose data should be retrieved. Must be between
+            2001 and the current year, inclusive of endpoints.
+        cost_year (int): dollar-year for costs. Defaults to the current year.
+        monthly (Path): True, if monthly data is desired, False if annual data is desired.
+        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 (Path, optional): Full file name of the file where the API key is located. If
+            no file name is provided, then the environment variables ``EIA_API_KEY`` is used.
+        latitude (float | None): WGS-84 y-coordinate of the site. Will not be used if
+            :py:attr:`state` has been provided.
+        longitude (float | None): WGS-84 x-coordinate of the site. Will not be used if
+            :py:attr:`state` has been provided.
+        site_name (str, optional): Name of the site from a multi-site private configuration. When
+            provided, the :py:class:`EIANaturalGasFeedstockCostModel` will populate the
+            :py:attr:`latitude` and :py:attr:`longitude` from the plant site configuration.
+        filename (str, optional): Filename for where to save the data or where the data may
+            already be located. If the file exists, the columns "period", "state", and "price" must
+            exist, otherwise the file will not be used. "period" should be of the form YYYY or
+            YYYY-MM, and state should be either the full state name or the two-letter abbreviation.
+        annual_cost (float, optional): fixed cost associated with the feedstock in USD/year.
+            Defaults to 0.0.
+        start_up_cost (float, optional): one-time capital cost associated with the feedstock in USD.
+            Defaults to 0.0.
+    """
+
+    resource_year: int = field(validator=attrs.validators.in_(range(2001, CURRENT_YEAR + 1)))
+    monthly: bool = field(validator=attrs.validators.instance_of(bool))
+    price_category: str = field(
+        converter=str.lower, validator=attrs.validators.in_(eia.EIA_NG_FACET)
+    )
+    api_key_file: str | None = field(default=None, converter=attrs.converters.optional(get_path))
+    state: str = field(
+        default=None,
+        converter=attrs.converters.optional(
+            attrs.converters.pipe(geospatial.convert_state_value, geospatial.convert_state_to_code)
+        ),
+        validator=attrs.validators.optional(
+            attrs.validators.in_([*geospatial.US_STATE_MAP, *geospatial.US_STATE_MAP.values()])
+        ),
+    )
+    latitude: float | None = field(
+        default=None, validator=attrs.validators.optional(range_val(-90.0, 90.0))
+    )
+    longitude: float | None = field(
+        default=None, validator=attrs.validators.optional(range_val(-180.0, 180.0))
+    )
+    site_name: str = field(
+        default=None, validator=attrs.validators.optional(attrs.validators.instance_of(str))
+    )
+    cost_year: int = field(default=CURRENT_YEAR)
+    annual_cost: float = field(default=0.0, converter=float)
+    start_up_cost: float = field(default=0.0, converter=float)
+    filename: str = field(default=None)
+
+    commodity: str = field(default="natural_gas", init=False)
+    commodity_rate_units: str = field(default="MMBtu/h", init=False)
+    commodity_amount_units: str = field(default="MMBtu", init=False)
+    price: pd.DataFrame = field(
+        default=default_price, init=False, validator=attrs.validators.instance_of(pd.DataFrame)
+    )
+
+    def __attrs_post_init__(self):
+        """Creates the EIA natural gas facet series code based on validated user inputs, sets the
+        :py:attr:`commodity_amount_units` if not given a value, and fetches the EIA natural gas
+        price.
+        """
+        if self.filename is not None:
+            try:
+                self.filename = get_path(self.filename)
+            except FileNotFoundError:
+                self.filename = Path(self.filename).resolve()
+
+        if self.state is None:
+            if self.latitude is None or self.longitude is None:
+                msg = (
+                    "The EIA natural gas feedstock model require one of `state` or"
+                    " `latitude` and `longitude`."
+                )
+                raise ValueError(msg)
+
+            self.state = geospatial.get_state_from_coords(
+                latitude=self.latitude, longitude=self.longitude
+            )
+
+
+class EIANaturalGasFeedstockCostModel(FeedstockCostModel):
+    """Feedstock cost model based on the EIA natural gas price API results that uses
+    annual or monthly data to model an hourly time step for a single year to model the
+    price of natural gas used in the model.
+
+    The model will pull the single site data if it is made available to pass the ``latitude`` and
+    ``longitude`` from the site configuration, otherwise the ``state`` will need to be provided
+    in the configuration.
+    """
+
+    def setup(self):
+        """Defines the inputs and outputs of the model and converts the
+        :py:attr:`EIANaturalGasFeedstockConfig.price` to an hourly timeseries for the
+        ``plant_life``.
+
+        Populates the site latitude and longitude with either the configuration's provided site
+        name or the first site in plant configuration's ``sites`` dictionary when a ``state`` is
+        not directly provided.
+        """
+        site_config = {}
+        sites = self.options["plant_config"].get("sites", {})
+        cost_config = merge_shared_inputs(self.options["tech_config"]["model_inputs"], "cost")
+
+        if cost_config.get("state") is None:
+            if (site_name := cost_config.get("site_name")) is not None and sites:
+                site_config = sites.get(site_name, {})
+            if site_name is None and sites:
+                site_config = sites[[*sites][0]]
+
+        self.config = EIANaturalGasFeedstockConfig.from_dict(
+            cost_config | site_config, additional_cls_name=self.__class__.__name__, strict=False
+        )
+
+        price = eia.get_eia_ng_data(
+            api_key_file=self.config.api_key_file,
+            resource_year=self.config.resource_year,
+            price_category=self.config.price_category,
+            state=self.config.state,
+            monthly=self.config.monthly,
+            filename=self.config.filename,
+        )
+        price = eia.convert_to_hourly(price)
+        self.config.price = price
+        super().setup()
+
+    def compute(self, inputs, outputs):
+        if not np.isclose(inputs["price"], self.config.price, rtol=1e-6):
+            warn_msg = "The NG price has changed from EIA price. This may be intended."
+            warnings.warn(warn_msg, UserWarning)
+        super().compute(inputs, outputs)