Jira progress: loading…

SRC

Share / Ratio Calculator Micro Engine

1. Identity

Loading identity…

Depends on module:

• Purpose: Computes the share (ratio) of one value or time-series relative to a defined total, with strict denominator guards and deterministic output.

• Typical usage:

  • GHG Scope 3 category shares
  • Renewable vs total energy share
  • Hazardous vs total waste share
  • Water source or stress-area shares

Versioning policy

• MEID remains stable.
• All executable versions, container images, and builds are governed via ZAR (CMI + version + execution_ref + build_hash).

---

The Share / Ratio Calculator Micro Engine is another cross-cutting primitive and will be reused heavily (GHG Scope 3 shares, renewable energy share, hazardous waste share, etc.).

---

2. Contract References (ZAR)

2.1. Input Schema

• ZAR Address: schema.compute.<domain>.share.inputs.v1_0_0

Required conceptual fields

• numerator: scalar or time-series
• denominator: scalar or time-series
• share_mode: RATIO | PERCENT
• alignment: BY_YEAR | BY_INDEX (default BY_YEAR)

2.2. Options Schema

• ZAR Address: schema.compute.<domain>.share.options.v1_0_0

Common options:

• denominator_floor (default: 1e-9)
• missing_policy: ERROR | SKIP | FILL_ZERO
• cap_range: [0,1] or [0,100] (default: enforce)
• rounding: optional digits

2.3. Output Schema

• ZAR Address: schema.compute.<domain>.share.output.v1_0_0

Outputs include:

• share_series
• metadata (denominator floors applied, capped values, alignment info)

As with DELTA, schemas are domain-namespaced but compute semantics are identical.

---

3. Accepted Input Shapes

A. Scalar share

{
  "numerator": 250,
  "denominator": 1000,
  "share_mode": "PERCENT"
}

B. Time-series (year-value pairs)

{
  "numerator": [[2025, 1200], [2026, 1300]],
  "denominator": [[2025, 5000], [2026, 5200]],
  "share_mode": "RATIO",
  "alignment": "BY_YEAR"
}

C. Flat arrays (legacy)

{
  "numerator": [2025, 1200, 2026, 1300],
  "denominator": [2025, 5000, 2026, 5200],
  "share_mode": "PERCENT"
}

All shapes MUST be normalized internally to: Map<period, {numerator, denominator}>.

---

4. Compute Semantics (Normative)

For each aligned period t:

Base ratio

share_raw(t) = numerator(t) / max(|denominator(t)|, denominator_floor)

Output value

• If share_mode = RATIO → output $share_raw(t)$
• If share_mode = PERCENT → output $share_raw(t) * 100$

Range enforcement

If cap_range is enabled:

• Values below 0 are capped to 0
• Values above max (1 or 100) are capped
• Each cap event MUST be recorded in output metadata

---

5. Alignment Rules (Normative)

Same alignment semantics as MEID_CALC_DELTA:

BY_YEAR

• Period keys must match unless missing_policy allows otherwise.

BY_INDEX

• Ordered comparison.
• Length mismatch handled per missing_policy.

Metadata MUST include:

• aligned_periods
• denominator_floor_applied
• capped_values_count

---

6. Validation & Error Model

Invariants

• denominator_floor > 0
• All numeric inputs must be finite
• share_mode must match output schema expectations

Error codes (suggested)

• SHARE_DIVIDE_BY_ZERO_GUARDED
• SHARE_ALIGNMENT_MISMATCH
• SHARE_VALUE_OUT_OF_RANGE
• SHARE_INPUT_SHAPE_INVALID

Errors MUST include:

• engine cmi_short_code
• period/key causing failure (if applicable)

---

7. Dependencies

MEID_CALC_SHARE is a pure arithmetic engine but depends on:

• shared normalization utilities
• schema resolver (ZAR)
• optional unit metadata handler (for percent vs ratio tagging)

These dependencies are declared in the engine’s ZAR registry row.

---

8. Federation & Audit Requirements

To externally reproduce a share calculation, the following must be provided:

• Engine identity (cmi or zar_code)
• Engine build proof (execution_ref + build_hash)
• Input, options, and output schemas (zar_code/cmi)
• Input datasets (numerator & denominator values)

The provenance chain MUST show:

… → MEID_CALC_SHARE → …

with the corresponding cmi_short_code in USO tails.

---

9. Performance Notes

• Complexity: $O(n)$ over periods
• Memory: $O(n)$
• Suitable for batch processing and streaming pipelines

---

10. Methods Served (v1)

• GHG.scope3.cat.share
• Energy.renewable.share
• Waste.hazardous.share
• Water.source.share

Additional share-based methods may map to this engine without changing MEID; only registry bindings are updated.

---