Jira progress: loading…

ENGY-ELEC

Electricity Consolidation Micro Engine

1. Identity

Loading identity…

Depends on module:

Purpose
Consolidates electricity consumption from utility invoices, metering feeds, and/or on-site generation systems into canonical electricity series suitable for ESRS-aligned energy reporting and downstream aggregation.

This engine exists because electricity almost always has:

• distinct source systems (invoices, meters, SCADA/EMS),
• import/export/netting complexity,
• and assurance expectations higher than other carriers.

Typical usage

• Purchased electricity total (MWh)
• Self-generated electricity (MWh)
• Exported electricity (MWh)
• Net electricity used on-site (MWh)
• Input to MEID_CALC_ENERGY_AGGR (as the authoritative electricity stream)

---

2. Contract References (ZAR)

2.1 Input Schema

ZAR Address: schema.compute.energy.electricity.inputs.v1_0_0

Required conceptual fields (v1 minimal):

• records: list of electricity records
• alignment: BY_YEAR | BY_INDEX (default BY_YEAR)

Each record conceptually includes:

• period (typically year; may be month if later supported)
• value
• unit (e.g. kWh, MWh)
• record_type: INVOICE | METER | GENERATION | EXPORT
• optional:
  • meter_id
  • invoice_id
  • site_id
  • grid_region
  • direction: IMPORT | EXPORT (if record_type is meter-based)

Optional structured fields (preferred when available):

• purchased_electricity: scalar or time-series
• self_generated_electricity: scalar or time-series
• exported_electricity: scalar or time-series

If the structured fields are provided, records may be omitted.

---

2.2 Options Schema

ZAR Address: schema.compute.energy.electricity.options.v1_0_0

Common options:

• unit_output: default MWh
• source_priority: ordered list (default ["INVOICE","METER","GENERATION"])
• netting_policy: NO_NETTING | NET_IMPORT_EXPORT (default NET_IMPORT_EXPORT)
• duplicate_policy: ALLOW | DEDUPE_BY_ID | ERROR (default DEDUPE_BY_ID)
• missing_policy: ERROR | SKIP
• negative_values_policy: ERROR | ALLOW_WITH_FLAG
• rounding: optional digits

---

2.3 Output Schema

ZAR Address: schema.compute.energy.electricity.output.v1_0_0

Outputs include:

• E_purchased(t)
• E_self_generated(t)
• E_exported(t)
• E_net(t)
• metadata (source selection, dedupe actions, netting, unit conversions, coverage)

---

3. Accepted Input Shapes

A. Invoice-based records (most common)

{
  "records": [
    { "record_type": "INVOICE", "invoice_id": "INV-001", "period": 2025, "value": 12000000, "unit": "kWh" },
    { "record_type": "INVOICE", "invoice_id": "INV-002", "period": 2026, "value": 11800000, "unit": "kWh" }
  ],
  "alignment": "BY_YEAR"
}

B. Meter import/export with netting

{
  "records": [
    { "record_type": "METER", "meter_id": "M-11", "direction": "IMPORT", "period": 2025, "value": 12500, "unit": "MWh" },
    { "record_type": "METER", "meter_id": "M-11", "direction": "EXPORT", "period": 2025, "value": 500, "unit": "MWh" }
  ],
  "netting_policy": "NET_IMPORT_EXPORT"
}

C. Structured series (preferred if already consolidated upstream)

{
  "purchased_electricity": [[2025, 12000], [2026, 11800]],
  "self_generated_electricity": [[2025, 800], [2026, 900]],
  "exported_electricity": [[2025, 100], [2026, 120]],
  "unit_output": "MWh",
  "alignment": "BY_YEAR"
}

All supported shapes MUST be normalized internally to:

Map<period, { purchased_MWh, self_generated_MWh, exported_MWh }>

---

4. Compute Semantics (Normative)

Let:

• $E_{\mathrm{purchased}}(t)$ be purchased electricity in period $t$
• $E_{\mathrm{self}}(t)$ be self-generated electricity in period $t$
• $E_{\mathrm{export}}(t)$ be exported electricity in period $t$

4.1. Unit normalization

All values MUST be converted to unit_output (default MWh).

---

4.2. Source selection

If multiple sources overlap for the same period:

• prefer the first available source in source_priority
• record which source won per period in metadata

---

4.3. Purchased electricity

If structured purchased_electricity provided:

$E_{\mathrm{purchased}}(t) = purchased_electricity(t)$

Else if invoice records exist for period $t$:

$E_{\mathrm{purchased}}(t) = \sum_{r \in R_{\mathrm{invoice}}(t)} v(r)$

Else if meter import exists:

$E_{\mathrm{purchased}}(t) = \sum_{r \in R_{\mathrm{meter,import}}(t)} v(r)$

---

4.4. Self-generated electricity

If structured self_generated_electricity provided:

$E_{\mathrm{self}}(t) = self_generated_electricity(t)$

Else if generation records exist:

$E_{\mathrm{self}}(t) = \sum_{r \in R_{\mathrm{generation}}(t)} v(r)$

---

4.5. Exported electricity

If structured exported_electricity provided:

$E_{\mathrm{export}}(t) = exported_electricity(t)$

Else if meter export exists:

$E_{\mathrm{export}}(t) = \sum_{r \in R_{\mathrm{meter,export}}(t)} v(r)$

---

4.6. Net electricity (site use)

If netting_policy = NET_IMPORT_EXPORT:

$E_{\mathrm{net}}(t) = \max\left(0, E_{\mathrm{purchased}}(t) - E_{\mathrm{export}}(t)\right) + E_{\mathrm{self}}(t)$

If netting_policy = NO_NETTING:

$E_{\mathrm{net}}(t) = E_{\mathrm{purchased}}(t) + E_{\mathrm{self}}(t)$

Export is reported separately either way; netting only affects the “net used” output series.

---

5. Validation & Error Model

Invariants

• Values must be finite
• Units must be convertible
• Duplicate invoices/meters must be handled per duplicate_policy
• Negative values default to error

Error codes (suggested)

• ENERGY_ELEC_MISSING_INPUT
• ENERGY_ELEC_UNIT_CONVERSION_FAILED
• ENERGY_ELEC_DUPLICATE_RECORD_ERROR
• ENERGY_ELEC_NON_FINITE_VALUE
• ENERGY_ELEC_ALIGNMENT_MISMATCH

Errors MUST include:

• engine cmi_short_code
• record identifier (invoice_id/meter_id) and period

---

6. Dependencies

MEID_CALC_ENERGY_ELEC depends on:

• schema resolver (ZAR)
• unit conversion utilities
• optional invoice parsing/normalization utilities (upstream)
• optional meter feed normalization utilities (upstream)

Declared via ZAR dependencies.

---

7. Federation & Audit Requirements

To reproduce electricity consolidation externally, the export MUST include:

• engine identity (cmi or zar_code)
• engine build proof (execution_ref + build_hash)
• input/options/output schemas used
• raw records (invoice/meter/generation) or structured series used
• source_priority, netting_policy, and duplicate_policy
• unit conversion reference/version used

Provenance chain MUST show:

… → MEID_CALC_ENERGY_ELEC → …

with cmi_short_code recorded in USO tail arrays.

---

8. Performance Notes

• Complexity: $O(n_{records})$ per run
• Memory: $O(|T|)$
• Highly parallelizable by site or meter group

---

9. Methods Served (v1)

• Energy.electricity.abs
• Energy.electricity.purchased.abs
• Energy.electricity.self_generated.abs
• Energy.electricity.exported.abs
• Energy.electricity.net.abs

---