Jira progress: loading…

ENGY-INT

Energy Intensity Calculator

1. Identity

Loading identity…

Depends on module:

Purpose
Computes energy intensity by normalizing absolute energy consumption against an activity denominator (typically revenue), producing disclosure-ready intensity series aligned with ESRS energy reporting practices.

This engine is the Energy analogue of MEID_CALC_GHG_INT.

Typical usage

• Total energy per € revenue
• Electricity per € revenue
• Fuels per € revenue
• Inputs to benchmarking and trend analytics

---

2. Contract References (ZAR)

2.1 Input Schema

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

Required conceptual fields:

• energy: scalar or time-series (absolute energy, typically output of MEID_CALC_ENERGY_AGGR)
• denominator: scalar or time-series (e.g., revenue in EURm, production volume)
• intensity_basis: TOTAL | ELECTRICITY | FUELS | CARRIER (default TOTAL)
• alignment: BY_YEAR | BY_INDEX (default BY_YEAR)

Optional:

• carrier: required if intensity_basis = CARRIER (e.g., natural_gas, diesel)
• unit_energy: default MWh
• unit_denominator: e.g. EURm

---

2.2 Options Schema

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

Common options:

• denominator_floor: default 1e-9
• missing_policy: ERROR | SKIP
• rounding: optional digits
• output_unit_style: MWh_per_EURm | MWh_per_EUR | auto (default auto)

---

2.3 Output Schema

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

Outputs include:

• energy_intensity
• metadata (basis, carrier if any, denominator floors applied, alignment info, units)

---

3. Accepted Input Shapes

A. Scalar intensity (total energy / revenue)

{
  "energy": 20000,
  "denominator": 250,
  "intensity_basis": "TOTAL"
}

B. Time-series intensity (preferred)

{
  "energy": [[2025, 20000], [2026, 19500]],
  "denominator": [[2025, 250], [2026, 260]],
  "intensity_basis": "TOTAL",
  "alignment": "BY_YEAR"
}

C. Electricity intensity

{
  "energy": {
    "electricity": [[2025, 12000], [2026, 11800]],
    "fuels": [[2025, 8000], [2026, 7700]]
  },
  "denominator": [[2025, 250], [2026, 260]],
  "intensity_basis": "ELECTRICITY"
}

D. Specific carrier intensity

{
  "energy": {
    "by_carrier": {
      "natural_gas": [[2025, 8000]],
      "diesel": [[2025, 1200]]
    }
  },
  "denominator": [[2025, 250]],
  "intensity_basis": "CARRIER",
  "carrier": "natural_gas"
}

All supported shapes MUST be normalized internally to:

Map<period, energy_value> + Map<period, denominator_value>

---

4. Compute Semantics (Normative)

For each aligned period $t$:

4.1. Select energy basis

Let $E(t)$ be the selected energy series according to intensity_basis:

• TOTAL: $E(t) = E_{\mathrm{total}}(t)$
• ELECTRICITY: $E(t) = E_{\mathrm{electricity}}(t)$
• FUELS: $E(t) = E_{\mathrm{fuels}}(t)$
• CARRIER: $E(t) = E(c,t)$ for the specified carrier $c$

4.2. Intensity formula

Let $D(t)$ be the denominator series (e.g. revenue).

$I(t) = \frac{E(t)}{\max(|D(t)|, \epsilon)}$

Where $\epsilon$ is denominator_floor.

4.3. Output units

If energy is in MWh and denominator is EURm, then:

• $I(t)$ unit is MWh/EURm

The engine MUST propagate unit metadata to output:

• unit_energy
• unit_denominator
• derived unit_intensity

---

5. Alignment Rules

BY_YEAR

• Energy and denominator must share period keys unless missing_policy = SKIP.

BY_INDEX

• Ordered alignment; length mismatch handled per missing_policy.

Metadata MUST include:

• aligned_periods
• missing_in_energy
• missing_in_denominator
• denominator_floor_applied_count

---

6. Validation & Error Model

Invariants

• Values must be finite
• denominator_floor > 0
• Denominator must be non-negative (default; allow only if schema permits)
• If intensity_basis = CARRIER, carrier must be provided and valid canonical key

Error codes (suggested)

• ENERGY_INT_MISSING_DENOMINATOR
• ENERGY_INT_INVALID_BASIS
• ENERGY_INT_INVALID_CARRIER
• ENERGY_INT_ALIGNMENT_MISMATCH
• ENERGY_INT_DENOMINATOR_ZERO_GUARDED (informational if floor applied)
• ENERGY_INT_NON_FINITE_VALUE

Errors MUST include:

• engine cmi_short_code
• basis/carrier and period context

---

7. Dependencies

MEID_CALC_ENERGY_INT depends on:

• MEID_CALC_ENERGY_AGGR (upstream energy totals)
• schema resolver (ZAR)
• unit conversion utilities (if mixed units allowed)

Declared via ZAR dependencies.

---

8. Federation & Audit Requirements

To reproduce energy intensity externally, the export MUST include:

• engine identity (cmi or zar_code)
• engine build proof (execution_ref + build_hash)
• input/options/output schemas used
• energy series selected (total/electricity/fuels/carrier)
• denominator series (e.g. revenue)
• denominator floor and missing-policy settings

Provenance chain MUST show:

… → MEID_CALC_ENERGY_AGGR → MEID_CALC_ENERGY_INT → …

with cmi_short_code recorded in USO tail arrays.

---

9. Performance Notes

• Complexity: $O(n)$ over periods
• Memory: $O(n)$
• Suitable for batch reporting and KPI analytics

---

10. Methods Served (v1)

• Energy.intensity
• Energy.electricity.intensity
• Energy.fuels.intensity

---