FlexMeasures · Flix6x · Jul 8, 2026 · Dec 4, 2025 · Dec 4, 2025 · Dec 4, 2025
diff --git a/documentation/changelog.rst b/documentation/changelog.rst
@@ -16,7 +16,10 @@ New features
 * Floor off-clock API datetimes to a non-instantaneous sensor's resolution by default when ingesting sensor data, uploading sensor data, and handling scheduler flex-model timed events; configurable with the ``floor_datetimes_to_resolution`` sensor attribute [see `PR #2146 <https://www.github.com/FlexMeasures/flexmeasures/pull/2146>`_]
 * Sensor references in flex-model and flex-context support various ways of filtering by source [see `PR #2209 <https://www.github.com/FlexMeasures/flexmeasures/pull/2209>`_]
 * Let storage scheduling infer missing ``power-capacity`` from directional device capacities before falling back to site capacity, and default the missing opposite capacity to zero when only a non-zero ``consumption-capacity`` or ``production-capacity`` is configured [see `PR #2222 <https://www.github.com/FlexMeasures/flexmeasures/pull/2222>`_]
+* Support multiple feeders to a shared storage [see `PR #2001 <https://www.github.com/FlexMeasures/flexmeasures/pull/2001>`_ ]
+* The flex-context can now define multiple commodities, each specifying their own prices and grid capacities [see `PR #1946 <https://www.github.com/FlexMeasures/flexmeasures/pull/1946>`_, `PR #2172 <https://www.github.com/FlexMeasures/flexmeasures/pull/2172>`_ and `PR #2235 <https://www.github.com/FlexMeasures/flexmeasures/pull/2235>`_]
 * CLI support for adding/editing account attributes [see `PR #2242 <https://www.github.com/FlexMeasures/flexmeasures/pull/2242>`_]
+* Breaking behaviour change: the top-level flex-context's ``relax-constraints`` field now defaults to ``True`` (matching the default already used within each ``commodities`` entry), so constraint violations are softly penalized by default instead of being hard constraints, unless explicitly set to ``False`` [see `PR #2172 <https://www.github.com/FlexMeasures/flexmeasures/pull/2172>`_]
 
 Infrastructure / Support
 ----------------------
@@ -34,6 +37,7 @@ Bugfixes
 -----------
 * Let storage scheduling treat missing constant SoC bounds as unconstrained lower or upper bounds [see `PR #2221 <https://www.github.com/FlexMeasures/flexmeasures/pull/2221>`_]
 * Allow root assets belonging to different accounts to share the same name, while keeping asset names unique among root assets within the same account and among children of the same parent [see `PR #2226 <https://www.github.com/FlexMeasures/flexmeasures/pull/2226>`_]
+* Fix several multi-commodity scheduling issues found in review of the flex-context ``commodities`` list: a broken cross-commodity currency check that could never fire, a ``KeyError`` when a flex-model contains no electricity device, ``inflexible-device-sensors`` declared inside a (non-electricity) commodity context being silently ignored (they now constrain that commodity's site capacity and are included in its aggregate schedule), devices without an explicit ``commodity`` key defaulting to ``electricity``, ``aggregate-power`` now summing only electricity devices, and duplicate commodities or a non-electricity ``commodity`` in the single-dict flex-context form now being rejected with a 422 instead of behaving unpredictably. Note: combining the ``commodities`` list with top-level flex-context fields is deliberately tolerated (top-level fields serve as the electricity context only when the list has no electricity entry), because assets with a db-stored flex-context get their stored fields merged at the top level [see `PR #2172 <https://www.github.com/FlexMeasures/flexmeasures/pull/2172>`_]
 
 
 v0.33.1 | July 1, 2026

diff --git a/documentation/features/scheduling.rst b/documentation/features/scheduling.rst
@@ -5,8 +5,8 @@ Scheduling
 
 Scheduling is the main value-drive of FlexMeasures. We have two major types of schedulers built-in, for storage devices (usually batteries or hot water storage) and processes (usually in industry).
 
-FlexMeasures computes schedules for energy systems that consist of multiple devices that consume and/or produce electricity.
-We model a device as an asset with a power sensor, and compute schedules only for flexible devices, while taking into account inflexible devices.
+FlexMeasures computes schedules for energy systems that consist of multiple devices that consume and/or produce a commodity (e.g. electricity or gas).
+We model a device as an asset with a consumption/production sensor recording power values, and compute schedules only for flexible devices, while taking into account inflexible devices.
 
 .. contents::
     :local:
@@ -39,14 +39,15 @@ The flex-context
 
 The ``flex-context`` is independent of the type of flexible device that is optimized, or which scheduler is used.
 With the flexibility context, we aim to describe the system in which the flexible assets operate, such as its physical and contractual limitations.
+For multi-commodity scheduling problems, the flex-context can be defined separately per commodity (e.g. electricity and gas). See :ref:`tut_multi_commodity` for a hands-on example.
 
 Fields can have fixed values, but some fields can also point to sensors, so they will always represent the dynamics of the asset's environment (as long as that sensor has current data).
 The full list of flex-context fields follows below.
 For more details on the possible formats for field values, see :ref:`variable_quantities`.
 
 Where should you set these fields?
 Within requests to the API or by editing the relevant asset in the UI.
-If they are not sent in via the API (one of the endpoints triggering schedule computation), the scheduler will look them up on the `flex-context` field of the asset.
+If they are not sent in via the API (one of the endpoints triggering schedule computation), the scheduler will look them up on the flex-context field of the asset.
 And if the asset belongs to a larger system (a hierarchy of assets), the scheduler will also search if parent assets have them set.
 
 
@@ -58,9 +59,18 @@ And if the asset belongs to a larger system (a hierarchy of assets), the schedul
    * - Field
      - Example value
      - Description
+   * - ``commodity``
+     - |COMMODITY_FLEX_CONTEXT.example|
+     - .. include:: ../_autodoc/COMMODITY_FLEX_CONTEXT.rst
    * - ``inflexible-device-sensors``
      - |INFLEXIBLE_DEVICE_SENSORS.example|
      - .. include:: ../_autodoc/INFLEXIBLE_DEVICE_SENSORS.rst
+   * - ``aggregate-consumption``
+     - |AGGREGATE_CONSUMPTION.example|
+     - .. include:: ../_autodoc/AGGREGATE_CONSUMPTION.rst
+   * - ``aggregate-production``
+     - |AGGREGATE_PRODUCTION.example|
+     - .. include:: ../_autodoc/AGGREGATE_PRODUCTION.rst
    * - ``aggregate-power``
      - |AGGREGATE_POWER.example|
      - .. include:: ../_autodoc/AGGREGATE_POWER.rst
@@ -183,6 +193,9 @@ For more details on the possible formats for field values, see :ref:`variable_qu
    * - Field
      - Example value
      - Description
+   * - ``commodity``
+     - |COMMODITY_FLEX_MODEL.example|
+     - .. include:: ../_autodoc/COMMODITY_FLEX_MODEL.rst
    * - ``consumption``
      - |CONSUMPTION.example|
      - .. include:: ../_autodoc/CONSUMPTION.rst
@@ -268,6 +281,8 @@ However, here are some tips to model a buffer correctly:
    - Set ``charging-efficiency`` to the sensor describing the :abbr:`COP (coefficient of performance)` values.
    - Set ``storage-efficiency`` to a value below 100% to model (heat) loss.
 
+   For a hands-on example of a heat buffer fed by multiple devices, see :ref:`tut_multi_feed_storage`.
+
 What happens if the flex model describes an infeasible problem for the storage scheduler? Excellent question!
 It is highly important for a robust operation that these situations still lead to a somewhat good outcome.
 From our practical experience, we derived a ``StorageFallbackScheduler``.
@@ -277,6 +292,7 @@ depending on the first target state of charge and the capabilities of the asset.
 Of course, we also log a failure in the scheduling job, so it's important to take note of these failures. Often, mis-configured flex models are the reason.
 
 For a hands-on tutorial on using some of the storage flex-model fields, head over to :ref:`tut_v2g` use case and `the API documentation for triggering schedules <../api/v3_0.html#post--api-v3_0-assets-id-schedules-trigger>`_.
+For further hands-on examples, see :ref:`tut_multi_feed_storage` (multiple devices feeding one shared storage) and :ref:`tut_multi_commodity` (devices on different commodities scheduled together).
 
 Finally, are you interested in the linear programming details behind the storage scheduler?
 Then head over to :ref:`storage_device_scheduler`!

diff --git a/documentation/index.rst b/documentation/index.rst
@@ -185,6 +185,8 @@ In :ref:`getting_started`, we have some helpful tips how to dive into this docum
     tut/toy-example-expanded
     tut/toy-example-multiasset-curtailment
     tut/flex-model-v2g
+    tut/multi-feed-storage
+    tut/multi-commodity
     tut/toy-example-process
     tut/toy-example-reporter
     tut/posting_data

diff --git a/documentation/tut/flex-model-v2g.rst b/documentation/tut/flex-model-v2g.rst
@@ -144,5 +144,6 @@ To provide an incentive for cycling the battery in response to market prices, th
     }
 
 
-We hope this demonstration helped to illustrate the flex-model of the storage scheduler. Until now, optimizing storage (like batteries) has been the sole focus of these tutorial series.
-In :ref:`tut_toy_schedule_process`, we'll turn to something different: the optimal timing of processes with fixed energy work and duration.
+We hope this demonstration helped to illustrate the flex-model of the storage scheduler.
+Until now, optimizing a single storage device (like a battery) has been the sole focus of these tutorial series.
+In :ref:`tut_multi_feed_storage`, we'll cover scheduling several devices that feed into one shared storage.