microgrid.engine.units¶

Units: a series in the unit its source gave, converted to the engine's.

The engine works in kW, kWh, fractions (an SOC of 0.62) and prices per kWh. A source gives what it gives: Home Assistant's unit_of_measurement may be W or kW, an SOC is usually %, a wholesale price may be per MWh. A client passes the unit with its series (microgrid.engine.series.Series.unit), and normalise converts it once, at the edge, so no client assumes a unit.

A unit this module does not know raises UnitError: a reading in an unknown unit is not used, rather than used wrongly by a factor of a thousand. A currency is never converted: a price's currency is the client's, and passes through as written, so a client must give prices in the currency it means (¢/kWh passes as a currency named ¢: the numbers stay in cents).

Pure: no I/O.

POWER_KW `module-attribute` ¶

POWER_KW: Final[Mapping[str, float]] = MappingProxyType(
    {"W": 0.001, "kW": 1.0, "MW": 1000.0}
)

Power units, as kW per unit.

ENERGY_KWH `module-attribute` ¶

ENERGY_KWH: Final[Mapping[str, float]] = MappingProxyType(
    {"Wh": 0.001, "kWh": 1.0, "MWh": 1000.0}
)

Energy units, as kWh per unit.

FRACTION `module-attribute` ¶

FRACTION: Final[Mapping[str, float]] = MappingProxyType(
    {"%": 0.01, "": 1.0}
)

Fraction units, as the fraction per unit. No unit (None or "") is a fraction.

Quantity ¶

Quantity = Literal['power', 'energy', 'fraction', 'price']

UnitError ¶

Bases: ValueError

A unit that is not one of the quantity's.

convert ¶

convert(
    value: float, unit: str | None, quantity: Quantity
) -> float

value in unit as the engine's unit for quantity. One finite value: raises ValueError for one that is not (normalise makes it None).

normalise ¶

normalise(
    series: Series[float], quantity: Quantity
) -> Series[float]

series in the engine's unit for quantity: kW, kWh, a fraction (no unit), or the same currency per kWh.

A sample that is not finite is already None, no value (Sample). Raises UnitError for a unit that is not quantity's.