Jira progress: loading…

ENGY-RE

Renewable Energy Calculator

1. Identity

Loading identity…

Depends on module:

Purpose
Computes renewable energy consumption in canonical units and (optionally) produces renewable share-ready outputs. This engine is responsible for renewable attribution governance, ensuring renewable claims are based on accepted evidence types (e.g., Guarantees of Origin / EACs) and are consistent with ESRS-aligned reporting.

This engine does not price anything; it classifies and consolidates renewable energy volumes.

Typical usage

• Total renewable energy consumption (MWh)
• Renewable electricity consumption (MWh)
• Inputs to MEID_CALC_ENERGY_SHARE for renewable share KPIs

---

2. Contract References (ZAR)

2.1 Input Schema

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

Required conceptual fields (v1 minimal):

• energy_items: list of energy consumption records (same carrier structure as MEID_CALC_ENERGY_AGGR)
• alignment: BY_YEAR | BY_INDEX (default BY_YEAR)

Optional renewable evidence fields:

• renewable_evidence: list of instruments / proofs (EAC/GO/REC/PPA allocations)
• evidence_map_ref: optional mapping ruleset for instrument validation
• renewable_tag: boolean per item (if pre-tagged upstream)

Each energy item conceptually includes:

• carrier
• period
• value
• unit
• optional: is_renewable (only trusted if evidence policy allows)

---

2.2 Options Schema

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

Common options:

• unit_output: default MWh
• renewable_scope: ELECTRICITY_ONLY | ALL_CARRIERS (default ELECTRICITY_ONLY)
• evidence_policy: STRICT | TAG_ONLY | MIXED (default STRICT)
• unknown_evidence_policy: ERROR | DROP | FLAG (default FLAG)
• double_count_policy: ERROR | CAP_AT_CONSUMPTION (default CAP_AT_CONSUMPTION)
• rounding: optional digits

---

2.3 Output Schema

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

Outputs include:

• energy_renewable_total
• energy_renewable_electricity
• energy_renewable_by_carrier (optional)
• metadata (evidence coverage, caps applied, validation flags)

---

3. Accepted Input Shapes

A. Renewable via evidence instruments (preferred)

{
  "energy_items": [
    { "carrier": "electricity", "period": 2025, "value": 12000, "unit": "MWh" }
  ],
  "renewable_evidence": [
    {
      "type": "EAC",
      "period": 2025,
      "carrier": "electricity",
      "volume_mwh": 4000,
      "issuer": "AIB",
      "certificate_id": "GO-XYZ-123"
    }
  ],
  "alignment": "BY_YEAR"
}

B. Pre-tagged renewable (allowed only if policy permits)

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

C. Mixed: evidence + tags (MIXED policy)

{
  "energy_items": [
    { "carrier": "electricity", "period": 2025, "value": 12000, "unit": "MWh" },
    { "carrier": "steam", "period": 2025, "value": 500, "unit": "MWh", "is_renewable": true }
  ],
  "renewable_evidence": [
    { "type": "PPA", "period": 2025, "carrier": "electricity", "volume_mwh": 3000 }
  ],
  "alignment": "BY_YEAR"
}

All supported shapes MUST be normalized internally to:

Map<period, consumption_by_carrier_MWh> + Map<period, renewable_claim_by_carrier_MWh>

---

4. Renewable Attribution Rules (Normative)

4.1. Renewable scope

If renewable_scope = ELECTRICITY_ONLY:

• only electricity can be counted as renewable in v1

If ALL_CARRIERS:

• allow renewable tagging for other carriers (requires stronger evidence governance; v1 should treat this as advanced)

4.2. Evidence policy

• STRICT: renewable volumes MUST be backed by renewable evidence instruments
• TAG_ONLY: trust is_renewable tags (discouraged for audit-grade reporting)
• MIXED: accept evidence where present, otherwise tags, but flag tag-derived volumes

4.3. Double counting prevention

Let:

• $R(t)$ be renewable claimed volume for period $t$
• $C(t)$ be total consumption volume for the relevant scope (electricity or all carriers)

Then renewable volume MUST satisfy:

$R(t) \le C(t)$

If double_count_policy = CAP_AT_CONSUMPTION:

$R(t) = \min(R(t), C(t))$

If ERROR: fail if $R(t) > C(t)$.

---

5. Compute Semantics (Normative)

Let $R(c,t)$ be renewable volume for carrier $c$ in period $t$, after unit normalization and evidence validation.

5.1. Renewable electricity

$E_{\mathrm{renewable,electricity}}(t) = R(\mathrm{electricity}, t)$

5.2. Renewable total

If renewable_scope = ELECTRICITY_ONLY: $E_{\mathrm{renewable,total}}(t) = R(\mathrm{electricity}, t)$

If ALL_CARRIERS: $E_{\mathrm{renewable,total}}(t) = \sum_{c \in C_{\mathrm{all}}} R(c,t)$

5.3. Coverage ratio (metadata)

If evidence instruments are used:

$coverage(t) = \frac{R(t)}{\max(C(t), \epsilon)}$

Where $\epsilon$ is a small positive constant to avoid division instability.

---

6. Validation & Error Model

Invariants

• Values must be finite
• Units must be convertible to unit_output
• Evidence periods must align with consumption periods
• Renewable claims must not exceed consumption under policy rules

Error codes (suggested)

• ENERGY_RE_INVALID_EVIDENCE
• ENERGY_RE_EVIDENCE_PERIOD_MISMATCH
• ENERGY_RE_DOUBLE_COUNT_DETECTED
• ENERGY_RE_UNIT_CONVERSION_FAILED
• ENERGY_RE_NON_FINITE_VALUE

Errors MUST include:

• engine cmi_short_code
• period and (if applicable) evidence instrument identifiers

---

7. Dependencies

MEID_CALC_ENERGY_RE depends on:

• MEID_CALC_ENERGY_AGGR (upstream consumption totals, optionally)
• schema resolver (ZAR)
• unit conversion utilities
• optional renewable instrument registry / validation ruleset (evidence_map_ref)

Declared via ZAR dependencies.

---

8. Federation & Audit Requirements

To reproduce renewable energy outputs externally, the export MUST include:

• engine identity (cmi or zar_code)
• engine build proof (execution_ref + build_hash)
• input/options/output schemas used
• consumption energy items
• renewable evidence instruments (if STRICT/MIXED)
• evidence validation ruleset reference/version (if used)
• double count policy and caps applied

Provenance chain MUST show:

… → MEID_CALC_ENERGY_RE → …

with cmi_short_code recorded in USO tail arrays.

---

9. Performance Notes

• Complexity: $O(n_{items} + n_{evidence})$
• Memory: $O(|T| \times |C|)$
• Suitable for batch reporting; evidence validation can be parallelized

---

10. Methods Served (v1)

• Energy.renewable.abs
• (share computed downstream) Energy.renewable.share via MEID_CALC_ENERGY_SHARE or MEID_CALC_SHARE

---