Remove system-level outputs from storage and replace with demand component (follow-on to 631) (#666)

* removed system level calcs from storage and updated most tests

* updated examples with storage but dont use storage as a commodity_stream in finances

* updated examples with storage defined as a commodity_stream for a finance subgroup

* added time_step_bounds to demand components

* added test for example 23

* added example for different demand between storage and demand component

* added demo for the demand components using example 13

* made it so demand is only input to battery performance model if using feedback control

* added standard_capacity_factor as output from storage

* added doc page for storage performance models

---------

Co-authored-by: kbrunik <102193481+kbrunik@users.noreply.github.com>
Co-authored-by: John Jasa <johnjasa11@gmail.com>
Co-authored-by: kbrunik <kbrunik@gmail.com>

Author: 3 people

CHANGELOG.md

@@ -52,6 +52,7 @@
   - The `DemandOpenLoopConverterController` has been renamed to `GenericDemandComponent`
 - Modified CI setup so Windows is temporarily disabled and also so unit, regression, and integration tests are run in separate jobs to speed up testing and provide more information on test failures. [PR 668](https://github.com/NatLabRockies/H2Integrate/pull/668)
 - Added infrastructure for running models with non-hourly time steps via a class attribute `_time_step_bounds` and sets new time step bounds of 5-minutes to 1-hour for the grid components. [PR 653](https://github.com/NatLabRockies/H2Integrate/pull/653) and [PR 671](https://github.com/NatLabRockies/H2Integrate/pull/671)
+- Remove demand-related outputs from storage performance models and replace usage with demand components [PR 666](https://github.com/NatLabRockies/H2Integrate/pull/666)
 
 ## 0.7.2 [April 9, 2026]
 

docs/_toc.yml

@@ -36,20 +36,22 @@ parts:
       - file: technology_models/atb_costs_pv.md
       - file: technology_models/atb_costs_wind.md
       - file: technology_models/co2.md
-      - file: technology_models/simple_generic_storage.md
       - file: technology_models/methanol.md
       - file: technology_models/ammonia.md
-      - file: technology_models/pysam_battery.md
       - file: technology_models/wind_plant_ard.md
       - file: technology_models/geologic_hydrogen.md
       - file: technology_models/grid
-      - file: technology_models/hydrogen_storage.md
       - file: technology_models/h2_fuel_cell.md
       - file: technology_models/h2_smr.md
       - file: technology_models/iron_ewin.md
       - file: technology_models/iron_mine.md
       - file: technology_models/iron_dri.md
       - file: technology_models/steel_eaf.md
+      - file: technology_models/storage_models_index.md
+        sections:
+          - file: technology_models/simple_generic_storage.md
+          - file: technology_models/pysam_battery.md
+          - file: technology_models/hydrogen_storage.md
   - caption: Resource Models
     chapters:
       - file: resource/resource_index
@@ -72,6 +74,7 @@ parts:
   - caption: Demand
     chapters:
       - file: demand/demand_components
+      - file: demand/demand_demo
   - caption: Finance Models
     chapters:
       - file: finance_models/financial_analyses

docs/api.md

@@ -15,4 +15,5 @@
    storage
    transporters
    tools
+   demand
 ```

docs/control/controller_demonstrations.md

@@ -17,48 +17,51 @@ kernelspec:
 from pathlib import Path
 from matplotlib import pyplot as plt
 from h2integrate.core.h2integrate_model import H2IntegrateModel
+from h2integrate import EXAMPLE_DIR
+
 ```
 
 ## Hydrogen Dispatch
 
 The following example is an expanded form of `examples/14_wind_hydrogen_dispatch`.
 
 Here, we're highlighting the dispatch controller setup from
-`examples/14_wind_hydrogen_dispatch/inputs/tech_config.yaml`. Please note some sections are removed
-simply to highlight the controller sections
+`examples/14_wind_hydrogen_dispatch/inputs/tech_config.yaml`. Please note some sections are removed simply to highlight the controller sections
+
+```{literalinclude} ../../examples/14_wind_hydrogen_dispatch/inputs/tech_config.yaml
+:language: yaml
+:lineno-start: 52
+:linenos: true
+:lines: 52,53-54,57-58,59-71
+```
+
+We also include a demand technology to calculate how much demand is met, how much commodity is unused to meet the demand, and how much demand is remaining:
 
 ```{literalinclude} ../../examples/14_wind_hydrogen_dispatch/inputs/tech_config.yaml
 :language: yaml
-:lineno-start: 54
+:lineno-start: 79
 :linenos: true
-:lines: 54,59-61,67-74
+:lines: 79-86
 ```
 
+
 Using the primary configuration, we can create, run, and postprocess an H2Integrate model.
 
 ```{code-cell} ipython3
 # Create an H2Integrate model
-model = H2IntegrateModel(Path("../../examples/14_wind_hydrogen_dispatch/inputs/h2i_wind_to_h2_storage.yaml"))
+model = H2IntegrateModel(EXAMPLE_DIR/"14_wind_hydrogen_dispatch"/"inputs"/"h2i_wind_to_h2_storage.yaml")
 
 # Run the model
 model.run()
-model.post_process()
 ```
 
 Now, we can visualize the demand profiles over time.
 
 ```{code-cell} ipython3
 fig, (ax1, ax2) = plt.subplots(2, 1, sharex=True, figsize=(8, 6), layout="tight")
 
-start_hour = 0
-end_hour = 200
-total_time_steps = model.prob.get_val("h2_storage.SOC").size
-demand_profile = [
-    model.technology_config["technologies"]["h2_storage"]["model_inputs"]["shared_parameters"][
-        "demand_profile"
-    ]
-    * 1e-3
-] * total_time_steps
+start_hour = 800
+end_hour = 1000
 xvals = list(range(start_hour, end_hour))
 
 ax1.plot(
@@ -74,41 +77,41 @@ ax2.plot(
 )
 ax2.plot(
     xvals,
-    model.prob.get_val("h2_storage.unused_hydrogen_out", units="t/h")[start_hour:end_hour],
+    model.prob.get_val("h2_load_demand.unused_hydrogen_out", units="t/h")[start_hour:end_hour],
     linestyle=":",
     label="H$_2$ Unused (kg)",
 )
 ax2.plot(
     xvals,
-    model.prob.get_val("h2_storage.unmet_hydrogen_demand_out", units="t/h")[start_hour:end_hour],
+    model.prob.get_val("h2_load_demand.unmet_hydrogen_demand_out", units="t/h")[start_hour:end_hour],
     linestyle=":",
     label="H$_2$ Unmet Demand (kg)",
 )
 ax2.plot(
     xvals,
-    model.prob.get_val("h2_storage.hydrogen_out", units="t/h")[start_hour:end_hour],
+    model.prob.get_val("h2_load_demand.hydrogen_out", units="t/h")[start_hour:end_hour],
     linestyle="-",
     label="H$_2$ Delivered (kg)",
 )
 ax2.plot(
     xvals,
-    demand_profile[start_hour:end_hour],
+    model.prob.get_val("h2_load_demand.hydrogen_demand", units="t/h")[start_hour:end_hour],
     linestyle="--",
     label="H$_2$ Demand (kg)",
 )
 
 ax1.set_ylabel("SOC (%)")
 ax1.grid()
 ax1.set_axisbelow(True)
-ax1.set_xlim(0, 200)
-ax1.set_ylim(0, 50)
+ax1.set_xlim(start_hour, end_hour)
+ax1.set_ylim(60, 100)
 
 ax2.set_ylabel("H$_2$ Hourly (t)")
 ax2.set_xlabel("Timestep (hr)")
 ax2.grid()
 ax2.set_axisbelow(True)
-ax2.set_ylim(0, 20)
-ax2.set_yticks(range(0, 21, 2))
+ax2.set_ylim(0, 18)
+ax2.set_yticks(range(0, 19, 2))
 
 plt.legend(ncol=3)
 fig.show()

docs/demand/demand_components.md

@@ -1,13 +1,32 @@
-# Demand components
-
-- [`GenericDemandComponent`](#generic-demand-component)
-- [`FlexibleDemandComponent`](#flexible-demand-component)
+# Demand Components
 
 Demand components define rule-based logic for meeting commodity demand profiles without using dynamic system feedback. These components operate independently at each timestep.
 
 This page documents two core demand types:
-1. Generic Demand Component — meets a fixed demand profile.
-2. Flexible Demand Component — adjusts demand up or down within flexible bounds.
+1. [`GenericDemandComponent`](#generic-demand-component) — meets a fixed demand profile.
+2. [`FlexibleDemandComponent`](#flexible-demand-component) — adjusts demand up or down within flexible bounds.
+
+
+(demand-component-inputs-and-outputs)=
+## Demand component inputs and outputs
+The inputs to the demand components are the `{commodity}_demand` profile and the `{commodity}_in` profile. The `{commodity}_in` profile is the initial commodity used to satisfy the demand. Suppose the `{commodity}_in` (pink) and `{commodity}_demand` (green) profiles look like whats shown below:
+
+![](./figures/demand_inputs.png)
+
+The demand components then compute the following output profiles:
+- `unmet_{commodity}_demand_out`: Unmet demand (non-zero when supply < demand, otherwise 0.)
+- `unused_{commodity}_out`: Unused commodity (non-zero when supply > demand, otherwise 0.)
+
+![](./figures/demand_calcs.png)
+
+- `commodity_out`: Delivered output (commodity supplied to demand sink)
+
+![](./figures/demand_commodity_out.png)
+
+The demand components also compute the following outputs:
+- `capacity_factor`: the ratio of the demand that's been met to the full demand
+- `rated_commodity_production`: the maximum value of the demand profile
+
 
 (generic-demand-component)=
 ### Generic Demand Component