Refactor scheduler interface - API and inner logic

documentation/api/change_log.rst

@@ -5,6 +5,24 @@ API change log
 
 .. note:: The FlexMeasures API follows its own versioning scheme. This is also reflected in the URL, allowing developers to upgrade at their own pace.
 
+v3.0-5 | 2022-12-30
+"""""""""""""""""""
+
+- Introduced ``flex-model`` and ``flex-context`` fields to `/sensors/<id>/schedules/trigger` (POST). They are dictionaries and group pre-existing fields:
+
+    - ``soc-at-start`` -> send in ``flex-model`` instead
+    - ``soc-min`` -> send in ``flex-model`` instead
+    - ``soc-max`` -> send in ``flex-model`` instead
+    - ``soc-unit`` -> send in ``flex-model`` instead
+    - ``roundtrip-efficiency`` -> send in ``flex-model`` instead
+    - ``prefer-charging-sooner`` -> send in ``flex-model`` instead
+    - ``consumption-price-sensor`` -> send in ``flex-context`` instead
+    - ``production-price-sensor`` -> send in ``flex-context`` instead
+    - ``inflexible-device-sensors`` -> send in ``flex-context`` instead
+
+- The field ``doc-sensor-id`` in `/sensors/<id>/schedules/trigger` (POST) has been deprecated.
+
+
 v3.0-4 | 2022-12-08
 """""""""""""""""""
 

documentation/api/notation.rst

@@ -163,9 +163,12 @@ Describing flexibility
 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.
 
-To compute a schedule, FlexMeasures first needs to assess the flexibility available to the system.
-For this it needs information about the state and possible actions of each device, as well as context information about the system as a whole, in order to assess the value of activating flexibility.
-This information goes beyond the usual time series recorded by an asset's sensors.
+To compute a schedule, FlexMeasures first needs to assess under what configuration flexibility can be made available to the system.
+This is described by the `flex model` (information about the state and possible actions of the flexible device) and the `flex-context`
+(information about the system as a whole, in order to assess the value of activating flexibility).
+
+This information goes beyond the usual time series recorded by an asset's sensors. It's being sent through the API when triggering schedule computation.
+Some parts of it can be persisted on the asset & sensor model as attributes (that's design work in progress). 
 
 We distinguish the information with two groups:
 

flexmeasures/data/models/planning/storage.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from datetime import datetime, timedelta
-from typing import List, Union, Dict
+from typing import List, Dict
 
 import pandas as pd
 import numpy as np
@@ -28,7 +28,7 @@ class StorageScheduler(Scheduler):
 
     def compute_schedule(
         self,
-    ) -> Union[pd.Series, None]:
+    ) -> pd.Series | None:
         """Schedule a battery or Charge Point based directly on the latest beliefs regarding market prices within the specified time window.
         For the resulting consumption schedule, consumption is defined as positive values.
         """
@@ -259,7 +259,7 @@ def inspect_flex_config(self):
 
     def get_min_max_targets(
         self, deserialized_names: bool = True
-    ) -> tuple[float | None]:
+    ) -> tuple[float | None, float | None]:
         min_target = None
         max_target = None
         soc_targets_label = "soc_targets" if deserialized_names else "soc-targets"

flexmeasures/data/services/scheduling.py

@@ -1,5 +1,6 @@
+from __future__ import annotations
+
 from datetime import datetime, timedelta
-from typing import Optional
 import os
 import sys
 import importlib.util
@@ -29,8 +30,8 @@
 
 
 def create_scheduling_job(
-    sensor: [int | Sensor],
-    job_id: Optional[str] = None,
+    sensor: int | Sensor,
+    job_id: str | None = None,
     enqueue: bool = True,
     **scheduler_kwargs,
 ) -> Job:
@@ -72,9 +73,9 @@ def make_schedule(
     start: datetime,
     end: datetime,
     resolution: timedelta,
-    belief_time: Optional[datetime] = None,
-    flex_model: Optional[dict] = None,
-    flex_context: Optional[dict] = None,
+    belief_time: datetime | None = None,
+    flex_model: dict | None = None,
+    flex_context: dict | None = None,
 ) -> bool:
     """
     This function is meant to be queued as a job. It returns True if it ran successfully.
@@ -238,7 +239,7 @@ def handle_scheduling_exception(job, exc_type, exc_value, traceback):
     job.save_meta()
 
 
-def get_data_source_for_job(job: Optional[Job]) -> Optional[DataSource]:
+def get_data_source_for_job(job: Job | None) -> DataSource | None:
     """
     Try to find the data source linked by this scheduling job.