waterledger-models 1.2.0__tar.gz

waterledger_models-1.2.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+.pytest_cache/

waterledger_models-1.2.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Northline Hydrology
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

waterledger_models-1.2.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.5
+Name: waterledger-models
+Version: 1.2.0
+Summary: Water Ledger's models: weather-driven data center cooling water (towers, hybrid, closed loop, lake-source) with Monte Carlo uncertainty, staff water, and site runoff quality
+Project-URL: Homepage, https://waterledger.org
+Project-URL: Source, https://github.com/northlinehydrology/waterledger
+Project-URL: Issues, https://github.com/northlinehydrology/waterledger/issues
+Author-email: Northline Hydrology <info@northlinehydrology.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Hydrology
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.24
+Description-Content-Type: text/markdown
+
+# waterledger-models
+
+The models behind [Water Ledger](https://waterledger.org): the water large new users take, use up and send back.
+Light dependencies (numpy only), so other modeling frameworks can use them directly.
+
+- `waterledger_models.datacenter.cooling`: weather-driven cooling water, hour by hour over decades of weather, for cooling
+  towers, hybrid, and closed loop with or without evaporative assist; Monte Carlo over the published parameter ranges; staff water.
+- `waterledger_models.datacenter.lake`: lake-source (once-through) cooling.
+- `waterledger_models.runoff`: runoff, sediment, nutrients, road salt and fuel from a developed site.
+
+`MODEL_VERSION` is Water Ledger's model version (currently 1.2); the package version follows it.

waterledger_models-1.2.0/README.md

@@ -0,0 +1,11 @@
+# waterledger-models
+
+The models behind [Water Ledger](https://waterledger.org): the water large new users take, use up and send back.
+Light dependencies (numpy only), so other modeling frameworks can use them directly.
+
+- `waterledger_models.datacenter.cooling`: weather-driven cooling water, hour by hour over decades of weather, for cooling
+  towers, hybrid, and closed loop with or without evaporative assist; Monte Carlo over the published parameter ranges; staff water.
+- `waterledger_models.datacenter.lake`: lake-source (once-through) cooling.
+- `waterledger_models.runoff`: runoff, sediment, nutrients, road salt and fuel from a developed site.
+
+`MODEL_VERSION` is Water Ledger's model version (currently 1.2); the package version follows it.

waterledger_models-1.2.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "waterledger-models"
+version = "1.2.0"
+description = "Water Ledger's models: weather-driven data center cooling water (towers, hybrid, closed loop, lake-source) with Monte Carlo uncertainty, staff water, and site runoff quality"
+readme = "README.md"
+license = "BSD-3-Clause"
+authors = [{ name = "Northline Hydrology", email = "info@northlinehydrology.com" }]
+requires-python = ">=3.11"
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: Hydrology",
+]
+dependencies = ["numpy>=1.24"]
+
+[project.urls]
+Homepage = "https://waterledger.org"
+Source = "https://github.com/northlinehydrology/waterledger"
+Issues = "https://github.com/northlinehydrology/waterledger/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/waterledger_models"]

waterledger_models-1.2.0/src/waterledger_models/__init__.py

@@ -0,0 +1,13 @@
+"""Water Ledger models: the water large new users take, use up and send back, starting with data centers, and runoff quality.
+
+    datacenter.cooling   weather-driven cooling water by design, Monte Carlo over the published parameter ranges, staff water
+    datacenter.lake      lake-source (once-through) cooling
+    runoff               runoff, sediment, nutrients, salt and fuel from a developed site
+
+MODEL_VERSION is Water Ledger's model version; every published estimate names the version that produced it.
+"""
+from waterledger_models import datacenter, runoff
+
+__all__ = ["datacenter", "runoff", "MODEL_VERSION"]
+MODEL_VERSION = "1.2"
+__version__ = "1.2.0"

waterledger_models-1.2.0/src/waterledger_models/datacenter/__init__.py

@@ -0,0 +1,4 @@
+"""Data centers: cooling water (towers, hybrid, closed loop with or without evaporative assist) and lake-source cooling."""
+from waterledger_models.datacenter import cooling, lake
+
+__all__ = ["cooling", "lake"]

waterledger_models-1.2.0/src/waterledger_models/datacenter/cooling.py

@@ -0,0 +1,213 @@
+"""Cooling water model v2 for Water Ledger: weather-driven, literature-aligned, with uncertainty.
+
+Hour by hour over 30 years of weather:
+  heat rejected (BTU) = IT energy × heat factor, where the heat factor is seasonal: lower when a
+      waterside economizer carries the load (cool wet-bulb), higher when chillers run (compressor heat
+      can add up to ~20% to tower load; DOE FEMP).
+  evaporation = heat × evaporative ratio ÷ latent heat, with the evaporative ratio from Rutberg et al. 2011
+      (the dry-bulb relation USGS SIR 2013-5188 uses for cooling towers).
+  drift = a small fraction of circulating flow (EPA WaterSense at Work §6.3: 0.05–0.2%, <0.005% with
+      modern eliminators); circulating flow from heat ÷ (500 × range °F).
+  blowdown = evaporation ÷ (cycles of concentration − 1)  (DOE FEMP BMP #10 water balance).
+Designs differ in when they evaporate:
+  dry       air-cooled / dry closed loop, designed to use no water for cooling: loop top-ups only, plus the staff water every design has
+  assist    closed loop with evaporative assist only on the hottest hours (dry-bulb setpoint; Microsoft
+            publishes 85 °F / 29.4 °C for its direct-air designs)
+  hybrid    dry coolers most of the year, evaporative in warm weather (ramp between two dry-bulb setpoints)
+  towers    open cooling towers, evaporative all year (upper bound for typical practice)
+Outputs per run: withdrawn (makeup), consumed (evaporation + drift + loop top-up), returned to sewer (blowdown).
+Monte Carlo over parameter ranges gives percentiles, per 100 MW of IT capacity.
+
+Staff water (restrooms, kitchens, cleaning) is not per kWh: it follows the people on site, which grow slowly with size, so it
+is a separate term, staff_runs() and staff_q(), added to the per-100 MW results at the campus's size (model 1.2). No humidification
+is counted: the designs modeled cool with liquid loops, chillers or towers and recirculate indoor air, so outside air comes in only
+for ventilation [estimate]; a direct outside-air design would need some in Michigan's dry winters and is not modeled.
+
+Parameter ranges and their sources are in RANGES and documented on the Water Ledger methods page
+(docs/research/water-ledger-methods-alignment.md).
+"""
+import numpy as np
+
+KWH_BTU = 3412.14
+HFG = 1050.0          # latent heat near tower temperatures, BTU/lb
+LB_GAL = 8.34
+DESIGNS = ["dry", "assist", "hybrid", "towers"]
+LABELS = {
+    "dry": "Closed loop (designed to use no water for cooling)",
+    "assist": "Closed loop with evaporative assist on the hottest days",
+    "hybrid": "Hybrid: dry most of the year, evaporative in warm weather",
+    "towers": "Cooling towers (evaporative all year)",
+}
+
+# (low, high) uniform ranges sampled in the Monte Carlo; central values are the midpoints.
+RANGES = {
+    "utilization": (0.60, 0.90),       # average IT load ÷ IT capacity [estimate]
+    "hf_econ": (1.03, 1.08),           # heat factor with economizer cooling (pumps, fans, losses) [estimate]
+    "hf_chiller": (1.15, 1.25),        # heat factor with chillers running; compressor heat up to ~20% (DOE FEMP)
+    "wb_econ": (8.0, 12.0),            # wet-bulb (°C) below which the economizer carries the load [estimate]
+    "wb_chiller": (16.0, 20.0),        # wet-bulb (°C) above which chillers carry the load [estimate]
+    "er_adj": (-0.05, 0.05),           # uncertainty on the Rutberg evaporative ratio (USGS ±5–15% at baseload)
+    "coc": (3.0, 7.0),                 # cycles of concentration (DOE FEMP: 2–4 typical, 6+ possible)
+    "range_f": (8.0, 15.0),            # tower range, °F (USGS SIR 2013-5188 tower suite: 10–25)
+    "drift": (0.00005, 0.0005),        # drift fraction of circulating flow (EPA: <0.005% modern to 0.05%)
+    "fill_gal_per_mw": (2000.0, 6000.0),  # closed loop volume, gal per MW of IT capacity [estimate; Lowell reported a 1.2 million gallon fill]
+    "assist_on": (27.5, 31.0),         # dry-bulb °C where assist starts (Microsoft 85 °F = 29.4 °C)
+    "assist_share": (0.10, 0.30),      # assist water as a share of the full evaporative rate [estimate]
+    "hybrid_on": (21.0, 27.0),         # dry-bulb °C where hybrid starts evaporating [estimate; cold-climate variant]
+    "hybrid_full": (30.0, 33.0),       # dry-bulb °C where hybrid is fully evaporative [estimate]
+}
+# Share of the loop volume lost to small leaks and topped up each year (NIH 2023: closed loops typically lose under 5% a year), all of
+# it counted as lost. Sampled on its own random stream (where model 1.1 drew its base-use share), so the other draws are unchanged.
+TOPUP = (0.01, 0.05)
+
+# Staff water [estimates]. People on site on a typical day (employees, security, contractors) = a fixed core plus a little per MW of
+# IT capacity: Michigan's sales tax exemption needs at least 30 new jobs, and hyperscale campuses employ tens to a few hundred people.
+# Gallons per person per day covers restrooms, kitchens and cleaning (office buildings use about 10 to 20; more with a cafeteria).
+# About 10% of it is used up and the rest goes down the drain (USGS Great Lakes consumptive-use coefficients for commercial use).
+STAFF = {"core": (20.0, 60.0), "per_mw": (0.1, 0.5), "gpcd": (15.0, 30.0), "used": (0.05, 0.15)}
+
+
+def wet_bulb(t_c, rh):
+    """Stull (2011) wet-bulb approximation, °C, valid for RH 5–99% and typical temperatures."""
+    rh = np.clip(rh, 5, 99)
+    return (t_c * np.arctan(0.151977 * np.sqrt(rh + 8.313659)) + np.arctan(t_c + rh) - np.arctan(rh - 1.676331)
+            + 0.00391838 * rh ** 1.5 * np.arctan(0.023101 * rh) - 4.686035)
+
+
+def evaporative_ratio(t_c, adj=0.0):
+    """Rutberg et al. 2011 dry-bulb relation (as used in USGS SIR 2013-5188): share of heat rejected by evaporation."""
+    er = 1 - (-0.000279 * t_c ** 3 + 0.00109 * t_c ** 2 - 0.345 * t_c + 26.7) / 100
+    return np.clip(er + adj, 0.55, 1.0)
+
+
+def _ramp(x, lo, hi):
+    return np.clip((x - lo) / (hi - lo), 0.0, 1.0)
+
+
+def hourly(tdb, twb, design, p):
+    """Gallons per IT kWh, by hour: (withdrawn, consumed, returned)."""
+    hf = p["hf_econ"] + (p["hf_chiller"] - p["hf_econ"]) * _ramp(twb, p["wb_econ"], p["wb_chiller"])
+    btu = KWH_BTU * hf
+    evap_full = btu * evaporative_ratio(tdb, p["er_adj"]) / HFG / LB_GAL
+    circ = btu / (LB_GAL * p["range_f"])                    # gal circulated per kWh (BTU / (8.34 × range))
+    if design == "towers":
+        w = np.ones_like(tdb)
+    elif design == "hybrid":
+        w = _ramp(tdb, p["hybrid_on"], p["hybrid_full"])
+    elif design == "assist":
+        w = _ramp(tdb, p["assist_on"], p["assist_on"] + 4.0) * p["assist_share"]
+    else:
+        w = np.zeros_like(tdb)
+    evap = evap_full * w
+    drift = circ * p["drift"] * (w > 0)
+    blow = evap / (p["coc"] - 1.0)
+    topup = np.full_like(tdb, p["fill_gal_per_mw"] * p["topup"] / 365.0 / (24 * 1000 * p["utilization"]))   # gal/day per MW, as gal per IT kWh
+    withdrawn = evap + drift + blow + topup
+    consumed = evap + drift + topup
+    returned = blow
+    return withdrawn, consumed, returned
+
+
+def sample(rng, n):
+    runs = [{k: rng.uniform(*v) for k, v in RANGES.items()} for _ in range(n)]
+    extra = np.random.default_rng(11)
+    for r in runs:
+        r["topup"] = extra.uniform(*TOPUP)
+    return runs
+
+
+def central():
+    return {**{k: (a + b) / 2 for k, (a, b) in RANGES.items()}, "topup": sum(TOPUP) / 2}
+
+
+def staff_runs(n=200, seed=13):
+    """Staff water parameters per run, [core people, people per MW, gal per person a day, share used up], on their own stream."""
+    rng = np.random.default_rng(seed)
+    return [[float(rng.uniform(*STAFF[k])) for k in ("core", "per_mw", "gpcd", "used")] for _ in range(n)]
+
+
+def staff_q(runs, mw):
+    """Staff water at `mw` MW of IT capacity, MGD: {"withdrawn"|"consumed"|"returned": {"p10","p50","p90"}}. Same as WQ.staff on the page."""
+    g = np.array([(c + k * mw) * gpcd / 1e6 for c, k, gpcd, u in runs])
+    u = np.array([r[3] for r in runs])
+    q = lambda v: {"p10": float(np.quantile(v, 0.1)), "p50": float(np.quantile(v, 0.5)), "p90": float(np.quantile(v, 0.9))}
+    return {"withdrawn": q(g), "consumed": q(g * u), "returned": q(g * (1 - u))}
+
+
+def daily_stats(day_index, ndays, years, gal_per_kwh_hour, kw, months=None):
+    """From hourly gal/kWh and IT kW, compute daily MGD and summary statistics: average day, 1-in-10-year peak day (90th percentile
+    of annual maxima), record day, average year, and with `months` (each day's YYYY-MM) the highest month's average day and the
+    highest calendar year."""
+    daily = np.bincount(day_index, weights=gal_per_kwh_hour * kw, minlength=ndays) / 1e6
+    ann_max = np.array([daily[years == y].max() for y in np.unique(years)])
+    out = {"avg": float(daily.mean()), "peak_1in10": float(np.quantile(ann_max, 0.9)), "record": float(daily.max()),
+           "annual_mg": float(daily.mean() * 365.25)}
+    if months is not None:
+        out["max_month"] = float(max(daily[months == m].mean() for m in np.unique(months)))
+        out["worst_year_mg"] = float(max(daily[years == y].sum() for y in np.unique(years)))
+    return out
+
+
+def summarize(days, mgd):
+    """Statistics of one daily series (MGD by ISO date), for figures and single-run reports: average day, highest month, 1-in-10-year
+    peak day, record day and its date, average and highest year."""
+    days, v = np.array(days), np.array(mgd)
+    years, months = np.array([d[:4] for d in days]), np.array([d[:7] for d in days])
+    ann = [v[years == y] for y in np.unique(years)]
+    return {"avg": float(v.mean()), "max_month": float(max(v[months == m].mean() for m in np.unique(months))),
+            "peak_1in10": float(np.quantile([a.max() for a in ann], 0.9)), "record": float(v.max()), "record_day": str(days[v.argmax()]),
+            "annual_mg": float(v.mean() * 365.25), "worst_year_mg": float(max(a.sum() for a in ann))}
+
+
+def daily(times, temps, rhs, design, mw, p=None):
+    """One run's daily series at `mw` MW of IT capacity (central parameters by default), staff water at its central values included:
+    (days, withdrawn MGD, returned MGD). For seasonal figures and record days; the pages and reviews use the Monte Carlo percentiles."""
+    p = p or central()
+    tdb, rh = np.array(temps, dtype=float), np.array(rhs, dtype=float)
+    w, c, r = hourly(tdb, wet_bulb(tdb, rh), design, p)
+    days = np.array([t[:10] for t in times])
+    uniq, idx = np.unique(days, return_inverse=True)
+    kw = mw * 1000 * p["utilization"]
+    core, per_mw, gpcd, used = (sum(STAFF[k]) / 2 for k in ("core", "per_mw", "gpcd", "used"))
+    g = (core + per_mw * mw) * gpcd / 1e6
+    wd = np.bincount(idx, weights=w * kw, minlength=len(uniq)) / 1e6 + g
+    rd = np.bincount(idx, weights=r * kw, minlength=len(uniq)) / 1e6 + g * (1 - used)
+    return [str(d) for d in uniq], wd.tolist(), rd.tolist()
+
+
+def run_location(times, temps, rhs, n=200, seed=7, mw=100.0):
+    """Monte Carlo for every design at one location, per `mw` MW of IT capacity.
+
+    Returns {design: {stat: {"p10","p50","p90"}}} for withdrawn/consumed/returned average, peak and annual,
+    plus the central-parameter run. Peak = 1-in-10-year peak day (90th percentile of annual maxima).
+    """
+    tdb = np.array(temps, dtype=float)
+    rh = np.array(rhs, dtype=float)
+    twb = wet_bulb(tdb, rh)
+    days = np.array([t[:10] for t in times])
+    uniq, day_index = np.unique(days, return_inverse=True)
+    years = np.array([d[:4] for d in uniq])
+    months = np.array([d[:7] for d in uniq])
+    rng = np.random.default_rng(seed)
+    runs = sample(rng, n)
+    out = {}
+    for design in DESIGNS:
+        acc = {}
+        for p in runs + [central()]:
+            kw = mw * 1000 * p["utilization"]
+            w, c, r = hourly(tdb, twb, design, p)
+            for name, arr in (("withdrawn", w), ("consumed", c), ("returned", r)):
+                s = daily_stats(day_index, len(uniq), years, arr, kw, months if name == "withdrawn" else None)
+                for stat, v in s.items():
+                    acc.setdefault(f"{name}_{stat}", []).append(v)
+            # water use effectiveness: liters consumed per IT kWh (annual average), for comparison with LBNL/operators
+            acc.setdefault("wue_l_per_kwh", []).append(float(np.average(c)) * 3.78541)          # consumed basis
+            acc.setdefault("wue_makeup_l_per_kwh", []).append(float(np.average(w)) * 3.78541)   # LBNL/Lei basis (evaporation + drift + blowdown)
+            acc.setdefault("utilization", []).append(p["utilization"])
+        res = {}
+        for k, vals in acc.items():
+            v = np.array(vals[:-1])
+            res[k] = {"p10": float(np.quantile(v, 0.1)), "p50": float(np.quantile(v, 0.5)), "p90": float(np.quantile(v, 0.9)),
+                      "central": float(vals[-1])}
+        out[design] = res
+    return out

waterledger_models-1.2.0/src/waterledger_models/datacenter/lake.py

@@ -0,0 +1,63 @@
+"""Lake-source (once-through) cooling: water taken from a Great Lake, run through heat exchangers once, and returned warmer.
+
+Withdrawal follows from the heat load and the temperature rise: flow = heat / (density x specific heat x rise).
+Nearly all of it is returned. The returned heat drives extra ("forced") evaporation from the lake surface, estimated with
+the heat-balance method used by USGS for once-through power plants (Diehl et al. 2013, after Harbeck 1964 and Ward 1980):
+the share of added heat that leaves as evaporation is dE / (dE + dC + dR), where evaporation and conduction share the same
+wind function and radiation does not. Natural surface temperatures are NOAA GLERL daily long-term averages for each lake.
+"""
+
+import numpy as np
+
+from waterledger_models.datacenter import cooling as cw
+
+RHO, CP, LV = 1000.0, 4186.0, 2.45e6  # kg/m3, J/(kg K), J/kg
+GAL_M3 = 264.172
+P_MB = 1013.0
+BOWEN = P_MB * 0.24 / (0.622 * 585.0)  # psychrometric constant in mb per deg C (cp of air 0.24 cal/g/K, L 585 cal/g)
+SIGMA = 1.17e-7 / 86400.0  # cal/(cm2 s K4)
+EMIS = 0.97
+
+# Ranges: utilization and heat factor reuse the cooling-water model; rise and wind are estimates (see methods page).
+RANGES = {
+    "utilization": cw.RANGES["utilization"],
+    "heat_factor": (cw.RANGES["hf_econ"][0], cw.RANGES["hf_chiller"][1]),
+    "rise_c": (6.0, 10.0),
+    "wind_mph": (5.0, 15.0),
+}
+
+
+def _es(t):
+    """Saturation vapor pressure over water, mb (Magnus)."""
+    return 6.112 * np.exp(17.62 * t / (243.12 + t))
+
+
+def evaporation_ratio(t, wind_mph):
+    """Share of added heat lost by evaporation at natural water temperature t (deg C), linearized heat balance (Ward 1980; USGS 2013 eq. 12-20)."""
+    f = 7.0e-8 * wind_mph  # Ward wind function, cal/(cm2 s mb)
+    de = (_es(t + 0.5) - _es(t - 0.5))  # mb per deg C
+    d_e = 585.0 * f * de
+    d_c = 585.0 * f * BOWEN
+    d_r = 4 * EMIS * SIGMA * (t + 273.15) ** 3
+    return d_e / (d_e + d_c + d_r)
+
+
+def run_lake(water_temps, n=200, seed=11, mw=100.0):
+    """Monte Carlo over the parameter ranges for one lake. water_temps: 366 daily long-term average surface temperatures (deg C).
+    Returns MGD per `mw` of IT capacity: withdrawn and returned (steady), forced evaporation average and its highest month."""
+    rng = np.random.default_rng(seed)
+    t = np.asarray(water_temps, dtype=float)
+    out = {"withdrawn": [], "evap_avg": [], "evap_peak_month": [], "er_avg": []}
+    for _ in range(n):
+        p = {k: rng.uniform(*v) for k, v in RANGES.items()}
+        heat_w = mw * 1e6 * p["utilization"] * p["heat_factor"]
+        m3s = heat_w / (RHO * CP * p["rise_c"])
+        out["withdrawn"].append(m3s * 86400 * GAL_M3 / 1e6)
+        er = evaporation_ratio(t, p["wind_mph"])
+        evap = er * heat_w / LV / RHO * 86400 * GAL_M3 / 1e6  # MGD by day of year
+        month = np.convolve(evap, np.ones(30) / 30, mode="valid")
+        out["evap_avg"].append(float(evap.mean()))
+        out["evap_peak_month"].append(float(month.max()))
+        out["er_avg"].append(float(er.mean()))
+    stat = lambda a: {"p10": float(np.percentile(a, 10)), "p50": float(np.percentile(a, 50)), "p90": float(np.percentile(a, 90))}
+    return {k: stat(v) for k, v in out.items()}

waterledger_models-1.2.0/src/waterledger_models/runoff.py

@@ -0,0 +1,134 @@
+"""Runoff water quality before and after a campus is built: annual runoff and pollutant loads, the construction years,
+road salt, generator fuel, runoff heat and what cooling-water blowdown carries to a sewer plant.
+
+Screening level, for a review or a public estimate, not a calibrated model:
+  runoff   EPA Simple Method, split by surface: R = P x 0.9 x Rv with Rv 0.95 on roofs and paving and 0.05 on turf or fields
+           (Rv = 0.05 + 0.9 x impervious share, Schueler 1987)
+  loads    L (lb/yr) = 0.226 x R (in) x C (mg/L) x A (ac), with event mean concentrations C by surface
+  controls Michigan's post-construction standard (treat the first inch or 90% of storms, 80% TSS removal; EGLE MS4 permits,
+           Kent County Drain Commissioner rules), applied to the captured share of runoff with wet-pond removal rates;
+           infiltration as the stronger option
+  farmland sediment comes from field erosion, not runoff concentrations: delivered soil loss [A] 0.25-1.0 t/ac/yr (U.S. cropland
+           sheet-and-rill erosion averages 2.67 t/ac/yr, USDA NRI 2017, and only part of it leaves the field), carrying phosphorus
+           at the soil's content [A]; tile-drain nitrate is not counted, so farmland nitrogen here is low
+PARAMS is the single source of every value; Water Ledger reads it from waters.json and the Water Review reads it here.
+"""
+
+LB = 0.226          # lb per (ac x in x mg/L)
+GAL_PER_AC_IN = 27154.0
+PJ = 0.9            # share of rain events that produce runoff (Simple Method)
+
+# Event mean concentrations, mg/L: [lo, mid, hi]. Mid is the Michigan source where one exists.
+PARAMS = {
+    "rv": {"imp": 0.95, "perv": 0.05, "sources": ["simple_method"]},
+    "emc": {
+        # Marquette, Michigan source areas (USGS WRIR 97-4242, Table 4, geometric means); TN = TKN + NO2+NO3
+        "roof": {"tss": [20, 24, 24], "tp": [0.03, 0.09, 0.09], "tn": [1.5, 2.3, 2.3], "sources": ["usgs_marquette", "mpca_emc"]},
+        "paved": {"tss": [75, 138, 201], "tp": [0.2, 0.21, 0.25], "tn": [1.5, 1.8, 2.5], "sources": ["usgs_marquette", "mpca_emc", "nsqd", "stepl"]},
+        "turf": {"tss": [11, 21, 70], "tp": [0.15, 0.19, 0.19], "tn": [1.5, 1.5, 1.5], "sources": ["mpca_emc", "stepl"]},
+        # Row crops: MPCA recommends no TSS EMC (range 50-160); TP 0.3 (STEPL) to 0.53 (MPCA review median); TN 1.9 (STEPL)
+        "farm": {"tss": [50, 100, 160], "tp": [0.3, 0.3, 0.53], "tn": [1.9, 1.9, 1.9], "sources": ["mpca_emc", "stepl"], "assumed": True},
+        "woods": {"tss": [26, 72, 140], "tp": [0.03, 0.09, 0.45], "tn": [0.2, 0.2, 0.2], "sources": ["mpca_emc", "stepl"]},
+        "built": {"tss": [75, 75, 201], "tp": [0.2, 0.2, 0.25], "tn": [2.0, 2.0, 2.5], "sources": ["mpca_emc", "stepl", "nsqd"]},
+    },
+    "before_imp": {"farm": 0.02, "woods": 0.01, "built": 0.60},     # [A] impervious share of the land as it is now
+    # Farmland field erosion reaching the field edge (t/ac/yr) and phosphorus on that soil (share by weight) [A]
+    "farm_soil": {"t_per_ac_yr": [0.25, 0.5, 1.0], "p_share": [0.0003, 0.0004, 0.0006], "sources": ["nri2017"]},
+    "after": {"imp": 0.50, "imp_range": [0.40, 0.60], "roof_share": 0.40},   # [A] roofs and paving; roofs as a share of that
+    # Michigan post-construction standard and removal by practice (share removed). Captured share of annual runoff [A].
+    "controls": {
+        "captured": [0.75, 0.85, 0.95],
+        "pond": {"tss": 0.80, "tp": 0.51, "tn": 0.26, "sources": ["egle_ms4", "kcdc_rules", "bmpdb2020"]},
+        "infiltration": {"tss": 0.95, "tp": 0.70, "tn": 0.51, "volume": 0.5, "sources": ["semcog_lid", "kcdc_rules"]},
+        "standard": "Treat the first inch of runoff or 90% of runoff-producing storms with at least 80% TSS removal (or 80 mg/L), and hold peak rate and volume to pre-development for storms up to the 2-year, 24-hour event",
+    },
+    # Construction: soil moved off bare ground per acre per year; EPA: construction sites shed sediment 10-20x agricultural land
+    "construction": {"t_per_ac_yr": [30, 100, 200], "ratio_to_farm": [10, 20], "years": [1, 2, 3], "sources": ["epa_fact26", "epa_mm8"],
+                     "permits": "Part 91 soil erosion permit for 1 acre or more, or within 500 ft of a lake or stream; construction storm water permit-by-rule (R 323.2190) with a Notice of Coverage above 5 acres and weekly inspection by a certified operator"},
+    # Road salt on parking and drives: lb per 1,000 sq ft per event (MPCA targets; practice is often higher) x events per winter [A]
+    "salt": {"lb_per_ksf": [0.75, 1.5, 3.0], "events": [20, 40, 60], "paved_share": 0.60, "chloride_share": 0.607,
+             "chronic_mg_l": 150, "sources": ["mpca_salt", "egle_rule57"]},
+    # Backup generators: diesel at full load (Cat 3516C, 133.6 gal/h at 2,000 ekW) x hours stored on site [A]
+    "fuel": {"gal_per_mwh": 66.8, "hours": [12, 48, 72], "gen_mw_per_it_mw": 1.2, "unit_mw": 2.5, "spcc_gal": 1320,
+             "sources": ["cat3516c", "uptime2014", "amazon_mo2026", "wyofile2025", "cfr112"]},
+    # Runoff heat: summer runoff from pavement averages about 25 C (77 F) vs a 68 F (20 C) coldwater limit in June-August
+    "heat": {"paved_c": 24.9, "forest_c": 21.5, "cold_limit_f": 68, "cold_rise_f": 2, "sources": ["herb2007", "rule75", "stefan2010"]},
+    # Cooling-tower blowdown: dissolved solids = makeup x cycles; phosphate inhibitors up to ~6.5 mg/L as P; plant limit 1 mg/L
+    "blowdown": {"makeup_tds": {"lake": 170, "ground": 400}, "cycles": [3, 5, 7], "p_mg_l": [0, 3, 6.5], "plant_p_limit": 1.0,
+                 "sources": ["epa_wsaw", "jea2024", "rule60", "egle_dc_faq"]},
+}
+
+
+def _w(lst, i):
+    return lst[i] if isinstance(lst, list) else lst
+
+
+def runoff_in(rain_in, imp):
+    """Annual runoff depth (in) from the whole site."""
+    rv = PARAMS["rv"]
+    return rain_in * PJ * (rv["imp"] * imp + rv["perv"] * (1 - imp))
+
+
+def loads(acres, rain_in, before="farm", imp=None, roof_share=None):
+    """Annual runoff (gallons) and loads (TSS tons, TP lb, TN lb) now, after with no controls, after with Michigan's standard
+    (wet ponds) and after with infiltration. Each value is [lo, mid, hi]."""
+    P, E = PARAMS, PARAMS["emc"]
+    imp = P["after"]["imp"] if imp is None else imp
+    roof = P["after"]["roof_share"] if roof_share is None else roof_share
+    rv = P["rv"]
+    r_imp, r_perv = rain_in * PJ * rv["imp"], rain_in * PJ * rv["perv"]
+    i0 = P["before_imp"][before]
+    out = {"runoff_gal": {}, "tss_t": {}, "tp_lb": {}, "tn_lb": {}}
+    out["runoff_gal"]["now"] = [acres * (i0 * r_imp + (1 - i0) * r_perv) * GAL_PER_AC_IN] * 3
+    out["runoff_gal"]["after"] = [acres * (imp * r_imp + (1 - imp) * r_perv) * GAL_PER_AC_IN] * 3
+    for k, unit in (("tss", "tss_t"), ("tp", "tp_lb"), ("tn", "tn_lb")):
+        div = 2000 if k == "tss" else 1
+        now_perv = E[before][k] if before != "built" else E["turf"][k]
+        now_imp = E["built"][k]
+        now = [LB * acres * (i0 * r_imp * _w(now_imp, i) + (1 - i0) * r_perv * _w(now_perv, i)) / div for i in range(3)]
+        if before == "farm":
+            fs = P["farm_soil"]
+            if k == "tss":
+                now = [acres * (1 - i0) * fs["t_per_ac_yr"][i] for i in range(3)]
+            elif k == "tp":
+                now = [now[i] + acres * (1 - i0) * fs["t_per_ac_yr"][i] * 2000 * fs["p_share"][i] for i in range(3)]
+        after = [LB * acres * (imp * r_imp * (roof * E["roof"][k][i] + (1 - roof) * E["paved"][k][i]) + (1 - imp) * r_perv * E["turf"][k][i]) / div for i in range(3)]
+        cap = P["controls"]["captured"]
+        # lo pairs with the most capture, hi with the least
+        pond = [after[i] * (1 - cap[2 - i] * P["controls"]["pond"][k]) for i in range(3)]
+        inf = P["controls"]["infiltration"]
+        infil = [after[i] * (1 - cap[2 - i] * (1 - (1 - inf["volume"]) * (1 - inf[k]))) for i in range(3)]
+        out[unit] = {"now": now, "after": after, "pond": pond, "infiltration": infil}
+    vol_inf = P["controls"]["infiltration"]["volume"]
+    out["runoff_gal"]["pond"] = out["runoff_gal"]["after"]
+    out["runoff_gal"]["infiltration"] = [out["runoff_gal"]["after"][0] * (1 - P["controls"]["captured"][2 - i] * vol_inf) for i in range(3)]
+    return out
+
+
+def construction(acres_disturbed, before="farm"):
+    """Soil that can move off bare ground in a year of construction (tons, before controls catch part of it)."""
+    c = PARAMS["construction"]["t_per_ac_yr"]
+    return [acres_disturbed * x for x in c]
+
+
+def salt(acres, imp=None):
+    """Road salt a winter on parking and drives (tons of salt) and the chloride in it."""
+    S, A = PARAMS["salt"], PARAMS["after"]
+    imp = A["imp"] if imp is None else imp
+    paved_ksf = acres * imp * (1 - A["roof_share"]) * 43.56
+    t = [paved_ksf * S["lb_per_ksf"][i] * S["events"][i] / 2000 for i in range(3)]
+    return {"salt_t": t, "chloride_t": [x * S["chloride_share"] for x in t], "paved_ac": acres * imp * (1 - A["roof_share"])}
+
+
+def fuel(it_mw):
+    """Backup generators and diesel stored on site."""
+    F = PARAMS["fuel"]
+    gen_mw = it_mw * F["gen_mw_per_it_mw"]
+    return {"gen_mw": gen_mw, "units": round(gen_mw / F["unit_mw"]), "gal": [gen_mw * F["gal_per_mwh"] * h for h in F["hours"]]}
+
+
+def blowdown(flow_mgd, source="lake"):
+    """Dissolved solids (mg/L, lb/day) and phosphorus (lb/day) in cooling-water blowdown sent to a plant."""
+    B = PARAMS["blowdown"]
+    tds = [B["makeup_tds"][source] * c for c in B["cycles"]]
+    return {"tds_mg_l": tds, "tds_lb_day": [t * flow_mgd * 8.34 for t in tds], "p_lb_day": [p * flow_mgd * 8.34 for p in B["p_mg_l"]]}