Feat: change toy tutorial to kW units by BelhsanHmida · Pull Request #2223 · FlexMeasures/flexmeasures

BelhsanHmida · 2026-06-05T02:54:19Z

Description

Change flexmeasures add toy-account to create kW-scale tutorial power sensors.
Change the toy account day-ahead price sensor from EUR/MWh to EUR/kWh.
Keep tutorial price CSV values in EUR/MWh and load them with --unit EUR/MWh to demonstrate unit conversion.
Change toy power flow sensors and schedules from MW-scale to kW-scale.
Keep the toy site and battery physical power capacities in 500 kVA.
Change the reporter tutorial grid connection capacity from 0.5 MW to 500 kW.
Update toy tutorial docs, runnable tutorial scripts, and CI tutorial inputs for the new units.
Add regression coverage for battery and reporter toy-account units.
Added changelog item in documentation/changelog.rst

Note on data-source IDs: Regenerating the tutorial outputs also shifts the forecast/reporter data-source IDs (forecaster 4→2, reporter 6→3). These are creation-order IDs and are independent of the asset/sensor sequence flexmeasures add toy-account now creates a single data source (toy-user), so the forecaster source becomes 2 and the reporter source 3. The old 4/6 were stale outputs from before that setup was streamlined. (The template assets that raised the sensor/asset IDs create no data sources, which is why sources moved the other way.)

Look & Feel

CLI examples now show kW-scale toy assets and schedules, for example:

Created <Sensor 2: discharging, unit: kW res.: 0:15:00>
Created <Sensor 7: grid connection capacity, unit: kW res.: P1Y>

The rerun toy tutorial plots showed kW labels such as 500kW, 0kW, -500kW, and reporter headroom values around 300kW to 500kW.

Simplified schedule output:

Beliefs for Sensor 'discharging' (ID 2).
Data spans 12 hours and starts at 2026-06-05 07:00:00+01:00.
The time resolution (x-axis) is 15 minutes.

  500kW |        /\                         /\
        |       /  \                       /  \
    0kW |------/----\---------------------/----\-----
        |     /      \                   /      \
 -500kW |____/        \_________________/        \___
             06:00        09:00        12:00        15:00
             discharging (toy-battery)

Simplified reporter output:

Beliefs for Sensor 'headroom' (ID 8).
Data spans a day and starts at 2026-06-05 00:00:00+01:00.
The time resolution (x-axis) is 15 minutes.

  500kW |--------\                              /--------
  400kW |         \____                  ____/
  300kW |              \________________/
             00:00        06:00        12:00        18:00
             headroom (toy-battery)

How to test

run the Docker tutorial scripts in order against a fresh isolated stack:

./documentation/tut/scripts/run-tutorial-in-docker.sh fm1139-server-1
./documentation/tut/scripts/run-tutorial2-in-docker.sh fm1139-server-1
./documentation/tut/scripts/run-tutorial3-in-docker.sh fm1139-server-1
./documentation/tut/scripts/run-tutorial4-in-docker.sh fm1139-server-1
./documentation/tut/scripts/run-tutorial5-in-docker.sh fm1139-server-1

Further Improvements

Regenerate and upload the external UI screenshots in the separate FlexMeasures/screenshots repository.

Related Items

Closes #1139.

Sign-off

I agree to contribute to the project under Apache 2 License.
To the best of my knowledge, the proposed patch is not based on code under GPL or other license that is incompatible with FlexMeasures

Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com>

Flix6x

Nice, my two main comments are:

to actually not change the toy battery and site power capacities from 500 kVA to 500 kW, and
to keep the example price data in EUR/MWh, but just scale it to the EUR/kWh sensor unit by explicitly setting the --unit EUR/MWh CLI option of flexmeasures add beliefs.

Also a question: are there screenshots that would need to be updated in https://github.com/FlexMeasures/screenshots (maybe making FlexMeasures/screenshots#8 obsolete by now)?

Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com>

BelhsanHmida · 2026-06-05T13:37:11Z

Nice, my two main comments are:

to actually not change the toy battery and site power capacities from 500 kVA to 500 kW, and

to keep the example price data in EUR/MWh, but just scale it to the EUR/kWh sensor unit by explicitly setting the --unit EUR/MWh CLI option of flexmeasures add beliefs.

Also a question: are there screenshots that would need to be updated in https://github.com/FlexMeasures/screenshots (maybe making FlexMeasures/screenshots#8 obsolete by now)?

yes that pr is obsolete.

Flix6x

Thanks. Unless screenshots still need to be updated, I approve.

BelhsanHmida · 2026-06-08T02:22:34Z

Thanks. Unless screenshots still need to be updated, I approve.

Yes there are photos to be updated. I will make the flexmeasures-screenshot PR and link it to this.

Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com> # Conflicts: # documentation/changelog.rst # flexmeasures/cli/tests/test_data_add_fresh_db.py

Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com>

nhoening · 2026-07-06T22:27:37Z

@BelhsanHmida is this PR mergeable now?

BelhsanHmida · 2026-07-06T22:31:16Z

@BelhsanHmida is this PR mergeable now?

I have three more screenshots to generate for the screenshots repo then this can be merged once that's merged.

…ial-to-kw-units Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com> # Conflicts: # .github/workflows/docker-build.yml # documentation/tut/scripts/run-tutorial-in-docker.sh # documentation/tut/scripts/run-tutorial4-in-docker.sh # documentation/tut/toy-example-process.rst # documentation/tut/toy-example-setup.rst # flexmeasures/cli/data_add.py

read-the-docs-community · 2026-07-13T12:31:09Z

Documentation build overview

📚 flexmeasures | 🛠️ Build #33933901 | 📁 Comparing 5d82836 against latest (0409655)

🔍 Preview build

93 files changed · + 15 added · ± 78 modified

+ Added

± Modified

Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com>

BelhsanHmida · 2026-07-14T22:02:08Z

Fixed the stale ID issue in the toy tutorial setup docs. Because template assets are now created before the toy account, the generated toy asset and sensor IDs shifted, so I updated the CLI output, shell-variable flow, sensor links, and referenced IDs to match the fresh tutorial setup.

…ial-to-kw-units

Signed-off-by: Nicolas Höning <nicolas@seita.nl>

nhoening

I approve.

I just want to note that there is a change which this PR is not mentioning, namely the switch of source ID for forecasts in the tutorial, from 4 to 2, and 6 to 3. There is no reason given, but it seems the tutorials pass the GH Action. I assume we did some work on sources previously and this change catches that? If possible, an explanation would be good.
@BelhsanHmida mentioned that IDs for sensors/assets are now higher as we add template assets on startup, but source IDs are decreasing here.

nhoening · 2026-07-25T13:44:42Z

Also, I am not sure dates are aligning. When the tutorials are run, all dates would be about $TOMORROW, so the day after the tutorial is run.

This PR aligns one data from 2022 to 2025, but if we actually re-ran, the dates would all have to be 2026
The screenshot PR updates some but not all screenshots, and that also means the dates on the x-axis of plots will not really align.
This is not very serious, but maybe we want to periodically update and align all of this in one go. This would be something agents can really be helpful for (saving manual work).
@BelhsanHmida would you open a follow-up issue?

BelhsanHmida · 2026-07-30T04:57:02Z

I approve.

I just want to note that there is a change which this PR is not mentioning, namely the switch of source ID for forecasts in the tutorial, from 4 to 2, and 6 to 3. There is no reason given, but it seems the tutorials pass the GH Action. I assume we did some work on sources previously and this change catches that? If possible, an explanation would be good. @BelhsanHmida mentioned that IDs for sensors/assets are now higher as we add template assets on startup, but source IDs are decreasing here.

Updated the PR description to explain the data-source ID change (forecaster 4→2, reporter 6→3) . I've also opened #2369 for the follow-up

Signed-off-by: Mohamed Belhsan Hmida <149331360+BelhsanHmida@users.noreply.github.com>

BelhsanHmida · 2026-08-05T21:34:12Z

@nhoening can i merge this this pr. i was waiting for the screenshots pr to be merged.

nhoening · 2026-08-05T22:55:49Z

@nhoening can i merge this this pr. i was waiting for the screenshots pr to be merged.

I approved the screenshot one now! :)

BelhsanHmida · 2026-08-05T22:57:24Z

@nhoening can i merge this this pr. i was waiting for the screenshots pr to be merged.

I approved the screenshot one now! :)

thanks! can you merge this pr, i don't have authorization to merge fm pr's.

BelhsanHmida added 7 commits June 4, 2026 21:46

cli: create toy accounts with kW-scale units

8998ce9

Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com>

cli/tests: cover kW-scale toy account data

74fafb4

Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com>

ci: use kW-scale toy tutorial inputs

360bac5

Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com>

docs/scripts: run toy tutorials with kW-scale data

f0be0ca

Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com>

docs/tutorial: show battery scheduling in kW units

9fae10c

Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com>

docs/tutorial: align follow-on examples with kW units

9f7a6f9

Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com>

docs: add changelog entry

1aa0426

Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com>

Flix6x changed the title ~~Feat: change toy tutorial to kw units~~ Feat: change toy tutorial to kW units Jun 5, 2026

Flix6x requested changes Jun 5, 2026

View reviewed changes

Flix6x assigned BelhsanHmida Jun 5, 2026

Flix6x added documentation Improvements or additions to documentation Units Deals with unit conversion labels Jun 5, 2026

Flix6x added this to the 1.0.0 milestone Jun 5, 2026

BelhsanHmida added 5 commits June 5, 2026 13:25

docs/tutorial: import toy prices as EUR per MWh

03bc4da

Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com>

ci: import toy prices as EUR per MWh

e4a89c8

Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com>

docs/tests: keep toy site capacity in kVA

d3c2d82

Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com>

docs/tests: keep toy battery capacity in kVA

1be8dea

Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com>

tests: explain toy schedule power bounds

d90941a

Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com>

Flix6x approved these changes Jun 5, 2026

View reviewed changes

Comment thread flexmeasures/cli/tests/test_data_add_fresh_db.py

BelhsanHmida added 2 commits July 5, 2026 15:01

Merge branch 'main' into feat/change-toy-tutorial-to-kw-units

fe8a95e

Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com> # Conflicts: # documentation/changelog.rst # flexmeasures/cli/tests/test_data_add_fresh_db.py

docs: restore main whitespace after merge

c771724

Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com>

Flix6x mentioned this pull request Jul 13, 2026

Regenerate toy tutorial screenshots for kW units FlexMeasures/screenshots#15

Merged

BelhsanHmida added 2 commits July 14, 2026 18:53

docs: refresh toy setup CLI examples

fd829eb

Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com>

docs: refresh toy setup price references

e05bec3

Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com>

BelhsanHmida added 6 commits July 14, 2026 18:53

docs: refresh toy tutorial UI examples

7d5d8d7

Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com>

docs: refresh toy tutorial API examples

2a40d2a

Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com>

docs: align toy tutorial outputs

3d31955

Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com>

docs: update toy-example-setup

4b49f52

Signed-off-by: Mohamed Belhsan Hmida <mohamedbelhsanhmida@gmail.com>

docs: restore toy account setup output

55efe9f

docs: align toy setup CLI output

fd04d12

Merge remote-tracking branch 'origin/main' into feat/change-toy-tutor…

8d541cc

…ial-to-kw-units

BelhsanHmida requested a review from nhoening July 15, 2026 00:41

Merge branch 'main' into feat/change-toy-tutorial-to-kw-units

6b42783

Signed-off-by: Nicolas Höning <nicolas@seita.nl>

nhoening approved these changes Jul 25, 2026

View reviewed changes

BelhsanHmida mentioned this pull request Jul 30, 2026

regenerate & date-align all toy-tutorial outputs and screenshots in one pass #2369

Open

Merge branch 'main' into feat/change-toy-tutorial-to-kw-units

5d82836

Signed-off-by: Mohamed Belhsan Hmida <149331360+BelhsanHmida@users.noreply.github.com>

nhoening merged commit dc1fe3b into main Aug 5, 2026
12 of 13 checks passed

nhoening deleted the feat/change-toy-tutorial-to-kw-units branch August 5, 2026 23:04

Uh oh!

Conversation

BelhsanHmida commented Jun 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Look & Feel

How to test

Further Improvements

Related Items

Sign-off

Uh oh!

Flix6x left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BelhsanHmida commented Jun 5, 2026

Uh oh!

Flix6x left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

BelhsanHmida commented Jun 8, 2026 • edited by Flix6x Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nhoening commented Jul 6, 2026

Uh oh!

BelhsanHmida commented Jul 6, 2026

Uh oh!

read-the-docs-community Bot commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

BelhsanHmida commented Jul 14, 2026

Uh oh!

nhoening left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nhoening commented Jul 25, 2026

Uh oh!

BelhsanHmida commented Jul 30, 2026

Uh oh!

BelhsanHmida commented Aug 5, 2026

Uh oh!

nhoening commented Aug 5, 2026

Uh oh!

BelhsanHmida commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

BelhsanHmida commented Jun 5, 2026 •

edited

Loading

BelhsanHmida commented Jun 8, 2026 •

edited by Flix6x

Loading

read-the-docs-community Bot commented Jul 13, 2026 •

edited

Loading

nhoening left a comment •

edited

Loading

BelhsanHmida commented Aug 5, 2026 •

edited

Loading