Metadata-Version: 2.4
Name: pyskby
Version: 0.1.0
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`
- **导入名**：`skby`
- **版本**：`0.1.0`
- **Python**：≥ 3.10，依赖 `numpy`

---

## 1. 安装指令

### 方式一：从 PyPI 安装（发布后）

```bash
pip install pyskby
```

### 方式二：从源码安装（开发模式）

```bash
cd skby_py
pip install -e .
```

### 验证安装

```bash
python -c "import skby; print(skby.__version__)"
# 输出: 0.1.0
```

---

## 2. 调用指令

### 2.1 Python API

```python
from skby.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 命令行

```bash
# 在仓库根目录（含 sim/ 与 data/）
python skby_py/run.py liulan_fupan OFF
# 输出: output/liulan_fupan/out/outlet_py.csv 和 QJ_py.csv
```

### 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.1.0-py3-none-any.whl`（wheel）和
`dist/pyskby-0.1.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 skby; print(skby.__version__)"
```

---

## 4. 升级发布版本

改版本号后需同步两处：

1. `skby_py/pyproject.toml` → `version = "x.y.z"`
2. `skby_py/skby/__init__.py` → `__version__ = "x.y.z"`

然后重新执行 §3.2 构建、§3.3 上传。

---

## 5. 常见问题

- **发布名 vs 导入名**：PyPI 用 `pyskby` 安装，Python 代码用 `import skby`。
- **不想发布源码**：只执行 `twine upload dist/*.whl`（wheel 只含 `.py` 与元数据，
  不含 sdist 附带的 `pyproject.toml`/readme 等原始工程文件）。
- **`升级改造.md` / `.pdf` 等内部文档**不会进入任何发布包。
