Jira progress: loading…

WTR-CONS

Water Consumption Calculator

1. Identity

Loading identity…

Depends on module:

Purpose
Computes water consumption (water that is withdrawn and not returned to the same source in the same quality and timeframe) in canonical units, aligned with ESRS-style water accounting.

This engine is intentionally separate from:

• MEID_CALC_WATER_AGGR (withdrawal)
• MEID_CALC_WATER_DISC (discharge)

because “consumption” is frequently derived and method-dependent.

Typical usage

• Water consumption absolute (m³)
• Consumption by source (where traceable)
• Input to intensity, stress-area allocation, and risk scoring

---

2. Contract References (ZAR)

2.1 Input Schema

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

Required conceptual fields (v1 supports two calculation modes):

• mode: DIRECT | DERIVED (default DERIVED)
• alignment: BY_YEAR | BY_INDEX (default BY_YEAR)

Mode A — DIRECT

• consumption_items: list of consumption records (already measured/estimated)

Each consumption item includes:

• period
• value
• unit
• optional: source, site_id, basin_id, quality

Mode B — DERIVED

• withdrawal: scalar or time-series (or by-source map)
• discharge: scalar or time-series (or by-source map)
• optional: other_losses: scalar or time-series (evaporation, product-embedded water, etc.)

In DERIVED mode, consumption is computed from a mass-balance relationship.

---

2.2 Options Schema

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

Common options:

• unit_output: default m3
• negative_consumption_policy: ERROR | FLOOR_AT_ZERO | ALLOW_WITH_FLAG (default FLOOR_AT_ZERO)
• missing_policy: ERROR | SKIP
• source_normalization: STRICT | LENIENT (default STRICT)
• rounding: optional digits

---

2.3 Output Schema

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

Outputs include:

• $W_{\mathrm{consumption,total}}(t)$
• optional $W_{\mathrm{consumption,by\_source}}(s,t)$ (if inputs allow by-source derivation)
• metadata (mode used, floors/flags, unit conversions, coverage)

---

3. Accepted Input Shapes

A. DIRECT mode (measured / estimated consumption)

{
  "mode": "DIRECT",
  "consumption_items": [
    { "period": 2025, "value": 15000, "unit": "m3", "source": "surface_water" },
    { "period": 2025, "value": 2000, "unit": "m3", "source": "groundwater" }
  ],
  "alignment": "BY_YEAR"
}

B. DERIVED mode (withdrawal - discharge + losses) — preferred for most orgs

{
  "mode": "DERIVED",
  "withdrawal": [[2025, 125000], [2026, 120000]],
  "discharge":  [[2025, 108000], [2026, 105000]],
  "other_losses": [[2025, 2000], [2026, 1500]],
  "alignment": "BY_YEAR"
}

C. DERIVED by source (when source tagging exists)

{
  "mode": "DERIVED",
  "withdrawal_by_source": {
    "surface_water": [[2025, 100000]],
    "groundwater": [[2025, 25000]]
  },
  "discharge_by_source": {
    "surface_water": [[2025, 90000]],
    "groundwater": [[2025, 18000]]
  },
  "alignment": "BY_YEAR"
}

All supported shapes MUST be normalized internally to:

• Total series:

Map<period, withdrawal_m3>, Map<period, discharge_m3>, Map<period, losses_m3>

• Optional by-source maps where provided

---

4. Compute Semantics (Normative)

Let:

• $W_{\mathrm{with}}(t)$ be withdrawal volume in period $t$
• $W_{\mathrm{disc}}(t)$ be discharge volume in period $t$
• $W_{\mathrm{loss}}(t)$ be other losses in period $t$ (default 0 if not provided)

4.1. DIRECT mode

If mode = DIRECT, total consumption is:

$W_{\mathrm{cons,total}}(t) = \sum_{i \in I(t)} v(i)$

Where $I(t)$ is the set of consumption items in period $t$.

If source breakdown is present:

$W_{\mathrm{cons,by-source}}(s,t) = \sum_{i \in I(s,t)} v(i)$

---

4.2. DERIVED mode (mass-balance)

If mode = DERIVED, consumption is computed as:

$W_{\mathrm{cons,total}}(t) = W_{\mathrm{with}}(t) - W_{\mathrm{disc}}(t) + W_{\mathrm{loss}}(t)$

If by-source inputs exist (and are aligned):

$W_{\mathrm{cons,by-source}}(s,t) = W_{\mathrm{with}}(s,t) - W_{\mathrm{disc}}(s,t) + W_{\mathrm{loss}}(s,t)$

If $W_{\mathrm{loss}}(s,t)$ is not available, it defaults to 0 for that source.

---

4.3. Negative consumption handling

If computed consumption is negative:

• ERROR: fail
• FLOOR_AT_ZERO (default):

$W_{\mathrm{cons,total}}(t) = \max(0, W_{\mathrm{cons,total}}(t))$

• ALLOW_WITH_FLAG: allow negatives but flag in metadata

All negative events MUST be recorded in metadata:

• negative_periods
• floored_periods_count (if floored)

---

5. Alignment Rules

BY_YEAR

• Withdrawal, discharge, and losses must share period keys unless missing_policy = SKIP.

BY_INDEX

• Ordered alignment; length mismatch handled per missing_policy.

Metadata MUST include:

• aligned_periods
• missing_in_withdrawal
• missing_in_discharge
• missing_in_losses

---

6. Validation & Error Model

Invariants

• Values must be finite
• Units must be convertible to unit_output
• mode must be declared or defaulted
• DERIVED mode requires withdrawal and discharge

Error codes (suggested)

• WATER_CONS_MISSING_INPUT
• WATER_CONS_INVALID_MODE
• WATER_CONS_UNIT_CONVERSION_FAILED
• WATER_CONS_ALIGNMENT_MISMATCH
• WATER_CONS_NEGATIVE_CONSUMPTION_ERROR
• WATER_CONS_NON_FINITE_VALUE

Errors MUST include:

• engine cmi_short_code
• period context and (if applicable) source key

---

7. Dependencies

MEID_CALC_WATER_CONS depends on:

• schema resolver (ZAR)
• unit conversion capability (delegated)
• upstream availability of withdrawal/discharge (often from MEID_CALC_WATER_AGGR and MEID_CALC_WATER_DISC)

Declared via ZAR dependencies.

---

8. Federation & Audit Requirements

To reproduce water consumption externally, the export MUST include:

• engine identity (cmi or zar_code)
• engine build proof (execution_ref + buil`d_hash)
• input/options/output schemas used
• whether DIRECT or DERIVED mode was used
• all input series (withdrawal, discharge, losses) or consumption items
• negative handling policy applied and evidence of floors/flags

Provenance chain MUST show:

… → MEID_CALC_WATER_CONS → …

with cmi_short_code recorded in USO tail arrays.

---

9. Performance Notes

• Complexity: $O(n)$ over periods (or $O(n_{items})$ in DIRECT mode)
• Memory: $O(n)$
• Suitable for batch reporting and KPI analytics

---

10. Methods Served (v1)

• Water.consumption.abs
• Water.consumption.by_source.abs (if inputs permit)
• Water.consumption.total.abs

---