basinledger 0.1.0__py3-none-any.whl

basinledger/__init__.py

@@ -0,0 +1,7 @@
+"""Basin Ledger: a basin's water, quantity and quality, balanced day by day across coupled models.
+
+SWAT+ (through swatplus-bmi), MODFLOW 6 (through libmf6 and modflowapi) and water-user components (from
+waterledger-models) are stepped one day at a time by one Python driver, on NextGen geography. See docs/design.md.
+"""
+
+__version__ = "0.1.0"

basinledger/__main__.py

@@ -0,0 +1,66 @@
+"""The command line.
+
+    python -m basinledger run basin.toml [--run NAME] [--days N] [--baseline] [--out DIR]
+                                         [--save-at DAY --save DIR] [--restart DIR]
+    python -m basinledger status basin.toml
+
+``run`` steps the example's models through its period (or ``--days``), checking the ledger every day, and writes
+ledger.csv, series.csv and summary.json to the run's outputs folder. ``--baseline`` runs it without its water users.
+``--save-at`` stops after that day and saves the state to ``--save``; ``--restart`` carries on from a saved state.
+``status`` prints whether the example is calibrated or a screening run.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import config as C
+from .driver import Basin
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="basinledger", description="Basin Ledger: coupled basin water accounting.")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    r = sub.add_parser("run", help="run an example")
+    r.add_argument("config")
+    r.add_argument("--run", default=None, help="run name (default: base, or baseline with --baseline)")
+    r.add_argument("--days", type=int, default=None)
+    r.add_argument("--baseline", action="store_true", help="without the example's water users")
+    r.add_argument("--out", default=None, help="outputs folder (default: <run folder>/outputs)")
+    r.add_argument("--save-at", type=int, default=None, help="stop after this many days and save the state")
+    r.add_argument("--save", default=None, help="folder for the saved state")
+    r.add_argument("--restart", default=None, help="carry on from a saved state")
+    s = sub.add_parser("status", help="calibrated or screening run")
+    s.add_argument("config")
+    a = ap.parse_args(argv)
+
+    if a.cmd == "status":
+        cfg = C.load(a.config)
+        print(f"{cfg.name}: {cfg.calibration_status}")
+        return 0
+
+    if (a.save_at is None) != (a.save is None):
+        ap.error("--save-at and --save go together")
+    run = a.run or ("baseline" if a.baseline else "base")
+    b = Basin.from_config(a.config, run=run, users=not a.baseline, days=a.days, restart=a.restart)
+    try:
+        if a.save_at is not None:
+            b.run(a.save_at - b.day)
+            b.save(a.save)
+        else:
+            b.run()
+        out = b.write_outputs(a.out)
+    finally:
+        b.finalize()
+    summary = json.loads((out / "summary.json").read_text())
+    print(f"{summary['example']} ({summary['status']}): {summary['days']} days, ledger closed every day")
+    print(f"outputs: {out}")
+    if summary["status_note"]:
+        print("note: " + summary["status_note"])
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

basinledger/calibration.py

@@ -0,0 +1,227 @@
+"""Calibration: parameters, observations, the forward model, statistics, and the calibration record.
+
+Built:
+- the record and its status (no record, or a status other than "calibrated", means a screening run);
+- parameters and observations as tables (CSV);
+- simulated values at observations, from a run's series (channel flow, heads at named cells);
+- statistics: NSE, KGE, percent bias, a low-flow NSE (on log flows), mean error and RMSE;
+- the forward model: run an example and write simulated values at every observation, for PEST++ to read.
+
+Not built yet (docs/design.md, Calibration):
+- applying a parameter set to the models' input files: SWAT+ through ``calibration.cal``, MODFLOW 6 arrays by zone or
+  pilot point (flopy, pyEMU), users through their config. ``apply_parameters`` refuses anything it can't apply yet;
+- writing PEST++ IES control and template files (pyEMU);
+- fetching observations: USGS daily streamflow and groundwater levels (``dataretrieval``), matched to hydrofabric
+  flowpaths and nexuses and to MODFLOW 6 cells.
+
+Tables:
+
+    parameters.csv    name, model, target, value, lower, upper, transform
+                      model: swatplus | modflow6 | user; target: what it changes (a calibration.cal parameter and
+                      object, a MODFLOW 6 package array and zone, a user's config key); transform: none | log
+    observations.csv  name, kind, object, date, value, weight, source
+                      kind: flow (m3 s-1, object = channel or hydrofabric id) | head (m, object = a named head
+                      output); date ISO; source: e.g. "USGS 04119055 dv"
+"""
+
+from __future__ import annotations
+
+import csv
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+
+STATUSES = ("calibrated", "screening")
+SCREENING = "screening"
+
+
+def model_statuses(record: Path | None, models: list[str]) -> dict[str, str]:
+    """Each model's status from an example's record.
+
+    A record gives either one status for the example (top-level ``status``, ``[calibration]``, ``[validation]``)
+    or one per model (``[models.<name>]`` with the same keys), e.g. streamflow from NextGen calibrated and MODFLOW 6
+    a screening model. A model the record doesn't name is screening. A calibrated model needs its calibration and
+    validation statistics.
+    """
+    if record is None:
+        return {m: SCREENING for m in models}
+    with open(record, "rb") as f:
+        rec = tomllib.load(f)
+    per = rec.get("models")
+    out = {}
+    for m in models:
+        entry = per.get(m) if per is not None else rec
+        status = (entry or {}).get("status", SCREENING)
+        if status not in STATUSES:
+            raise ValueError(f"{record}: status must be one of {STATUSES}, not {status!r}")
+        if status == "calibrated":
+            missing = [k for k in ("calibration", "validation") if k not in entry]
+            if missing:
+                raise ValueError(f"{record}: a calibrated record needs its {' and '.join(missing)} statistics")
+        out[m] = status
+    return out
+
+
+def record_targets(record: Path | None) -> dict[str, str]:
+    """What each model in a record was calibrated to (its ``target``), e.g. streamflow at a gage."""
+    if record is None:
+        return {}
+    with open(record, "rb") as f:
+        rec = tomllib.load(f)
+    return {m: e["target"] for m, e in (rec.get("models") or {}).items() if "target" in e}
+
+
+def record_status(record: Path | None, models: list[str] | None = None) -> str:
+    """'calibrated' only if every model the example runs is calibrated; otherwise a screening run."""
+    st = model_statuses(record, models or ["all"])
+    return "calibrated" if all(v == "calibrated" for v in st.values()) else SCREENING
+
+
+@dataclass
+class Parameter:
+    name: str
+    model: str
+    target: str
+    value: float
+    lower: float
+    upper: float
+    transform: str = "none"
+
+    def __post_init__(self):
+        if self.model not in ("swatplus", "modflow6", "user"):
+            raise ValueError(f"parameter {self.name}: model must be swatplus, modflow6 or user")
+        if not self.lower <= self.value <= self.upper:
+            raise ValueError(f"parameter {self.name}: {self.value} outside [{self.lower}, {self.upper}]")
+
+
+@dataclass
+class Observation:
+    name: str
+    kind: str       # flow | head
+    object: str     # channel (or hydrofabric id) for flow; named head output for head
+    date: str
+    value: float
+    weight: float = 1.0
+    source: str = ""
+
+
+def read_parameters(path: Path) -> list[Parameter]:
+    with open(path, newline="") as f:
+        return [Parameter(r["name"], r["model"], r["target"], float(r["value"]), float(r["lower"]),
+                          float(r["upper"]), r.get("transform") or "none") for r in csv.DictReader(f)]
+
+
+def read_observations(path: Path) -> list[Observation]:
+    with open(path, newline="") as f:
+        obs = [Observation(r["name"], r["kind"], r["object"], r["date"], float(r["value"]),
+                           float(r.get("weight") or 1.0), r.get("source", "")) for r in csv.DictReader(f)]
+    for o in obs:
+        if o.kind not in ("flow", "head"):
+            raise ValueError(f"observation {o.name}: kind must be flow or head")
+    return obs
+
+
+def apply_parameters(model: str, folder: Path, params: list[Parameter]):
+    """Write a parameter set into a run's copy of one model's inputs, before it starts (the driver's ``prepare``
+    hook). Not built yet for any model."""
+    mine = [p for p in params if p.model == model]
+    if mine:
+        raise NotImplementedError(f"applying {model} parameters is planned; see docs/design.md, Calibration")
+
+
+def simulated(series: dict[str, list[float]], dates: list[str], observations: list[Observation]) -> np.ndarray:
+    """The run's value at each observation: channel flow (``flow:<object>``) or head (``head:<object>``) on its
+    date."""
+    index = {d: i for i, d in enumerate(dates)}
+    out = np.empty(len(observations))
+    for j, o in enumerate(observations):
+        key = f"{o.kind}:{o.object}"
+        if key not in series:
+            raise KeyError(f"observation {o.name}: the run has no {key!r} output (add it under [outputs])")
+        if o.date not in index:
+            raise KeyError(f"observation {o.name}: {o.date} is outside the run")
+        out[j] = series[key][index[o.date]]
+    return out
+
+
+def nse(sim, obs) -> float:
+    sim, obs = np.asarray(sim, float), np.asarray(obs, float)
+    return float(1 - np.sum((sim - obs) ** 2) / np.sum((obs - obs.mean()) ** 2))
+
+
+def log_nse(sim, obs, floor: float = 1e-6) -> float:
+    """NSE on log flows: weights low flows, where a large user shows."""
+    return nse(np.log(np.maximum(sim, floor)), np.log(np.maximum(obs, floor)))
+
+
+def kge(sim, obs) -> float:
+    """Kling-Gupta efficiency (Gupta et al. 2009)."""
+    sim, obs = np.asarray(sim, float), np.asarray(obs, float)
+    r = np.corrcoef(sim, obs)[0, 1]
+    return float(1 - np.sqrt((r - 1) ** 2 + (sim.std() / obs.std() - 1) ** 2 + (sim.mean() / obs.mean() - 1) ** 2))
+
+
+def pbias(sim, obs) -> float:
+    """Percent bias, positive when the model overestimates."""
+    sim, obs = np.asarray(sim, float), np.asarray(obs, float)
+    return float(100 * np.sum(sim - obs) / np.sum(obs))
+
+
+def mean_error(sim, obs) -> float:
+    return float(np.mean(np.asarray(sim, float) - np.asarray(obs, float)))
+
+
+def rmse(sim, obs) -> float:
+    return float(np.sqrt(np.mean((np.asarray(sim, float) - np.asarray(obs, float)) ** 2)))
+
+
+def statistics(observations: list[Observation], sim: np.ndarray) -> dict[str, dict[str, float]]:
+    """Statistics per site (kind and object): flow gets NSE, log NSE, KGE and percent bias; heads mean error, RMSE
+    and RMSE over the observed range."""
+    out = {}
+    for key in dict.fromkeys((o.kind, o.object) for o in observations):
+        idx = [i for i, o in enumerate(observations) if (o.kind, o.object) == key]
+        s = sim[idx]
+        o = np.array([observations[i].value for i in idx])
+        if key[0] == "flow":
+            out[f"flow:{key[1]}"] = {"n": len(idx), "nse": nse(s, o), "log_nse": log_nse(s, o), "kge": kge(s, o),
+                                     "pbias": pbias(s, o)}
+        else:
+            rng = float(o.max() - o.min())
+            out[f"head:{key[1]}"] = {"n": len(idx), "mean_error": mean_error(s, o), "rmse": rmse(s, o),
+                                     "rmse_over_range": rmse(s, o) / rng if rng > 0 else float("nan")}
+    return out
+
+
+def run_forward_model(config: str | Path, parameters: Path | None, observations: Path, out: Path,
+                      run: str = "calibration") -> Path:
+    """The forward model PEST++ calls: apply a parameter set, run the example, and write the simulated value at
+    every observation (name, simulated) to ``out``."""
+    from . import config as C
+    from .driver import Basin
+
+    cfg = C.load(config)
+    obs = read_observations(observations)
+    params = read_parameters(parameters) if parameters else []
+    b = Basin(cfg, run=run, prepare=lambda model, folder: apply_parameters(model, folder, params))
+    try:
+        b.run()
+        sim = simulated(b.series, b.dates(), obs)
+    finally:
+        b.finalize()
+    with open(out, "w", newline="") as f:
+        w = csv.writer(f)
+        w.writerow(["name", "simulated"])
+        for o, s in zip(obs, sim):
+            w.writerow([o.name, repr(float(s))])
+    return out
+
+
+def write_pest_files(*args, **kwargs):
+    raise NotImplementedError("PEST++ IES control and template files (pyEMU) are planned; see docs/design.md")
+
+
+def fetch_usgs(*args, **kwargs):
+    raise NotImplementedError("USGS streamflow and groundwater level downloads are planned; see docs/design.md")

basinledger/chain.py

@@ -0,0 +1,106 @@
+"""The utility chain: source -> distribution -> customers -> sewer -> wastewater plant -> outfall.
+
+The chain is accounting, not a model. Each day it takes the volumes of the users on the system, adds the system's
+existing customers, and places the water in the hydrologic models through routes:
+
+    produced    = delivered / (1 - losses)          withdrawn from the sources, by share
+    delivered   = existing demand + users' withdrawals
+    losses      = produced - delivered              distribution losses (non-revenue water)
+    sewer       = existing demand x sewered + users' returns + inflow and infiltration
+    outfall     = sewer                             the plant's discharge, to its route
+
+Config (one ``[[utilities]]`` table per system):
+
+    name = "city"
+    sources = [{route = "well:pw2", share = 0.6}, {route = "swat:place_of_use:intake", share = 0.4}]
+    losses = 0.10              # fraction of production
+    demand = 0.003             # m3 s-1, existing customers (a constant for now; later a daily series)
+    sewered = 0.8              # share of existing demand that reaches the sewer
+    infiltration = 0.0002      # m3 s-1 of inflow and infiltration into the sewer
+    outfall = "swat:point_source:wwtp"
+
+Ledger accounts, all in m3 per day, under ``utility:<name>:``. They pair as: produced = delivered + losses;
+produced = the sum of the source shares; sewer = outfall. Each route then carries its own pair of requested and
+delivered.
+
+Not yet: losses returned to the aquifer as recharge, inflow and infiltration taken from the aquifer, a daily demand
+series, and the plant's own consumption and loads.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .units import DAY
+
+
+@dataclass
+class Source:
+    route: str
+    share: float
+
+
+@dataclass
+class UtilityChain:
+    name: str
+    sources: list[Source]
+    outfall: str
+    losses: float = 0.0
+    demand: float = 0.0
+    sewered: float = 1.0
+    infiltration: float = 0.0
+    _withdrawals: float = field(default=0.0, repr=False)
+    _returns: float = field(default=0.0, repr=False)
+
+    def __post_init__(self):
+        total = sum(s.share for s in self.sources)
+        if not self.sources or abs(total - 1.0) > 1e-9:
+            raise ValueError(f"utility {self.name}: source shares sum to {total}, not 1")
+        if not 0 <= self.losses < 1 or not 0 <= self.sewered <= 1:
+            raise ValueError(f"utility {self.name}: losses must be in [0, 1) and sewered in [0, 1]")
+        for s in self.sources:
+            if s.route.startswith("utility:"):
+                raise ValueError(f"utility {self.name}: a source can't be another utility (not yet)")
+
+    @classmethod
+    def from_config(cls, c: dict) -> "UtilityChain":
+        return cls(name=c["name"], sources=[Source(s["route"], float(s["share"])) for s in c["sources"]],
+                   outfall=c["outfall"], losses=float(c.get("losses", 0.0)), demand=float(c.get("demand", 0.0)),
+                   sewered=float(c.get("sewered", 1.0)), infiltration=float(c.get("infiltration", 0.0)))
+
+    def add_user(self, withdrawal: float, returned: float):
+        """A user's day on this system: m3 withdrawn from the tap, m3 returned to the sewer."""
+        self._withdrawals += withdrawal
+        self._returns += returned
+
+    def close_day(self, ledger) -> dict[str, float]:
+        """The day's requests on each route (m3): sources positive withdrawals, the outfall a discharge."""
+        existing = self.demand * DAY
+        delivered = existing + self._withdrawals
+        produced = delivered / (1.0 - self.losses)
+        sewer = existing * self.sewered + self._returns + self.infiltration * DAY
+        k = f"utility:{self.name}:"
+        ledger.enter(k + "produced", produced)
+        ledger.enter(k + "delivered", delivered)
+        ledger.enter(k + "losses", produced - delivered)
+        ledger.enter(k + "existing_demand", existing)
+        ledger.enter(k + "users_withdrawal", self._withdrawals)
+        ledger.enter(k + "users_return", self._returns)
+        ledger.enter(k + "infiltration", self.infiltration * DAY)
+        ledger.enter(k + "consumed_by_existing", existing * (1 - self.sewered))
+        ledger.enter(k + "sewer", sewer)
+        requests = {}
+        for s in self.sources:
+            requests[s.route] = requests.get(s.route, 0.0) + produced * s.share
+            ledger.enter(k + f"source:{s.route}", produced * s.share)
+        requests[self.outfall] = requests.get(self.outfall, 0.0) + sewer
+        ledger.enter(k + "outfall", sewer)
+        self._withdrawals = self._returns = 0.0
+        return requests
+
+    def declare(self, ledger):
+        k = f"utility:{self.name}:"
+        ledger.pair(k + "produced", [k + "delivered", k + "losses"])
+        ledger.pair(k + "produced", [k + f"source:{s.route}" for s in self.sources])
+        ledger.pair(k + "delivered", [k + "existing_demand", k + "users_withdrawal"])
+        ledger.pair(k + "sewer", k + "outfall")

basinledger/config.py

@@ -0,0 +1,214 @@
+"""An example's configuration: one TOML file that wires real models for one basin and its water users.
+
+Paths are relative to the config file. ``{swatplus_refdata}`` stands for the example projects that ship with SWAT+
+(``refdata/`` in the source that ``swatplus-bmi build`` fetched), for the synthetic example.
+
+    name = "synthetic"
+    description = "..."
+
+    [run]
+    folder = "../../runs/synthetic"     # each run copies the models here
+    days = 0                            # 0: the SWAT+ project's whole period
+
+    [swatplus]                          # the surface model: SWAT+, stepped live through swatplus-bmi
+    project = "{swatplus_refdata}/Osu_1hru"
+    places_of_use = [{name = "intake", channel = "cha01"}]    # added to the run's copy, set daily
+    point_sources = [{name = "wwtp", channel = "cha01"}]
+
+    # or [nextgen]                      # the surface model: a finished NGIAB run, replayed (coupling/nextgen.py)
+    # run = "{nextgen_michigan}/runs/scenarios/baseline"
+
+    [modflow6]                          # optional: the groundwater model
+    builder = "model:build"             # model.py beside this file: build(workspace, days, start_date)
+    # workspace = "mf6"                 # or an existing simulation folder, copied into the run
+    model = "gwf"
+
+    [recharge]                          # SWAT+ aquifers -> MODFLOW 6 recharge (one-way)
+    package = "rch"
+    map = "all:aqu001"                  # every top-layer cell to one aquifer, or a CSV (see mapping.py)
+    area_rtol = 0.001                   # optional: mapped area must match SWAT+'s aquifer area
+
+    [[wells]]
+    name = "pw1"
+    package = "wel"
+    cell = [0, 20, 30]                  # layer, row, col (0-based)
+
+    [exchange]                          # optional: two-way stream-aquifer exchange (MODFLOW 6 RIV <-> SWAT+)
+    package = "riv"
+    map = "all:cha01"                   # every RIV entry to one channel, or a CSV: object, layer, row, col
+
+    [[utilities]]                       # optional: a water system (see chain.py)
+    name = "city"
+    sources = [{route = "well:pw1", share = 1.0}]
+    outfall = "swat:point_source:wwtp"
+
+    [[rules]]                           # optional: feedback rules (see rules.py)
+    name = "low-flow cut"
+    kind = "curtailment"
+    user = "plant"
+    channel = "cha01"
+    threshold = 0.001
+
+    [outputs]                           # optional: daily series written with the ledger
+    channels = ["cha01"]                # outflow, m3 s-1 (default: every channel)
+    heads = [{name = "pw1", cell = [0, 20, 28]}]
+
+    [calibration]                       # optional: the example's calibration record
+    record = "calibration/record.toml"  # without one, the example is a screening run
+
+    [[users]]
+    name = "plant"
+    component = "basinledger.testing:SyntheticUser"
+    config = "user.toml"
+    withdrawal = "well:pw1"             # source: a MODFLOW 6 well (later: a SWAT+ place of use, a utility)
+    return = "outfall:creek"            # sink: an outfall account (later: a SWAT+ point source, a sewer)
+    # variables = {withdrawal = "...", gain = "..."}   for components without the common names
+    # forcing = {source = "nextgen", catchment = "cat-652059"}   hourly weather inputs (forcing.py)
+
+Routes also include ``offsite:<name>``: water from or to somewhere outside the basin (a Great Lakes intake, a plant on
+another river), entered in the ledger only.
+
+``{nextgen_michigan}`` stands for a checkout of github.com/northlinehydrology/nextgen-michigan (``$NEXTGEN_MICHIGAN``,
+or ``~/repos/nextgen-michigan``).
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+def nextgen_michigan() -> Path:
+    return Path(os.environ.get("NEXTGEN_MICHIGAN", Path.home() / "repos" / "nextgen-michigan"))
+
+
+def swatplus_refdata() -> Path:
+    if os.environ.get("SWATPLUS_REFDATA"):
+        return Path(os.environ["SWATPLUS_REFDATA"])
+    from swatplus_bmi.build import DEFAULT_TAG, home
+    return home() / "build" / DEFAULT_TAG / "swatplus" / "refdata"
+
+
+@dataclass
+class UserConfig:
+    name: str
+    component: str
+    config: Path | None
+    withdrawal: str
+    returns: str
+    variables: dict = field(default_factory=dict)
+    constituents: dict | None = None
+    forcing: dict | None = None
+
+
+@dataclass
+class WellConfig:
+    name: str
+    package: str
+    cell: tuple[int, int, int]
+
+
+@dataclass
+class ExampleConfig:
+    path: Path
+    name: str
+    description: str
+    run_folder: Path
+    days: int
+    swat_project: Path | None
+    mf6_builder: str | None
+    mf6_workspace: Path | None
+    mf6_model: str
+    recharge_package: str
+    recharge_map: str
+    area_rtol: float | None
+    wells: list[WellConfig]
+    users: list[UserConfig]
+    calibration_record: Path | None = None
+    places_of_use: list[tuple[str, str]] = field(default_factory=list)
+    point_sources: list[tuple[str, str]] = field(default_factory=list)
+    exchange: dict | None = None
+    utilities: list[dict] = field(default_factory=list)
+    rules: list[dict] = field(default_factory=list)
+    outputs: dict = field(default_factory=dict)
+    nextgen_run: Path | None = None
+
+    @property
+    def surface(self) -> str:
+        return "nextgen" if self.nextgen_run else "swatplus"
+
+    @property
+    def has_modflow6(self) -> bool:
+        return bool(self.mf6_builder or self.mf6_workspace)
+
+    @property
+    def models(self) -> list[str]:
+        """The hydrologic models a run of this example uses, for its calibration status."""
+        return [self.surface] + (["modflow6"] if self.has_modflow6 else [])
+
+    @property
+    def folder(self) -> Path:
+        return self.path.parent
+
+    @property
+    def calibration_status(self) -> str:
+        """'calibrated' or 'screening' (no record, or a record that doesn't say calibrated)."""
+        from .calibration import record_status
+        return record_status(self.calibration_record, self.models)
+
+
+def _path(base: Path, p: str) -> Path:
+    if "{swatplus_refdata}" in p:
+        p = p.replace("{swatplus_refdata}", str(swatplus_refdata()))
+    p = p.replace("{nextgen_michigan}", str(nextgen_michigan()))
+    q = Path(p).expanduser()
+    return q if q.is_absolute() else (base / q).resolve()
+
+
+def load(path: str | Path) -> ExampleConfig:
+    path = Path(path).resolve()
+    with open(path, "rb") as f:
+        c = tomllib.load(f)
+    base = path.parent
+    known = {"name", "description", "run", "swatplus", "modflow6", "recharge", "wells", "users", "calibration",
+             "exchange", "utilities", "rules", "outputs", "nextgen"}
+    if set(c) - known:
+        raise ValueError(f"{path}: unknown sections {sorted(set(c) - known)}")
+    mf = c.get("modflow6", {})
+    if "modflow6" in c and bool(mf.get("builder")) == bool(mf.get("workspace")):
+        raise ValueError(f"{path}: [modflow6] needs one of builder or workspace")
+    if ("swatplus" in c) == ("nextgen" in c):
+        raise ValueError(f"{path}: needs one surface model, [swatplus] or [nextgen]")
+    sw = c.get("swatplus", {})
+    rch = c.get("recharge", {})
+    users = []
+    for u in c.get("users", []):
+        users.append(UserConfig(
+            name=u["name"], component=u["component"],
+            config=_path(base, u["config"]) if u.get("config") else None,
+            withdrawal=u["withdrawal"], returns=u["return"],
+            variables=u.get("variables", {}), constituents=u.get("constituents"), forcing=u.get("forcing")))
+    return ExampleConfig(
+        path=path, name=c["name"], description=c.get("description", ""),
+        run_folder=_path(base, c.get("run", {}).get("folder", f"runs/{c['name']}")),
+        days=int(c.get("run", {}).get("days", 0)),
+        swat_project=_path(base, sw["project"]) if sw else None,
+        mf6_builder=mf.get("builder"),
+        mf6_workspace=_path(base, mf["workspace"]) if mf.get("workspace") else None,
+        mf6_model=mf.get("model", "gwf"),
+        recharge_package=rch.get("package", "rch"),
+        recharge_map=rch.get("map", ""),
+        area_rtol=rch.get("area_rtol"),
+        wells=[WellConfig(w["name"], w.get("package", "wel"), tuple(w["cell"])) for w in c.get("wells", [])],
+        users=users,
+        calibration_record=_path(base, c["calibration"]["record"]) if c.get("calibration", {}).get("record") else None,
+        places_of_use=[(x["name"], x["channel"]) for x in sw.get("places_of_use", [])],
+        point_sources=[(x["name"], x["channel"]) for x in sw.get("point_sources", [])],
+        exchange=c.get("exchange"),
+        utilities=c.get("utilities", []),
+        rules=c.get("rules", []),
+        outputs=c.get("outputs", {}),
+        nextgen_run=_path(base, c["nextgen"]["run"]) if "nextgen" in c else None,
+    )