Skip to main content
Jira progress: loading…

WTR-CONS

Water Consumption Calculator

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 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:

  • Wconsumption,total(t)W_{\mathrm{consumption,total}}(t)
  • optional Wconsumption,by_source(s,t)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:

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

4.1. DIRECT mode​

If mode = DIRECT, total consumption is:

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

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

If source breakdown is present:

Wcons,by−source(s,t)=∑i∈I(s,t)v(i)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:

Wcons,total(t)=Wwith(t)−Wdisc(t)+Wloss(t)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):

Wcons,by−source(s,t)=Wwith(s,t)−Wdisc(s,t)+Wloss(s,t)W_{\mathrm{cons,by-source}}(s,t) = W_{\mathrm{with}}(s,t) - W_{\mathrm{disc}}(s,t) + W_{\mathrm{loss}}(s,t)

If Wloss(s,t)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):

Wcons,total(t)=max⁡(0,Wcons,total(t))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)O(n) over periods (or O(nitems)O(n_{items}) in DIRECT mode)
  • Memory: O(n)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


GitHub RepoRequest for Change (RFC)