Merge pull request #700 from johnjasa/per_year_grid_feedstock

Add per-year pricing support for Grid and Feedstock cost models

Author: johnjasa

CHANGELOG.md

@@ -12,6 +12,7 @@
 - Added electricity and water consumption profiles as outputs to the `ECOElectrolyzerPerformanceModel` [PR 690](https://github.com/NatLabRockies/H2Integrate/pull/690)
 - Add `PeakLoadManagementHeuristicOpenLoopStorageController` as a storage control strategy. [PR 641](https://github.com/NatLabRockies/H2Integrate/pull/641)
 - Minor cleanup to `pose_optimization` [PR 695](https://github.com/NatLabRockies/H2Integrate/pull/695)
+- Add per-year pricing support for Grid and Feedstock cost models, allowing price arrays of length `plant_life` in addition to scalar and per-timestep arrays. [PR 700](https://github.com/NatLabRockies/H2Integrate/pull/700)
 - Added ability to have a custom/user-specified resource model [PR 698](https://github.com/NatLabRockies/H2Integrate/pull/698)
 - 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)

docs/technology_models/feedstocks.md

@@ -73,14 +73,15 @@ ng_feedstock:
 - `commodity_rate_units` (str): Must match the performance model commodity_rate_units
 - `price` (float, int, or list): Cost per unit in `USD/commodity_amount_units`. Can be:
   - Scalar: Constant price for all timesteps and years
-  - List: Price per timestep
+  - List of length `n_timesteps`: Price per timestep, applied uniformly across all years
+  - List of length `plant_life`: Price per year of plant operation
 - `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
 - `cost_year` (int): Dollar year for cost inputs
 - `commodity_amount_units` (str | None, optional): the amount units of the commodity (i.e., "MMBtu", "kg", "galUS" or "kW*h"). If None, will be set as `commodity_rate_units*h`
 
 ```{tip}
-The `price` parameter is flexible - you can specify constant pricing with a single value or time-varying pricing with an array of values matching the number of simulation timesteps.
+The `price` parameter is flexible - you can specify constant pricing with a single value, time-varying pricing with an array of length `n_timesteps`, or per-year pricing with an array of length `plant_life`. When `n_timesteps == plant_life`, the per-year interpretation will be used and a warning is issued for clarity.
 ```
 
 ### Consumed Feedstock Outputs

docs/technology_models/grid.md

@@ -48,10 +48,14 @@ Multiple grid instances may be used within the same plant to represent different
 | `interconnection_capex_per_kw`  | scalar                       | $/kW      | Capital cost per kW of interconnection.                                |
 | `interconnection_opex_per_kw`   | scalar                       | $/kW/year | Annual O&M cost per kW of interconnection.                             |
 | `fixed_interconnection_cost`    | scalar                       | $         | One-time fixed cost regardless of size.                                |
-| `electricity_out`               | array[n_timesteps]           | kW        | Electricity flowing out of grid (buying from grid).                    |
-| `electricity_buy_price`         | scalar/array[n_timesteps]    | $/kWh     | Price to buy electricity from grid (optional, time-varying supported). |
-| `electricity_sold`              | array[n_timesteps]           | kW        | Electricity flowing into grid (selling to grid).                       |
-| `electricity_sell_price`        | scalar/array[n_timesteps]    | $/kWh     | Price to sell electricity to grid (optional, time-varying supported).  |
+| `electricity_buy_price`         | scalar or array              | $/kWh     | Price to buy electricity from grid (optional). Shape is `n_timesteps` when `buy_price_mode` is `per_timestep`, or `plant_life` when `per_year`. |
+| `buy_price_mode`                | string                       | —         | `"per_timestep"` or `"per_year"`. Controls the buy price input shape and cost calculation. |
+| `electricity_out`               | array[n_timesteps]           | kW        | Electricity flowing out of grid (buying). Present when `buy_price_mode` is `per_timestep` (or buy price is not set). |
+| `annual_electricity_out`        | array[plant_life]            | kWh/yr    | Annual electricity bought from grid. Present when `buy_price_mode` is `per_year`. |
+| `electricity_sell_price`        | scalar or array              | $/kWh     | Price to sell electricity to grid (optional). Shape is `n_timesteps` when `sell_price_mode` is `per_timestep`, or `plant_life` when `per_year`. |
+| `sell_price_mode`               | string                       | —         | `"per_timestep"` or `"per_year"`. Controls the sell price input shape and cost calculation. |
+| `electricity_sold`              | array[n_timesteps]           | kW        | Electricity flowing into grid (selling). Present when `sell_price_mode` is `per_timestep` (or sell price is not set). |
+| `annual_electricity_sold`       | array[plant_life]            | kWh/yr    | Annual electricity sold to grid. Present when `sell_price_mode` is `per_year`. |
 
 **Outputs**
 | Name      | Description                                                                                                     |
@@ -71,3 +75,20 @@ If you're using a price-maker financial model (e.g., calculating the LCOE) and s
 ```{note}
 The grid components are currently compatible with 5-minute (300-second) to 1-hour (3600-second) time steps.
 ```
+
+### Price Input Modes
+
+The pricing mode is controlled explicitly via `buy_price_mode` and `sell_price_mode` in the grid cost configuration. Each can be set to:
+
+- **`per_timestep`** (default): The price is a scalar or an array of length `n_timesteps`. The cost model uses the timestep-level `electricity_out` / `electricity_sold` inputs (in kW) and converts to energy using `dt`. The resulting `VarOpEx` is a single value applied uniformly across all years.
+- **`per_year`**: The price is an array of length `plant_life`. The cost model uses `annual_electricity_out` / `annual_electricity_sold` inputs (in kWh/yr, shape `plant_life`) directly, producing a per-year `VarOpEx` array with no `dt` conversion needed in the cost model.
+
+Example YAML configuration for per-year pricing:
+
+```yaml
+cost_parameters:
+  electricity_buy_price: [0.05, 0.06, 0.07, ...]  # length = plant_life
+  buy_price_mode: per_year
+  electricity_sell_price: [0.03, 0.04, 0.05, ...]  # length = plant_life
+  sell_price_mode: per_year
+```

h2integrate/converters/grid/grid.py

@@ -119,6 +119,14 @@ def setup(self):
             desc="Electricity that was not sold due to interconnection limits",
         )
 
+        self.add_output(
+            "annual_electricity_sold",
+            val=0.0,
+            shape=self.plant_life,
+            units=f"({self.commodity_amount_units})/year",
+            desc="Annual electricity sold to the grid",
+        )
+
     def compute(self, inputs, outputs):
         interconnection_size = inputs["interconnection_size"]
 
@@ -148,6 +156,11 @@ def compute(self, inputs, outputs):
             1 / self.fraction_of_year_simulated
         )
 
+        total_electricity_sold = np.sum(electricity_sold) * (self.dt / 3600)
+        outputs["annual_electricity_sold"] = total_electricity_sold * (
+            1 / self.fraction_of_year_simulated
+        )
+
 
 @define(kw_only=True)
 class GridCostModelConfig(CostModelBaseConfig):
@@ -168,6 +181,8 @@ class GridCostModelConfig(CostModelBaseConfig):
     fixed_interconnection_cost: float = field()  # $
     electricity_buy_price: float | list[float] | np.ndarray | None = field(default=None)  # $/kWh
     electricity_sell_price: float | list[float] | np.ndarray | None = field(default=None)  # $/kWh
+    buy_price_mode: str | None = field(default=None)  # 'per_timestep' or 'per_year'
+    sell_price_mode: str | None = field(default=None)  # 'per_timestep' or 'per_year'
 
 
 class GridCostModel(CostModelBaseClass):
@@ -198,6 +213,7 @@ def setup(self):
         super().setup()
 
         n_timesteps = self.options["plant_config"]["plant"]["simulation"]["n_timesteps"]
+        plant_life = int(self.options["plant_config"]["plant"]["plant_life"])
 
         # Common input for sizing costs
         self.add_input(
@@ -207,28 +223,20 @@ def setup(self):
             desc="Interconnection capacity for cost calculation",
         )
 
-        # Electricity flowing OUT of grid (buying from grid)
-        self.add_input(
-            "electricity_out",
-            val=0.0,
-            shape=n_timesteps,
-            units="kW",
-            desc="Electricity flowing out of grid (buying from grid)",
-        )
-
         # Add buy price input if configured
         if self.config.electricity_buy_price is not None:
-            buy_price = self.config.electricity_buy_price
-            if isinstance(buy_price, list | np.ndarray):
-                if len(buy_price) != n_timesteps:
-                    raise ValueError(
-                        f"electricity_buy_price length ({len(buy_price)}) "
-                        f"must match n_timesteps ({n_timesteps})"
-                    )
-                buy_price_shape = n_timesteps
-
+            self._buy_price_mode = self.config.buy_price_mode
+            if self._buy_price_mode is None:
+                # Default: scalar if single value, per_timestep if array
+                if isinstance(self.config.electricity_buy_price, list | np.ndarray):
+                    self._buy_price_mode = "per_timestep"
+                else:
+                    self._buy_price_mode = "per_timestep"
+
+            if self._buy_price_mode == "per_year":
+                buy_price_shape = plant_life
             else:
-                buy_price_shape = 1
+                buy_price_shape = n_timesteps
 
             self.add_input(
                 "electricity_buy_price",
@@ -237,28 +245,40 @@ def setup(self):
                 units="USD/(kW*h)",
                 desc="Price to buy electricity from grid",
             )
+        else:
+            self._buy_price_mode = None
 
-        # Electricity flowing INTO grid (selling to grid)
-        self.add_input(
-            "electricity_sold",
-            val=0.0,
-            shape=n_timesteps,
-            units="kW",
-            desc="Electricity flowing into grid (selling to grid)",
-        )
+        # Electricity bought: use annual input for per-year pricing, timestep input otherwise
+        if self._buy_price_mode == "per_year":
+            self.add_input(
+                "annual_electricity_out",
+                val=0.0,
+                shape=plant_life,
+                units="kW*h/yr",
+                desc="Annual electricity flowing out of grid (buying from grid)",
+            )
+        else:
+            self.add_input(
+                "electricity_out",
+                val=0.0,
+                shape=n_timesteps,
+                units="kW",
+                desc="Electricity flowing out of grid (buying from grid)",
+            )
 
         # Add sell price input if configured
         if self.config.electricity_sell_price is not None:
-            sell_price = self.config.electricity_sell_price
-            if isinstance(sell_price, list | np.ndarray):
-                if len(sell_price) != n_timesteps:
-                    raise ValueError(
-                        f"electricity_sell_price length ({len(sell_price)}) "
-                        f"must match n_timesteps ({n_timesteps})"
-                    )
-                sell_price_shape = n_timesteps
+            self._sell_price_mode = self.config.sell_price_mode
+            if self._sell_price_mode is None:
+                if isinstance(self.config.electricity_sell_price, list | np.ndarray):
+                    self._sell_price_mode = "per_timestep"
+                else:
+                    self._sell_price_mode = "per_timestep"
+
+            if self._sell_price_mode == "per_year":
+                sell_price_shape = plant_life
             else:
-                sell_price_shape = 1
+                sell_price_shape = n_timesteps
 
             self.add_input(
                 "electricity_sell_price",
@@ -267,6 +287,26 @@ def setup(self):
                 units="USD/(kW*h)",
                 desc="Price to sell electricity to grid",
             )
+        else:
+            self._sell_price_mode = None
+
+        # Electricity sold: use annual input for per-year pricing, timestep input otherwise
+        if self._sell_price_mode == "per_year":
+            self.add_input(
+                "annual_electricity_sold",
+                val=0.0,
+                shape=plant_life,
+                units="kW*h/yr",
+                desc="Annual electricity sold to grid",
+            )
+        else:
+            self.add_input(
+                "electricity_sold",
+                val=0.0,
+                shape=n_timesteps,
+                units="kW",
+                desc="Electricity flowing into grid (selling to grid)",
+            )
 
     def compute(self, inputs, outputs, discrete_inputs, discrete_outputs):
         interconnection_size = inputs["interconnection_size"]
@@ -281,21 +321,26 @@ def compute(self, inputs, outputs, discrete_inputs, discrete_outputs):
         outputs["OpEx"] = interconnection_size * opex_per_kw
 
         # Variable operating costs (positive cost for buying, negative for selling)
-        varopex = 0.0
+        plant_life = int(self.options["plant_config"]["plant"]["plant_life"])
+        varopex = np.zeros(plant_life)
 
         # Add buying costs if buy price is configured
-        # electricity_out represents power flowing OUT of grid (buying)
         if self.config.electricity_buy_price is not None:
-            electricity_out = inputs["electricity_out"]
             buy_price = inputs["electricity_buy_price"]
-            # Buying costs money (positive VarOpEx)
-            varopex += np.sum((self.dt / 3600) * electricity_out * buy_price)
+            if self._buy_price_mode == "per_year":
+                # annual_electricity_out is already in kW*h/yr (shape=plant_life)
+                varopex += inputs["annual_electricity_out"] * buy_price
+            else:
+                # Scalar or per-timestep: same cost each year
+                varopex += np.sum((self.dt / 3600) * inputs["electricity_out"] * buy_price)
 
         # Add selling revenue if sell price is configured
-        # electricity_sold represents power flowing INTO grid (selling)
         if self.config.electricity_sell_price is not None:
             sell_price = inputs["electricity_sell_price"]
-            # Selling generates revenue (negative VarOpEx)
-            varopex -= np.sum((self.dt / 3600) * inputs["electricity_sold"] * sell_price)
+            if self._sell_price_mode == "per_year":
+                # annual_electricity_sold is already in kW*h/yr (shape=plant_life)
+                varopex -= inputs["annual_electricity_sold"] * sell_price
+            else:
+                varopex -= np.sum((self.dt / 3600) * inputs["electricity_sold"] * sell_price)
 
         outputs["VarOpEx"] = varopex