Docs: Convert notebooks to scripts and executable markdown

.gitignore

@@ -117,19 +117,24 @@ ENV/
 *.db-wal
 *n2.html
 
-# H2Integrate structure specific
+# H2Integrate test, documentation, and examples outputs
 tests/h2integrate/data/*
 tests/h2integrate/output.txt
 tests/h2integrate/test_hydrogen/data/*
 tests/h2integrate/test_hydrogen/output.txt
 *speed_dir_data.csv
 examples/h2integrate/*/data
 examples/h2integrate/*/figures
+examples/*/*_new.*
+examples/*/*[0-9].*
+*wind_electrolyzer/
 tests/h2integrate/reports/
 tests/h2integrate/test_hydrogen/output/
 **/run_*_out/
 *_out/
 **/test_*_out/
+docs/misc_resources/wind_electrolyzer/
+docs/_autosummary
 
 output*
 snopt_history.txt

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Changelog
+
 ## 0.5.x [TBD]
+
 - Updates models for NumPy version 2.4.0
 - Update test values for WOMBAT update to 0.13.0
 - Added standalone iron DRI and steel EAF performance and cost models
@@ -10,6 +12,16 @@
 - Minor reorg for profast tools
 - Added ability to plot multi-layer geospatial point heat map and simple straight line transport routes with GeoPandas and Contextily [PR 413](https://github.com/NREL/H2Integrate/pull/413)
 - Removed hydrogen tank cost and performance models that were unused
+- Converted the documentation Jupyter notebooks to markdown files to simplify output diffs
+- Updated the contributing documentation to clarify what developers should expect for including
+  executable content in the documentation.
+- Converted the example notebooks to documentation examples, and maintain a basic working example
+  in the examples folder:
+  - `examples/14_wind_hydrogen_dispatch/hydrogren_dispatch.ipynb` -> `docs/control/controller_demonstrations.md`
+  - `examples/20_solar_electrolyzer_doe/run_csv_doe.ipynb` content added to `docs/user_guide/design_of_experiments_in_h2i.md`
+  - `examples/25_sizing_modes/run_size_modes.ipynb` -> `docs/user_guide/run_size_modes.md`
+- `.gitignore` is updated to be more inclusive of example output data.
+- Documentation builds will now fail if a demonstration errors during execution that is not marked as an allowed error, ensuring previously silent errors get caught.
 - `pyproject.toml` is tidied up after moving past Python 3.9 and early H2I limitations.
   - Cleans up unnecessary ignore rules in the ruff settings.
   - Removes duplicate dependency listings, and alphabetizes for legibility with NLR packages

docs/CONTRIBUTING.md

@@ -55,6 +55,25 @@ If the browser appears to be out of date from what you expected to be built, ple
 3. Delete the `_build` folder and rebuild the docs
 ```
 
+### Writing Executable Content
+
+All executable content, such as Jupyter notebooks, should be converted to the executable markdown
+format used by Jupyter Book. For users that prefer to develop examples in Jupyter notebooks, then
+Jupytext (separate installation required) can be used to convert their work using the following
+command. For more details, please see their documentation:
+https://jupytext.readthedocs.io/en/latest/using-cli.html.
+
+```bash
+jupytext notebook.ipynb --to myst
+```
+
+Similarly, any documentation example that users wish to interact with can be converted to a notebook
+using the following command.
+
+```bash
+jupytext notebook.md --to .ipynb
+```
+
 ## Tests
 
 The test suite can be run using `pytest tests/h2integrate`. Individual test files can be run by specifying them:

docs/_config.yml

@@ -92,3 +92,4 @@ sphinx:
     napoleon_use_admonition_for_notes: true
     napoleon_use_rtype: false
     nb_merge_streams: true
+    nb_execution_raise_on_error: true

docs/_toc.yml

@@ -22,7 +22,7 @@ parts:
   - file: user_guide/recording_and_loading_data
   - file: user_guide/how_to_interface_with_user_defined_model
   - file: user_guide/how_to_run_several_cases_in_sequence
-  - file: ../examples/25_sizing_modes/run_size_modes
+  - file: user_guide/run_size_modes
   - file: user_guide/plotting_geospatial_data_with_geopandas
 
 - caption: Technology Models
@@ -62,6 +62,7 @@ parts:
   - file: control/control_overview
   - file: control/open-loop_controllers
   - file: control/pyomo_controllers
+  - file: control/controller_demonstrations
 
 - caption: Finance Models
   chapters:

docs/control/controller_demonstrations.md

@@ -0,0 +1,115 @@
+---
+jupytext:
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.18.1
+kernelspec:
+  display_name: native-ard-h2i
+  language: python
+  name: python3
+---
+
+# Open-Loop Storage Controllers Demonstrations
+
+```{code-cell} ipython3
+from pathlib import Path
+from matplotlib import pyplot as plt
+from h2integrate.core.h2integrate_model import H2IntegrateModel
+```
+
+## 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
+
+```{literalinclude} ../../examples/14_wind_hydrogen_dispatch/inputs/tech_config.yaml
+:language: yaml
+:lineno-start: 54
+:linenos: true
+:lines: 54,59-61,67-74
+```
+
+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"))
+
+# 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.hydrogen_soc").size
+demand_profile = [
+    model.technology_config["technologies"]["h2_storage"]["model_inputs"]["control_parameters"][
+        "demand_profile"
+    ]
+    * 1e-3
+] * total_time_steps
+xvals = list(range(start_hour, end_hour))
+
+ax1.plot(
+    xvals,
+    model.prob.get_val("h2_storage.hydrogen_soc", units="percent")[start_hour:end_hour],
+    label="SOC",
+)
+ax2.plot(
+    xvals,
+    model.prob.get_val("h2_storage.hydrogen_in", units="t/h")[start_hour:end_hour],
+    linestyle="-",
+    label="H$_2$ Produced (kg)",
+)
+ax2.plot(
+    xvals,
+    model.prob.get_val("h2_storage.hydrogen_unused_commodity", units="t/h")[start_hour:end_hour],
+    linestyle=":",
+    label="H$_2$ Unused (kg)",
+)
+ax2.plot(
+    xvals,
+    model.prob.get_val("h2_storage.hydrogen_unmet_demand", 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],
+    linestyle="-",
+    label="H$_2$ Delivered (kg)",
+)
+ax2.plot(
+    xvals,
+    demand_profile[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)
+
+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))
+
+plt.legend(ncol=3)
+fig.show()
+```