Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions CHANGELOG-S2.rst
Original file line number Diff line number Diff line change
Expand Up @@ -19,11 +19,12 @@ Added
* ``FRBCSimple`` can record what a resource manager declares about its storage, so it can be seen and planned with. Give it any of the new ``soc_minima_sensor_id``, ``soc_maxima_sensor_id``, ``usage_forecast_sensor_id`` and ``leakage_behaviour_sensor_id``; a declaration without a sensor is not recorded.

- A fill-level target profile is recorded on the minima and maxima sensors, if both are given. It is recorded on the handler's ``resolution`` steps, starting from the step its start falls in. It is kept inside the declared fill-level range: a target past either end, such as a night setback below the range, is cut back to the range, and a target band wholly outside the range is recorded at its nearest end, with a warning. If one of the two bounds cannot be recorded, this is logged and the other is still recorded.
- A usage forecast is recorded in ``<energy_unit>/s``. A negative expected usage is recorded as zero, with a warning.
- A usage forecast is recorded in ``fill_rate_unit`` (see below). A negative expected usage is recorded as zero, with a warning.
- A leakage behaviour is recorded as a storage efficiency, each time a schedule is requested (see Changed).

[`#244 <https://github.com/FlexMeasures/flexmeasures-client/pull/244>`__, `#259 <https://github.com/FlexMeasures/flexmeasures-client/pull/259>`__, `#271 <https://github.com/FlexMeasures/flexmeasures-client/pull/271>`__, `#274 <https://github.com/FlexMeasures/flexmeasures-client/pull/274>`__]
* ``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 an ``energy_unit`` (default ``kWh``). The state of charge and the fill-level band are recorded in this unit. 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_rate_unit`` (default ``W``; also ``kW`` or ``MW``). Rates of fill level, which S2 states per second, are recorded in it: the fill rate and the usage forecast. In ``kWh/s``, a heat buffer's rates of some tens of watts would read about 0.00001. Any other unit is refused when the handler is created [`#290 <https://github.com/FlexMeasures/flexmeasures-client/pull/290>`__]
* ``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: 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.
Expand All @@ -48,10 +49,10 @@ Added
* An FRBC handler tracks the instruction batch the resource manager is working from, and can revoke instructions it no longer wants carried out. Set its ``send_revocations`` attribute to ``True``. When a new batch replaces that one, the handler revokes the old batch's pending instructions: those without a reported status, or reported as ``NEW`` or ``ACCEPTED``. This is off by default, because a resource manager does not have to honour revocations [`#237 <https://github.com/FlexMeasures/flexmeasures-client/pull/237>`__]
* New ``FRBC`` methods for handlers. ``filter_instruction_transitions()`` drops instructions that repeat the previous one. ``send_instruction_batch()`` sends a batch that replaces the previous one, unless a newer request has arrived in the meantime. ``system_description_fingerprint()`` tells a changed system description from a re-sent one [`#237 <https://github.com/FlexMeasures/flexmeasures-client/pull/237>`__]
* ``ControlTypeHandler.send_message()``. Handlers now use it to send messages, instead of putting them on the CEM's sending queue themselves [`#237 <https://github.com/FlexMeasures/flexmeasures-client/pull/237>`__]
* ``FRBCSimple`` takes an optional ``fill_rate_sensor_id``, and records the actuator's fill rate there. The fill rate is recorded in ``<energy_unit>/s``, not as a power: S2 states a fill rate as fill level per second, which for a heat buffer is not electricity at all [`#236 <https://github.com/FlexMeasures/flexmeasures-client/pull/236>`__, `#244 <https://github.com/FlexMeasures/flexmeasures-client/pull/244>`__]
* ``FRBCSimple`` takes an optional ``fill_rate_sensor_id``, and records the actuator's fill rate there. The fill rate is recorded in ``fill_rate_unit``, not in ``power_unit``: a fill rate is what the actuator delivers into its buffer, which for a heat buffer is not electricity at all [`#236 <https://github.com/FlexMeasures/flexmeasures-client/pull/236>`__, `#244 <https://github.com/FlexMeasures/flexmeasures-client/pull/244>`__]
* ``flexmeasures_client.s2.clock``, with a ``WallClock`` and a ``SimulatedClock``, and ``CEM(clock=...)``. The clock sets the time for the CEM and for every handler it registers. That includes their timers, and the time a recorded state of charge is known from [`#264 <https://github.com/FlexMeasures/flexmeasures-client/pull/264>`__, `#268 <https://github.com/FlexMeasures/flexmeasures-client/pull/268>`__]
* ``CEM(accept_simulation_metadata=True)`` accepts messages from a co-simulation that are wrapped with the simulated time (``S2Wrapper``), and sets the CEM's clock from them. It is off by default, and then a wrapped message is refused as invalid. The example server turns it on with ``S2_ACCEPT_SIMULATION_METADATA`` [`#264 <https://github.com/FlexMeasures/flexmeasures-client/pull/264>`__]
* ``flexmeasures_client.s2.site``, with ``FRBC_SITE_SENSORS``, ``ensure_site`` and ``FRBCSiteConfigurator``. It gives each resource manager its own FlexMeasures site, named after it, with an FRBC handler connected to that site's sensors [`#265 <https://github.com/FlexMeasures/flexmeasures-client/pull/265>`__]
* ``flexmeasures_client.s2.site``, with ``FRBC_SITE_SENSORS``, ``ensure_site`` and ``FRBCSiteConfigurator``. It gives each resource manager its own FlexMeasures site, named after it, with an FRBC handler connected to that site's sensors. The sensors' units suit a residential site and match the handler's defaults: powers and rates of fill level in ``W``, energy and fill levels in ``kWh``, and prices per ``kWh``. For sites at a larger scale, such as charge points, pass ``sensors`` with other units, and the handler's ``power_unit`` and ``fill_rate_unit`` in ``handler_options`` [`#265 <https://github.com/FlexMeasures/flexmeasures-client/pull/265>`__, `#290 <https://github.com/FlexMeasures/flexmeasures-client/pull/290>`__]
* ``CEM(site_configurator=...)`` sets up a resource manager's site once its details arrive. Until then, the CEM answers its messages with a temporary error. The example server enables this with ``S2_SITE_PER_RESOURCE_MANAGER`` [`#265 <https://github.com/FlexMeasures/flexmeasures-client/pull/265>`__]
* ``examples/S2-co-simulation``: a FlexMeasures stack with one CEM per simulated home, for co-simulations whose resource managers connect over websockets [`#265 <https://github.com/FlexMeasures/flexmeasures-client/pull/265>`__, `#267 <https://github.com/FlexMeasures/flexmeasures-client/pull/267>`__]
* ``flexmeasures_client.s2.measurements.MeasurementRecorder`` and ``CEM(measurement_recorder=...)`` record a resource manager's measured power. Use one recorder per server, so that a resource manager that reconnects is not recorded twice [`#266 <https://github.com/FlexMeasures/flexmeasures-client/pull/266>`__]
Expand Down
55 changes: 37 additions & 18 deletions src/flexmeasures_client/s2/control_types/FRBC/frbc_simple.py
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@
from flexmeasures_client.s2.control_types.FRBC import FRBC, STORAGE_STATUS_REQUESTS
from flexmeasures_client.s2.control_types.FRBC.utils import (
WATTS_PER_ENERGY_UNIT_PER_SECOND,
WATTS_PER_FILL_RATE_UNIT,
clip_fill_level_target_profile,
element_for_fill_level,
fm_schedule_to_instructions,
Expand Down Expand Up @@ -271,6 +272,10 @@ def __init__(
# The default is kilowatt-hours, because S2 is a residential protocol, and a home battery or heat buffer is of that order.
# A deployment at another scale can set a different unit here.
energy_unit: str = "kWh",
# The unit that rates of fill level are recorded in: the fill rate and the usage forecast.
# S2 states them per second, which in kWh/s makes tiny numbers, so they are recorded in a power unit: W, kW or MW.
# The default is watts, in which a residential heat buffer's rates read as such.
fill_rate_unit: str = "W",
) -> None:
super().__init__(max_size)
self._power_sensor_id = power_sensor_id
Expand Down Expand Up @@ -340,24 +345,34 @@ def __init__(
f"energy_unit has to be one of {', '.join(WATTS_PER_ENERGY_UNIT_PER_SECOND)}, but {energy_unit!r} was given."
)
self.energy_unit = energy_unit
if fill_rate_unit not in WATTS_PER_FILL_RATE_UNIT:
raise ValueError(
f"fill_rate_unit has to be one of {', '.join(WATTS_PER_FILL_RATE_UNIT)}, but {fill_rate_unit!r} was given."
)
self._fill_rate_unit = fill_rate_unit

# delay the start of the schedule from the time `valid_from`
# of the FRBC.SystemDescription.
self._valid_from_shift = valid_from_shift

def fill_rate_unit(self) -> str:
"""The unit a rate of change of the fill level is recorded in.
"""The unit a rate of change of the fill level is recorded in: the fill_rate_unit given, by default W.

S2 states a fill rate, and a usage forecast, as fill level per second, so this follows
whatever unit the fill level itself is recorded in. It is not the power unit: a fill rate
is what an actuator delivers into its buffer, which for a heat buffer is not electricity
at all, and which even for a battery differs from kilowatts by the seconds in an hour.
S2 states a fill rate and a usage forecast as fill level per second.
Per second, a residential heat buffer's rates are tiny numbers in kWh/s, so they are recorded in a power unit instead (see _per_second_in_fill_rate_unit).
It is not the power unit: a fill rate is what an actuator delivers into its buffer, which for a heat buffer is not electricity at all.

A method rather than a property, because S2 Handler's discover() walks dir(self) and
getattrs every name during __init__, before a subclass has assigned its own attributes.
A method rather than a property, because S2 Handler's discover() walks dir(self) and getattrs every name during __init__, before a subclass has assigned its own attributes.
A property would be evaluated there and raise on the energy_unit it reads.
"""
return f"{self.energy_unit}/s"
return self._fill_rate_unit

def _per_second_in_fill_rate_unit(self, rate):
"""Return a rate of fill level per second, as S2 states it, in the fill-rate unit; a number or a series."""
return rate * (
WATTS_PER_ENERGY_UNIT_PER_SECOND[self.energy_unit]
/ WATTS_PER_FILL_RATE_UNIT[self._fill_rate_unit]
)

def align_to_resolution(self, moment: datetime) -> datetime:
"""The last resolution boundary at or before that moment.
Expand Down Expand Up @@ -810,10 +825,13 @@ async def send_actuator_status(self, status: FRBCActuatorStatus):
# useful quantity - what the actuator delivers into its buffer - it simply is not power.
if self._fill_rate_sensor_id is not None:
fill_rate = element.fill_rate
rate = (
fill_rate.start_of_range
+ (fill_rate.end_of_range - fill_rate.start_of_range) * factor
) * self._fill_level_scale
rate = self._per_second_in_fill_rate_unit(
(
fill_rate.start_of_range
+ (fill_rate.end_of_range - fill_rate.start_of_range) * factor
)
* self._fill_level_scale
)
# Catch failures, like for the power above, because this runs in a task that nobody awaits.
try:
await self._fm_client.post_sensor_data(
Expand Down Expand Up @@ -1414,11 +1432,13 @@ async def send_usage_forecast(self, usage_forecast: FRBCUsageForecast):
)
return

translated = translate_usage_forecast_to_fm(
usage_forecast,
self._resolution,
strategy="mean",
fill_level_scale=self._fill_level_scale,
translated = self._per_second_in_fill_rate_unit(
translate_usage_forecast_to_fm(
usage_forecast,
self._resolution,
strategy="mean",
fill_level_scale=self._fill_level_scale,
)
)
# A negative usage is a gain that the storage is forced to take, and FlexMeasures cannot relax it.
# Above the hard ceiling, it makes every schedule for the window infeasible, so the storage gets no instruction at all.
Expand All @@ -1441,7 +1461,6 @@ async def send_usage_forecast(self, usage_forecast: FRBCUsageForecast):
start=self.align_to_resolution(usage_forecast.start_time),
prior=self.now(),
values=translated.tolist(),
# translate_usage_forecast_to_fm returns fill level per second, scaled.
unit=self.fill_rate_unit(),
duration=pd.Timedelta(self._resolution) * len(translated),
)
Expand Down
5 changes: 5 additions & 0 deletions src/flexmeasures_client/s2/control_types/FRBC/utils.py
Original file line number Diff line number Diff line change
Expand Up @@ -451,6 +451,11 @@ def get_soc_min_max(
}


#: The units a rate of fill level can be recorded in, and the number of watts in one of each.
#: S2 states rates per second, which in kWh/s puts a heat buffer's rates of some tens of watts near 1e-5, so they are recorded in a power unit instead, by default W.
WATTS_PER_FILL_RATE_UNIT: dict[str, float] = {"W": 1.0, "kW": 1e3, "MW": 1e6}


def fill_rate_in_watts(fill_rate: float, energy_unit: str) -> float:
"""Convert a fill rate to watts, given the unit that the fill level is recorded in.

Expand Down
10 changes: 5 additions & 5 deletions src/flexmeasures_client/s2/site.py
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ class SiteSensor:


#: The sensors an FRBC site needs, by name.
#: Their units are the units the CEM records in: fill levels in kWh, and fill rates per second, as in S2.
#: Their units suit a residential site, and match the handler's defaults: energy and fill levels in kWh, prices per kWh, and powers and rates of fill level in W.
#: The names are a contract with any reader of the site, such as a co-simulation.
#: A co-simulation looks up "price", "production price", "power", "state of charge" and "measured-power" by name.
FRBC_SITE_SENSORS: dict[str, SiteSensor] = {
Expand All @@ -48,15 +48,15 @@ class SiteSensor:
# This sensor holds both an actuator's power and the schedule planned for it.
# Without this attribute, FlexMeasures treats production as positive on a power sensor.
# It would then flip the sign of an incoming schedule, so the power and the schedule would point in opposite directions.
"power": SiteSensor("kW", "PT15M", {"consumption_is_positive": True}),
"power": SiteSensor("W", "PT15M", {"consumption_is_positive": True}),
# The power the resource manager measures its site drawing, kept separate from the schedule on "power".
"measured-power": SiteSensor("kW", "PT15M", {"consumption_is_positive": True}),
"measured-power": SiteSensor("W", "PT15M", {"consumption_is_positive": True}),
"state of charge": SiteSensor("kWh", "PT0M"),
"RM discharge": SiteSensor("dimensionless", "PT15M"),
"fill rate": SiteSensor("kWh/s", "PT15M"),
"fill rate": SiteSensor("W", "PT15M"),
"soc minima": SiteSensor("kWh", "PT15M"),
"soc maxima": SiteSensor("kWh", "PT15M"),
"usage forecast": SiteSensor("kWh/s", "PT15M"),
"usage forecast": SiteSensor("W", "PT15M"),
"storage efficiency": SiteSensor("%", "PT15M"),
"charging efficiency": SiteSensor("dimensionless", "PT15M"),
}
Expand Down
4 changes: 2 additions & 2 deletions tests/s2/test_example_end_to_end.py
Original file line number Diff line number Diff line change
Expand Up @@ -326,7 +326,7 @@ async def test_the_site_gets_a_sensor_for_every_declaration_and_prices_from_toda
made = {call.kwargs["name"]: call.kwargs for call in fm.add_sensor.await_args_list}
assert "price" not in made
assert made["power"]["attributes"] == {"consumption_is_positive": True}
assert made["fill rate"]["unit"] == "kWh/s"
assert made["fill rate"]["unit"] == "W"
assert made["soc minima"]["unit"] == "kWh"
prices = fm.post_sensor_data.await_args.kwargs
assert prices["sensor_id"] == 50
Expand Down Expand Up @@ -539,7 +539,7 @@ def test_the_site_sensors_are_what_the_cem_records_in():
server.SITE_SENSORS["state of charge"].resolution,
) == ("kWh", "PT0M")
assert server.SITE_SENSORS["storage efficiency"].unit == "%"
assert server.SITE_SENSORS["usage forecast"].unit == "kWh/s"
assert server.SITE_SENSORS["usage forecast"].unit == "W"


@pytest.mark.asyncio
Expand Down
Loading
Loading