feat(tutorials): ship tutorial data + downloadable example systems (#706)

FBumann · claude · web-flow · commit c9652bc12be7 · 2026-06-16T14:04:08.000Z
* feat(tutorials): ship tutorial data + downloadable example systems Notebook tutorial data was only reachable by cloning the repo or copying files out of GitHub, so users hit dead imports on a plain `pip install`. Add a public `fx.tutorials` API that makes every notebook standalone: - `get_data(name)` returns the synthetic datasets for notebooks 01-07, generated from numpy/pandas with no files or network. - `load_example(name)` downloads a pre-built FlowSystem for notebooks 08-09 from the project's GitHub releases (cached + hash-verified via pooch), so the heavy demandlib/pvlib/holidays generation no longer runs at user runtime. Gated behind the new `flixopt[tutorials]` extra. The dataset/example names live once each in the `DataName`/`ExampleName` Literals; lists, validation and builder dispatch all derive from them. Add `scripts/build_tutorial_datasets.py` and a manual `tutorial-data` workflow to build and upload the example artefacts to the data release, and migrate all notebooks to the new API. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * ci(tutorials): disable checkout credential persistence The tutorial-data job is `contents: write` and authenticates its release steps via an explicit GH_TOKEN, so the checkout action's persisted git credentials are unnecessary. Set persist-credentials: false to reduce token exposure (per CodeRabbit review on #706). Action version tags left as-is to match the repo-wide convention. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
diff --git a/.github/workflows/tutorial-data.yaml b/.github/workflows/tutorial-data.yaml
@@ -0,0 +1,74 @@
+name: Tutorial data
+
+# Builds the pre-built example FlowSystems and uploads them (plus registry.txt) as
+# assets to the GitHub release that `flixopt.tutorials.load_example` downloads from.
+# Run manually whenever the example systems change. The release tag must match
+# `flixopt.tutorials._examples.DATA_RELEASE` (default: tutorial-data-v1).
+
+on:
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: "Release tag to (re)upload the data assets to (must match DATA_RELEASE)."
+        required: true
+        default: "tutorial-data-v1"
+
+env:
+  PYTHON_VERSION: "3.11"
+
+jobs:
+  build-and-upload:
+    name: Build and upload example systems
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          version: "0.10.9"
+          enable-cache: true
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      # docs extra provides demandlib/pvlib/holidays used by the example generators.
+      - name: Install build dependencies
+        run: uv pip install --system -e ".[docs,full]"
+
+      - name: Verify DATA_RELEASE matches the requested tag
+        run: |
+          EXPECTED=$(python -c "from flixopt.tutorials._examples import DATA_RELEASE; print(DATA_RELEASE)")
+          if [[ "$EXPECTED" != "$TAG" ]]; then
+            echo "::error::DATA_RELEASE is '$EXPECTED' but the workflow was asked to upload to '$TAG'."
+            echo "Update flixopt/tutorials/_examples.py or pass the matching tag."
+            exit 1
+          fi
+        env:
+          TAG: ${{ inputs.release_tag }}
+
+      - name: Build example systems
+        run: python scripts/build_tutorial_datasets.py --out-dir dist/tutorial_datasets
+
+      - name: Create the data release if it does not exist
+        run: |
+          if ! gh release view "$TAG" >/dev/null 2>&1; then
+            gh release create "$TAG" \
+              --title "Tutorial data ($TAG)" \
+              --notes "Pre-built example FlowSystems downloaded by flixopt.tutorials.load_example." \
+              --prerelease
+          fi
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ inputs.release_tag }}
+
+      - name: Upload data assets
+        run: gh release upload "$TAG" dist/tutorial_datasets/* --clobber
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ inputs.release_tag }}
diff --git a/docs/notebooks/02-heat-system.ipynb b/docs/notebooks/02-heat-system.ipynb
@@ -57,9 +57,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from data.tutorial_data import get_heat_system_data\n",
-    "\n",
-    "data = get_heat_system_data()\n",
+    "data = fx.tutorials.get_data('heat_system')\n",
     "timesteps = data['timesteps']\n",
     "heat_demand = data['heat_demand']\n",
     "gas_price = data['gas_price']"
diff --git a/docs/notebooks/03-investment-optimization.ipynb b/docs/notebooks/03-investment-optimization.ipynb
@@ -82,9 +82,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from data.tutorial_data import get_investment_data\n",
-    "\n",
-    "data = get_investment_data()\n",
+    "data = fx.tutorials.get_data('investment')\n",
     "timesteps = data['timesteps']\n",
     "solar_profile = data['solar_profile']\n",
     "pool_demand = data['pool_demand']\n",
diff --git a/docs/notebooks/04-operational-constraints.ipynb b/docs/notebooks/04-operational-constraints.ipynb
@@ -71,9 +71,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from data.tutorial_data import get_constraints_data\n",
-    "\n",
-    "data = get_constraints_data()\n",
+    "data = fx.tutorials.get_data('constraints')\n",
     "timesteps = data['timesteps']\n",
     "steam_demand = data['steam_demand']"
    ]
diff --git a/docs/notebooks/05-multi-carrier-system.ipynb b/docs/notebooks/05-multi-carrier-system.ipynb
@@ -83,9 +83,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from data.tutorial_data import get_multicarrier_data\n",
-    "\n",
-    "data = get_multicarrier_data()\n",
+    "data = fx.tutorials.get_data('multicarrier')\n",
     "timesteps = data['timesteps']\n",
     "electricity_demand = data['electricity_demand']\n",
     "heat_demand = data['heat_demand']\n",
diff --git a/docs/notebooks/06a-time-varying-parameters.ipynb b/docs/notebooks/06a-time-varying-parameters.ipynb
@@ -77,9 +77,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from data.tutorial_data import get_time_varying_data\n",
-    "\n",
-    "data = get_time_varying_data()\n",
+    "data = fx.tutorials.get_data('time_varying')\n",
     "timesteps = data['timesteps']\n",
     "outdoor_temp = data['outdoor_temp']\n",
     "heat_demand = data['heat_demand']\n",
diff --git a/docs/notebooks/07-scenarios-and-periods.ipynb b/docs/notebooks/07-scenarios-and-periods.ipynb
@@ -71,9 +71,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from data.tutorial_data import get_scenarios_data\n",
-    "\n",
-    "data = get_scenarios_data()\n",
+    "data = fx.tutorials.get_data('scenarios')\n",
     "timesteps = data['timesteps']\n",
     "periods = data['periods']\n",
     "scenarios = data['scenarios']\n",
diff --git a/docs/notebooks/08a-aggregation.ipynb b/docs/notebooks/08a-aggregation.ipynb
@@ -59,9 +59,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from data.generate_example_systems import create_district_heating_system\n",
-    "\n",
-    "flow_system = create_district_heating_system()\n",
+    "flow_system = fx.tutorials.load_example('district_heating')\n",
     "flow_system.connect_and_transform()  # Align all data as xarray\n",
     "\n",
     "timesteps = flow_system.timesteps\n",
diff --git a/docs/notebooks/08b-rolling-horizon.ipynb b/docs/notebooks/08b-rolling-horizon.ipynb
@@ -63,9 +63,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from data.generate_example_systems import create_operational_system\n",
-    "\n",
-    "flow_system = create_operational_system().transform.resample('1h')\n",
+    "flow_system = fx.tutorials.load_example('operational').transform.resample('1h')\n",
     "flow_system.connect_and_transform()  # Align all data as xarray\n",
     "\n",
     "timesteps = flow_system.timesteps\n",
diff --git a/docs/notebooks/08c-clustering.ipynb b/docs/notebooks/08c-clustering.ipynb
@@ -54,9 +54,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from data.generate_example_systems import create_district_heating_system\n",
-    "\n",
-    "flow_system = create_district_heating_system()\n",
+    "flow_system = fx.tutorials.load_example('district_heating')\n",
     "flow_system.connect_and_transform()\n",
     "\n",
     "timesteps = flow_system.timesteps\n",
diff --git a/docs/notebooks/08c2-clustering-storage-modes.ipynb b/docs/notebooks/08c2-clustering-storage-modes.ipynb
@@ -63,9 +63,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from data.generate_example_systems import create_seasonal_storage_system\n",
-    "\n",
-    "flow_system = create_seasonal_storage_system()\n",
+    "flow_system = fx.tutorials.load_example('seasonal_storage')\n",
     "flow_system.connect_and_transform()  # Align all data as xarray\n",
     "\n",
     "timesteps = flow_system.timesteps\n",
diff --git a/docs/notebooks/08d-clustering-multiperiod.ipynb b/docs/notebooks/08d-clustering-multiperiod.ipynb
@@ -62,9 +62,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from data.generate_example_systems import create_multiperiod_system\n",
-    "\n",
-    "flow_system = create_multiperiod_system()\n",
+    "flow_system = fx.tutorials.load_example('multiperiod')\n",
     "\n",
     "print(f'Timesteps: {len(flow_system.timesteps)} ({len(flow_system.timesteps) // 24} days)')\n",
     "print(f'Periods: {list(flow_system.periods.values)}')\n",
diff --git a/docs/notebooks/08e-clustering-internals.ipynb b/docs/notebooks/08e-clustering-internals.ipynb
@@ -31,13 +31,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from data.generate_example_systems import create_district_heating_system\n",
-    "\n",
     "import flixopt as fx\n",
     "\n",
     "fx.CONFIG.notebook()\n",
     "\n",
-    "flow_system = create_district_heating_system()\n",
+    "flow_system = fx.tutorials.load_example('district_heating')\n",
     "flow_system.connect_and_transform()"
    ]
   },
diff --git a/docs/notebooks/08f-clustering-segmentation.ipynb b/docs/notebooks/08f-clustering-segmentation.ipynb
@@ -80,9 +80,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from data.generate_example_systems import create_district_heating_system\n",
-    "\n",
-    "flow_system = create_district_heating_system()\n",
+    "flow_system = fx.tutorials.load_example('district_heating')\n",
     "flow_system.connect_and_transform()\n",
     "\n",
     "print(f'Timesteps: {len(flow_system.timesteps)}')\n",
@@ -466,9 +464,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from data.generate_example_systems import create_multiperiod_system\n",
-    "\n",
-    "fs_multi = create_multiperiod_system()\n",
+    "fs_multi = fx.tutorials.load_example('multiperiod')\n",
     "# Use first week only for faster demo\n",
     "fs_multi = fs_multi.transform.isel(time=slice(0, 168))\n",
     "\n",
diff --git a/docs/notebooks/09-plotting-and-data-access.ipynb b/docs/notebooks/09-plotting-and-data-access.ipynb
@@ -35,8 +35,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from data.generate_example_systems import create_complex_system, create_multiperiod_system, create_simple_system\n",
-    "\n",
     "import flixopt as fx\n",
     "\n",
     "fx.CONFIG.notebook()"
@@ -62,14 +60,14 @@
     "# Create and optimize the example systems\n",
     "solver = fx.solvers.HighsSolver(mip_gap=0.01, log_to_console=False)\n",
     "\n",
-    "simple = create_simple_system()\n",
+    "simple = fx.tutorials.load_example('simple')\n",
     "\n",
     "simple.optimize(solver)\n",
     "\n",
-    "complex_sys = create_complex_system()\n",
+    "complex_sys = fx.tutorials.load_example('complex')\n",
     "complex_sys.optimize(solver)\n",
     "\n",
-    "multiperiod = create_multiperiod_system()\n",
+    "multiperiod = fx.tutorials.load_example('multiperiod')\n",
     "multiperiod.optimize(solver)\n",
     "\n",
     "print('Created systems:')\n",
diff --git a/flixopt/__init__.py b/flixopt/__init__.py
@@ -17,7 +17,7 @@
 # - xr.Dataset.fxstats (from stats_accessor)
 import xarray_plotly as _xpx  # noqa: F401
 
-from . import clustering, linear_converters, plotting, results, solvers
+from . import clustering, linear_converters, plotting, results, solvers, tutorials
 from . import stats_accessor as _fxstats  # noqa: F401
 from .carrier import Carrier, CarrierContainer
 from .comparison import Comparison
@@ -69,6 +69,7 @@
     'results',
     'linear_converters',
     'solvers',
+    'tutorials',
 ]
 
 # Initialize logger with default configuration (silent: WARNING level, NullHandler).
diff --git a/flixopt/tutorials/__init__.py b/flixopt/tutorials/__init__.py
@@ -0,0 +1,24 @@
+"""Datasets and example systems for the flixopt tutorials and notebooks.
+
+Two tiers, so every notebook is standalone after ``pip install flixopt`` - no need
+to clone the repository or copy files out of GitHub:
+
+* **Synthetic data** (notebooks 01-07) - generated on the fly from numpy/pandas,
+  no files and no network. Access by name with :func:`get_data`; see :func:`list_data`.
+
+* **Pre-built example systems** (notebooks 08-09) - downloaded (and cached) from the
+  project's GitHub releases with :func:`load_example`; see :func:`list_examples`.
+  Needs ``pooch`` (``pip install flixopt[tutorials]``).
+"""
+
+from ._examples import ExampleName, list_examples, load_example
+from ._tutorial_data import DataName, get_data, list_data
+
+__all__ = [
+    'DataName',
+    'get_data',
+    'list_data',
+    'ExampleName',
+    'load_example',
+    'list_examples',
+]
diff --git a/flixopt/tutorials/_examples.py b/flixopt/tutorials/_examples.py
diff --git a/flixopt/tutorials/_tutorial_data.py b/flixopt/tutorials/_tutorial_data.py
diff --git a/pyproject.toml b/pyproject.toml
diff --git a/scripts/build_tutorial_datasets.py b/scripts/build_tutorial_datasets.py
diff --git a/tests/test_tutorials.py b/tests/test_tutorials.py
