pyskby 0.2.3__py3-none-any.whl

pyskby/__init__.py

@@ -0,0 +1,31 @@
+"""pyskby — SKBY (spatially and temporally variable source-area) hydrological model.
+
+Pure-Python (numpy/pandas) port of STVSRM_old. The import name is ``pyskby``,
+matching the PyPI package name.
+
+Usage::
+
+    from pyskby.model import SKBYModel
+    m = SKBYModel(params_csv, data_csv)
+    m.run()
+    m.write_outlet_csv("outlet.csv")
+
+All units follow the original OMS3/PRMS conventions (inches/feet/cms), with
+conversion constants centralized in ``pyskby.units``.
+"""
+
+__author__ = "wly"
+
+# 版本号单一来源：以 pyproject.toml [project].version 为准，
+# 通过包元数据动态读取，避免两处维护不一致。
+try:
+    from importlib.metadata import version as _version
+
+    __version__ = _version("pyskby")
+except Exception:  # 兜底（如 editable 安装未完成时）
+    __version__ = "0.2.3"
+
+from . import units
+from .model import SKBYModel
+
+__all__ = ["SKBYModel", "units", "__version__"]

pyskby/cli.py

@@ -0,0 +1,201 @@
+"""Command-line entry points for the pyskby model.
+
+Two console scripts are installed with the package:
+
+* ``skby-run <sim> [--conservative] [--root PATH]`` — run a simulation case.
+  Reads ``sim/<sim>.groovy`` to learn which params/data CSVs to use, runs the
+  model, and writes ``output/<sim>/out/outlet_py.csv`` (plus ``QJ_py.csv``).
+
+* ``skby-example [name]`` — copy the bundled example case(s) into the current
+  working directory (``examples/<sim>``) so they can be run with ``skby-run``.
+
+Both are also runnable as a module::
+
+    python -m pyskby.cli liulan_fupan
+    python -m pyskby.cli --example liulan_fupan
+
+Mimics ``java -jar RunModel.jar <sim_name> OFF``. The ``<sim_name>`` is resolved
+against a project root, which defaults to the current working directory (so users
+run the CLI from their own case-study folder that contains ``sim/`` and ``data/``).
+Override with ``--root``.
+"""
+
+__author__ = "wly"
+
+import argparse
+import importlib.resources as _resources
+import os
+import re
+import shutil
+import sys
+from pathlib import Path
+
+from .model import SKBYModel
+
+
+def _examples_dir() -> Path:
+    """Filesystem path to the packaged example cases (works for both the source
+    tree and an installed wheel via importlib.resources)."""
+    return Path(str(_resources.files("pyskby").joinpath("examples")))
+
+
+def copy_example(argv=None):
+    """Console-script entry: ``skby-example [name]``.
+
+    Copies the bundled example(s) into ``./examples/<sim>`` of the current
+    working directory. With no ``name`` all examples are copied.
+    """
+    parser = argparse.ArgumentParser(
+        prog="skby-example",
+        description="Copy bundled pyskby example case(s) into ./examples/.",
+    )
+    parser.add_argument(
+        "name",
+        nargs="?",
+        default=None,
+        help="example case name (defaults to all); e.g. liulan_fupan",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="overwrite an existing ./examples/<name> instead of skipping",
+    )
+    args = parser.parse_args(argv)
+
+    src_root = _examples_dir()
+    if not src_root.is_dir():
+        print(f"error: no bundled examples found at {src_root}", file=sys.stderr)
+        return 1
+
+    sim_dir = src_root.joinpath("sim")
+    data_dir = src_root.joinpath("data")
+
+    def _copy_one(sim_name):
+        # Preserve the bundled layout: examples/sim/<name>.groovy and
+        # examples/data/<name>/..., so `skby-run <name> --root examples` works.
+        dst_sim = os.path.join(os.getcwd(), "examples", "sim")
+        dst_data = os.path.join(os.getcwd(), "examples", "data", sim_name)
+        gsrc = sim_dir.joinpath(f"{sim_name}.groovy")
+        dsrc = data_dir.joinpath(sim_name)
+        if (not gsrc.is_file()) and (not dsrc.is_dir()):
+            print(f"warning: example '{sim_name}' not found", file=sys.stderr)
+            return
+        if gsrc.is_file():
+            if os.path.exists(os.path.join(dst_sim, f"{sim_name}.groovy")) and not args.force:
+                print(f"skip   examples/sim/{sim_name}.groovy (exists; --force to overwrite)")
+            else:
+                os.makedirs(dst_sim, exist_ok=True)
+                shutil.copy2(gsrc, os.path.join(dst_sim, f"{sim_name}.groovy"))
+        if dsrc.is_dir():
+            if os.path.exists(dst_data) and not args.force:
+                print(f"skip   examples/data/{sim_name} (exists; --force to overwrite)")
+            else:
+                shutil.copytree(dsrc, dst_data, dirs_exist_ok=True)
+        print(f"copied example '{sim_name}' -> ./examples/")
+
+    if args.name:
+        _copy_one(args.name)
+    else:
+        names = sorted(
+            p.stem for p in sim_dir.glob("*.groovy") if p.is_file()
+        )
+        if not names:
+            print("no example cases found", file=sys.stderr)
+            return 1
+        for n in names:
+            _copy_one(n)
+    print("done. Now run: skby-run <name> --root examples")
+    return 0
+
+
+
+def parse_groovy(root, sim_name):
+    """Read sim/<sim>.groovy to find the params/data CSV filenames it references."""
+    gpath = os.path.join(root, "sim", f"{sim_name}.groovy")
+    if not os.path.exists(gpath):
+        raise FileNotFoundError(f"sim file not found: {gpath}")
+    params_file = "params-testnew.csv"
+    data_file = "data-test.csv"
+    with open(gpath, "r", encoding="utf-8") as f:
+        txt = f.read()
+    m = re.search(r'params.*?"([^"]+\.csv)"', txt)
+    if m:
+        params_file = m.group(1)
+    m = re.search(r'data.*?"([^"]+\.csv)"', txt)
+    if m:
+        data_file = m.group(1)
+    return params_file, data_file
+
+
+def _resolve(root, sim, filename):
+    """Resolve a params/data path: absolute, root-relative, or data/<sim>/-relative."""
+    if os.path.isabs(filename):
+        return filename
+    p = os.path.join(root, filename)
+    if os.path.exists(p):
+        return p
+    alt = os.path.join(root, "data", sim, os.path.basename(filename))
+    if os.path.exists(alt):
+        return alt
+    return p  # fall back to the root-relative guess (will surface a clear error)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="skby-run",
+        description="Run the pyskby hydrological model for a given simulation case.",
+    )
+    parser.add_argument("sim", help="simulation name (matches sim/<sim>.groovy)")
+    parser.add_argument(
+        "--conservative",
+        action="store_true",
+        help="mass-conserving routing (Newton-implicit non-linear reservoirs); "
+        "default is faithful (Java-reference behaviour, not water-conserving).",
+    )
+    parser.add_argument(
+        "--routing",
+        choices=["explicit", "implicit"],
+        default="explicit",
+        help="kinematic-wave scheme: 'explicit' (default, faithful Java) or "
+        "'implicit' (opt-in 4-point implicit scheme, for an explicit-vs-implicit "
+        "comparison on the same case).",
+    )
+    parser.add_argument(
+        "--root",
+        default=os.getcwd(),
+        help="project root containing sim/ and data/ (default: current directory)",
+    )
+    args = parser.parse_args(argv)
+
+    root = os.path.abspath(args.root)
+    params_file, data_file = parse_groovy(root, args.sim)
+    ppath = _resolve(root, args.sim, params_file)
+    dpath = _resolve(root, args.sim, data_file)
+
+    print(f"params: {ppath}")
+    print(f"data:   {dpath}")
+    print(f"mode:   {'conservative (守恒修复版)' if args.conservative else 'faithful (Java参考/不守恒)'}"
+          f" | routing: {args.routing}")
+
+    model = SKBYModel(ppath, dpath, conservative=args.conservative,
+                      routing=args.routing)
+    model.run()
+
+    out_dir = os.path.join(root, "output", args.sim, "out")
+    os.makedirs(out_dir, exist_ok=True)
+    # Keep faithful and conservative outputs separate so a conservative run
+    # never overwrites the faithful (Java-reference) results.
+    suffix = ("_conservative" if args.conservative else "") + (
+        "_implicit" if args.routing == "implicit" else "")
+    out_path = os.path.join(out_dir, f"outlet_py{suffix}.csv")
+    model.write_outlet_csv(out_path)
+    print(f"wrote {out_path}")
+    qj_path = os.path.join(out_dir, f"QJ_py{suffix}.csv")
+    model.write_qj_csv(qj_path)
+    print(f"wrote {qj_path}")
+    print(f"basin_cfs[0] = {model.basin_cfs_series[0]:.6f}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pyskby/component.py

@@ -0,0 +1,47 @@
+"""Component interface contract (phase-2 pluggable-process design).
+
+Per doc/升级改造说明.md §4.3, the model components will become interchangeable
+so that algorithms (e.g. infiltration, PET) can be swapped without disturbing the
+overall assembly -- mirroring USGS pywatershed's "replaceable conceptualization".
+
+This module defines the shared contract. Existing components (components.py) are
+NOT yet required to inherit from it; this is the intended target interface and a
+safe place to evolve toward. New/refactored components should subclass
+``BaseComponent`` and implement ``initialize``/``run``.
+"""
+
+__author__ = "wly"
+
+from abc import ABC, abstractmethod
+
+import numpy as np
+
+
+class BaseComponent(ABC):
+    """Common interface for every model process component.
+
+    Subclasses receive the parsed parameter object in ``__init__`` and expose a
+    ``run`` method that advances one time step. State is held on the instance so
+    that multi-step runs preserve cross-step memory (e.g. channel/groundwater
+    states), matching the Java per-component state model.
+    """
+
+    #: logical name used in diagnostics / registry (e.g. "HRUOut")
+    name: str = "component"
+
+    def __init__(self, cfg):
+        self.cfg = cfg
+
+    @abstractmethod
+    def initialize(self) -> None:
+        """One-time setup before the simulation loop (allocate state arrays)."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def run(self, *args, **kwargs) -> object:
+        """Advance one time step; return the component's contribution(s)."""
+        raise NotImplementedError
+
+    @property
+    def nhru(self) -> int:
+        return int(self.cfg.get("nhru", 1))