price scaling

HSEM Price Interval Semantics and Scaling

This document explains how HSEM handles the interaction between electricity price update intervals and planning slot widths.

---

The problem

HSEM supports two independent interval settings:

Setting	Values	What it controls
electricity_price_update_interval	15, 30, or 60 minutes	How often the price source publishes records
recommendation_interval_minutes	15 or 60 minutes	The width of each planning slot

When these differ (most commonly: price update 60 min, slots 15 min), the price rate must be correctly scaled so the planner always sees the full currency/kWh rate.

---

The price_share conversion factor

$$ \mathrm{price_share} = \frac{\text{Price update interval}}{\text{Slot width}} $$

Price update interval	Slot width	price_share	Effect
60 min	15 min	4.0	Price ÷ 4 stored; planner gets price × 4 back
15 min	15 min	1.0	No scaling
30 min	15 min	2.0	Price ÷ 2 stored; planner gets price × 2 back
60 min	60 min	1.0	No scaling

---

Scaling pipeline

flowchart TD
    A[Price source raw price P\nfull hourly currency per kWh]
    B[HourlyDataPopulator.async_populate_price_and_solcast]
    C[Recommendation slot storage\nHourlyRecommendation objects]
    D[coordinator._build_planner_input]
    E[Planner engine PricePoint\nimport_price = P]

    A --> B
    B -->|Per-slot stored value = P / price_share| C
    C --> D
    D -->|Planner input value = stored value × price_share = P| E

Loading

What this is NOT

• price_share is not a VAT multiplier
• price_share is not a currency conversion
• price_share is not an energy-splitting factor (prices are rates, not energy)

---

Price sources

HSEM is provider-agnostic. Prices are read from generic electricity price sensors:

Config key	Purpose
hsem_import_electricity_price_sensor	Live import price (required)
hsem_export_electricity_price_sensor	Live export price (required)
hsem_import_electricity_price_forecast_sensor	Optional dedicated import forecast (e.g. Amber Electric)
hsem_export_electricity_price_forecast_sensor	Optional dedicated export forecast

Supported providers include Energi Data Service, Nordpool, Amber Electric, and any sensor that publishes hourly (or sub-hourly) price records with a raw_today / raw_tomorrow attribute structure. The populator reads the full time-series from sensor attributes and projects them onto the planning horizon.

---

Invariants

For any configuration:

1. A 60-min price source value of P must reach the planner as P (not P/4 or P*4)
2. A 15-min price source value of P must reach the planner as P
3. Intermediate per-slot stored values must equal P / price_share
4. Changing electricity_price_update_interval from 60 to 15 with the same price input must not change the price seen by the planner engine
5. Negative prices must survive the full pipeline unchanged (no absolute-value clipping, no zero-flooring)

---

Multi-day price data

For horizons beyond 24 hours, prices and PV data are projected onto the shared time-series index per calendar day:

Field	Source	Day offset
Today's prices	Live price sensor attributes	day_offset = 0
Tomorrow's prices	Tomorrow sensor attributes (or same sensor)	day_offset = 1
Day+2 prices	Day+2 sensor attributes (if available)	day_offset = 2

Missing future-day data is surfaced in DataQuality as:

• tomorrow_price_missing_hours
• day2_price_missing_hours
• tomorrow_pv_missing_hours
• day2_pv_missing_hours

Non-critical missing data triggers Degraded mode (writes allowed).