From a01b8cf0168f42b473220d7e47df6dfc31f32e02 Mon Sep 17 00:00:00 2001 From: Jakub Kozlowicz Date: Thu, 29 Sep 2022 17:30:33 +0200 Subject: [PATCH 1/2] Change component data wrappers to be data classes Signed-off-by: Jakub Kozlowicz --- .../benchmark_microgrid_data.py | 8 +- src/frequenz/sdk/microgrid/client.py | 10 +- src/frequenz/sdk/microgrid/component_data.py | 322 ++++++++---------- .../test_distribution_algorithm.py | 10 +- .../test_power_distributor.py | 32 +- tests/test_microgrid/test_component_data.py | 21 ++ tests/utils/data_generation.py | 8 +- 7 files changed, 205 insertions(+), 206 deletions(-) create mode 100644 tests/test_microgrid/test_component_data.py diff --git a/benchmarks/data_ingestion/benchmark_microgrid_data.py b/benchmarks/data_ingestion/benchmark_microgrid_data.py index ef532f957..1f4f8e749 100644 --- a/benchmarks/data_ingestion/benchmark_microgrid_data.py +++ b/benchmarks/data_ingestion/benchmark_microgrid_data.py @@ -45,7 +45,7 @@ def gen_market_data(component_id: int) -> MeterData: """ timestamp = Timestamp() timestamp.GetCurrentTime() - return MeterData( + return MeterData.from_proto( microgrid_pb.ComponentData( id=component_id, ts=timestamp, @@ -69,7 +69,7 @@ def gen_pv_data(component_id: int) -> MeterData: """ timestamp = Timestamp() timestamp.GetCurrentTime() - return MeterData( + return MeterData.from_proto( microgrid_pb.ComponentData( id=component_id, ts=timestamp, @@ -93,7 +93,7 @@ def gen_battery_data(component_id: int) -> BatteryData: """ timestamp = Timestamp() timestamp.GetCurrentTime() - return BatteryData( + return BatteryData.from_proto( microgrid_pb.ComponentData( id=component_id, ts=timestamp, @@ -123,7 +123,7 @@ def gen_inverter_data(component_id: int) -> InverterData: """ timestamp = Timestamp() timestamp.GetCurrentTime() - return InverterData( + return InverterData.from_proto( microgrid_pb.ComponentData( id=component_id, ts=timestamp, diff --git a/src/frequenz/sdk/microgrid/client.py b/src/frequenz/sdk/microgrid/client.py index 5ae5c8044..b6ec835a0 100644 --- a/src/frequenz/sdk/microgrid/client.py +++ b/src/frequenz/sdk/microgrid/client.py @@ -413,7 +413,9 @@ async def meter_data( A channel receiver that provides realtime meter data. """ await self._expect_category(component_id, ComponentCategory.METER) - return self._get_component_data_channel(component_id, MeterData).get_receiver() + return self._get_component_data_channel( + component_id, MeterData.from_proto + ).get_receiver() async def battery_data( self, @@ -436,7 +438,7 @@ async def battery_data( """ await self._expect_category(component_id, ComponentCategory.BATTERY) return self._get_component_data_channel( - component_id, BatteryData + component_id, BatteryData.from_proto ).get_receiver() async def inverter_data( @@ -460,7 +462,7 @@ async def inverter_data( """ await self._expect_category(component_id, ComponentCategory.INVERTER) return self._get_component_data_channel( - component_id, InverterData + component_id, InverterData.from_proto ).get_receiver() async def ev_charger_data( @@ -484,7 +486,7 @@ async def ev_charger_data( """ await self._expect_category(component_id, ComponentCategory.EV_CHARGER) return self._get_component_data_channel( - component_id, EVChargerData + component_id, EVChargerData.from_proto ).get_receiver() async def set_power(self, component_id: int, power_w: int) -> Empty: diff --git a/src/frequenz/sdk/microgrid/component_data.py b/src/frequenz/sdk/microgrid/component_data.py index 0ed53b9eb..c486f3fcd 100644 --- a/src/frequenz/sdk/microgrid/component_data.py +++ b/src/frequenz/sdk/microgrid/component_data.py @@ -6,10 +6,12 @@ License MIT """ +from __future__ import annotations -from abc import ABC +from abc import ABC, abstractmethod +from dataclasses import dataclass, field from datetime import datetime -from typing import Tuple +from typing import Optional, Tuple import frequenz.api.microgrid.microgrid_pb2 as microgrid_pb import pytz @@ -17,229 +19,201 @@ from .component_states import EVChargerCableState -class _BaseComponentData(ABC): - """A private base class for strongly typed component data classes.""" +@dataclass(frozen=True) +class ComponentData(ABC): + """A private base class for strongly typed component data classes. - _raw: microgrid_pb.ComponentData + Attributes: + component_id: the ID identifying this component in the microgrid + timestamp: the timestamp of when the data was measured. + raw: raw component data as decoded from the wire + """ - @property - def component_id(self) -> int: - """Return the component id of the message. + component_id: int + timestamp: datetime + # The `raw` attribute is excluded from the constructor as it can only be provided + # when instantiating `ComponentData` using the `from_proto` method, which reads + # data from a protobuf message. The whole protobuf message is stored as the `raw` + # attribute. When `ComponentData` is not instantiated from a protobuf message, + # i.e. using the constructor, `raw` will be set to `None`. + raw: Optional[microgrid_pb.ComponentData] = field(default=None, init=False) - Returns: - Component id of the message. - """ - return self._raw.id - - @property - def timestamp(self) -> datetime: - """Return the timestamp of the message. - - Returns: - Timestamp of the message. - """ - return self._raw.ts.ToDatetime(tzinfo=pytz.UTC) + def _set_raw(self, raw: microgrid_pb.ComponentData) -> None: + """Store raw protobuf message. - -class MeterData(_BaseComponentData): - """A wrapper class for holding meter data.""" - - def __init__(self, raw: microgrid_pb.ComponentData) -> None: - """Create a `MeterData` instance. + It is preferred to keep the dataclasses immutable (frozen) and make the `raw` + attribute read-only, which is why the approach of writing to `__dict__` + was used, instead of mutating the `self.raw = raw` attribute directly. Args: raw: raw component data as decoded from the wire. """ - self._raw = raw - - @property - def active_power(self) -> float: - """Get current power with which the meter is being discharged. + self.__dict__["raw"] = raw - Returns: - Current power with which the meter is being discharged. - """ - return self._raw.meter.data.ac.power_active.value + @classmethod + @abstractmethod + def from_proto(cls, raw: microgrid_pb.ComponentData) -> ComponentData: + """Create ComponentData from a protobuf message. - @property - def current_per_phase(self) -> Tuple[float, float, float]: - """Get apparant current measured by the meter per-phase. - - Returns: - Current values for each phase. + Args: + raw: raw component data as decoded from the wire. """ - phase_1 = self._raw.meter.data.ac.phase_1.current.value - phase_2 = self._raw.meter.data.ac.phase_2.current.value - phase_3 = self._raw.meter.data.ac.phase_3.current.value - return (phase_1, phase_2, phase_3) - - @property - def voltage_per_phase(self) -> Tuple[float, float, float]: - """Get voltages measured by the meter per phase. - Returns: - Voltage values for each phase. - """ - phase_1 = self._raw.meter.data.ac.phase_1.voltage.value - phase_2 = self._raw.meter.data.ac.phase_2.voltage.value - phase_3 = self._raw.meter.data.ac.phase_3.voltage.value - return (phase_1, phase_2, phase_3) +@dataclass(frozen=True) +class MeterData(ComponentData): + """A wrapper class for holding meter data.""" -class BatteryData(_BaseComponentData): - """A wrapper class for holding battery data.""" + active_power: float + current_per_phase: Tuple[float, float, float] + voltage_per_phase: Tuple[float, float, float] - def __init__(self, raw: microgrid_pb.ComponentData) -> None: - """Create a `BatteryData` instance. + @classmethod + def from_proto(cls, raw: microgrid_pb.ComponentData) -> MeterData: + """Create MeterData from a protobuf message. Args: raw: raw component data as decoded from the wire. - """ - self._raw = raw - - @property - def soc(self) -> float: - """Get current SoC level. Returns: - SoC level. + Instance of MeterData created from the protobuf message. """ - return self._raw.battery.data.soc.avg + meter_data = cls( + component_id=raw.id, + timestamp=raw.ts.ToDatetime(tzinfo=pytz.UTC), + active_power=raw.meter.data.ac.power_active.value, + current_per_phase=( + raw.meter.data.ac.phase_1.current.value, + raw.meter.data.ac.phase_2.current.value, + raw.meter.data.ac.phase_3.current.value, + ), + voltage_per_phase=( + raw.meter.data.ac.phase_1.voltage.value, + raw.meter.data.ac.phase_2.voltage.value, + raw.meter.data.ac.phase_3.voltage.value, + ), + ) + meter_data._set_raw(raw=raw) + return meter_data - @property - def soc_upper_bound(self) -> float: - """Get SoC upper bound. - Returns: - Maximum SoC level. - """ - return self._raw.battery.data.soc.system_bounds.upper +@dataclass(frozen=True) +class BatteryData(ComponentData): + """A wrapper class for holding battery data. - @property - def soc_lower_bound(self) -> float: - """Get SoC lower bound. + soc: battery's overall SoC in percent (%). - Returns: - Minimum SoC level. - """ - return self._raw.battery.data.soc.system_bounds.lower + soc_lower_bound: the SoC below which discharge commands will be blocked by the + system, in percent (%). - @property - def capacity(self) -> float: - """Get battery capacity. + soc_upper_bound: the SoC above which charge commands will be blocked by the + system, in percent (%). - Returns: - Capacity of the battery. - """ - return self._raw.battery.properties.capacity + capacity: the capacity of the battery in Wh (Watt-hour) - @property - def power_upper_bound(self) -> float: - """Get maximum power with which the battery can be charged. + power_lower_bound: the maximum discharge power, in Watts, represented in the + passive sign convention. This will be a negative number, or zero if no + discharging is possible. - Returns: - Maximum power with which the battery can be charged. - """ - return self._raw.battery.data.dc.power.system_bounds.upper - - @property - def power_lower_bound(self) -> float: - """Get minimum power with which the battery can be discharged. + power_upper_bound: the maximum charge power, in Watts, represented in the + passive sign convention. This will be a positive number, or zero if no + charging is possible. + """ - Returns: - Minimum power with which the battery can be discharged. - """ - return self._raw.battery.data.dc.power.system_bounds.lower - - -class InverterData(_BaseComponentData): - """A wrapper class for holding inverter data.""" + soc: float + soc_lower_bound: float + soc_upper_bound: float + capacity: float + power_lower_bound: float + power_upper_bound: float - def __init__(self, raw: microgrid_pb.ComponentData) -> None: - """Create a `InverterData` instance. + @classmethod + def from_proto(cls, raw: microgrid_pb.ComponentData) -> BatteryData: + """Create BatteryData from a protobuf message. Args: raw: raw component data as decoded from the wire. - """ - self._raw = raw - - @property - def active_power(self) -> float: - """Get current power with which the inverter is being discharged. Returns: - Current power with which the inverter is being discharged. + Instance of BatteryData created from the protobuf message. """ - return self._raw.inverter.data.ac.power_active.value - - @property - def active_power_upper_bound(self) -> float: - """Get maximum power with which the inverter can be charged. - - Returns: - Maximum power with which the inverter can be charged. - """ - return self._raw.inverter.data.ac.power_active.system_bounds.upper - - @property - def active_power_lower_bound(self) -> float: - """Get minimum power with which the inverter can be discharged. + battery_data = cls( + component_id=raw.id, + timestamp=raw.ts.ToDatetime(tzinfo=pytz.UTC), + soc=raw.battery.data.soc.avg, + soc_lower_bound=raw.battery.data.soc.system_bounds.lower, + soc_upper_bound=raw.battery.data.soc.system_bounds.upper, + capacity=raw.battery.properties.capacity, + power_lower_bound=raw.battery.data.dc.power.system_bounds.lower, + power_upper_bound=raw.battery.data.dc.power.system_bounds.upper, + ) + battery_data._set_raw(raw=raw) + return battery_data - Returns: - Minimum power with which the inverter can be discharged. - """ - return self._raw.inverter.data.ac.power_active.system_bounds.lower +@dataclass(frozen=True) +class InverterData(ComponentData): + """A wrapper class for holding inverter data.""" -class EVChargerData(_BaseComponentData): - """A wrapper class for holding ev_charger data.""" + active_power: float + active_power_lower_bound: float + active_power_upper_bound: float - def __init__(self, raw: microgrid_pb.ComponentData) -> None: - """Create a `EVChargerData` instance. + @classmethod + def from_proto(cls, raw: microgrid_pb.ComponentData) -> InverterData: + """Create InverterData from a protobuf message. Args: raw: raw component data as decoded from the wire. - """ - self._raw = raw - - @property - def active_power(self) -> float: - """Get current power with which the EV charger is being charged. Returns: - Current power with which the EV charger is being charged. + Instance of InverterData created from the protobuf message. """ - return self._raw.ev_charger.data.ac.power_active.value + inverter_data = cls( + component_id=raw.id, + timestamp=raw.ts.ToDatetime(tzinfo=pytz.UTC), + active_power=raw.inverter.data.ac.power_active.value, + active_power_lower_bound=raw.inverter.data.ac.power_active.system_bounds.lower, + active_power_upper_bound=raw.inverter.data.ac.power_active.system_bounds.upper, + ) + inverter_data._set_raw(raw=raw) + return inverter_data - @property - def current_per_phase(self) -> Tuple[float, float, float]: - """Get apparant current consumed by the ev charger, per-phase. - Returns: - Current values for each phase. - """ - phase_1 = self._raw.ev_charger.data.ac.phase_1.current.value - phase_2 = self._raw.ev_charger.data.ac.phase_2.current.value - phase_3 = self._raw.ev_charger.data.ac.phase_3.current.value - return (phase_1, phase_2, phase_3) +@dataclass(frozen=True) +class EVChargerData(ComponentData): + """A wrapper class for holding ev_charger data.""" - @property - def voltage_per_phase(self) -> Tuple[float, float, float]: - """Get voltages measured by the ev charger, per phase. + active_power: float + current_per_phase: Tuple[float, float, float] + voltage_per_phase: Tuple[float, float, float] + cable_state: EVChargerCableState - Returns: - Voltage values for each phase. - """ - phase_1 = self._raw.ev_charger.data.ac.phase_1.voltage.value - phase_2 = self._raw.ev_charger.data.ac.phase_2.voltage.value - phase_3 = self._raw.ev_charger.data.ac.phase_3.voltage.value - return (phase_1, phase_2, phase_3) + @classmethod + def from_proto(cls, raw: microgrid_pb.ComponentData) -> EVChargerData: + """Create EVChargerData from a protobuf message. - @property - def cable_state(self) -> EVChargerCableState: - """Get cable state of the ev charger. + Args: + raw: raw component data as decoded from the wire. Returns: - Cable state. - """ - return EVChargerCableState.from_pb(self._raw.ev_charger.state.cable_state) + Instance of EVChargerData created from the protobuf message. + """ + ev_charger_data = cls( + component_id=raw.id, + timestamp=raw.ts.ToDatetime(tzinfo=pytz.UTC), + active_power=raw.ev_charger.data.ac.power_active.value, + current_per_phase=( + raw.meter.data.ac.phase_1.current.value, + raw.meter.data.ac.phase_2.current.value, + raw.meter.data.ac.phase_3.current.value, + ), + voltage_per_phase=( + raw.meter.data.ac.phase_1.voltage.value, + raw.meter.data.ac.phase_2.voltage.value, + raw.meter.data.ac.phase_3.voltage.value, + ), + cable_state=EVChargerCableState.from_pb(raw.ev_charger.state.cable_state), + ) + ev_charger_data._set_raw(raw=raw) + return ev_charger_data diff --git a/tests/power_distribution/test_distribution_algorithm.py b/tests/power_distribution/test_distribution_algorithm.py index 1b7a47fb2..ad2152ae6 100644 --- a/tests/power_distribution/test_distribution_algorithm.py +++ b/tests/power_distribution/test_distribution_algorithm.py @@ -153,10 +153,10 @@ def create_components_with_capacity( id=2 * i, battery=Battery(properties=BatteryProperties(capacity=capacity[i])), ) - battery = BatteryData(bat_msg) + battery = BatteryData.from_proto(bat_msg) inv_msg = microgrid_pb.ComponentData(id=2 * i + 1, inverter=Inverter()) - inverter = InverterData(inv_msg) + inverter = InverterData.from_proto(inv_msg) components.append(InvBatPair(battery, inverter)) return components @@ -327,7 +327,7 @@ def create_components( # pylint: disable=too-many-arguments components: List[InvBatPair] = [] for i in range(0, num): - battery = BatteryData( + battery = BatteryData.from_proto( create_battery_msg( 2 * i, capacity[i], @@ -335,7 +335,9 @@ def create_components( # pylint: disable=too-many-arguments power[2 * i], ) ) - inverter = InverterData(create_inverter_msg(2 * i + 1, power[2 * i + 1])) + inverter = InverterData.from_proto( + create_inverter_msg(2 * i + 1, power[2 * i + 1]) + ) components.append(InvBatPair(battery, inverter)) return components diff --git a/tests/power_distribution/test_power_distributor.py b/tests/power_distribution/test_power_distributor.py index da885d2ab..c3f75707a 100644 --- a/tests/power_distribution/test_power_distributor.py +++ b/tests/power_distribution/test_power_distributor.py @@ -210,7 +210,7 @@ async def test_power_distributor_one_user( soc=Metric(40, Bound(20, 80)), power=Bound(-1000, 1000), ) - await sender.send(BatteryData(bat)) + await sender.send(BatteryData.from_proto(bat)) for key_id, inv_chan in inv_channels.items(): inv_sender = inv_chan.get_sender() @@ -218,7 +218,7 @@ async def test_power_distributor_one_user( key_id, power=Bound(-500, 500), ) - await inv_sender.send(InverterData(inv)) + await inv_sender.send(InverterData.from_proto(inv)) channel = Bidirectional[Request, Result]("user1", "power_distributor") with mock.patch("asyncio.sleep", new_callable=AsyncMock): @@ -262,7 +262,7 @@ async def test_power_distributor_two_users( soc=Metric(40, Bound(20, 80)), power=Bound(-1000, 1000), ) - await sender.send(BatteryData(bat)) + await sender.send(BatteryData.from_proto(bat)) for key_id, inv_chan in inv_channels.items(): inv_sender = inv_chan.get_sender() @@ -270,7 +270,7 @@ async def test_power_distributor_two_users( key_id, power=Bound(-500, 500), ) - await inv_sender.send(InverterData(inv)) + await inv_sender.send(InverterData.from_proto(inv)) channel1 = Bidirectional[Request, Result]("user1", "power_distributor") channel2 = Bidirectional[Request, Result]("user2", "power_distributor") @@ -331,7 +331,7 @@ async def test_power_distributor_invalid_battery_id(self) -> None: soc=Metric(40, Bound(20, 80)), power=Bound(-1000, 1000), ) - await sender.send(BatteryData(bat)) + await sender.send(BatteryData.from_proto(bat)) for key_id, inv_chan in inv_channels.items(): inv_sender = inv_chan.get_sender() @@ -339,7 +339,7 @@ async def test_power_distributor_invalid_battery_id(self) -> None: key_id, power=Bound(-500, 500), ) - await inv_sender.send(InverterData(inv)) + await inv_sender.send(InverterData.from_proto(inv)) channel1 = Bidirectional[Request, Result]("user1", "power_distributor") service_channels = { @@ -383,7 +383,7 @@ async def test_power_distributor_overlapping_batteries(self) -> None: soc=Metric(40, Bound(20, 80)), power=Bound(-1000, 1000), ) - await sender.send(BatteryData(bat)) + await sender.send(BatteryData.from_proto(bat)) for key_id, inv_chan in inv_channels.items(): inv_sender = inv_chan.get_sender() @@ -391,7 +391,7 @@ async def test_power_distributor_overlapping_batteries(self) -> None: key_id, power=Bound(-500, 500), ) - await inv_sender.send(InverterData(inv)) + await inv_sender.send(InverterData.from_proto(inv)) channel1 = Bidirectional[Request, Result]("user1", "power_distributor") channel2 = Bidirectional[Request, Result]("user2", "power_distributor") @@ -464,7 +464,7 @@ async def test_power_distributor_one_user_adjust_power_out_of_bound( soc=Metric(40, Bound(20, 80)), power=Bound(-1000, 1000), ) - await sender.send(BatteryData(bat)) + await sender.send(BatteryData.from_proto(bat)) for key_id, inv_chan in inv_channels.items(): inv_sender = inv_chan.get_sender() @@ -472,7 +472,7 @@ async def test_power_distributor_one_user_adjust_power_out_of_bound( key_id, power=Bound(-500, 500), ) - await inv_sender.send(InverterData(inv)) + await inv_sender.send(InverterData.from_proto(inv)) channel1 = Bidirectional[Request, Result]("user1", "power_distributor") service_channels = { @@ -522,7 +522,7 @@ async def test_power_distributor_one_user_adjust_power_success( soc=Metric(40, Bound(20, 80)), power=Bound(-1000, 1000), ) - await sender.send(BatteryData(bat)) + await sender.send(BatteryData.from_proto(bat)) for key_id, inv_chan in inv_channels.items(): inv_sender = inv_chan.get_sender() @@ -530,7 +530,7 @@ async def test_power_distributor_one_user_adjust_power_success( key_id, power=Bound(-500, 500), ) - await inv_sender.send(InverterData(inv)) + await inv_sender.send(InverterData.from_proto(inv)) channel1 = Bidirectional[Request, Result]("user1", "power_distributor") service_channels = { @@ -591,7 +591,7 @@ async def test_power_distributor_stale_battery_message( soc=Metric(40, Bound(20, 80)), power=Bound(-1000, 1000), ) - await sender.send(BatteryData(bat)) + await sender.send(BatteryData.from_proto(bat)) for key_id, inv_chan in inv_channels.items(): inv_sender = inv_chan.get_sender() @@ -599,7 +599,7 @@ async def test_power_distributor_stale_battery_message( key_id, power=Bound(-500, 500), ) - await inv_sender.send(InverterData(inv)) + await inv_sender.send(InverterData.from_proto(inv)) channel = Bidirectional[Request, Result]("user1", "power_distributor") @@ -654,7 +654,7 @@ async def test_power_distributor_stale_all_components_message( soc=Metric(40, Bound(20, 80)), power=Bound(-1000, 1000), ) - await sender.send(BatteryData(bat)) + await sender.send(BatteryData.from_proto(bat)) for key_id, inv_chan in inv_channels.items(): inv_sender = inv_chan.get_sender() @@ -669,7 +669,7 @@ async def test_power_distributor_stale_all_components_message( key_id, power=Bound(-500, 500), ) - await inv_sender.send(InverterData(inv)) + await inv_sender.send(InverterData.from_proto(inv)) channel = Bidirectional[Request, Result]("user1", "power_distributor") diff --git a/tests/test_microgrid/test_component_data.py b/tests/test_microgrid/test_component_data.py new file mode 100644 index 000000000..7903ce6e5 --- /dev/null +++ b/tests/test_microgrid/test_component_data.py @@ -0,0 +1,21 @@ +""" +Tests for the microgrid component data. + +Copyright +Copyright © 2022 Frequenz Energy-as-a-Service GmbH + +License +MIT +""" +import datetime + +import pytest + +from frequenz.sdk.microgrid.component_data import ComponentData + + +def test_component_data_abstract_class() -> None: + """Verify the base class ComponentData may not be instantiated.""" + with pytest.raises(TypeError): + # pylint: disable=abstract-class-instantiated + ComponentData(0, datetime.datetime.utcnow()) # type: ignore diff --git a/tests/utils/data_generation.py b/tests/utils/data_generation.py index 4c83bfaf0..d3df92c56 100644 --- a/tests/utils/data_generation.py +++ b/tests/utils/data_generation.py @@ -70,7 +70,7 @@ def generate_battery_data( if overrides is not None and component_id in overrides: _params.update(overrides[component_id]) - return BatteryData( + return BatteryData.from_proto( microgrid_pb.ComponentData( ts=timestamp, id=component_id, @@ -124,7 +124,7 @@ def generate_inverter_data( if overrides is not None and component_id in overrides: _params.update(overrides[component_id]) - return InverterData( + return InverterData.from_proto( microgrid_pb.ComponentData( ts=timestamp, id=component_id, @@ -174,7 +174,7 @@ def generate_meter_data( if overrides is not None and component_id in overrides: _params.update(overrides[component_id]) - return MeterData( + return MeterData.from_proto( microgrid_pb.ComponentData( ts=timestamp, id=component_id, @@ -235,7 +235,7 @@ def generate_ev_charger_data( if overrides is not None and component_id in overrides: _params.update(overrides[component_id]) - return EVChargerData( + return EVChargerData.from_proto( microgrid_pb.ComponentData( ts=timestamp, id=component_id, From 6bd9212296d52e213d949f02c99abdb785310e61 Mon Sep 17 00:00:00 2001 From: Jakub Kozlowicz Date: Fri, 30 Sep 2022 13:18:46 +0200 Subject: [PATCH 2/2] Add field descriptions and units Signed-off-by: Jakub Kozlowicz --- src/frequenz/sdk/microgrid/component_data.py | 76 ++++++++++++++------ 1 file changed, 56 insertions(+), 20 deletions(-) diff --git a/src/frequenz/sdk/microgrid/component_data.py b/src/frequenz/sdk/microgrid/component_data.py index c486f3fcd..cb1e10b9f 100644 --- a/src/frequenz/sdk/microgrid/component_data.py +++ b/src/frequenz/sdk/microgrid/component_data.py @@ -62,7 +62,20 @@ def from_proto(cls, raw: microgrid_pb.ComponentData) -> ComponentData: @dataclass(frozen=True) class MeterData(ComponentData): - """A wrapper class for holding meter data.""" + """A wrapper class for holding meter data. + + Attributes: + active_power: the 3-phase active power, in Watts, represented in the passive + sign convention. + +ve current means consumption, away from the grid. + -ve current means supply into the grid. + current_per_phase: AC current in Amperes (A) for phase/line 1,2 and 3 + respectively. + +ve current means consumption, away from the grid. + -ve current means supply into the grid. + voltage_per_phase: the AC voltage in Volts (V) between the line and the neutral + wire for phase/line 1,2 and 3 respectively. + """ active_power: float current_per_phase: Tuple[float, float, float] @@ -101,23 +114,19 @@ def from_proto(cls, raw: microgrid_pb.ComponentData) -> MeterData: class BatteryData(ComponentData): """A wrapper class for holding battery data. - soc: battery's overall SoC in percent (%). - - soc_lower_bound: the SoC below which discharge commands will be blocked by the - system, in percent (%). - - soc_upper_bound: the SoC above which charge commands will be blocked by the - system, in percent (%). - - capacity: the capacity of the battery in Wh (Watt-hour) - - power_lower_bound: the maximum discharge power, in Watts, represented in the - passive sign convention. This will be a negative number, or zero if no - discharging is possible. - - power_upper_bound: the maximum charge power, in Watts, represented in the - passive sign convention. This will be a positive number, or zero if no - charging is possible. + Attributes: + soc: battery's overall SoC in percent (%). + soc_lower_bound: the SoC below which discharge commands will be blocked by the + system, in percent (%). + soc_upper_bound: the SoC above which charge commands will be blocked by the + system, in percent (%). + capacity: the capacity of the battery in Wh (Watt-hour) + power_lower_bound: the maximum discharge power, in Watts, represented in the + passive sign convention. This will be a negative number, or zero if no + discharging is possible. + power_upper_bound: the maximum charge power, in Watts, represented in the + passive sign convention. This will be a positive number, or zero if no + charging is possible. """ soc: float @@ -153,7 +162,20 @@ def from_proto(cls, raw: microgrid_pb.ComponentData) -> BatteryData: @dataclass(frozen=True) class InverterData(ComponentData): - """A wrapper class for holding inverter data.""" + """A wrapper class for holding inverter data. + + Attributes: + active_power: the 3-phase active power, in Watts, represented in the passive + sign convention. + +ve current means consumption, away from the grid. + -ve current means supply into the grid. + active_power_lower_bound: the maximum discharge power, in Watts, represented in + the passive sign convention. This will be a negative number, or zero if no + discharging is possible. + active_power_upper_bound: the maximum charge power, in Watts, represented in + the passive sign convention. This will be a positive number, or zero if no + charging is possible. + """ active_power: float active_power_lower_bound: float @@ -182,7 +204,21 @@ def from_proto(cls, raw: microgrid_pb.ComponentData) -> InverterData: @dataclass(frozen=True) class EVChargerData(ComponentData): - """A wrapper class for holding ev_charger data.""" + """A wrapper class for holding ev_charger data. + + Attributes: + active_power_consumption: the 3-phase active power, in Watts, represented in + the passive sign convention. + +ve current means consumption, away from the grid. + -ve current means supply into the grid. + current_per_phase: AC current in Amperes (A) for phase/line 1,2 and 3 + respectively. + +ve current means consumption, away from the grid. + -ve current means supply into the grid. + voltage_per_phase: the AC voltage in Volts (V) between the line and the neutral + wire for phase/line 1,2 and 3 respectively. + cable_state: the state of the ev charger's cable + """ active_power: float current_per_phase: Tuple[float, float, float]