flexmeasures.utils.unit_utils

Utility module for unit conversion

FlexMeasures stores units as strings in short scientific notation (such as ‘kWh’ to denote kilowatt-hour). We use the pint library to convert data between compatible units (such as ‘m/s’ to ‘km/h’). Three-letter currency codes (such as ‘KRW’ to denote South Korean Won) are valid units. Note that converting between currencies requires setting up a sensor that registers conversion rates over time. The preferred compact form for combinations of units can be derived automatically (such as ‘kW*EUR/MWh’ to ‘EUR/h’). Time series with fixed resolution can be converted from units of flow to units of stock (such as ‘kW’ to ‘kWh’), and vice versa. Percentages can be converted to units of some physical capacity if a capacity is known (such as ‘%’ to ‘kWh’).

Functions

Updates data values to reflect the given unit conversion.

Handles units in short scientific notation (e.g. m³/h, kW, and ºC), as well as three special units to convert from: - from_unit=”datetime” (with data point such as “2023-05-02”, “2023-05-02 05:14:49” or “2023-05-02 05:14:49 +02:00”) - from_unit=”dayfirst datetime” (with data point such as “02-05-2023”) - from_unit=”timedelta” (with data point such as “0 days 01:18:25”)

flexmeasures.utils.unit_utils.determine_flow_unit(stock_unit: str, time_unit: str = 'h'): For example: >>> determine_flow_unit(“m³”) # m³/h >>> determine_flow_unit(“kWh”) # kW

flexmeasures.utils.unit_utils.determine_stock_unit(flow_unit: str, time_unit: str = 'h')

Determine the shortest unit of stock, given a unit of flow.

For example: >>> determine_stock_unit(“m³/h”) # m³ >>> determine_stock_unit(“kW”) # kWh

flexmeasures.utils.unit_utils.determine_unit_conversion_multiplier(from_unit: str, to_unit: str, duration: timedelta | None = None): Determine the value multiplier for a given unit conversion. If needed, requires a duration to convert from units of stock change to units of flow, or vice versa.

flexmeasures.utils.unit_utils.is_currency_unit(unit: str | pint.Quantity | pint.Unit) → bool: For Example: >>> is_energy_price_unit(“EUR”) True >>> is_energy_price_unit(“KRW”) True >>> is_energy_price_unit(“potatoe”) False >>> is_energy_price_unit(“MW”) False

flexmeasures.utils.unit_utils.is_energy_price_unit(unit: str) → bool: For example: >>> is_energy_price_unit(“EUR/MWh”) True >>> is_energy_price_unit(“KRW/MWh”) True >>> is_energy_price_unit(“KRW/MW”) False >>> is_energy_price_unit(“beans/MW”) False

flexmeasures.utils.unit_utils.is_energy_unit(unit: str) → bool: For example: >>> is_energy_unit(“kW”) False >>> is_energy_unit(”°C”) False >>> is_energy_unit(“kWh”) True >>> is_energy_unit(“EUR/MWh”) False

flexmeasures.utils.unit_utils.is_power_unit(unit: str) → bool: For example: >>> is_power_unit(“kW”) True >>> is_power_unit(”°C”) False >>> is_power_unit(“kWh”) False >>> is_power_unit(“EUR/MWh”) False

flexmeasures.utils.unit_utils.is_valid_unit(unit: str) → bool: Return True if the pint library can work with this unit identifier.

flexmeasures.utils.unit_utils.to_preferred(x: Quantity) → Quantity: From https://github.com/hgrecco/pint/issues/676#issuecomment-689157693

flexmeasures.utils.unit_utils.units_are_convertible(from_unit: str, to_unit: str, duration_known: bool = True) → bool: For example, a sensor with W units allows data to be posted with units: >>> units_are_convertible(“kW”, “W”) # True (units just have different prefixes) >>> units_are_convertible(“J/s”, “W”) # True (units can be converted using some multiplier) >>> units_are_convertible(“Wh”, “W”) # True (units that represent a stock delta can, knowing the duration, be converted to a flow) >>> units_are_convertible(”°C”, “W”) # False