S2 changelog: one sensor holds the charging efficiency of all operation modes

CHANGELOG-S2.rst

@@ -26,9 +26,9 @@ Added
 * ``FRBCSimple`` takes an ``energy_unit`` (default ``kWh``). The state of charge, the fill-level band, the fill rate and the usage forecast are recorded in this unit (the last two per second). Allowed units are ``J``, ``kJ``, ``MJ``, ``Wh``, ``kWh`` and ``MWh``; any other unit is refused when the handler is created. In a flex model, the state of charge is stated in ``kWh`` or ``MWh``, converted from the other units, because FlexMeasures accepts no others [`#244 <https://github.com/FlexMeasures/flexmeasures-client/pull/244>`__, `#260 <https://github.com/FlexMeasures/flexmeasures-client/pull/260>`__]
 * ``FRBCSimple`` takes a ``fill_level_scale`` (default 1). Every fill level and fill rate sent to FlexMeasures is multiplied by it: the state of charge, the flex model, the fill-level band, the fill rate, the usage forecast and the storage efficiency. Translating a schedule into instructions keeps the resource manager's own units, because it matches fill levels against the operation modes, which are stated in those units. A scale of zero or below is refused. ``FRBCSimple`` also takes a ``power_unit`` (default ``W``), which an actuator's power is converted into and posted in [`#236 <https://github.com/FlexMeasures/flexmeasures-client/pull/236>`__, `#244 <https://github.com/FlexMeasures/flexmeasures-client/pull/244>`__, `#245 <https://github.com/FlexMeasures/flexmeasures-client/pull/245>`__, `#252 <https://github.com/FlexMeasures/flexmeasures-client/pull/252>`__]
 * ``FRBCSimple`` takes a ``hard_bound_factor`` (default 1.5). It sets how far above the declared fill-level range a schedule's hard upper bound lies. If a schedule starts from a state of charge above that bound, the bound is raised to include it. A factor below 1 is refused: FlexMeasures clips the band to the hard bounds, so a hard upper bound inside the declared range would narrow the band to something the resource manager never asked for [`#245 <https://github.com/FlexMeasures/flexmeasures-client/pull/245>`__]
-* ``FRBCSimple`` can take the actuator's charging efficiency into account. Give it the new ``charging_efficiency_sensor_id``: it records there what the operation modes say about converting drawn power into stored energy, and requests a schedule with it as ``charging-efficiency``. For a heat pump, this ratio is its coefficient of performance. Without it, the scheduler assumes power converts into stored energy one to one, and plans to reach fill-level targets at a power the actuator cannot deliver.
+* ``FRBCSimple`` can take the actuator's charging efficiency into account: how much stored energy the drawn power becomes. For a heat pump, this is its coefficient of performance. Give it the new ``charging_efficiency_sensor_id``. Before each schedule request, it records the efficiency there, over the window of the schedule, and requests the schedule with it as ``charging-efficiency``. Without it, the scheduler assumes power converts into stored energy one to one, and plans to reach fill-level targets at a power the actuator cannot deliver.
 
-  - FlexMeasures takes one efficiency per device. If a mode's efficiency depends on the fill level, the value where the schedule starts is used. If modes differ, the lowest is used, and the choice is logged.
+  - FlexMeasures takes one efficiency per device, so all operation modes share one sensor and one value. If modes differ, the lowest is used, and the choice is logged. If a mode's efficiency depends on the fill level, the value where the schedule starts is used. A sensor per mode would only help once FlexMeasures can plan with an efficiency per mode (`FlexMeasures #2832 <https://github.com/FlexMeasures/flexmeasures/issues/2832>`__).
   - A mode that draws power without filling the storage, such as standby or circulation, does not count. Counting it as zero would tell the scheduler that the storage cannot be filled at all. Modes reserved for abnormal conditions do not count either.
   - The efficiency is recorded once per window. It is recorded again for the next schedule if FlexMeasures did not confirm storing it. If it cannot be recorded, the schedule is requested without it, and this is logged.