Skip to main content
Jira progress: loading…

ENGY-AGGR

Energy Aggregation

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
Aggregates energy consumption across carriers into canonical totals, enforcing ESRS-aligned energy carrier semantics and unit normalization.
This engine is the anchor for all Energy KPIs (intensity, renewable share, deltas).

Typical usage

  • Total energy consumption reporting (ESRS E1 / E5)
  • Electricity vs fuel separation
  • Upstream input to intensity and renewable share engines

2. Contract References (ZAR)​

2.1. Input Schema​

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

Required conceptual fields:

  • energy_items: list of energy consumption records
  • alignment: BY_YEAR | BY_INDEX (default BY_YEAR)

Each energy item conceptually includes:

  • carrier: canonical energy carrier identifier
  • value
  • unit (e.g. MWh, GJ, kWh)
  • period (typically year)

Canonical carriers (v1):

  • electricity
  • natural_gas
  • diesel
  • gasoline
  • fuel_oil
  • coal
  • steam
  • heat
  • renewable_electricity (if pre-tagged)

2.2. Options Schema​

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

Common options:

  • unit_output: default MWh
  • carrier_normalization: STRICT | LENIENT (default STRICT)
  • unknown_carrier_policy: ERROR | DROP
  • negative_values_policy: ERROR | ALLOW_WITH_FLAG
  • rounding: optional digits

2.3. Output Schema​

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

Outputs include:

  • energy_total
  • energy_by_carrier
  • energy_electricity
  • energy_fuels
  • metadata (unit conversions, unknown carriers, flags)

3. Accepted Input Shapes​

A. Flat item list (preferred)

{
  "energy_items": [
    { "carrier": "electricity", "period": 2025, "value": 12000, "unit": "MWh" },
    { "carrier": "natural_gas", "period": 2025, "value": 8000, "unit": "MWh" }
  ],
  "alignment": "BY_YEAR"
}

B. Mixed units

{
  "energy_items": [
    { "carrier": "electricity", "period": 2025, "value": 12000, "unit": "MWh" },
    { "carrier": "diesel", "period": 2025, "value": 30000, "unit": "GJ" }
  ]
}

C. Time-series per carrier (legacy-friendly)

{
  "energy_items": [
    { "carrier": "electricity", "values": [[2025, 12000], [2026, 11800]], "unit": "MWh" },
    { "carrier": "natural_gas", "values": [[2025, 8000], [2026, 7600]], "unit": "MWh" }
  ],
  "alignment": "BY_YEAR"
}

All supported shapes MUST be normalized internally to:

Map<period, Map<carrier, energy_value_MWh>>

4. Carrier Normalization Rules (Normative)​

4.1. Canonical carrier identifiers​

Input carriers MUST normalize to canonical keys:

  • electricity
  • fuels (derived group)
  • individual fuels: natural_gas, diesel, gasoline, fuel_oil, coal
  • thermal: steam, heat

If carrier_normalization = STRICT:

  • unknown carriers → error

If LENIENT:

  • unknown carriers may be dropped with metadata annotation

5. Compute Semantics (Normative)​

Let:

  • E(c,t)E(c,t) = energy consumption of carrier cc in period tt (after unit normalization)

5.1. Unit normalization​

All inputs MUST be converted to unit_output (default MWh) before aggregation.

5.2. Energy by carrier​

Eby_carrier(c,t)=E(c,t)E_{\mathrm{by\_carrier}}(c,t) = E(c,t)

5.3. Electricity total​

Energyelectricity(t)=E(electricity,t)Energy_{electricity}(t) = E(electricity, t)

5.4. Fuels total​

Let CfuelC_{fuel} be the set of fuel carriers:

Efuels(t)=∑c∈CfuelE(c,t)E_{\mathrm{fuels}}(t) = \sum_{c \in C_{\mathrm{fuel}}} E(c,t)

5.5. Total energy​

Etotal(t)=∑c∈CallE(c,t)E_{\mathrm{total}}(t) = \sum_{c \in C_{\mathrm{all}}} E(c,t)

Where CallC_{all} includes electricity, fuels, and thermal carriers.

6. Validation & Error Model​

Invariants

  • Energy values must be finite
  • Units must be convertible
  • Negative values rejected unless explicitly allowed

Error codes (suggested)

  • ENERGY_AGGR_INVALID_CARRIER
  • ENERGY_AGGR_UNIT_CONVERSION_FAILED
  • ENERGY_AGGR_NEGATIVE_VALUE
  • ENERGY_AGGR_NON_FINITE_VALUE
  • ENERGY_AGGR_ALIGNMENT_MISMATCH

Errors MUST include:

  • engine cmi_short_code
  • carrier and period context

7. Dependencies​

MEID_CALC_ENERGY_AGGR depends on:

  • schema resolver (ZAR)
  • unit conversion utilities
  • canonical energy carrier reference list

Declared via ZAR dependencies.

8. Federation & Audit Requirements​

To reproduce energy aggregation externally, the export MUST include:

  • engine identity (cmi or zar_code)
  • engine build proof (execution_ref + build_hash)
  • input/options/output schemas
  • raw energy item list
  • unit conversion table/version used

Provenance chain MUST show:

… → MEID_CALC_ENERGY_AGGR → …

with cmi_short_code recorded in USO tail arrays.

9. Performance Notes​

  • Complexity: O(nitems)O(n_{items}) for normalization + aggregation
  • Memory: O(∣C∣×∣T∣)O(|C| × |T|)
  • Suitable for batch ESG reporting

10. Methods Served (v1)​

  • Energy.abs
  • Energy.electricity.abs
  • Energy.fuels.abs
  • Energy.total.abs


GitHub RepoRequest for Change (RFC)