Jira progress: loading…

WTR-AGGR

Water Withdrawal Aggregation

1. Identity

Loading identity…

Depends on module:

Purpose
Aggregates water withdrawal into canonical totals and structured breakdowns aligned with ESRS E3-style water accounting. This engine is the anchor for Water KPIs (intensity, stress-area allocation, YoY deltas, and discharge/consumption comparisons).

Typical usage

• Total water withdrawal (m³)
• Withdrawal by source (surface, groundwater, seawater, third-party, etc.)
• Withdrawal by quality (freshwater vs other, where provided)
• Input to MEID_CALC_WATER_INT, MEID_CALC_WATER_STRESS

---

2. Contract References (ZAR)

2.1 Input Schema

ZAR Address: schema.compute.water.withdrawal.inputs.v1_0_0

Required conceptual fields:

• water_items: list of water withdrawal records
• alignment: BY_YEAR | BY_INDEX (default BY_YEAR)

Each water_item conceptually includes:

• period (typically year)
• value
• unit (e.g., m3, L, ML)
• source: canonical source identifier
• optional:
  • quality: FRESH | NON_FRESH | UNKNOWN
  • site_id
  • basin_id
  • geo_ref (for stress-area mapping upstream/downstream)
  • meter_id / invoice_id
  • is_estimate (boolean)

Canonical sources (v1):

• surface_water
• groundwater
• seawater
• third_party
• rainwater_harvested
• produced_water (sector-specific; optional)
• other

Note: This engine focuses on withdrawal. Water consumption and discharge are handled in separate MICEs.

---

2.2 Options Schema

ZAR Address: schema.compute.water.withdrawal.options.v1_0_0

Common options:

• unit_output: default m3
• source_normalization: STRICT | LENIENT (default STRICT)
• unknown_source_policy: ERROR | DROP | ASSIGN_OTHER (default ERROR)
• negative_values_policy: ERROR | ALLOW_WITH_FLAG
• missing_policy: ERROR | SKIP
• rounding: optional digits
• include_quality_breakdown: boolean (default false)

---

2.3 Output Schema

ZAR Address: schema.compute.water.withdrawal.output.v1_0_0

Outputs include:

• $W_{\mathrm{withdrawal,total}}(t)$
• $W_{\mathrm{withdrawal,by\_source}}(s,t)$
• optional $W_{\mathrm{withdrawal,by\_quality}}(q,t)$
• metadata (unit conversions, unknown sources, flags, completeness)

---

3. Accepted Input Shapes

A. Flat withdrawal item list (preferred)

{
  "water_items": [
    { "source": "surface_water", "period": 2025, "value": 100000, "unit": "m3" },
    { "source": "groundwater", "period": 2025, "value": 25000, "unit": "m3" }
  ],
  "alignment": "BY_YEAR"
}

B. Mixed units

{
  "water_items": [
    { "source": "surface_water", "period": 2025, "value": 100000, "unit": "m3" },
    { "source": "third_party",  "period": 2025, "value": 50000000, "unit": "L" }
  ]
}

C. With quality tagging

{
  "water_items": [
    { "source": "surface_water", "quality": "FRESH", "period": 2025, "value": 80000, "unit": "m3" },
    { "source": "seawater",      "quality": "NON_FRESH", "period": 2025, "value": 30000, "unit": "m3" }
  ],
  "include_quality_breakdown": true
}

All supported shapes MUST be normalized internally to:

Map<period, Map<source, withdrawal_m3>> (+ optional quality dimension)

---

4. Source Normalization Rules (Normative)

4.1. Canonical source identifiers

Input sources MUST normalize to canonical keys:

• surface_water
• groundwater
• seawater
• third_party
• rainwater_harvested
• produced_water (optional)
• other

If source_normalization = STRICT:

• unknown sources MUST error (default)

If LENIENT:

• unknown sources handled per unknown_source_policy

4.2. Unknown source handling

If a record cannot be mapped:

• ERROR: fail the computation
• DROP: omit record and record in metadata
• ASSIGN_OTHER: map to other and record in metadata

---

5. Compute Semantics (Normative)

Let $W(s,t)$ be withdrawal volume from source $s$ at time $t$ (after unit normalization).

5.1. Withdrawal by source

$W_{\mathrm{withdrawal,by_source}}(s,t) = W(s,t)$

5.2. Total withdrawal

$W_{\mathrm{withdrawal,total}}(t) = \sum_{s \in S_{\mathrm{all}}} W(s,t)$

Where $S_{\mathrm{all}}$ is the set of included canonical sources.

5.3. Optional quality breakdown

If include_quality_breakdown = true, let $q \in {FRESH, NON_FRESH, UNKNOWN}$:

$W_{\mathrm{withdrawal,by_quality}}(q,t) = \sum_{s \in S_{\mathrm{all}}} W(s,q,t)$

---

6. Completeness & Coverage Metadata (Normative)

This engine MUST compute a structural completeness measure:

• $S_{\mathrm{present}}$: sources present in input (post-normalization)
• $S_{\mathrm{expected}}$: expected sources (defaults to the canonical set unless overridden)

$coverage_ratio = \frac{|S_{\mathrm{present}} \cap S_{\mathrm{expected}}|}{|S_{\mathrm{expected}}|}$

Metadata MUST include:

• sources_present
• sources_expected
• coverage_ratio
• unknown_source_count
• negative_value_count (if allowed)

---

7. Validation & Error Model

Invariants

• Values must be finite
• Units must be convertible to unit_output
• Negative values rejected unless explicitly allowed
• Period keys must be coherent under alignment rules

Error codes (suggested)

• WATER_AGGR_INVALID_SOURCE
• WATER_AGGR_UNIT_CONVERSION_FAILED
• WATER_AGGR_NEGATIVE_VALUE
• WATER_AGGR_NON_FINITE_VALUE
• WATER_AGGR_ALIGNMENT_MISMATCH

Errors MUST include:

• engine cmi_short_code
• source and period context

---

8. Dependencies

MEID_CALC_WATER_AGGR depends on:

• schema resolver (ZAR)
• unit conversion capability (delegated)
• canonical water source reference list

Declared via ZAR dependencies.

---

9. Federation & Audit Requirements

To reproduce water withdrawal externally, the export MUST include:

• engine identity (cmi or zar_code)
• engine build proof (execution_ref + build_hash)
• input/options/output schemas used
• raw water withdrawal items
• source normalization policy used
• unit conversion reference/version used (if applicable)

Provenance chain MUST show:

… → MEID_CALC_WATER_AGGR → …

with cmi_short_code recorded in USO tail arrays.

---

10. Performance Notes

• Complexity: $O(n_{items})$
• Memory: $O(|T| \times |S|)$
• Suitable for batch reporting and KPI analytics

---

11. Methods Served (v1)

• Water.withdrawal.abs
• Water.withdrawal.by_source.abs
• Water.withdrawal.by_quality.abs (if enabled)
• Water.withdrawal.total.abs

---