pyskby 0.2.1__tar.gz

pyskby-0.2.1/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: pyskby
+Version: 0.2.1
+Summary: SKBY spatially and temporally variable source-area hydrological model (Python port of STVSRM)
+Author: wly
+License: MIT
+Keywords: hydrology,rainfall-runoff,watershed,runoff,source-area,infiltration,channel-routing,STVSRM,SKBY
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Hydrology
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+
+# pyskby
+
+SKBY（时空变源混合产流）水文模型的 Python 版 —— 由 Java 版 STVSRM 完整移植，
+与 Java 参考模型**逐位对齐**（对拍通过），支持物理-守恒双模式、多外部水源接入。
+
+- **发布名**：`pyskby`
+- **导入名**：`pyskby`
+- **版本**：`0.2.0`
+- **Python**：≥ 3.10，依赖 `numpy`
+
+---
+
+## 1. 安装指令
+
+### 方式一：从 PyPI 安装（发布后）
+
+```bash
+pip install pyskby
+```
+
+### 方式二：从源码安装（开发模式）
+
+```bash
+cd skby_py
+pip install -e .
+```
+
+### 验证安装
+
+```bash
+python -c "import pyskby; print(pyskby.__version__)"
+# 输出: 0.2.0
+```
+
+---
+
+## 2. 调用指令
+
+### 2.1 Python API
+
+```python
+from pyskby.model import SKBYModel
+
+# Faithful 模式（默认，与 Java 逐位对齐）
+m = SKBYModel(
+    "data/liulan_fupan/params-testnew.csv",   # 参数文件
+    "data/liulan_fupan/data-test.csv",        # 驱动/时序数据
+    conservative=False,
+)
+m.run()
+m.write_outlet_csv("outlet.csv")   # 流域出口流量
+m.write_qj_csv("QJ.csv")           # 逐河道出流明细
+
+# Conservative 守恒模式（修复运动波质量损失，≠ Java 基线）
+m2 = SKBYModel("params.csv", "data.csv", conservative=True)
+m2.run()
+```
+
+### 2.2 命令行
+
+pyskby 提供两种命令行入口，底层都调用同一套逻辑（`pyskby.cli:main`）。
+
+**方式 A：安装后的 console script（推荐给使用者）**
+
+```bash
+pip install pyskby          # 安装后自动注册 skby-run 命令
+skby-run liulan_fupan                          # faithful 模式（Java 参考/不守恒）
+skby-run liulan_fupan --conservative           # 守恒修复版
+```
+
+`skby-run` 默认从**当前工作目录**查找 `sim/<sim>.groovy` 与 `data/`，因此使用者
+在自己的算例目录（含 `sim/`、`data/`）下运行即可；也可用 `--root PATH` 指定根目录：
+
+```bash
+cd my_case_study && skby-run liulan_fupan --root .
+```
+
+输出写到 `<root>/output/<sim>/out/outlet_py.csv` 与 `QJ_py.csv`。
+
+**打包内置示例（安装后直接跑通）**
+
+pyskby 在 wheel 中内置了示例算例 `liulan_fupan`。安装后用 `skby-example` 把示例
+解包到当前目录，再用 `skby-run` 运行：
+
+```bash
+pip install pyskby
+skby-example liulan_fupan          # 复制 ./examples/{sim,data}/liulan_fupan
+skby-run liulan_fupan --root examples          # faithful 模式
+skby-run liulan_fupan --root examples --conservative   # 守恒模式
+# 结果: ./examples/output/liulan_fupan/out/outlet_py.csv 与 QJ_py.csv
+```
+
+`skby-example` 不带参数则复制全部示例；已存在时跳过（加 `--force` 覆盖）。
+
+> **关于 `--root` 与 `site-packages`**
+> 安装后示例其实就在 `site-packages/pyskby/examples/`。`--root` 直接指向它
+> （如 `--root $(python -c "import pyskby,os;print(os.path.dirname(pyskby.__file__))")/examples`）
+> **也能算**，但输出会写到该安装目录下的 `.../examples/output/<sim>/out/`。不推荐：
+> 会污染 pip 管理的安装目录（重装/升级会被清掉），且在无写权限环境下会报 `PermissionError`。
+> 标准做法仍是 `skby-example` 把示例导出到你自己的工作目录再跑。
+
+**方式 B：仓库内调试（`run.py`，加载本地源码）**
+
+```bash
+cd skby_py
+python run.py liulan_fupan                  # 等价于 --root 指向仓库根
+python run.py liulan_fupan --conservative
+```
+
+`run.py` 会把自身所在目录（`skby_py`）插入 `sys.path` 最前，**强制优先加载本地
+`pyskby` 源码**（而非已安装的 PyPI 副本）。因此调试时改动 `pyskby/` 下的代码，
+`python run.py` 立即生效，不会误加载已 `pip install` 的版本。
+
+也可以用模块方式调用（等价于安装后的 console script）：
+
+```bash
+python -m pyskby.cli liulan_fupan --conservative --root /path/to/case
+```
+
+### 2.3 可选水量平衡诊断
+
+```python
+m.run(diag="diag.csv")   # 落盘逐时步水量平衡
+```
+
+> 详细参数说明见仓库内 `skby_py/使用手册.md`（产汇流参数、水源/分洪/水库出流等）。
+
+---
+
+## 3. 打包发布指令
+
+### 3.1 一次性安装发布工具
+
+```bash
+pip install --upgrade build twine
+```
+
+### 3.2 构建分发包
+
+```bash
+cd skby_py
+python -m build
+```
+
+会生成 `dist/pyskby-0.2.0-py3-none-any.whl`（wheel）和
+`dist/pyskby-0.2.0.tar.gz`（sdist）。
+
+### 3.3 发布到 PyPI
+
+```bash
+# 方式一：只发布 wheel（不含 sdist 源码包，推荐）
+twine upload dist/*.whl
+
+# 方式二：同时发布 wheel + sdist
+twine upload dist/*
+
+# 先上传到测试服务器验证
+twine upload --repository testpypi dist/*
+```
+
+> `twine upload` 会提示输入 PyPI 账号的 API Token（用户名填 `__token__`，密码填 token）。
+
+### 3.4 发布后验证
+
+```bash
+pip install pyskby
+python -c "import pyskby; print(pyskby.__version__)"
+```
+
+---
+
+## 4. 升级发布版本
+
+改版本号后需同步两处：
+
+1. `skby_py/pyproject.toml` → `version = "x.y.z"`
+2. `skby_py/pyskby/__init__.py` → `__version__ = "x.y.z"`
+
+然后重新执行 §3.2 构建、§3.3 上传。
+
+---
+
+## 5. 常见问题
+
+- **发布名 vs 导入名**：PyPI 包名和 Python 导入名均为 `pyskby`（`import pyskby`）。
+
+- **调试时改了 `pyskby/` 源码，`run.py` 用的还是旧代码？**
+  不会。`run.py` 在导入前把自身目录（`skby_py`）插到 `sys.path` 最前，因此
+  `python run.py ...` 永远加载**本地** `pyskby` 源码，即使系统里已 `pip install`
+  过正式版也优先本地。发布后的使用者用 `skby-run` 命令则加载其安装的副本。
+
+- **`skby-run` 与 `python run.py` 的区别？**
+  二者调用同一套逻辑（`pyskby.cli:main`）。`skby-run` 是给**安装者**用的
+  console script（从 cwd 找算例）；`run.py` 是给**开发者**调试用的入口
+  （默认把仓库根作为算例根，并强制加载本地源码）。

pyskby-0.2.1/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyskby"
+version = "0.2.1"
+description = "SKBY spatially and temporally variable source-area hydrological model (Python port of STVSRM)"
+readme = "readme.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "wly" },
+]
+keywords = [
+    "hydrology",
+    "rainfall-runoff",
+    "watershed",
+    "runoff",
+    "source-area",
+    "infiltration",
+    "channel-routing",
+    "STVSRM",
+    "SKBY",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Hydrology",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+]
+dependencies = [
+    "numpy",
+]
+
+# Console entry points: `pip install pyskby` -> `skby-run` + `skby-example`
+[project.scripts]
+skby-run = "pyskby.cli:main"
+skby-example = "pyskby.cli:copy_example"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["pyskby*"]
+
+# 随包分发的数据/文档文件（示例算例需打进 wheel，供 skby-example 解包）
+[tool.setuptools.package-data]
+pyskby = [
+    "*.py",
+    "examples/**/*",
+]
+
+# --- pytest: run the regression suite from the skby_py root ---
+[tool.pytest.ini_options]
+testpaths = ["autotest"]
+pythonpath = ["."]
+
+# --- ruff: lint + format (mirrors USGS pywatershed conventions) ---
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["pyskby", "autotest"]
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "F",    # pyflakes
+    "W",    # pycodestyle warnings
+    "I",    # isort
+    "B",    # flake8-bugbear
+    "UP",   # pyupgrade
+]
+ignore = [
+    "E501",  # line too long (handled by formatter)
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["pyskby"]
+
+[tool.ruff.format]
+quote-style = "double"

pyskby-0.2.1/pyskby/__init__.py

@@ -0,0 +1,24 @@
+"""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"
+
+__version__ = "0.2.0"
+
+from . import units
+from .model import SKBYModel
+
+__all__ = ["SKBYModel", "units", "__version__"]

pyskby-0.2.1/pyskby/cli.py

@@ -0,0 +1,187 @@
+"""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(
+        "--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参考/不守恒)'}")
+
+    model = SKBYModel(ppath, dpath, conservative=args.conservative)
+    model.run()
+
+    out_dir = os.path.join(root, "output", args.sim, "out")
+    os.makedirs(out_dir, exist_ok=True)
+    out_path = os.path.join(out_dir, "outlet_py.csv")
+    model.write_outlet_csv(out_path)
+    print(f"wrote {out_path}")
+    qj_path = os.path.join(out_dir, "QJ_py.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-0.2.1/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))