Jira progress: loading…

WTR-INT

Water Intensity Calculator

1. Identity

Loading identity…

Depends on module:

Purpose
Computes water intensity by normalizing a water quantity (withdrawal, consumption, or discharge) against an activity denominator (typically revenue), producing disclosure-ready intensity series aligned with ESRS E3 reporting patterns.

This engine is the Water analogue of:

• MEID_CALC_ENERGY_INT (energy intensity)
• MEID_CALC_GHG_INT (GHG intensity)

Typical usage

• Withdrawal per € revenue (m³/€m)
• Consumption per € revenue (m³/€m)
• Discharge per € revenue (m³/€m)
• Inputs to benchmarking and trend analytics

---

2. Contract References (ZAR)

2.1 Input Schema

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

Required conceptual fields:

• water: scalar or time-series (absolute water quantity)
• denominator: scalar or time-series (e.g., revenue in EURm, production volume)
• intensity_basis: WITHDRAWAL | CONSUMPTION | DISCHARGE (default WITHDRAWAL)
• alignment: BY_YEAR | BY_INDEX (default BY_YEAR)

Optional:

• unit_water: default m3
• unit_denominator: e.g. EURm
• water_by_source: optional map source → series (if intensity per source needed later)

Note: v1 focuses on a single intensity output per request. Per-source intensity can be introduced as an extension without changing the core formula.

---

2.2 Options Schema

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

Common options:

• denominator_floor: default 1e-9
• missing_policy: ERROR | SKIP
• rounding: optional digits
• output_unit_style: m3_per_EURm | m3_per_EUR | auto (default auto)
• non_positive_denominator_policy: ERROR | FLOOR_AT_EPS (default ERROR)

---

2.3 Output Schema

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

Outputs include:

• water_intensity
• metadata (basis, floors applied, alignment info, units)

---

3. Accepted Input Shapes

A. Withdrawal intensity (scalar)

{
  "water": 125000,
  "denominator": 250,
  "intensity_basis": "WITHDRAWAL"
}

B. Consumption intensity (time-series)

{
  "water": [[2025, 15000], [2026, 14500]],
  "denominator": [[2025, 250], [2026, 260]],
  "intensity_basis": "CONSUMPTION",
  "alignment": "BY_YEAR"
}

C. Discharge intensity (resolved upstream)

{
  "water": [[2025, 108000]],
  "denominator": [[2025, 250]],
  "intensity_basis": "DISCHARGE"
}

All supported shapes MUST be normalized internally to:

Map<period, water_value> + Map<period, denominator_value>

---

4. Compute Semantics (Normative)

For each aligned period $t$:

4.1 Select water basis

Let $W(t)$ be the selected water series corresponding to intensity_basis:

• WITHDRAWAL: $W(t) = W_{\mathrm{withdrawal,total}}(t)$
• CONSUMPTION: $W(t) = W_{\mathrm{cons,total}}(t)$
• DISCHARGE: $W(t) = W_{\mathrm{discharge,total}}(t)$

If the caller supplies a raw water series, it is treated as $W(t)$ directly; the basis label is still required for metadata.

4.2 Intensity formula

Let $D(t)$ be the denominator series (e.g. revenue).

$I(t) = \frac{W(t)}{\max(|D(t)|, \epsilon)}$

Where $\epsilon$ is denominator_floor.

4.3 Denominator policy

If non_positive_denominator_policy = ERROR, then:

• if $D(t) \le 0$, the computation MUST fail for that period (or entire run, depending on schema strictness).

If FLOOR_AT_EPS, then: $D(t) \leftarrow \max(D(t), \epsilon)$ and the event MUST be recorded in metadata.

4.4 Output units

If water is m³ and denominator is EURm, then:

• $I(t)$ unit is m³/EURm

The engine MUST propagate unit metadata to output:

• unit_water
• unit_denominator
• derived unit_intensity

---

5. Alignment Rules

BY_YEAR

• Water and denominator 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_water
• missing_in_denominator
• denominator_floor_applied_count
• non_positive_denominator_events (if any)

---

6. Validation & Error Model

Invariants

• Values must be finite
• denominator_floor > 0
• Denominator must be positive under default policy
• intensity_basis must be valid

Error codes (suggested)

• WATER_INT_MISSING_DENOMINATOR
• WATER_INT_INVALID_BASIS
• WATER_INT_ALIGNMENT_MISMATCH
• WATER_INT_NON_POSITIVE_DENOMINATOR
• WATER_INT_DENOMINATOR_ZERO_GUARDED (informational if floor applied)
• WATER_INT_NON_FINITE_VALUE

Errors MUST include:

• engine cmi_short_code
• basis and period context

---

7. Dependencies

MEID_CALC_WATER_INT depends on:

• upstream water totals (often from MEID_CALC_WATER_AGGR, MEID_CALC_WATER_CONS, MEID_CALC_WATER_DISC)
• schema resolver (ZAR)

Declared via ZAR dependencies.

---

8. Federation & Audit Requirements

To reproduce water intensity externally, the export MUST include:

• engine identity (cmi or zar_code)
• engine build proof (execution_ref + build_hash)
• input/options/output schemas used
• water series selected (withdrawal/consumption/discharge)
• denominator series (e.g. revenue)
• denominator floor and denominator-policy settings

Provenance chain MUST show:

… → MEID_CALC_WATER_INT → …

with cmi_short_code recorded in USO tail arrays.

---

9. Performance Notes

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

---

10. Methods Served (v1)

• Water.withdrawal.intensity
• Water.consumption.intensity
• Water.discharge.intensity

---