Skip to main content
Jira progress: loading…

SRC

Share / Ratio Calculator Micro Engine

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: 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 shareraw(t)share_raw(t)
  • If share_mode = PERCENT → output shareraw(t)∗100share_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)O(n) over periods
  • Memory: O(n)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.



GitHub RepoRequest for Change (RFC)