Skip to main content
Jira progress: loading…

ENGY-ELEC

Electricity Consolidation Micro Engine

1. Identity​

Loading identity…

Depends on module:

Canonical computation and modeling domain for ESG calculations, simulations, extrapolation, aggregation, normalization, and decision-grade metric synthesis. Provides governed, auditable compute services to other modules (e.g., Reporting, Risk, Net Zero, ZARA).
Domain:
computation-hub
Category:
analytics-modeling
Classification:
module
Lifecycle status:
active
Semver:
1.0.0
Introduced in:
v0.3
Governance
AI risk level:
high
Trust threshold:
0.9
Human review required:
true
Verifier involved:
false
Audit required:
true
Ownership
Primary owner:
Platform
Architecture board:
true
White-label allowed:
true
Entrypoints
Docs:
/computation-hub
UI:
/app/computation-hub
API:
/api/computation-hub
Dependencies
Modules
  • sis
  • input-hub
Unresolved tokens
  • BUME
  • SEM
  • VTE
Engines (declared)
  • DICE
  • DaVE
  • VTE
  • SEM
  • BUME
Micro-engines (from registry)
Micro-engines (declared)
None
Signals
USO
  • DATA.COMPUTATION
  • DATA.VALIDATION
  • DATA.EXTRAPOLATION
  • MODEL.SIMULATION
  • MODEL.UNCERTAINTY
CSI
  • CSI_COMPUTATION_HUB
SSSR tags
  • computation
  • modeling
  • simulation
  • monte-carlo
  • bayesian
  • extrapolation
  • aggregation
  • normalization
  • validation
  • mice
Workflows & Outputs
Workflows
  • MicroEngineRouting
  • RuleBasedComputeDispatch
  • ScenarioModeling
  • UncertaintyQuantification
  • AggregationAndRollups
  • NormalizationAndBenchmarking
  • ExtrapolationAndGapFilling
  • ComputeAuditAndReplay
Outputs
  • computed_metrics
  • scenario_ranges
  • confidence_intervals
  • normalized_values
  • validation_findings
  • trust_scored_compute_outputs
Audit
Ledger:
ALTD
Replay supported:
true
PII policy:
no_pii_in_omr
Tags

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:

  • Epurchased(t)E_{\mathrm{purchased}}(t) be purchased electricity in period tt
  • Eself(t)E_{\mathrm{self}}(t) be self-generated electricity in period tt
  • Eexport(t)E_{\mathrm{export}}(t) be exported electricity in period tt

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:

Epurchased(t)=purchasedelectricity(t)E_{\mathrm{purchased}}(t) = purchased_electricity(t)

Else if invoice records exist for period tt:

Epurchased(t)=∑r∈Rinvoice(t)v(r)E_{\mathrm{purchased}}(t) = \sum_{r \in R_{\mathrm{invoice}}(t)} v(r)

Else if meter import exists:

Epurchased(t)=∑r∈Rmeter,import(t)v(r)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:

Eself(t)=selfgeneratedelectricity(t)E_{\mathrm{self}}(t) = self_generated_electricity(t)

Else if generation records exist:

Eself(t)=∑r∈Rgeneration(t)v(r)E_{\mathrm{self}}(t) = \sum_{r \in R_{\mathrm{generation}}(t)} v(r)

4.5. Exported electricity​

If structured exported_electricity provided:

Eexport(t)=exportedelectricity(t)E_{\mathrm{export}}(t) = exported_electricity(t)

Else if meter export exists:

Eexport(t)=∑r∈Rmeter,export(t)v(r)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:

Enet(t)=max⁡(0,Epurchased(t)−Eexport(t))+Eself(t)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:

Enet(t)=Epurchased(t)+Eself(t)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(nrecords)O(n_{records}) per run
  • Memory: O(∣T∣)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


GitHub RepoRequest for Change (RFC)