0.9 release: develop -> main

.github/PULL_REQUEST_TEMPLATE.md

@@ -48,7 +48,7 @@ IMPORTANT NOTES
 - [ ] 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)
+- [ ] Complete Section 8: New Model Checklist (if applicable)
 <!-- Describe the feature in this PR and outline next steps -->
 ### TODO:
 - [ ] Step 1
@@ -113,6 +113,7 @@ failing test cases.
   - [ ] Added: `initialize()` method, `setup()` method, `compute()` method
     - [ ] If applicable: inherit from `CostModelBaseClass`
 - [ ] **Integration**: Model has been properly integrated into H2Integrate
+  - [ ] Add the new model to the appropriate `__init__.py` file to ensure it is properly imported and used in `supported_models.py`
   - [ ] Added to `supported_models.py`
   - [ ] If a new commodity_type is added, update `create_financial_model` in `h2integrate_model.py`
 - [ ] **Tests**: Unit tests have been added for the new model

.github/workflows/ci.yml

@@ -16,6 +16,7 @@ on:
 jobs:
   build:
     strategy:
+      fail-fast: false
       matrix:
         os:
           - ubuntu-latest

.gitignore

@@ -161,3 +161,6 @@ resource_files/solar/*
 
 # Ignore library files
 library/*
+
+# Don't ignore docs images
+!docs/*/images/*.png

.pre-commit-config.yaml

@@ -27,7 +27,7 @@ repos:
       - id: yamlfix
         # Exclude YAML files that are used as inputs for testing or examples, or ones for desired schedule in HOPP as they
         # expect misformatted YAML files.
-        exclude: ^(h2integrate/core/test/inputs/.*|examples/11_hybrid_energy_plant/tech_inputs/desired_schedules/.*)$
+        exclude: ^(h2integrate/core/test/inputs/.*|examples/11_hybrid_energy_plant/tech_inputs/desired_schedules/.*|examples/33_peak_load_management/demand_profiles/.*|examples/34_plm_optimized_dispatch/demand_profiles/.*)$
   - repo: https://github.com/astral-sh/ruff-pre-commit
   # Ruff version.
     rev: v0.8.1

.readthedocs.yaml

@@ -1,19 +1,20 @@
 version: 2
 # https://docs.readthedocs.io/en/stable/config-file/v2.html
+#
+# We use `build.commands` to fully take over the build so that Read the Docs
+# runs the same script developers use locally (docs/build_book.sh). This keeps
+# local and hosted builds consistent: any pre-build code generation, jupyter-
+# book config, and the final HTML build all live in one place.
 build:
   os: ubuntu-24.04
   tools:
     python: '3.11'
-  jobs:
-    pre_build:
-      - python docs/generate_class_hierarchy.py
-      - jupyter-book config sphinx docs/
-python:
-  install:
-    - method: pip
-      path: .
-      extra_requirements: [develop]
-sphinx:
-  configuration: docs/conf.py
-  builder: html
-  fail_on_warning: false
+  commands:
+    # Install the package and docs dependencies.
+    - pip install --upgrade pip
+    - pip install .[develop]
+    # Build the book exactly the way we do locally.
+    - bash docs/build_book.sh
+    # Read the Docs expects the built HTML under $READTHEDOCS_OUTPUT/html/.
+    - mkdir -p "$READTHEDOCS_OUTPUT/html"
+    - cp -R docs/_build/html/. "$READTHEDOCS_OUTPUT/html/"

README.md

@@ -35,7 +35,7 @@ This is a non-exhaustive list, and the library of available technologies is acti
 
 - **Electricity generation**: solar PV, wind, wave, tidal, natural gas combined cycle (NGCC), natural gas combustion turbines (NGCT), nuclear, grid
 - **Hydrogen production**: PEM electrolysis, NG-SMR
-- **Energy storage**: Li-ion batteries, long-duration energy storage (LDES), pumped storage hydropower (PSH)
+- **Energy storage**: Li-ion batteries, long-duration energy storage (LDES), pumped storage hydropower (PSH), hydrogen storage, compressed gas storage
 - **Fuel cells**: H2 PEM fuel cells
 - **Industrial processes**: ammonia synthesis, iron ore reduction, steel production, and more
 

docs/_config.yml

@@ -10,7 +10,11 @@ only_build_toc_files: false
 # See https://jupyterbook.org/content/execute.html
 execute:
   execute: null
-  execute_notebooks: auto
+  # "cache" uses jupyter-cache to skip re-executing notebooks and MyST cells
+  # whose source/kernel hasn't changed, so local rebuilds are fast when only
+  # prose or unrelated Python has changed. Pass --clean to build_book.sh (or
+  # delete docs/_build) to force a full re-execution.
+  execute_notebooks: cache
   timeout: -1  # better for longer running notebooks
   merge_streams: true  # keeps unsynchronized cell outputs in a single output cell
   exclude_patterns:
@@ -57,7 +61,41 @@ sphinx:
     autodoc_typehints: description
     html_static_path:
       - _static
+    # A local ``autosummary/module.rst`` template lives here that filters out
+    # pytest ``conftest.py`` submodules from the generated stubs (they can't be
+    # imported outside a pytest session, so autosummary would emit "failed to
+    # import" warnings for every one).
+    templates_path:
+      - _templates
     napoleon_use_admonition_for_notes: true
     napoleon_use_rtype: false
+    # Render "Attributes:" sections with the :ivar: role instead of separate
+    # ".. attribute::" directives. This prevents autodoc from documenting the
+    # same attribute twice (once from the napoleon-parsed Attributes: block and
+    # once from autodoc's own member discovery), which was the single largest
+    # source of "duplicate object description" warnings in the docs build.
+    napoleon_use_ivar: true
+    # Teach napoleon about extra Google-style section headings that appear in
+    # H2Integrate docstrings. Each entry is either a plain string (renders as
+    # a generic section) or a ``[name, style]`` pair mapping the section to
+    # an existing napoleon style so its contents are parsed as parameters.
+    napoleon_custom_sections:
+      - [Inputs, params_style]
+      - [Outputs, params_style]
+      - [Promoted Inputs, params_style]
+      - [Promoted Outputs, params_style]
+      - [Subsystems, params_style]
+      - [Discrete Inputs, params_style]
+      - [Discrete Outputs, params_style]
+      - [Options, params_style]
+      - [Behavior, notes_style]
+      - [Side Effects, notes_style]
+    # Suppress the class of warnings emitted by sphinx-external-toc for
+    # ``.. toctree::`` directives inside autosummary-generated stubs. Those
+    # toctrees are how ``autosummary :recursive:`` links its child module
+    # pages together and can't be moved into ``_toc.yml``, so the warnings
+    # are noise rather than a real problem to fix.
+    suppress_warnings:
+      - etoc.toctree
     nb_merge_streams: true
     nb_execution_raise_on_error: true

docs/_templates/autosummary/module.rst

@@ -0,0 +1,65 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{# Filter out pytest conftest modules; they cannot be imported outside a
+   pytest session (they use `from test.conftest import ...` which requires
+   the repo-root ``test/`` package to be on ``sys.path``) and so autosummary
+   raises "failed to import" warnings on them. #}
+{% set filtered_modules = modules | reject('equalto', 'conftest') | list %}
+{% if filtered_modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+{% for item in filtered_modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/_toc.yml

@@ -15,7 +15,7 @@ parts:
       - file: user_guide/connecting_technologies
       - file: user_guide/defining_sites_and_resources
       - file: user_guide/design_optimization_in_h2i
-      - file: user_guide/design_of_experiments_in_h2i
+      - file: user_guide/parameter_sweep_in_h2i
       - file: user_guide/postprocessing_results
       - file: user_guide/recording_and_loading_data
       - file: user_guide/how_to_interface_with_user_defined_model
@@ -38,15 +38,18 @@ parts:
       - file: technology_models/co2.md
       - file: technology_models/methanol.md
       - file: technology_models/ammonia.md
+      - file: technology_models/ammonia_synloop_dynamics
       - file: technology_models/wind_plant_ard.md
       - file: technology_models/geologic_hydrogen.md
       - file: technology_models/grid
       - file: technology_models/h2_fuel_cell.md
       - file: technology_models/h2_smr.md
+      - file: technology_models/h2_htse.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/steel_eaf_cmu.md
   - caption: Storage Models
     chapters:
       - file: storage/storage_models_index.md
@@ -69,10 +72,20 @@ parts:
           - file: resource/tidal_resource
   - caption: Control
     chapters:
-      - file: control/control_overview
-      - file: control/open-loop_controllers
-      - file: control/pyomo_controllers
-      - file: control/controller_demonstrations
+      - file: control/system_level_control/system_level_control
+        sections:
+          - file: control/system_level_control/system_level_control_base
+          - file: control/system_level_control/control_classifier
+          - file: control/system_level_control/controllers
+            sections:
+              - file: control/system_level_control/slc_demand_following
+              - file: control/system_level_control/slc_profit_max
+              - file: control/system_level_control/slc_cost_min
+      - file: control/technology_level_control/technology_control_overview
+        sections:
+          - file: control/technology_level_control/open-loop_controllers
+          - file: control/technology_level_control/pyomo_controllers
+          - file: control/technology_level_control/controller_demonstrations
   - caption: Demand
     chapters:
       - file: demand/demand_components
@@ -94,16 +107,17 @@ parts:
       - file: developer_guide/coding_guidelines
       - file: developer_guide/why_make_h2integrate
       - file: developer_guide/adding_a_new_technology
-      - file: developer_guide/features_not_currently_implemented
       - file: developer_guide/class_structure
-      - file: developer_guide/describing_whats_in_classes
+      - file: developer_guide/technology_model_types
       - file: developer_guide/testing
+      - file: developer_guide/features_not_currently_implemented
   - caption: Miscellaneous Resources
     chapters:
       - file: misc_resources/FAQ
       - file: misc_resources/glossary
       - file: misc_resources/defining_filepaths
       - file: misc_resources/turbine_models_library_preprocessing
+      - file: misc_resources/debugging_environment_variables
   - caption: API Reference
     maxdepth: 3
     chapters:

docs/api.md

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

docs/build_book.sh

@@ -1,6 +1,36 @@
-rm -rf _build
+#!/usr/bin/env bash
+#
+# Build the H2Integrate Jupyter Book.
+#
+# By default this preserves the _build/ directory so jupyter-cache can skip
+# re-executing notebooks and MyST cells whose source hasn't changed, which
+# makes incremental local rebuilds much faster. Pass --clean to force a
+# from-scratch build (e.g. after upgrading Sphinx/jupyter-book or changing
+# execution config).
+set -euo pipefail
+
+# Always run from the docs/ directory so relative paths below work regardless
+# of where the caller invoked this script from (e.g. repo root, CI, RTD).
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+if [[ "${1:-}" == "--clean" ]]; then
+    rm -rf _build
+fi
+
+# Always remove the autosummary-generated stubs before building. These files
+# are regenerated from the current package layout by ``autosummary_generate``,
+# but sphinx does not delete stubs for modules that were renamed or removed.
+# Leaving stale stubs behind produces spurious "failed to import" /
+# "document isn't included in any toctree" warnings on every subsequent build.
+rm -rf _autosummary
 
 # Generate the interactive class hierarchy diagram
 python generate_class_hierarchy.py
 
-jupyter-book build --keep-going .
+# Refresh the auto-generated section of docs/user_guide/model_overview.md from
+# the live supported_models registry. Run this before jupyter-book so the
+# rendered overview always matches what the package actually exposes.
+python generate_model_overview.py
+
+jupyter-book build --keep-going --warningiserror .