Feature: EIA Natural Gas Price Retrieval for Feedstocks by RHammond2 · Pull Request #719 · NatLabRockies/H2Integrate

RHammond2 · 2026-05-01T00:38:37Z

Create an EIA Natural Gas API Feedstock Model

The newly created EIANaturalGasFeedstockConfig and EIANaturalGasFeedstockCostModel allow users to directly download or rely on previously downloaded EIA API data for natural gas prices for the US or any of its 50 states, for each of the available price categories. Users can use a single cost year's annual average or monthly results to create an hourly price profile to match the consumption model.

Section 1: Type of Contribution

Section 2: Draft PR Checklist

Open draft PR
Describe the feature that will be added
Fill out TODO list steps
Describe requested feedback from reviewers on draft PR
Complete Section 7: New Model Checklist (if applicable)

TODO:

The model is functionally complete, but is awaiting any amendments based on reviewer feedback.
Run some more local tests to ensure things work as anticipated since the model relies on external data and API keys

Type of Reviewer Feedback Requested (on Draft PR)

Any feedback is welcome from anyone who might be interested in this or impacted by it

Structural feedback: Are there any missing considerations for when this gets scaled to a national level or for prototyping purposes?

Implementation feedback: Do the naming conventions make sense?

Other feedback: Any thoughts on integrating tests relying on local data or API keys? I wasn't sure if we crossed this bridge with H2I yet or not, so held back on it.

Section 3: General PR Checklist

Section 4: Related Issues

N/A

Section 5: Impacted Areas of the Software

Section 5.1: New Files

h2integrate/feedstocks/eia_ng_pricing.py
- convert_to_monthly: Converts an annual timeseries to monthly.
- convert_state_value: Converts the state input to a compliant mapping format.
- convert_state_to_code: Maps a compliant state name to a 2-letter state code.
- get_eia_api_key: retrieves the API key from a file or environment variable.
- EIANaturalGasFeedstockConfig: EIA natural gas price configuration model that will also retrieve the data upon initialization to ensure the price attribute is populated for the cost model.
- EIANaturalGasFeedstockCostModel: EIA cost model attuned to the specifics of the configuration model.
- EIANaturalGasFeedstockPerformanceConfig: Same as FeedstockPerformanceConfig, but with fixed units and commodity values.
- EIANaturalGasFeedstockPerformanceModel: Same as FeedstockPerformanceModel, but uses EIANaturalGasFeedstockPerformanceConfig.
h2integrate/feedstocks/test/test_eia_ng_feedstock.py: Adds tests for all the basic functionality, except for any step requiring access to the EIA data (downloaded or API).

Section 5.2: Modified Files

h2integrate/core/feedstocks.py: moved to the h2integrate/feedstocks/feedstocks.py, and updated some of the docstrings and inline commentary as I was reviewing it.
h2integrate/core/supported_models.py: Adds the new EIA natural gas feedstock cost and performance model.

Section 6: Additional Supporting Information

This addition is geared towards the MPPOC model for a national scale data center modeling project, but has been made broadly applicable by allowing all the pricing data to be accessed.

Neither tests for the execution of the API retrieval nor examples have been added for this addition because it relies on either an API key or downloaded file. Please let me know if we should still provide something more than the documentation for users.

Section 7: Test Results, if applicable

Tests pass.

Section 8 (Optional): New Model Checklist

…bles

cfrontin · 2026-05-01T15:50:56Z

            desc="Capacity factor",
        )
+        self.add_output(
+            "replacement_schedule",


this is an overall comment that's acute here; but I thought of EIA NG almost as a resource, like wind. I think you're right that it's more of a specialized feedstock. but at the same time it comes with some funkiness, like how "replacement schedule" doesn't really make that much sense as a feedstock.

really this is a question for a H2I pro and not me lol

I originally built it as a resource system, but realized there was nowhere to model price, which is what feedstocks are used for. The replacement schedule and other such costs are more for compatibility, so it could be worthwhile that they are set to zero and not allowed to have input values because we're simply connecting to a grid for natural gas. Then again, there may be costs associated with hooking up the power plant to the pipeline, so that could be the actual intent.

@elenya-grant and I are on a call right now, tagging her to chime in here as well as the whole PR!

bayc

Looks good to me, thanks for putting this together! Definitely useful for multiple workstreams right now. As discussed in the standup, my one request was that we can support conversion of lat/long coords to the states so it is not up to the user to change both when doing runs.

RHammond2 · 2026-05-05T20:22:58Z

+        # TODO: Update to the commodity_capacity input of the FeedstockPerformanceModel
+        # NOTE: Should I set this to rated_capacity if it's available?
        self.add_output(
            f"rated_{self.config.commodity}_production",
            val=0,
            units=self.config.commodity_rate_units,
        )



@elenya-grant and @johnjasa should this also get updated per the todo/note here and in the EIA feedstock?

elenya-grant

Hi Rob! I think this is cool functionality - thanks for adding it in! A few higher-level thoughts:

I wonder if the API download and grabbing data should instead be a pre-processing method (since, as-is, the price data wouldn't change in a site-sweep like what's done in Example 22)
To get the price data to change per site (if lat/lon are being swept) would require the latitude and longitude to be inputs to this method. This would also require a lot of the functionality in the cost config class to be called in the compute() method.
The H2IntegrateModel has some special handling for feedstocks - I think that if we want to make this a feedstock cost model then it should inherit the FeedstockCostModel and the logic within H2I should be updated to check if a model is or inherits the FeedstockCostModel rather than checking that the name of the model is FeedstockCostModel.

I am curious what the main purpose of this feedstock model is perhaps. Is the goal to get data downloaded once OR to make it so that the cost is updated in a sweep? My current suggestion is that someone wants to do a design sweep of site locations (like example 22) and have the natural gas price change per site, that would instead look like:

use the EIA API calls and functions that you added here as functions available in the preprocess folder instead. A user can make a run-script that loops through lat/lons and get the natural gas price using those methods/functions. User basically makes a data frame with columns of site.latitude, site.longitude, and natural_gas_feedstock.price.
Save the data frame from step 1 as a csv. Run a DOE like what's done in Example 22 (but with natural_gas_feedstock.price as a design variable too). The feedstock model would still be using the FeedstockCostModel.

This suggestion would require no changes to H2IntegrateModel, or feedstocks.py. I think that integrating the feedstocks with the site information should perhaps be targeted in future work since, and I think the above suggestion would work well enough in the meantime.

I'd be curious what folks thoughts are on the proposed approach and I'm sorry to propose such a big change! I honestly hope that my suggestion would be the easiest to get this functionality in sooner rather than later.

Please let me know if you want to talk through it at all! Happy to discuss over a call!

elenya-grant · 2026-05-06T19:05:55Z

+
+
+@define(kw_only=True)
+class EIANaturalGasFeedstockPerformanceConfig(BaseConfig):


I don't think the performance model or the config are necessary - aren't these identical to the FeedstockPerformanceModel?

elenya-grant · 2026-05-06T19:06:41Z

+        return df[["price"]]
+
+
+class EIANaturalGasFeedstockCostModel(CostModelBaseClass):


Suggested change

class EIANaturalGasFeedstockCostModel(CostModelBaseClass):

class EIANaturalGasFeedstockCostModel(FeedstockCostModel):

elenya-grant · 2026-05-06T19:08:48Z

+
+        super().setup()
+
+        self.dt = self.options["plant_config"]["plant"]["simulation"]["dt"]


I think the rest of this setup() method could be replaced with super().setup() if this class inherits the FeedstockCostModel

elenya-grant · 2026-05-06T19:13:24Z

            units="unitless",
            desc="Capacity factor",
        )
+        self.add_output(


why was replacement_schedule added as an output? It shouldn't be needed.

It was already there (https://github.com/NatLabRockies/H2Integrate/tree/develop/h2integrate/core/feedstocks.py#L183), I just moved the inline comment to the output's description.

elenya-grant · 2026-05-06T19:13:30Z

-        # Estimate annual consumption based on consumption over the simulation
-        # NOTE: once we standardize feedstock consumption outputs in models, this should
-        # be updated to handle consumption that varies over years of operation
+        # TODO: update to handle varying consumption levels when feedstock consumption is available


I'm curious why this comment was changed? I thin the previous NOTE was a bit more clear to me

I converted from a note to a todo because of "this should be updated". Happy to revert it to its longer form, but I would still strongly argue this is a TODO for when the variable consumption is implemented.

elenya-grant · 2026-05-06T19:22:23Z

+            attrs.validators.in_([*STATE_MAP, *STATE_MAP.values()])
+        ),
+    )
+    latitude: float = field(default=999.9, validator=attrs.validators.instance_of(float))


I think latitude and longitude should look like this:

latitude: float = field(default=0.0, validator=range_val(-90.0, 90.0)) longitude: float = field(default=0.0, validator=range_val(-180.0, 180.0))

I originally used, this, but needed a value to trigger that no location data was provided. I think that we could simply riff on the original by using:

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)))

yeah! I didn't even know about the optional attrs validators! Those are slick!

elenya-grant · 2026-05-06T19:23:14Z

+    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)
+    filename: str = field(default=None)


I got an AttributeError when the filename wasn't specified because Path(None) doesnt work. I think the default should be an empty string.

Thanks for flagging, I think I fixed this (among other things) in some commits after you would've pulled this down. I also implemented a bunch of tests around much of the configuration class and functions.

elenya-grant · 2026-05-06T19:24:06Z

+
+
+@define
+class EIANaturalGasFeedstockConfig(BaseConfig):


I think this should inherit the FeedstockCostConfig

It originally did, but I need a couple pieces of the FeedstockCostConfig.setup() prior to being able to call setup, otherwise the price data won't be available. One remedy, and could work well for the next comment is to just set a default value, and get the actual data at the end of the setup. This could be ok because the price is automatically converted to monthly anyway for simplified handling of converting it to an 8760.

elenya-grant · 2026-05-06T19:25:09Z

+        self.url = self.create_eia_api_url()
+        self.price = self.get_data()
+
+    def create_eia_api_url(self):


I think create_eia_api_url() and get_data() should be methods in EIANaturalGasFeedstockCostModel instead of the config class.

Similar to the previous comment, I originally did that as well, but the price data was required for determining the annual vs per timestep logic. Similar to the above, I think that if I use a dummy value for the price data prior to retrieval, then this could work even if the logic will be a bit out of order.

elenya-grant · 2026-05-06T19:26:20Z

+            units=self.config.commodity_rate_units,
+        )
+
+    def compute(self, inputs, outputs, discrete_inputs, discrete_outputs):


If this class inherits the FeedstockCostModel - then it would only need to have

super().compute(inputs, outputs)

Same commentary as the above couple of responses.

RHammond2 · 2026-05-06T23:03:37Z

Thanks for the feedback, @elenya-grant! I think pretty much everything you're saying makes good sense to me. My own concern is that this isn't inherently built around multi-site analyses, so there is still some use in having a single site version be available. Otherwise, I agree that much of the actual API functionality could become preprocessing code that a single site or generic feedstock can use. I've also scheduled a meeting so we can iterate on these ideas a bit more effectively.

RHammond2 · 2026-05-07T19:21:21Z

The path forward based on a call with @elenya-grant is to make the following amendments:

Move all the API-specific functionality to a new preprocessing module
Expand the API to allow for downloading of multiple years and sites
Only use a specialized cost model and configuration that inherits the main feedstock model in place of an entirely separate model for each component.

RHammond2 added 21 commits April 27, 2026 12:41

add unintegrated, working EIA API data querier

b6de770

probably working integration into H2I

f0898f5

ensure data are always in monthly format

194f592

add openmdao

80987d2

move feedstocks to its own folder

aaa333a

move natural gas pricing to feedstocks and convert config for compliance

f8fd1be

update long comment and start building out NG cost model

6e978f6

update compute docstring and include feedstocks folder in api docs

52a5bcb

update inline comment usage

17b62dd

convert price to hourly over full year and update comments/docstrings

febfa21

Merge branch 'develop' into feature/ng-industrial-price

6cf2eb7

remove placeholder for lint ignore

fcf54c5

ensure price timeseries matches n_timesteps

7675156

add leap year handling for clean 8760s

829835d

update changelog

d5baed6

fix typos, make api_key_file consistent, and enable environment varia…

adbb8d8

…bles

update docstrings and spacing

2cbcfdc

add the EIA model to the docs page

ddba1d1

add requests instead of relying on other packages requiring it

d714c6d

add to supported models

786bd0e

update class hierarchy

789a417

RHammond2 requested review from cfrontin and johnjasa May 1, 2026 00:38

RHammond2 added enhancement New feature or request nationwide sweeps Functionality needed to enable nationwide sweeps (potentially ported from NEDsim) labels May 1, 2026

RHammond2 changed the base branch from main to develop May 1, 2026 15:08

fix import

5464b49

cfrontin reviewed May 1, 2026

View reviewed changes

Comment thread h2integrate/feedstocks/feedstocks.py Outdated

cfrontin reviewed May 1, 2026

View reviewed changes

fix typo

78e18e9

RHammond2 added 7 commits May 1, 2026 14:50

update supported models

db24117

remove lingering resource reference

db00870

update column filtering from previous modification

319c1f5

remove deprecated arg

2f48312

fix miscellaneous data handling issues

4a5f199

ensure saved data is compatible with reload

6da03da

fix final data handling issue

df2f837

RHammond2 marked this pull request as ready for review May 1, 2026 23:23

RHammond2 added ready for review This PR is ready for input from folks labels May 1, 2026

RHammond2 added 2 commits May 1, 2026 16:25

update changelog for pr number

8f39425

fix conflict and merge develop

605c1d0

RHammond2 mentioned this pull request May 4, 2026

Bump miniconda action for upgraded node usage #722

Merged

51 tasks

bayc self-requested a review May 5, 2026 16:56

elenya-grant self-requested a review May 5, 2026 19:41

bayc approved these changes May 5, 2026

View reviewed changes

Merge branch 'develop' into feature/ng-industrial-price

25676f9

RHammond2 commented May 5, 2026

View reviewed changes

RHammond2 added 7 commits May 5, 2026 15:50

add latitude and longitude, and handle no api key file input

cb56bb6

add reverse geocoding

05a4866

update docs for reverse geocoding

3794a6e

add back correct annual reindex logic

8e37cd9

add test for all but feedstock cost model and fix minor issues

1cad6b1

add missing docstring

67c2fb9

add test for configuration class and fix class issues

68070f3

elenya-grant requested changes May 6, 2026

View reviewed changes

RHammond2 added 2 commits May 6, 2026 16:03

Merge branch 'develop' into feature/ng-industrial-price

c0074f2

Merge branch 'develop' into feature/ng-industrial-price

e1e9e45



		@define(kw_only=True)
		class EIANaturalGasFeedstockPerformanceConfig(BaseConfig):

		return df[["price"]]


		class EIANaturalGasFeedstockCostModel(CostModelBaseClass):

	class EIANaturalGasFeedstockCostModel(CostModelBaseClass):
	class EIANaturalGasFeedstockCostModel(FeedstockCostModel):


		super().setup()

		self.dt = self.options["plant_config"]["plant"]["simulation"]["dt"]

Conversation

RHammond2 commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Create an EIA Natural Gas API Feedstock Model

Section 1: Type of Contribution

Section 2: Draft PR Checklist

TODO:

Type of Reviewer Feedback Requested (on Draft PR)

Section 3: General PR Checklist

Section 4: Related Issues

Section 5: Impacted Areas of the Software

Section 5.1: New Files

Section 5.2: Modified Files

Section 6: Additional Supporting Information

Section 7: Test Results, if applicable

Section 8 (Optional): New Model Checklist

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bayc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elenya-grant left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RHammond2 commented May 6, 2026

Uh oh!

RHammond2 commented May 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

RHammond2 commented May 1, 2026 •

edited

Loading