distributed-buffer-resilience-utac 1.0.0__py3-none-any.whl

distributed_buffer_resilience_utac/__init__.py

@@ -0,0 +1,86 @@
+"""distributed-buffer-resilience-utac -- distributed hydrological/ecosystem buffer resilience.
+
+GenesisAeon Package 103. Companion to glacier-buffer-utac (P99, the
+loss) and glacier-buffer-replacement-utac (P100, technical
+replacement): P103 covers the broader "distributed functional
+resilience" idea -- a portfolio of reservoirs, groundwater, wetlands
+and demand management, each with different response times, rather than
+one storage type trying to replace the glacier alone. Deliberately no
+UTAC/CREP/AFET bridge -- see DISCLAIMER.md.
+
+Two explicit confidence tiers, kept separate in every module:
+- CORE (drought_buffer, storage_portfolio, water_towers,
+  ecosystem_services): real, peer-reviewed findings independently
+  re-verified 2026-08-14.
+- OPTIONAL/SPECULATIVE (gbr): a ratio-style metric this ecosystem
+  itself constructed from a source document's own proposed formula,
+  not a published metric, always exposed with an explicit warning.
+"""
+
+from .constants import (
+    ALPINE_RESERVOIR_SUMMER_DEFICIT_CEILING_FRACTION,
+    CASALLAS_2025_CITATION,
+    FARINOTTI_2016_CITATION,
+    FARINOTTI_2019_CITATION,
+    HUSS_HOCK_2018_CITATION,
+    IMMERZEEL_2020_CITATION,
+    PACKAGE_ID,
+    PRITCHARD_2017_CITATION,
+    VAN_TIEL_2026_CITATION,
+    WATER_TOWER_DEPENDENT_POPULATION_BILLIONS,
+)
+from .drought_buffer import (
+    SWISS_2022_DROUGHT,
+    DroughtBufferObservation,
+    buffer_functions_while_eroding,
+)
+from .ecosystem_services import (
+    ECOSYSTEM_SERVICES_CITATION,
+    NBS_DESIGN_RULE,
+    nbs_effect_is_guaranteed_positive,
+)
+from .gbr import (
+    GBR_NOT_PEER_REVIEWED_WARNING,
+    glacier_buffer_replacement_score,
+)
+from .storage_portfolio import (
+    GLOBAL_STORAGE_POTENTIAL,
+    STORAGE_PORTFOLIO_NOTE,
+    GlobalStoragePotential,
+    reservoir_summer_deficit_ceiling_fraction,
+    theoretical_vs_realistic_gap_fraction,
+)
+from .water_towers import (
+    is_disproportionate_drought_buffer,
+    water_tower_dependent_population_billions,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "ALPINE_RESERVOIR_SUMMER_DEFICIT_CEILING_FRACTION",
+    "CASALLAS_2025_CITATION",
+    "ECOSYSTEM_SERVICES_CITATION",
+    "FARINOTTI_2016_CITATION",
+    "FARINOTTI_2019_CITATION",
+    "GBR_NOT_PEER_REVIEWED_WARNING",
+    "GLOBAL_STORAGE_POTENTIAL",
+    "HUSS_HOCK_2018_CITATION",
+    "IMMERZEEL_2020_CITATION",
+    "NBS_DESIGN_RULE",
+    "PACKAGE_ID",
+    "PRITCHARD_2017_CITATION",
+    "STORAGE_PORTFOLIO_NOTE",
+    "SWISS_2022_DROUGHT",
+    "VAN_TIEL_2026_CITATION",
+    "WATER_TOWER_DEPENDENT_POPULATION_BILLIONS",
+    "DroughtBufferObservation",
+    "GlobalStoragePotential",
+    "buffer_functions_while_eroding",
+    "glacier_buffer_replacement_score",
+    "is_disproportionate_drought_buffer",
+    "nbs_effect_is_guaranteed_positive",
+    "reservoir_summer_deficit_ceiling_fraction",
+    "theoretical_vs_realistic_gap_fraction",
+    "water_tower_dependent_population_billions",
+]

distributed_buffer_resilience_utac/constants.py

@@ -0,0 +1,186 @@
+"""Verified constants for distributed hydrological/ecosystem buffer resilience.
+
+Companion to glacier-buffer-utac (P99, the natural loss) and
+glacier-buffer-replacement-utac (P100, technical replacement). P103
+covers the broader "distributed functional resilience" idea from
+P102.md: instead of one storage type replacing the glacier, a portfolio
+of reservoirs, groundwater, wetlands and demand management, each with
+different response times, is what actually buffers a deglacierizing
+catchment.
+
+Two explicit confidence tiers, kept separate throughout this package:
+- CORE: real, peer-reviewed findings independently re-verified via
+  direct paper/DOI lookup on 2026-08-14.
+- OPTIONAL/SPECULATIVE (see gbr.py): a ratio-style metric this
+  ecosystem itself constructed (following P102.md's own proposal),
+  not a published, peer-reviewed formula -- exposed with an explicit
+  warning constant, same pattern as P100's RRF.
+"""
+
+PACKAGE_ID = 103
+
+# =====================================================================
+# CORE -- independently re-verified 2026-08-14
+# =====================================================================
+
+# --- van Tiel, Huss, Zappa, Jonas & Farinotti 2026: the empirical anchor ---
+
+VAN_TIEL_2026_CITATION = (
+    "van Tiel, M., Huss, M., Zappa, M., Jonas, T., Farinotti, D. "
+    "(2026). Swiss glacier mass loss during the 2022 drought: "
+    "persistent streamflow contributions amid declining melt water "
+    "volumes. Hydrology and Earth System Sciences, 30, 23-43. "
+    "DOI: 10.5194/hess-30-23-2026"
+)
+VAN_TIEL_2026_DOI = "10.5194/hess-30-23-2026"
+
+# Number of glacierized Swiss catchments analyzed
+VAN_TIEL_CATCHMENT_COUNT = 88
+# Swiss glacier mass lost during 2022 alone, percent of remaining volume
+VAN_TIEL_2022_MASS_LOSS_PCT = 6.0
+
+VAN_TIEL_NOTE = (
+    "This is currently the strongest single empirical anchor for the "
+    "whole P99-P103 series: during the extreme, hot, dry summer of "
+    "2022, glacier melt across 88 Swiss catchments STILL substantially "
+    "buffered precipitation/snowmelt deficits -- yet in roughly "
+    "two-thirds of the studied catchments, the absolute summer "
+    "meltwater volume was already LOWER than in the comparably extreme "
+    "2003 summer, because shrinking glacier area increasingly "
+    "outweighs higher specific melt rates. The buffer still works, but "
+    "its physical capacity is measurably eroding -- not a hypothetical "
+    "future transition, an already-observed one."
+)
+
+# --- Farinotti, Pistocchi & Huss 2016: reservoir ceiling (reused from P100) ---
+
+FARINOTTI_2016_CITATION = (
+    "Farinotti, D., Pistocchi, A., Huss, M. (2016). From dwindling ice "
+    "to headwater lakes: could dams replace glaciers in the European "
+    "Alps? Environmental Research Letters, 11(5), 054022. "
+    "DOI: 10.1088/1748-9326/11/5/054022"
+)
+FARINOTTI_2016_DOI = "10.1088/1748-9326/11/5/054022"
+
+# Ceiling on the fraction of the projected end-of-century Alpine
+# summer-runoff CHANGE (not total hydrological loss) a reservoir
+# strategy could offset -- a specific, regional, scenario-bound
+# estimate, NOT a universal replacement constant. See P100's
+# mass_balance module for the same figure applied to reservoirs alone;
+# here it anchors the "technical storage" layer of the wider portfolio.
+ALPINE_RESERVOIR_SUMMER_DEFICIT_CEILING_FRACTION = 0.65
+
+FARINOTTI_2016_SCOPE_NOTE = (
+    "Farinotti et al. (2016) found NO general physical upper bound of "
+    "65% for technical glacier replacement. They estimated that, for a "
+    "specific European Alps scenario to 2100, reservoir management "
+    "could offset up to ~65% of the EXPECTED CHANGE in summer runoff "
+    "from presently glacierized areas -- and explicitly state that "
+    "reservoirs cannot compensate the annual non-renewable runoff share "
+    "lost as glacier ice permanently disappears. Treat 65% as a "
+    "modeled, regional, scenario-bound ceiling, never as a portable "
+    "'universal replacement fraction'."
+)
+
+# --- Farinotti et al. 2019: global storage potential in ice-free basins ---
+
+FARINOTTI_2019_CITATION = (
+    "Farinotti, D., Round, V., Huss, M., Compagno, L., Zekollari, H. "
+    "(2019). Large hydropower and water-storage potential in future "
+    "glacier-free basins. Nature, 575, 341-344. "
+    "DOI: 10.1038/s41586-019-1740-z"
+)
+FARINOTTI_2019_DOI = "10.1038/s41586-019-1740-z"
+
+# Global theoretical storage potential in future ice-free glacier
+# basins, km^3 (based on ~185,000 glaciers analyzed)
+GLOBAL_THEORETICAL_STORAGE_POTENTIAL_KM3 = 875.0
+GLOBAL_THEORETICAL_STORAGE_POTENTIAL_KM3_UNCERTAINTY = 260.0
+GLOBAL_THEORETICAL_HYDROPOWER_POTENTIAL_TWH_PER_YR = 1350.0
+
+# After a first technical/ecological/economic suitability screen, the
+# fraction of the theoretical potential judged "potentially" realistic
+REALISTIC_STORAGE_FRACTION_OF_THEORETICAL = 0.40
+REALISTIC_STORAGE_POTENTIAL_KM3 = 355.0
+REALISTIC_HYDROPOWER_POTENTIAL_TWH_PER_YR = 533.0
+
+FARINOTTI_2019_NOTE = (
+    "875 +/- 260 km3 is a global THEORETICAL maximum across ~185,000 "
+    "glaciers; only ~40% (355 km3) passed a first-pass technical, "
+    "ecological and economic suitability screen. The paper itself "
+    "stresses this remains theoretical and requires site-specific "
+    "assessment before any real project -- do not read 875 km3 as "
+    "'available' storage."
+)
+
+# --- Huss & Hock 2018: peak water (reused from P99) ---
+
+HUSS_HOCK_2018_CITATION = (
+    "Huss, M., Hock, R. (2018). Global-scale hydrological response to "
+    "future glacier mass loss. Nature Climate Change, 8, 135-140. "
+    "DOI: 10.1038/s41558-017-0049-x"
+)
+HUSS_HOCK_2018_DOI = "10.1038/s41558-017-0049-x"
+
+# --- Pritchard 2017: glaciers as a regional drought buffer ---
+
+PRITCHARD_2017_CITATION = (
+    "Pritchard, H.D. (2017). Asia's glaciers are a regionally important "
+    "buffer against drought. Nature, 545, 169-174. "
+    "DOI: 10.1038/nature22062"
+)
+PRITCHARD_2017_DOI = "10.1038/nature22062"
+
+PRITCHARD_NOTE = (
+    "Pritchard (2017) is the explicit origin of the 'glaciers as "
+    "drought buffer' framing this whole package series builds on: "
+    "glacier meltwater contribution to river flow is disproportionately "
+    "important precisely during low-flow/drought years in High Mountain "
+    "Asia, even in basins where glacier melt is a small share of the "
+    "long-term mean flow."
+)
+
+# --- Immerzeel et al. 2020: Water Tower Index ---
+
+IMMERZEEL_2020_CITATION = (
+    "Immerzeel, W.W., Lutz, A.F., Andrade, M. et al. (2020). "
+    "Importance and vulnerability of the world's water towers. Nature, "
+    "577, 364-369. DOI: 10.1038/s41586-019-1822-y"
+)
+IMMERZEEL_2020_DOI = "10.1038/s41586-019-1822-y"
+
+# Global population living in or immediately downstream of mountain
+# water-tower regions, billions
+WATER_TOWER_DEPENDENT_POPULATION_BILLIONS = 1.9
+
+IMMERZEEL_NOTE = (
+    "The Water Tower Index ranks mountain water systems not just by "
+    "hydrological importance but also by water stress, governance "
+    "quality, hydropolitical tension, and climatic/socioeconomic "
+    "change -- some of the world's most important water towers "
+    "(Indus, Amu Darya, Tarim) are simultaneously among the most "
+    "vulnerable, precisely because high dependence coincides with weak "
+    "governance capacity."
+)
+
+# --- Velasquez Casallas, Khelidj, Moran-Ordonez & Losapio 2025: ecosystem services ---
+
+CASALLAS_2025_CITATION = (
+    "Velasquez Casallas, L.M., Khelidj, N., Moran-Ordonez, A., "
+    "Losapio, G. (2025). Global impacts of glacier retreat on "
+    "ecosystem services provided by soil and vegetation in mountain "
+    "regions: A literature review. Ecosystem Services, 73, 101730. "
+    "DOI: 10.1016/j.ecoser.2025.101730"
+)
+CASALLAS_2025_DOI = "10.1016/j.ecoser.2025.101730"
+
+CASALLAS_NOTE = (
+    "This systematic review found that regulating ecosystem services "
+    "(e.g. climate regulation, erosion control) can INCREASE in "
+    "postglacial landscapes as vegetation establishes -- but the "
+    "effects are spatially and temporally heterogeneous, with real "
+    "trade-offs against other services, not a uniform net benefit. "
+    "Nature-based solutions should be selected by measured local "
+    "function, never assumed positive purely from their 'natural' "
+    "label -- see ecosystem_services.py."
+)

distributed_buffer_resilience_utac/drought_buffer.py

@@ -0,0 +1,52 @@
+"""The empirical anchor: glacier drought buffering is real but eroding.
+
+Core module -- van Tiel, Huss, Zappa, Jonas & Farinotti (2026)'s Swiss
+2022-drought analysis, the strongest current empirical evidence for
+this whole package series' central claim: the natural buffer still
+functions during extreme events, even as its physical capacity shrinks.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .constants import (
+    VAN_TIEL_2022_MASS_LOSS_PCT,
+    VAN_TIEL_2026_CITATION,
+    VAN_TIEL_CATCHMENT_COUNT,
+    VAN_TIEL_NOTE,
+)
+
+
+@dataclass(frozen=True)
+class DroughtBufferObservation:
+    """A real, dated observation of glacier drought-buffering under extreme conditions."""
+
+    catchment_count: int
+    mass_loss_pct: float
+    note: str
+    citation: str
+
+
+SWISS_2022_DROUGHT = DroughtBufferObservation(
+    catchment_count=VAN_TIEL_CATCHMENT_COUNT,
+    mass_loss_pct=VAN_TIEL_2022_MASS_LOSS_PCT,
+    note=VAN_TIEL_NOTE,
+    citation=VAN_TIEL_2026_CITATION,
+)
+
+
+def buffer_functions_while_eroding() -> bool:
+    """The core van Tiel et al. (2026) finding: both things are true at once.
+
+    Always True. During the extreme 2022 Swiss drought, glacier melt
+    still substantially buffered precipitation/snowmelt deficits AND
+    the absolute meltwater volume was already below the comparable 2003
+    extreme in roughly two-thirds of studied catchments. A buffer that
+    still 'works' in the present is not evidence its capacity isn't
+    shrinking -- this is the empirical basis for treating resilience
+    loss as something that can precede visible system failure (see
+    P102.md's Adaptive Option Capacity discussion, not implemented here
+    as code -- too undefined for that, see DISCLAIMER.md).
+    """
+    return True

distributed_buffer_resilience_utac/ecosystem_services.py

@@ -0,0 +1,38 @@
+"""Postglacial ecosystem services: real, but heterogeneous and trade-off-laden.
+
+Core module -- Velasquez Casallas, Khelidj, Moran-Ordonez & Losapio
+(2025)'s systematic literature review. The key discipline this module
+encodes: Nature-based Solutions are selected by measured local
+function, never assumed positive purely from their "natural" label.
+"""
+
+from __future__ import annotations
+
+from .constants import CASALLAS_2025_CITATION, CASALLAS_NOTE
+
+NBS_DESIGN_RULE = (
+    "Nature-based Solutions are selected by measured local hydrological "
+    "function, not by their label. A wetland, a paramo, or reforestation "
+    "project is not automatically hydrologically beneficial -- see "
+    "CASALLAS_NOTE."
+)
+
+
+def nbs_effect_is_guaranteed_positive() -> bool:
+    """Whether a Nature-based Solution's hydrological effect can be assumed positive by its label.
+
+    Always False. Velasquez Casallas et al. (2025)'s systematic review
+    found regulating ecosystem services (climate regulation, erosion
+    control) can increase after glacier retreat as vegetation
+    establishes -- but the effects are spatially/temporally
+    heterogeneous with real trade-offs, not a uniform net benefit. Some
+    land-use changes framed as 'natural' (e.g. converting paramo to
+    pine plantation) measurably REDUCE total and base flow. This
+    function exists to make that non-guarantee an explicit, testable
+    fact rather than an assumption buried in prose.
+    """
+    return False
+
+
+ECOSYSTEM_SERVICES_CITATION = CASALLAS_2025_CITATION
+ECOSYSTEM_SERVICES_NOTE = CASALLAS_NOTE

distributed_buffer_resilience_utac/gbr.py

@@ -0,0 +1,77 @@
+"""The Glacier Buffer Replacement (GBR) score.
+
+OPTIONAL / SPECULATIVE module -- READ THIS BEFORE USING ANYTHING BELOW.
+
+GBR is NOT a peer-reviewed, published metric. It is this ecosystem's
+own discretized implementation of a formula P102.md itself proposes as
+its own synthesis (not a literature citation) for scoring how much of a
+drought-period flow deficit a set of adaptation measures actually
+closes. Same honesty pattern as glacier-buffer-replacement-utac (P100)'s
+Resilience Replacement Factor -- see RRF_NOT_PEER_REVIEWED_WARNING
+there for the analogous precedent.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+GBR_NOT_PEER_REVIEWED_WARNING = (
+    "The Glacier Buffer Replacement (GBR) score is NOT a peer-reviewed "
+    "or published metric. It is a discretized implementation of a "
+    "formula P102.md proposes as its own synthesis, built on top of "
+    "this ecosystem's real, verified drought/streamflow data -- but the "
+    "scoring formula itself carries no primary citation. Do not present "
+    "GBR outputs as a measured or literature-validated quantity."
+)
+
+
+def glacier_buffer_replacement_score(
+    deficit_without_adaptation: Sequence[float],
+    flow_gain_from_adaptation: Sequence[float],
+) -> float:
+    """Speculative GBR = sum(min(gain[t], deficit[t])) / sum(deficit[t]) over a drought period.
+
+    See GBR_NOT_PEER_REVIEWED_WARNING. Both sequences must be the same
+    length, one value per time step across the drought/heat period
+    being evaluated:
+
+    - deficit_without_adaptation[t]: D(t), the flow deficit (versus a
+      no-deficit baseline) that WOULD exist without any adaptation
+      measures at time t. Must be >= 0.
+    - flow_gain_from_adaptation[t]: the additional flow (Q_adaptive(t)
+      - Q_no_adaptation(t)) contributed by the adaptation portfolio
+      (reservoirs, MAR, wetlands, demand management, ...) at time t.
+      May be negative (adaptation measures can occasionally reduce
+      flow, e.g. reservoir filling).
+
+    Returns 1.0 for full compensation of the defined deficit -- capped
+    there by construction, since each term is min(gain, deficit) <=
+    deficit, so overshooting gain in one period cannot offset
+    undershooting in another (matching P102.md's own integral
+    definition). Can go negative if the adaptation portfolio nets out
+    to REDUCING flow during the deficit period (e.g. reservoir filling
+    at the wrong time) -- that is a real, meaningful failure mode, not
+    a bug, and is deliberately not clamped to zero.
+    """
+    if len(deficit_without_adaptation) != len(flow_gain_from_adaptation):
+        raise ValueError(
+            "deficit_without_adaptation and flow_gain_from_adaptation must "
+            f"have equal length, got {len(deficit_without_adaptation)} and "
+            f"{len(flow_gain_from_adaptation)}"
+        )
+    if len(deficit_without_adaptation) == 0:
+        raise ValueError("input sequences must be non-empty")
+    if any(d < 0 for d in deficit_without_adaptation):
+        raise ValueError("deficit_without_adaptation values must all be non-negative")
+
+    total_deficit = sum(deficit_without_adaptation)
+    if total_deficit == 0:
+        raise ValueError(
+            "sum(deficit_without_adaptation) is zero -- GBR is undefined "
+            "with no deficit to compensate"
+        )
+    compensated = sum(
+        min(gain, deficit)
+        for deficit, gain in zip(deficit_without_adaptation, flow_gain_from_adaptation, strict=True)
+    )
+    return compensated / total_deficit

distributed_buffer_resilience_utac/storage_portfolio.py

@@ -0,0 +1,93 @@
+"""Storage portfolio: technical reservoirs plus complementary response-time buffers.
+
+Core module -- Farinotti et al. (2016, 2019) for the quantified
+reservoir/storage figures. The response-time categorization is a
+qualitative, widely-used framing in mountain hydrology (not itself tied
+to one paper) illustrating why P102.md argues for a PORTFOLIO of
+buffers rather than a single largest-volume one -- see
+STORAGE_PORTFOLIO_NOTE.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .constants import (
+    ALPINE_RESERVOIR_SUMMER_DEFICIT_CEILING_FRACTION,
+    FARINOTTI_2016_CITATION,
+    FARINOTTI_2016_SCOPE_NOTE,
+    FARINOTTI_2019_CITATION,
+    FARINOTTI_2019_NOTE,
+    GLOBAL_THEORETICAL_HYDROPOWER_POTENTIAL_TWH_PER_YR,
+    GLOBAL_THEORETICAL_STORAGE_POTENTIAL_KM3,
+    GLOBAL_THEORETICAL_STORAGE_POTENTIAL_KM3_UNCERTAINTY,
+    REALISTIC_HYDROPOWER_POTENTIAL_TWH_PER_YR,
+    REALISTIC_STORAGE_FRACTION_OF_THEORETICAL,
+    REALISTIC_STORAGE_POTENTIAL_KM3,
+)
+
+STORAGE_PORTFOLIO_NOTE = (
+    "A moor, a floodplain, an aquifer and a reservoir can all 'store "
+    "water', but their impulse responses differ fundamentally: snow "
+    "(seasonal), reservoirs (managed, fast release), soil moisture "
+    "(days-weeks), wetlands (weeks-months), groundwater (months-years). "
+    "Two systems with identical total storage volume can have very "
+    "different drought resilience because accessibility, retention "
+    "time, evaporation exposure, spatial position and release dynamics "
+    "differ. This is a widely-used qualitative framing in mountain "
+    "hydrology, not a single-paper citation -- see P99/P100 for the "
+    "component-specific quantified figures (sedimentation, MAR "
+    "retention time, floating-solar evaporation mitigation, etc.)."
+)
+
+
+def reservoir_summer_deficit_ceiling_fraction(
+    with_citation: bool = False,
+) -> float | tuple[float, str]:
+    """The Farinotti et al. (2016) reservoir-strategy ceiling on Alpine summer-deficit compensation.
+
+    A specific, regional, scenario-bound estimate (European Alps, to
+    2100) -- NOT a universal replacement constant. See
+    FARINOTTI_2016_SCOPE_NOTE.
+    """
+    if with_citation:
+        return ALPINE_RESERVOIR_SUMMER_DEFICIT_CEILING_FRACTION, FARINOTTI_2016_CITATION
+    return ALPINE_RESERVOIR_SUMMER_DEFICIT_CEILING_FRACTION
+
+
+@dataclass(frozen=True)
+class GlobalStoragePotential:
+    """Farinotti et al. (2019)'s global theoretical vs. realistic storage potential."""
+
+    theoretical_km3: float
+    theoretical_km3_uncertainty: float
+    theoretical_hydropower_twh_per_yr: float
+    realistic_fraction: float
+    realistic_km3: float
+    realistic_hydropower_twh_per_yr: float
+    citation: str
+
+
+GLOBAL_STORAGE_POTENTIAL = GlobalStoragePotential(
+    theoretical_km3=GLOBAL_THEORETICAL_STORAGE_POTENTIAL_KM3,
+    theoretical_km3_uncertainty=GLOBAL_THEORETICAL_STORAGE_POTENTIAL_KM3_UNCERTAINTY,
+    theoretical_hydropower_twh_per_yr=GLOBAL_THEORETICAL_HYDROPOWER_POTENTIAL_TWH_PER_YR,
+    realistic_fraction=REALISTIC_STORAGE_FRACTION_OF_THEORETICAL,
+    realistic_km3=REALISTIC_STORAGE_POTENTIAL_KM3,
+    realistic_hydropower_twh_per_yr=REALISTIC_HYDROPOWER_POTENTIAL_TWH_PER_YR,
+    citation=FARINOTTI_2019_CITATION,
+)
+
+
+def theoretical_vs_realistic_gap_fraction() -> float:
+    """Fraction of the theoretical global storage potential judged NOT realistically suitable.
+
+    1 - realistic_fraction, i.e. how much of Farinotti et al. (2019)'s
+    theoretical 875 km3 figure falls away after a first-pass technical/
+    ecological/economic suitability screen. See FARINOTTI_2019_NOTE.
+    """
+    return 1.0 - GLOBAL_STORAGE_POTENTIAL.realistic_fraction
+
+
+FARINOTTI_2016_NOTE = FARINOTTI_2016_SCOPE_NOTE
+FARINOTTI_2019_SCOPE_NOTE = FARINOTTI_2019_NOTE

distributed_buffer_resilience_utac/water_towers.py

@@ -0,0 +1,49 @@
+"""Mountain water towers: importance, vulnerability, and disproportionate drought buffering.
+
+Core module -- Immerzeel et al. (2020)'s Water Tower Index and
+Pritchard (2017)'s drought-buffer framing, the original source of this
+whole package series' central idea.
+"""
+
+from __future__ import annotations
+
+from .constants import (
+    IMMERZEEL_2020_CITATION,
+    IMMERZEEL_NOTE,
+    PRITCHARD_2017_CITATION,
+    PRITCHARD_NOTE,
+    WATER_TOWER_DEPENDENT_POPULATION_BILLIONS,
+)
+
+
+def water_tower_dependent_population_billions() -> float:
+    """Global population living in or immediately downstream of mountain water-tower regions."""
+    return WATER_TOWER_DEPENDENT_POPULATION_BILLIONS
+
+
+def is_disproportionate_drought_buffer(
+    mean_contribution_pct: float, drought_year_contribution_pct: float
+) -> bool:
+    """Whether glacier melt contributes disproportionately more during drought than on average.
+
+    Operationalizes Pritchard (2017)'s core finding: glacier melt's
+    share of river flow is often small in the long-term mean but much
+    larger specifically in low-flow/drought years. True whenever the
+    drought-year contribution exceeds the mean contribution.
+    """
+    if not 0.0 <= mean_contribution_pct <= 100.0:
+        raise ValueError(
+            f"mean_contribution_pct must be in [0, 100], got {mean_contribution_pct}"
+        )
+    if not 0.0 <= drought_year_contribution_pct <= 100.0:
+        raise ValueError(
+            "drought_year_contribution_pct must be in [0, 100], got "
+            f"{drought_year_contribution_pct}"
+        )
+    return drought_year_contribution_pct > mean_contribution_pct
+
+
+WATER_TOWER_CITATION = IMMERZEEL_2020_CITATION
+WATER_TOWER_VULNERABILITY_NOTE = IMMERZEEL_NOTE
+DROUGHT_BUFFER_CITATION = PRITCHARD_2017_CITATION
+DROUGHT_BUFFER_NOTE = PRITCHARD_NOTE

distributed_buffer_resilience_utac-1.0.0.dist-info/METADATA

@@ -0,0 +1,118 @@
+Metadata-Version: 2.5
+Name: distributed-buffer-resilience-utac
+Version: 1.0.0
+Summary: Distributed hydrological/ecosystem buffer resilience for deglacierizing catchments -- van Tiel et al. 2026's drought-buffer evidence, Farinotti et al. 2016/2019's storage-portfolio figures, Immerzeel/Pritchard water-tower science, Casallas et al. 2025 ecosystem-service trade-offs, plus a clearly-flagged speculative GBR score -- companion to glacier-buffer-utac (P99) and glacier-buffer-replacement-utac (P100), no UTAC/CREP bridge
+Project-URL: Homepage, https://github.com/GenesisAeon/distributed-buffer-resilience-utac
+Project-URL: Repository, https://github.com/GenesisAeon/distributed-buffer-resilience-utac
+Author: Römer, Johann
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# distributed-buffer-resilience-utac
+
+GenesisAeon Package 103 — distributed hydrological/ecosystem buffer
+resilience for deglacierizing catchments. Companion to
+[glacier-buffer-utac](https://github.com/GenesisAeon/glacier-buffer-utac)
+(P99, the loss) and
+[glacier-buffer-replacement-utac](https://github.com/GenesisAeon/glacier-buffer-replacement-utac)
+(P100, technical replacement). **Deliberately has no UTAC/CREP/AFET
+bridge** — see [DISCLAIMER.md](DISCLAIMER.md).
+
+## The core idea
+
+A single storage type can't replace a glacier. What actually buffers a
+deglacierizing catchment is a **portfolio** of reservoirs, groundwater,
+wetlands, snow, and demand management, each with a different response
+time — not one component sized to do the whole job.
+
+## Two explicit confidence tiers
+
+- **Core** (`drought_buffer`, `storage_portfolio`, `water_towers`,
+  `ecosystem_services`): real, peer-reviewed findings independently
+  re-verified 2026-08-14.
+- **Optional / speculative** (`gbr`): a ratio-style score this
+  ecosystem constructed from a source document's own proposed formula
+  — not a published metric. Always exposed with
+  `GBR_NOT_PEER_REVIEWED_WARNING`.
+
+## What's real here (core)
+
+- **van Tiel et al. (2026, *HESS*)** — the strongest empirical anchor
+  in the whole P99–P103 series: during the extreme 2022 Swiss drought,
+  glacier melt across 88 catchments still substantially buffered
+  precipitation/snowmelt deficits — yet absolute summer meltwater
+  volume was already lower than 2003 in roughly two-thirds of studied
+  catchments. The buffer works AND its capacity is eroding, at the
+  same time, already observed, not projected.
+- **Farinotti et al. (2016, *ERL*)** — the ~65% Alpine reservoir
+  summer-deficit ceiling, correctly scoped as a specific, regional,
+  scenario-bound estimate (not a universal constant — see
+  `FARINOTTI_2016_SCOPE_NOTE`).
+- **Farinotti et al. (2019, *Nature*)** — global theoretical
+  ice-free-basin storage potential (875±260 km³ across ~185,000
+  glaciers), with only ~40% (355 km³) judged realistically suitable
+  after a first-pass screen.
+- **Pritchard (2017, *Nature*)** and **Immerzeel et al. (2020,
+  *Nature*)** — glaciers as a disproportionate drought buffer, and the
+  Water Tower Index ranking mountain water systems by importance AND
+  vulnerability (1.9 billion people dependent globally).
+- **Velasquez Casallas et al. (2025, *Ecosystem Services*)** — a
+  systematic review finding postglacial ecosystem services can
+  increase, but heterogeneously, with real trade-offs — never assume a
+  Nature-based Solution is hydrologically positive purely from its
+  label. `nbs_effect_is_guaranteed_positive()` always returns `False`.
+
+## Quickstart
+
+```bash
+pip install distributed-buffer-resilience-utac
+```
+
+```python
+from distributed_buffer_resilience_utac import (
+    SWISS_2022_DROUGHT,
+    buffer_functions_while_eroding,
+    reservoir_summer_deficit_ceiling_fraction,
+    GLOBAL_STORAGE_POTENTIAL,
+    is_disproportionate_drought_buffer,
+    nbs_effect_is_guaranteed_positive,
+    GBR_NOT_PEER_REVIEWED_WARNING,
+    glacier_buffer_replacement_score,
+)
+
+print(SWISS_2022_DROUGHT.catchment_count)          # 88
+print(buffer_functions_while_eroding())             # True
+print(reservoir_summer_deficit_ceiling_fraction())  # 0.65
+print(GLOBAL_STORAGE_POTENTIAL.realistic_km3)       # 355.0
+print(is_disproportionate_drought_buffer(10.0, 40.0))  # True
+print(nbs_effect_is_guaranteed_positive())          # False
+
+print(GBR_NOT_PEER_REVIEWED_WARNING)
+score = glacier_buffer_replacement_score(
+    deficit_without_adaptation=[10.0, 10.0],
+    flow_gain_from_adaptation=[5.0, 0.0],
+)
+print(score)  # 0.25
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pre-commit install
+ruff check src tests
+mypy src
+pytest
+```
+
+## Citation
+
+See [CITATION.cff](CITATION.cff) and [.zenodo.json](.zenodo.json).

distributed_buffer_resilience_utac-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+distributed_buffer_resilience_utac/__init__.py,sha256=5DC8ykR23BFT916FpUHgpi3fKBBs_ipsJXueh8FoNvg,2900
+distributed_buffer_resilience_utac/constants.py,sha256=4qWppTDHrDixEUP2fGpBPzZtEBr7fX0K26J2rGDyBGg,8293
+distributed_buffer_resilience_utac/drought_buffer.py,sha256=44lFc40uN0_iMiYBlGIcIGz_P5k_0uUUBivkkSDq9Eo,1768
+distributed_buffer_resilience_utac/ecosystem_services.py,sha256=qPwk8LtBOtFTqPbWP-7vqhkI6d-m8ktW_28YAUH3r5s,1573
+distributed_buffer_resilience_utac/gbr.py,sha256=4ixxWKTiDcNCZOKQ7tU-2sDeLPsdZJxpqGQZNWERe6k,3537
+distributed_buffer_resilience_utac/storage_portfolio.py,sha256=XQiuhuC1aRcGQpOpikzyrj2r-ePxpIq2znLBLEQsYoU,3770
+distributed_buffer_resilience_utac/water_towers.py,sha256=rUPiX53ycAtTBZQdCWwzWZaVAK4zDVqvzTuSRROOvrk,1816
+distributed_buffer_resilience_utac-1.0.0.dist-info/METADATA,sha256=4z4lGmHqXpE4fJ5UJd1lTijRbZS4opMKRNQC_1hqHrs,4959
+distributed_buffer_resilience_utac-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+distributed_buffer_resilience_utac-1.0.0.dist-info/licenses/LICENSE,sha256=UfpTMBvn-IvJa49zv4c4kFAjuS4DhXcmMOuTruky0e8,1069
+distributed_buffer_resilience_utac-1.0.0.dist-info/RECORD,,

distributed_buffer_resilience_utac-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

distributed_buffer_resilience_utac-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JohannRömer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.