metering

German energy metering domain library — interval types, gas conversion, billing period aggregation, SLP/RLM/iMSys classification, BSI TR-03109 SMGW lifecycle, virtual meters, resampling, forecasting, and Hampel-filter quality scoring.

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>,
}

QualityFlag (8 variants)

Gas conversion: m³ → kWh_Hs

Implements the Brennwertkorrektur formula per §24 GasGVV / 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));

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 EEG GGV)

let rule = AggregationRule::GgvAllocation {
    plant_malo_id: "PLANT".into(),
    tenant_fractions: vec![("TENANT_A".into(), dec!(0.4)), ("TENANT_B".into(), dec!(0.35))],
};
let virtual_series = compute_virtual_meter(&rule, &source_map)?;

Available rules: Sum, Residual (§42a EEG), PvSelfConsumption, GgvAllocation (§42b EEG).

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

Feature flags

Testing

cargo test -p metering --all-features

177 tests covering: gas conversion (DVGW G 685), aggregation (RLM/SLP/Gas), Messtyp classification, imbalance arithmetic, V01–V10 validation engine (incl. DST transitions), §17 MessZV substitute methods, resampling (hourly/daily/monthly), virtual meters (GGV/Residual), 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
• §24 GasGVV / 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

Design constraints

Core types

MeterInterval

A single timestamped energy reading:

pub struct MeterInterval {
    pub period_start: OffsetDateTime,
    pub period_end: OffsetDateTime,
    pub value_kwh: Decimal,
    pub quality: QualityFlag,
}

Sparte

pub enum Sparte { Strom, Gas }

QualityFlag

Measured, Substituted, Estimated, Invalid — mapped to MSCONS/UTILTS Datenqualitätskennzeichen.

Gas conversion: m³ → kWh_Hs

pub fn gas_m3_to_kwh_hs(
    m3: Decimal,
    brennwert_kwh_m3: Decimal,
    zustandszahl: Decimal,
) -> Decimal

Implements the Brennwertkorrektur formula per §24 GasGVV / DVGW G 685:

$$kWh_{Hs} = m^3 \times z \times H_s$$

Billing period aggregation

aggregate computes a BillingPeriodAggregate from a slice of MeterIntervals:

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

AggregationConfig presets

SLP/RLM/iMSys classification

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

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>

QualityGrade

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

§17 MessZV substitute value generation

When meter readings are missing or faulty, the MSB must supply substitute values before billing. metering implements all four methods from §17 MessZV and BDEW practice.

Quick usage

use metering::{fill_gaps, fill_gaps_with_config, FillGapsConfig, SubstituteMethod};

// Automatic method selection (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 (same time-slot, prior week)
let prior_week: Vec<MeterInterval> = fetch_prior_week(&malo_id);
let filled = fill_gaps_with_config(
    &intervals, 900, period_from, period_to,
    &FillGapsConfig::prior_period(prior_week),
);

SubstituteMethod variants

FillGapsConfig

pub struct FillGapsConfig {
    pub method: SubstituteMethod,            // default: LinearInterpolation
    pub prior_period_intervals: Vec<MeterInterval>, // for PriorPeriodAverage
    pub short_gap_threshold: usize,          // default: 3 (auto-linear below this)
}

FillGapsConfig::prior_period(prior_week_intervals) and FillGapsConfig::zero_fill() are convenience constructors.

Filled intervals carry quality = QualityFlag::Substituted (billable per §17 MessZV Abs. 1).

Feature flags

Testing

cargo test -p metering --all-features

37 tests covering gas conversion, aggregation (RLM/SLP/Gas), Messtyp classification, imbalance arithmetic, Hampel filter edge cases, and §17 MessZV substitute value generation (all four methods including PriorPeriodAverage).

Regulatory basis

• §3, §4 MessZV — SLP/RLM classification thresholds
• §2 Nr. 17 MessZV — Spitzenleistung definition for RLM
• §17 MessZV — Ersatzwertbildung (substitute value generation)
• §27 MessZV — Mehr-/Mindermengensaldo
• §24 GasGVV / DVGW G 685 — Gas Brennwertkorrektur
• §41a EnWG — 15-Minuten-Lastgang and iMSys Pflichteinbau