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’).


flexmeasures.utils.unit_utils.convert_units(data: tb.BeliefsSeries | pd.Series | list[int | float] | int | float, from_unit: str, to_unit: str, event_resolution: timedelta | None = None, capacity: str | None = None) pd.Series | list[int | float] | int | float

Updates data values to reflect the given unit conversion.

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_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