Skip to main content
Jira progress: loading…

ENGY-SHR

Energy Share / Composition Calculator

1. Identity​

Loading identity…

Depends on module:

Purpose
Computes Energy composition shares (ratios or percentages) with energy-governed semantics, enforcing canonical carrier identifiers, allowed denominators, unit expectations, and disclosure-ready metadata.

This engine is a domain adapter over the generic MEID_CALC_SHARE primitive and is the Energy analogue of MEID_CALC_GHG_SHARE.

Typical usage

  • Renewable electricity share of total electricity
  • Electricity share of total energy
  • Fuels share of total energy
  • Individual carrier share of total energy (e.g., natural gas share)

2. Contract References (ZAR)​

2.1 Input Schema​

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

Required conceptual fields:

  • numerator_ref: identifies numerator basis (e.g., renewable_electricity, electricity, fuels, or a specific carrier key)
  • denominator_ref: identifies denominator basis (e.g., electricity_total, energy_total)
  • share_mode: RATIO | PERCENT (default PERCENT)
  • alignment: BY_YEAR | BY_INDEX (default BY_YEAR)

Two supported input styles:

Style A (direct values):

  • numerator: scalar or time-series
  • denominator: scalar or time-series

Style B (reference values):

  • numerator_signal_ref and denominator_signal_ref (CSI/USO references)
  • values resolved upstream by orchestration and provided at runtime

2.2 Options Schema​

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

Common options:

  • denominator_floor: default 1e-9
  • cap_range: ENFORCE | ALLOW (default ENFORCE)
  • missing_policy: ERROR | SKIP
  • carrier_normalization: STRICT | LENIENT (default STRICT)
  • rounding: optional digits

2.3 Output Schema​

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

Outputs include:

  • share_series
  • share_unit (ratio or percent)
  • metadata (normalized refs, floors, caps, alignment)

3. Accepted Input Shapes​

A. Renewable electricity share of total electricity

{
  "numerator_ref": "renewable_electricity",
  "denominator_ref": "electricity_total",
  "numerator": [[2025, 4000], [2026, 4200]],
  "denominator": [[2025, 12000], [2026, 11800]],
  "share_mode": "PERCENT",
  "alignment": "BY_YEAR"
}

B. Electricity share of total energy

{
  "numerator_ref": "electricity",
  "denominator_ref": "energy_total",
  "numerator": [[2025, 12000]],
  "denominator": [[2025, 20000]],
  "share_mode": "RATIO"
}

C. Carrier share (e.g., natural gas share of total energy)

{
  "numerator_ref": "carrier:natural_gas",
  "denominator_ref": "energy_total",
  "numerator": [[2025, 8000]],
  "denominator": [[2025, 20000]],
  "share_mode": "PERCENT"
}

All supported shapes MUST be normalized internally to:

Map<period, numerator_value> + Map<period, denominator_value>

4. Energy-Specific Normalization Rules (Normative)​

4.1. Canonical numerator_ref values​

Allowed numerator refs (v1):

  • renewable_electricity
  • electricity
  • fuels
  • energy_total (only for special cases)
  • carrier:<carrier_key> where <carrier_key> is canonical (e.g., natural_gas, diesel, coal, steam, heat)

4.2. Canonical denominator_ref values​

Allowed denominator refs (v1):

  • electricity_total
  • energy_total
  • fuels_total

4.3. Carrier normalization​

If carrier_normalization = STRICT:

  • unknown carrier keys MUST error

If LENIENT:

  • unknown carriers MAY be dropped with metadata annotation

Metadata MUST include:

  • normalized_numerator_ref
  • normalized_denominator_ref

5. Compute Semantics (Normative)​

For each aligned period tt:

5.1. Base ratio​

Let N(t)N(t) be numerator and D(t)D(t) be denominator.

shareraw(t)=N(t)max⁡(∣D(t)∣,ϵ)share_{\mathrm{raw}}(t) = \frac{N(t)}{\max(|D(t)|, \epsilon)}

Where ϵ\epsilon is denominator_floor.

5.2. Output scaling​

If share_mode = RATIO:

share(t)=shareraw(t)share(t) = share_{\mathrm{raw}}(t)

If share_mode = PERCENT:

share(t)=100⋅shareraw(t)share(t) = 100 \cdot share_{\mathrm{raw}}(t)

5.3. Range enforcement​

If cap_range = ENFORCE:

  • ratio mode: clamp to [0,1][0, 1]
  • percent mode: clamp to [0,100][0, 100]

Clamp events MUST be recorded in:

  • metadata.capped_values_count

6. Alignment Rules​

BY_YEAR

  • Numerator and denominator MUST share the same period keys unless missing_policy = SKIP.

BY_INDEX

  • Ordered alignment; length mismatch handled per missing_policy.

Metadata MUST include:

  • aligned_periods
  • missing_in_numerator
  • missing_in_denominator
  • denominator_floor_applied_count

7. Validation & Error Model​

Invariants

  • Values must be finite
  • denominator_floor > 0
  • Denominator should be non-negative (default; allow only if schema permits)
  • Refs must be valid canonical forms

Error codes (suggested)

  • ENERGY_SHARE_INVALID_REF
  • ENERGY_SHARE_INVALID_CARRIER
  • ENERGY_SHARE_ALIGNMENT_MISMATCH
  • ENERGY_SHARE_DENOMINATOR_ZERO_GUARDED (informational if floor applied)
  • ENERGY_SHARE_VALUE_OUT_OF_RANGE
  • ENERGY_SHARE_NON_FINITE_VALUE

Errors MUST include:

  • engine cmi_short_code
  • offending ref/carrier and period

8. Dependencies​

MEID_CALC_ENERGY_SHARE depends on:

  • MEID_CALC_SHARE (primitive)
  • schema resolver (ZAR)
  • canonical energy carrier reference list

Declared via ZAR dependencies.

9. Federation & Audit Requirements​

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

  • engine identity (cmi or zar_code)
  • engine build proof (execution_ref + build_hash)
  • input/options/output schemas used
  • numerator and denominator series used (or resolvable signal refs)
  • normalization settings and caps

Provenance chain MUST show:

… → MEID_CALC_ENERGY_SHARE → …

with cmi_short_code recorded in USO tail arrays.

10. Performance Notes​

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

11. Methods Served (v1)​

  • Energy.renewable.share
  • Energy.electricity.share
  • Energy.fuels.share
  • Energy.carrier.share


GitHub RepoRequest for Change (RFC)