metering

**German energy metering domain library — interval types, gas conversion, billing period aggregation, SLP/RLM/iMSys classification, BSI TR-03109 SMGW lifecycle, virtual meters (§42b EnWG GGV Solarpaket I), resampling, forecasting, and Hampel-filter quality scoring.

214 tests · zero I/O · no async · no float money**

metering is the pure domain library used by edmd, mako-gabi-gas, and mako-mabis for all metering arithmetic. It has no I/O, no async, and no floating-point money.

Modules at a glance

Design constraints

Core types

MeterInterval

A single timestamped energy reading:

pub struct MeterInterval {
    pub from: OffsetDateTime,
    pub to:   OffsetDateTime,
    pub value_kwh: Decimal,
    pub quality: QualityFlag,
    pub obis_code: Option<String>,
}

Sparte and MeasurementUnit

pub enum Sparte          { Strom, Gas, Waerme, Wasser }
pub enum MeasurementUnit { KiloWattHour, CubicMetre }

A Sparte has two units, and conflating them is a correctness bug:

A gas meter registers volume; its energy content is derived from Brennwert and Zustandszahl (gas_m3_to_kwh_hs). requires_conversion() lets an ingest path require those parameters before storing a value in an energy column.

Wasser is the one Sparte billed in a volume — water has no calorific value, so the gas conversion does not apply to it. For the heat share of warm water see HeizkostenV §9 Abs. 2.

Wire units vs storage units

Storage is canonical — exactly two units reach a database, so no consumer has to know the table below exists. The wire is liberal, because real devices are:

MeasurementUnit::parse("MWh")         // None — would need rescaling
MeasurementUnit::parse_scaled("MWh")  // Some(UnitScale { KiloWattHour, 1000, 1 })

No German law prescribes a unit for heat meters. MID Annex VI (MI-004) has no units clause, and EN 1434-1 cl. 6.3.1 permits "Joules, Watt-hours or decimal multiples of those units" — so a GJ meter is exactly as compliant as a kWh one. German heat meters ship with kWh, MWh or GJ registers depending on the ordered variant (ista sensonic 3 is sold in both kWh and GJ; Zenner multidata WR3 offers MJ), and water submeters commonly report litres. The register unit is therefore device metadata, not a constant.

UN/ECE Rec 20 codes are also accepted, and their mnemonics do not follow the unit symbols:

Rec 20 also assigns GJ to gram per millilitre. This crate reads GJ as gigajoule, since no Sparte modelled here carries a density; callers emitting Rec 20 codes should send GV.

The GJ and MJ factors are held as exact rationals, not decimals: 1 GJ is 277.7… kWh, so a Decimal factor would lose precision on every reading. UnitScale::apply multiplies before dividing, making 3.6 GJ exactly 1000 kWh.

parse rejects anything needing a rescale, so a caller must go through parse_scaled to obtain a factor.

QualityFlag (8 variants)

Gas conversion: m³ → kWh_Hs

Implements the Brennwertkorrektur formula per §25 Nr. 4 MessEV / DVGW G 685:

// kWh_Hs = m³ × Hs × Z  (rounded to 6 dp)
let kwh = gas_m3_to_kwh_hs(dec!(100), dec!(10.55), dec!(0.9764));

Warm water → heat energy (HeizkostenV §9 Abs. 2)

warm_water_heat_kwh(volume_m3, mean_temp_c, WarmWaterAdjustments::NONE)
warm_water_heat_kwh_unmetered(flaeche_m2, adjustments)

Q [kWh/a] = 2.5 × V [m³] × (t_w [°C] − 10)      // Satz 2, metered volume
Q [kWh/a] = 32 × A_Wohn [m²]                    // Satz 4, floor area

Both are fallbacks. §9 Abs. 2 Satz 1 requires a Wärmezähler; Satz 2 applies only where measurement is possible "nur mit einem unzumutbar hohen Aufwand", and Satz 4 only "in Ausnahmefällen" where neither the heat quantity nor the volume can be measured.

These are Zahlenwertgleichungen — numerical-value equations, not dimensionally consistent — so the constants carry no unit, and they bundle different things:

Because the Erzeugeraufwandszahl sits inside both constants, Q is generator-input heat, not delivered useful heat.

t_w is "die gemessene oder geschätzte mittlere Temperatur" — an estimate is permitted and no default or cap is prescribed. A_Wohn is the "Wohn- oder Nutzfläche", not living area alone.

WarmWaterAdjustments

A struct of flags rather than an enum: §9 Abs. 2 Satz 6 applies these to the result of "den Zahlenwertgleichungen in Satz 2 oder 4" and does not make them exclusive, so a heat-pump system under eigenständige gewerbliche Wärmelieferung takes both. eigenständig is a term of art (cf. §1 Abs. 1 Nr. 2); ordinary commercial heat supply does not qualify.

A warm-water meter therefore carries two quantities: the m³ billed as water, and the kWh this apportions out of the building's heating bill. The metered and floor-area forms are separate functions rather than one Option parameter, because they are different evidentiary categories.

Validation engine (V01–V10)

let result = validate_intervals(&intervals, &ValidationConfig::default());
println!("Issues: {}", result.issues.len());
println!("Billing blocked: {}", result.billing_block_count());

§17 MessZV substitute value generation

// Automatic: linear for short gaps, carry-forward for long
let filled = fill_gaps(&intervals, 900, period_from, period_to);

// Prior-period averaging per §17 Abs. 2 MessZV
let filled = fill_gaps_with_config(
    &intervals, 900, period_from, period_to,
    &FillGapsConfig::prior_period(prior_week_intervals),
);

// Annual forecast (Jahresprognose)
let forecast = project_annual_consumption("MALO_ID", &intervals, None)?;
println!("Projected annual kWh: {}", forecast.projected_annual_kwh);

Resampling

// Down-sample 15-min RLM data to monthly totals (for MaBiS §27 MessZV)
let monthly = resample(&intervals, &ResampleConfig::to_monthly());
for bucket in &monthly {
    println!("{}: {} kWh (coverage {:.1}%)",
        bucket.from.date(), bucket.total_kwh, bucket.coverage_pct());
}

Virtual meters (§42b EnWG GGV — Solarpaket I)

Both GGV variants compute the tenant's net grid draw after PV allocation, satisfying §42b Abs. 5 EnWG sentence 2: the allocated PV energy can never exceed the tenant's actual consumption in any 15-minute interval. This is enforced by the Pos() = max(0, x) operator per the BDEW "Anwendungshilfe Berechnungsformeln Solarpaket 1" (v1.0, 25.01.2024).

Formula overview

Constant allocation (BDEW Beispiel 1 — UTILTS CCI+ZG6):

net_grid_draw_i[t] = max(0, tenant_consumption_i[t] - fraction_i × plant_generation[t])

Proportional allocation (BDEW Beispiel 3 — variable ratio):

ratio_i[t]         = tenant_consumption_i[t] / Σ all_tenant_consumption_j[t]
                     (0 if denominator = 0 — zero-division protected)
net_grid_draw_i[t] = max(0, tenant_consumption_i[t] - ratio_i[t] × plant_generation[t])

Constant allocation (Beispiel 1 — UTILTS CCI+ZG6)

// Tenant receives 10 % of plant generation; result = net grid draw
let rule = AggregationRule::GgvConstantAllocation {
    plant_melo_id: "MELO_PLANT".into(),
    tenant_melo_id: "MELO_T2".into(),
    fraction: dec!(0.10),
};
let net_grid_draw = compute_virtual_meter(&rule, &source_map)?;
// Each interval: max(0, tenant_consumption - 0.10 × plant_generation)
// Examples:
//   gen=10, consumption=5  → max(0, 5 - 1) = 4  (1 kWh covered by PV)
//   gen=10, consumption=0.5 → max(0, 0.5 - 1) = 0 (§42b cap: no negative draw)

Proportional allocation (Beispiel 3 — variable ratio)

let rule = AggregationRule::GgvProportionalAllocation {
    plant_melo_id: "MELO_PLANT".into(),
    tenant_melo_id: "MELO_T2".into(),
    all_tenant_melo_ids: vec!["MELO_T2".into(), "MELO_T3".into()],
};
let net_grid_draw = compute_virtual_meter(&rule, &source_map)?;
// ratio = T2_consumption / (T2 + T3); net = max(0, T2 - ratio × generation)
// zero-division protected: if all consumptions are 0 → net = 0

Energy balance check (plant feed-in)

The residual plant feed-in (grid export from PV) equals:

plant_feedin[t] = plant_generation[t] - Σ (tenant_consumption_i[t] - net_grid_draw_i[t])
               = plant_generation[t] - Σ pv_allocated_i[t]

Available rules: Sum, Residual (§42a EEG), PvSelfConsumption, GgvConstantAllocation, GgvProportionalAllocation (§42b EnWG Solarpaket I).

BSI TR-03109 SMGW lifecycle

let session = SmgwSession { device_id, status, certificates, cls_channels, .. };

// Certificate expiry (BSI TR-03109-4 §6.3 — renew ≥ 30 days before expiry)
let expiring = session.expiring_certificates(today, 30);

// §14a CLS channel compliance
assert!(session.has_section_14a_cls());

// Communication fault detection (triggers §17 MessZV substitute)
if session.is_communication_fault(2) { // 2h threshold
    // create Sonderablesung reading order
}

Billing period aggregation

let agg = aggregate(&intervals, &AggregationConfig::rlm_strom());
println!("kWh total:    {}", agg.arbeitsmenge_kwh);
println!("kWh HT:       {:?}", agg.ht_kwh);
println!("kWh NT:       {:?}", agg.nt_kwh);
println!("Spitzenlast:  {:?} kW", agg.spitzenleistung_kw);

AggregationConfig presets

SLP/RLM/iMSys classification

pub fn classify_messtyp(
    malo: &MaloId,
    jahresverbrauch_kwh: Decimal,
    sparte: Sparte,
) -> Messtyp

OBIS medium (value group A)

ObisCode::is_heat, is_water and is_heat_cost_allocator follow the DLMS/COSEM Blue Book media list that OMS Spec Vol. 2 adopts:

A = 8 is water, not heat. An HCA (A = 4) reports dimensionless Verbrauchseinheiten and carries no Eichfrist — HeizkostenV §5 Abs. 1 Satz 3 admits it as an apportionment device precisely because it measures no unit.

Mehr-/Mindermengensaldo

pub fn compute_imbalance(
    forecast_kwh: Decimal,
    actual_kwh: Decimal,
) -> ImbalanceResult

ImbalanceResult contains delta_kwh and delta_pct. Positive = Mehrmenge (actual > forecast); negative = Mindermenge. Basis: §27 MessZV.

Hampel-filter quality scoring

score_intervals runs a Hampel filter over a time-ordered slice of intervals and returns per-interval QualityGrades:

pub fn score_intervals(
    intervals: &[MeterInterval],
    window_k: usize,   // half-window size (default: 3)
    threshold: f64,    // MAD threshold in sigma units (default: 3.0)
) -> Vec<QualityGrade>

Media-aware thresholds

QualityConfig::for_sparte(Sparte::Wasser)

min_sigma guards MAD implosion: across a flat window the median absolute deviation is 0, so t × sigma is 0 and every nonzero value scores as an outlier. hampel_filter_with_floor exposes the same guard as a primitive.

QualityGrade

hampel_filter is also exposed as a low-level primitive that returns raw outlier indices.

Feature flags

Testing

cargo test -p metering --all-features

214 tests covering: gas conversion (DVGW G 685), aggregation (RLM/SLP/Gas), Messtyp classification, imbalance arithmetic, V01–V10 validation engine (incl. DST transitions and V07 DST ambiguity), §17 MessZV substitute methods, resampling (hourly/daily/monthly), §42b EnWG GGV virtual meters (Beispiel 1 constant + Beispiel 3 proportional, Pos() cap, zero-division guard), §42a Residuallast, BSI TR-03109 SMGW + CLS lifecycle, measurement series provenance, register + ObisCode.

Regulatory basis

• §3, §4 MessZV — SLP/RLM classification thresholds
• §2 Nr. 17 MessZV — Spitzenleistung definition for RLM
• §17 MessZV — Ersatzwertbildung + Jahresprognose (substitute values + annual forecast)
• §22 MessZV — 3-year provenance retention (MeasurementSeries, ProvenanceEntry)
• §27 MessZV — Mehr-/Mindermengensaldo
• §25 Nr. 4 MessEV / DVGW G 685 — Gas Brennwertkorrektur
• §41a EnWG — 15-Minuten-Lastgang and iMSys Pflichteinbau
• §42a/§42b EEG — Residuallast / GGV community solar virtual meters
• §14a EnWG — Steuerbare Verbrauchseinrichtungen (CLS channels)
• BSI TR-03109 — Smart Meter Gateway lifecycle and certificates