feat: adapt configuration for multi optimization algorithms

Decouple configuration from optimization algorithm parameters. Add to_[algorithm]_param() methods
to the configuration that derive optimization algorithm specific parameters from the configuration.
Add x-scope tags to the configuration options that describe for which specific algorithms the
configuration option is for.

The whole device settings are restructured. There are now general settings for the device classes
with the afore mentioned to_[algorithm]_param() methods. The general device settings got their own
directory `devices/settings`. By this the parameter class also does not have to be a pydantic model
which can be used for future optimization/ simulations speed up.

Also the parameter class for a device is now part of the device module. This better decouples and
also is the natural place for parameters of a device.

Besides this feature there are also fixes and improvements:

* feat: extend home appliance time window settings and simulation

  Home appliance can now be configured for multiple runs with per-cycle allowed time windows. The
  number of remaining cycles to plan is determined at runtime by reading the
  ``cycles_completed_measurement_key`` from the measurement store.

* feat: specialiced CycleTimeWindowSequence for time window sequences

  Sequence of time windows associated to cycles.

  This model specializes ``ValueTimeWindowSequence`` so that the ``value``
  field of each ``ValueTimeWindow`` encodes the **cycle index** (0-based
  integer) the window belongs to.

  Typical use: an appliance that must run ``n`` times per day, each run
  constrained to a distinct time window.  Assign ``value=0`` to windows
  for the first cycle, ``value=1`` for the second, and so on.  Multiple
  windows may share the same cycle index (their allowed regions are unioned).
  Windows with ``value=None`` are silently ignored by all cycle-aware methods.

* fix: Make test_configmigrate also regard the _ANY_SENTENIEL in key values

* chore: Make devices configurations a map instead of a list

  This makes config paths stable regardless of declaration order and lets each device settings
  class build its own config path from ``self.device_id`` without needing an external index.
  Tests are adapted likewise.

  Devices configurations are automatically migrated from lists to maps.

* chore: rename levelized_cost_of_storage_kwh to levelized_cost_of_storage_amt kwh

  This better fits in the naming scheme and also makes clear the costs are money.

Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>
This commit is contained in:
Bobby Noelte
2026-08-25 15:18:00 +02:00
parent ba76087db9
commit 6ebd343047
49 changed files with 4838 additions and 2130 deletions
+94 -7
View File
@@ -198,18 +198,18 @@ horizon.
### Home Appliance Simulation
### Home Appliance Configuration
### GENETIC0 Home Appliance Configuration
Home appliance to run within the optimization horizon.
```json
[
{
{
"dishwasher1": {
"device_id": "dishwasher1",
"consumption_wh": 2000,
"duration_h": 3
}
]
}
```
Home appliance to run within a time window of 5 hours starting at 8:00 every day and another time
@@ -217,8 +217,8 @@ window of 3 hours starting at 15:00 every day. See
[Time Window Sequence Configuration](configtimewindow-page) for more information.
```json
[
{
{
"dishwasher1": {
"device_id": "dishwasher1",
"consumption_wh": 2000,
"duration_h": 3,
@@ -235,7 +235,7 @@ window of 3 hours starting at 15:00 every day. See
]
}
}
]
}
```
:::{admonition} Note
@@ -244,6 +244,93 @@ The optimization algorithm always restricts to one start within the optimization
energy management run.
:::
### GENETIC Home Appliance Configuration
Home appliance to run once, unconstrained, within the optimization horizon:
```json
{
"dishwasher1": {
"device_id": "dishwasher1",
"consumption_wh": 2000,
"duration_h": 3,
"num_cycles": 1
}
}
```
Home appliance to run within a time window of 5 hours starting at 8:00. Each window's `value`
field carries the 0-based cycle index it applies to -- here there is only one cycle (index `0`),
so `num_cycles` does not need to be set explicitly; it is derived from the distinct cycle indices
found in `cycle_time_windows`. See
[ime Window Sequence Configuration](configimewindow-page) for more information.
```json
{
"dishwasher1": {
"device_id": "dishwasher1",
"consumption_wh": 2000,
"duration_h": 3,
"cycle_time_windows": {
"windows": [
{
"start_time": "08:00",
"duration": "5 hours",
"value": 0
}
]
}
}
}
```
Home appliance that must run **twice** per day, each run confined to its own time window --
cycle 0 in the morning (07:00, 5 hours), cycle 1 in the evening (17:00, 5 hours) -- with at least
1 hour idle between the two runs:
```json
{
"washing_machine1": {
"device_id": "washing_machine1",
"consumption_wh": 2000,
"duration_h": 2,
"min_cycle_gap_h": 1,
"cycle_time_windows": {
"windows": [
{
"start_time": "07:00",
"duration": "5 hours",
"value": 0
},
{
"start_time": "17:00",
"duration": "5 hours",
"value": 1
}
]
}
}
}
```
`min_cycle_gap_h` enforces a minimum idle time between the end of one cycle and the start of the
next; it defaults to `0`, which permits back-to-back runs. To let both cycles run anywhere in a
shared window instead of separate morning/evening slots, give both windows the same `start_time`
and `duration` but keep their distinct `value` (cycle index) -- the optimizer still places each
cycle independently within that shared window.
How many cycles remain to be scheduled on a given energy management run is read at runtime from
the measurement store, under the key configured in `cycles_completed_measurement_key` (defaults
to `{device_id}.cycles_completed`). This lets the optimizer skip cycles the appliance has already
completed earlier the same day.
:::{admonition} Note
:class: note
Unlike GENETIC0, the GENETIC algorithm can plan multiple cycles -- and therefore multiple starts
-- of the same appliance within a single energy management run, whenever `num_cycles` (or the
number of distinct cycle indices in `cycle_time_windows`) is greater than 1.
:::
### Home Appliance Instructions
The home appliance instructions assume an idealized home appliance model. Under this model,