openkarhydro 0.1.0__py3-none-any.whl

openkarhydro/__init__.py

@@ -0,0 +1,33 @@
+"""OpenKarHydro — Solar Farm Hydrological Model
+
+光伏电站水文生态过程模拟的开源 Python 实现。
+"""
+
+from openkarhydro.__version__ import __version__
+from openkarhydro.model import SolarFarmModel
+from openkarhydro.config import SimConfig, GridConfig, PanelConfig
+from openkarhydro.config import SoilParams, VegParams, SiteConfig, TimeConfig
+from openkarhydro.config import DistributedConfig
+from openkarhydro.forcing import ForcingData
+from openkarhydro.geometry.pv_geometry import (
+    PanelGeometry,
+    UniformPanelGeometry,
+    ArrayPanelGeometry,
+)
+
+__all__ = [
+    "__version__",
+    "SolarFarmModel",
+    "SimConfig",
+    "GridConfig",
+    "PanelConfig",
+    "SoilParams",
+    "VegParams",
+    "SiteConfig",
+    "TimeConfig",
+    "DistributedConfig",
+    "ForcingData",
+    "PanelGeometry",
+    "UniformPanelGeometry",
+    "ArrayPanelGeometry",
+]

openkarhydro/__main__.py

@@ -0,0 +1,6 @@
+"""CLI 入口: python -m openkarhydro run/init/plot"""
+
+from openkarhydro.cli import cli
+
+if __name__ == "__main__":
+    cli()

openkarhydro/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

openkarhydro/cli.py

@@ -0,0 +1,489 @@
+"""OpenKarHydro CLI"""
+
+from pathlib import Path
+import click
+import numpy as np
+
+
+def _get_config_dir(config_path: str) -> Path:
+    """获取 config.yaml 所在目录"""
+    return Path(config_path).resolve().parent
+
+
+# ═══════════════════════════════════════════════════════════════
+# init
+# ═══════════════════════════════════════════════════════════════
+
+CONFIG_TEMPLATE = """# ============================================================================
+# OpenKarHydro 模型配置
+# ============================================================================
+# 所有模型参数和文件路径集中于此。修改参数无需改动 Python 代码。
+#
+# 运行命令: openkarhydro run config.yaml
+# ============================================================================
+
+
+# ============================================================================
+# INPUT — 输入文件路径
+# ============================================================================
+# 路径相对于 config.yaml 所在目录。CLI 选项 (--dem/--pv/--forcing) 优先级更高。
+input:
+  forcing:  "inputs/forcing.csv"            # [必需] 逐日气象数据 (CSV)
+  dem:      "inputs/dem.tif"                # [必需] 数字高程模型 (GeoTIFF)
+  pv_layout: "inputs/pv_layout.geojson"     # [可选] PV 面板布局文件
+  soil_shrub: ""                            # [可选] 自定义非 PV 区土壤参数
+  soil_grass: ""                            # [可选] 自定义 PV 区土壤参数
+  veg_shrub: ""                             # [可选] 自定义非 PV 区植被参数
+  veg_grass: ""                             # [可选] 自定义 PV 区植被参数
+
+
+# ============================================================================
+# OUTPUT — 输出目录与格式
+# ============================================================================
+output:
+  dir: "outputs"                            # 结果输出目录
+  out_dt: 2592000                            # 输出间隔(s), 默认30天 (out_day>0时被覆盖)
+  out_day: 1                                 # 每月第1天输出 (1-28, 0=按out_dt间隔)
+  geotiff: true                             # 导出 GeoTIFF
+  netcdf: true                              # 导出 NetCDF
+  timeseries: true                          # 导出时间序列 CSV
+
+
+# ============================================================================
+# SITE — 站点地理与环境参数
+# ============================================================================
+site:
+  name: "my_site"            # 站点名称
+  latitude:  38.1            # 纬度 [°N]（北正南负）
+  longitude: 106.2           # 经度 [°E]（东正西负）
+  elevation:  1350           # 海拔 [m]
+  wind_speed: 2.0            # 年平均风速 [m/s]
+  obs_height: 2.0            # 气象观测高度 [m]
+  root_depth: 600            # 根系层深度 [mm]
+
+
+# ============================================================================
+# GRID — 空间网格参数
+# ============================================================================
+grid:
+  length: 100                # x 方向网格数 [—]
+  width:  100                # y 方向网格数 [—]
+  depth:  10                 # 土壤剖面总深度 [cm]
+  dz:     10                 # 垂向网格步长 [cm]
+  dx:     100                # x 方向水平分辨率 [cm]
+  dy:     100                # y 方向水平分辨率 [cm]
+
+
+# ============================================================================
+# TIME — 模拟时间参数
+# ============================================================================
+time:
+  start_date: "2023-01-01"              # 模拟开始日期
+  end_date: "2023-12-31"                # 模拟结束日期
+  pv_start_date: "2025-01-01"           # PV 投运日期（不设则无 PV）
+  pv_end_date: "2025-07-01"             # PV 运维开始 (不设则建设期长度为0)
+  rst_dt: 15768000                       # 重启间隔 (s), 15768000≈半年(182.5d×86400)
+  rst_day: 0                             # 每月固定日重启 (1-28), 0=用rst_dt间隔
+  growing_start:  91                    # 生长季开始 [DOY]（91=4月1日）
+  growing_end:   273                    # 生长季结束 [DOY]（273=9月30日）
+
+
+# ============================================================================
+# PANEL — 光伏面板参数
+# ============================================================================
+panel:
+  length:  2.0               # 面板长度 [m]
+  width:   1.0               # 面板宽度 [m]
+  spacing_area: 0.3          # 面板面积占比 [—]
+  tilt:    37.2              # 面板倾角 [°]
+  shading_angle: 0.384       # 遮阴角 [rad]
+  dz: 60.0                   # 面板子网格垂向步长 [cm]
+
+
+# ============================================================================
+# SOIL / VEG — 土壤与植被参数
+# ============================================================================
+soil_type: loess_shrub         # 非 PV 区土壤模板名
+veg_type: shrub                # 非 PV 区植被模板名
+# 自定义参数文件: inputs/soil_shrub.yaml, veg_shrub.yaml
+
+
+# ============================================================================
+# DISTRIBUTED — 分布式参数（可选）
+# ============================================================================
+# 未配置时自动使用 soil_shrub/soil_grass 两套参数按 PV 区分。
+# 配置后支持逐格独立土壤/植被参数（需与 DEM 同 CRS、同网格尺寸）。
+distributed:
+  soil_map: ""               # 土壤类型图 (GeoTIFF)，整数值对应 soil_types
+  veg_map: ""                # 植被类型图 (GeoTIFF)，整数值对应 veg_types
+  soil_types: {}             # {1: "loess_shrub", 2: "silt_loam"}
+  veg_types: {}              # {1: "shrub", 2: "grass"}
+
+
+# ============================================================================
+# RICHARDS — 隐式 Richards 求解器
+# ============================================================================
+richards:
+  scheme: "implicit"                            # 求解方案 (目前仅支持 implicit)
+  num_iter: 3                                   # 子步数 (2~10, 大雨自动增至6)
+  bottom_boundary: "mmf"                        # 底边界: mmf(地下水耦合) | free_drain | zero
+  drain_slope: 1.0                              # 排水坡度 (free_drain时用)
+
+
+# ============================================================================
+# GROUNDWATER — 侧向地下水流
+# ============================================================================
+groundwater:
+  enabled: true                                 # 启用 MMF 8向 Darcy 侧向流 + QRF
+  klat_factor: 0.3                              # 水平/垂向渗透率比
+  f_depth: 300.0                                # 导水率衰减深度 [cm]
+  spec_yield: 0.2                               # 给水度
+  update_interval: 5                            # 侧向流更新间隔 [d]
+
+
+# ============================================================================
+# 模型开关
+# ============================================================================
+has_pv: true                   # 激活光伏面板 [true/false]
+"""
+
+
+def _write_example_param(path, label):
+    """写入土壤/植被参数示例文件"""
+    if path.exists():
+        return
+    path.write_text(f"# {label}\n#\n"
+                    f"# 将此文件重命名为 soil_shrub.yaml 即可生效。\n"
+                    f"# 查看内置模板: openkarhydro.data.soil_templates.SOIL_TEMPLATES\n")
+
+
+@click.command()
+@click.argument("project_dir", default="my_project")
+def init(project_dir):
+    """创建新项目
+
+    生成 config.yaml 配置文件和 inputs/ 输入目录。
+    用户需将 DEM、气象数据、PV 布局等文件放入 inputs/ 目录。
+    """
+    d = Path(project_dir)
+    d.mkdir(parents=True, exist_ok=True)
+
+    # config.yaml
+    config = d / "config.yaml"
+    if not config.exists():
+        config.write_text(CONFIG_TEMPLATE)
+        click.echo(f"  📄 {config.name}")
+    else:
+        click.echo(f"  ⏭️  {config.name} 已存在，跳过")
+
+    # inputs/ 目录及示例参数文件
+    inputs_dir = d / "inputs"
+    inputs_dir.mkdir(exist_ok=True)
+    click.echo(f"  📁 {inputs_dir.name}/")
+
+    # 生成土壤/植被参数示例文件
+    _write_example_param(inputs_dir / "soil_shrub.yaml.example",
+                         "预置土壤参数模板: loess_shrub (注释中的完整参数列表)")
+    _write_example_param(inputs_dir / "veg_shrub.yaml.example",
+                         "预置植被参数模板: shrub (注释中的完整参数列表)")
+
+    click.echo(f"\n✅ 项目已创建: {d.resolve()}")
+    click.echo("   编辑 config.yaml 中的 input 段指定输入文件路径，")
+    click.echo("   然后执行: openkarhydro run config.yaml")
+    click.echo("")
+    click.echo("   也可用 CLI 选项覆盖路径:")
+    click.echo("     openkarhydro run config.yaml --dem xxx.tif --forcing xxx.csv")
+
+
+# ═══════════════════════════════════════════════════════════════
+# run
+# ═══════════════════════════════════════════════════════════════
+
+@click.command()
+@click.argument("config_path", default="config.yaml")
+@click.option("--dem", default=None, help="DEM GeoTIFF 路径")
+@click.option("--pv", default=None, help="PV 布局文件路径")
+@click.option("--forcing", default=None, help="气象 CSV 路径")
+@click.option("--output", "-o", default=None, help="输出目录")
+@click.option("--years", "-y", default=None, type=int, help="模拟年数")
+@click.option("--resume", default=None, help="从检查点续算（.npz 路径）")
+@click.option("--parallel", "use_parallel", flag_value=True, default=None,
+              help="强制启用并行")
+@click.option("--no-parallel", "use_parallel", flag_value=False,
+              help="强制串行")
+@click.option("--n-tiles-x", default=0, type=int, help="X 方向瓦片数 (0=自动)")
+@click.option("--n-tiles-y", default=0, type=int, help="Y 方向瓦片数 (0=自动)")
+@click.option("--n-threads", default=0, type=int, help="每瓦片线程数 (0=自动)")
+def run(config_path, dem, pv, forcing, output, years, resume, use_parallel, n_tiles_x, n_tiles_y, n_threads):
+    """运行模拟
+
+    从 config.yaml 和 inputs/ 目录加载数据，执行三阶段模拟
+    （建设前→建设期→运营期），导出结果。
+    """
+    # 强制行缓冲（解决管道/重定向下输出被缓冲的问题）
+    import sys as _sys
+    if hasattr(_sys.stdout, 'reconfigure'):
+        _sys.stdout.reconfigure(line_buffering=True)
+
+    from openkarhydro.config import SimConfig
+    from openkarhydro.forcing import ForcingData
+    from openkarhydro.model import SolarFarmModel
+
+    click.echo("=" * 60)
+    click.echo("OpenKarHydro — 光伏电站水文模拟")
+    click.echo("=" * 60)
+
+    # ── 0. 加载原始 YAML（获取路径配置） ──
+    cfg_path = Path(config_path)
+    if not cfg_path.exists():
+        click.echo(f"  ❌ 未找到: {cfg_path}")
+        return
+    project_dir = cfg_path.parent
+    import yaml
+    with open(cfg_path) as f:
+        raw_cfg = yaml.safe_load(f) or {}
+
+    in_paths = raw_cfg.get("input", {})
+    out_cfg = raw_cfg.get("output", {})
+
+    # 输入文件路径（CLI 选项 > config.yaml > 默认值）
+    def _resolve(path_str):
+        return str(project_dir / path_str) if path_str else None
+
+    forcing_file = (forcing or _resolve(in_paths.get("forcing")) or
+                    str(project_dir / "inputs" / "forcing.csv"))
+    dem_file = (dem or _resolve(in_paths.get("dem")))
+    pv_file = (pv or _resolve(in_paths.get("pv_layout")))
+
+    # 输出目录（CLI 选项 > config.yaml > 默认值）
+    out_dir = (output or _resolve(out_cfg.get("dir")) or
+               str(project_dir / "outputs"))
+    # ── 1. 加载配置 ──
+    click.echo("\n[1/4] 加载配置...")
+    config = SimConfig.from_yaml(str(cfg_path), inputs_dir=project_dir / "inputs")
+    click.echo(f"  网格: {config.grid.Nx}×{config.grid.Ny}×{config.grid.Nz}")
+    pv_info = f"PV 投运: {config.time.pv_start_date}" if config.time.pv_start_date else "无 PV"
+    click.echo(f"  时间: {config.time.start_date} → {config.time.end_date} ({pv_info})")
+
+    # ── 2. 准备输入数据 ──
+    click.echo("\n[2/4] 加载输入数据...")
+
+    # 气象
+    if not Path(forcing_file).exists():
+        click.echo(f"  ❌ 未找到气象数据: {forcing_file}")
+        click.echo("     请将逐日气象 CSV 放入 input.forcing 指定的路径")
+        click.echo("     格式: date, precip, tmax, tmin [, solar_radiation]")
+        return
+    forcing = ForcingData.load(forcing_file)
+    click.echo(f"  🌤️  气象: {Path(forcing_file).name} ({forcing.precipitation.shape[1]}天)")
+
+    # 地形
+    topo = _load_topography(config, project_dir, dem_file, pv_file)
+    if topo is None:
+        return
+    click.echo(f"  🗺️  地形: {topo.dem.shape[0]}×{topo.dem.shape[1]}")
+    if hasattr(topo, "pv_index") and topo.pv_index is not None and topo.pv_index.sum() > 0:
+        click.echo(f"  ☀️  PV {topo.pv_index.sum()} 块 "
+                   f"({100*topo.pv_index.sum()/topo.pv_index.size:.1f}%)")
+
+    # ── 3. 运行 ──
+    click.echo("\n[3/4] 运行模拟...")
+    # 并行配置: --parallel 强制开, --no-parallel 强制关, 不传跟随 config.yaml
+    if use_parallel is not None:
+        config.parallel.enabled = use_parallel
+    if n_tiles_x > 0:
+        config.parallel.n_tiles_x = n_tiles_x
+    if n_tiles_y > 0:
+        config.parallel.n_tiles_y = n_tiles_y
+    if n_threads > 0:
+        config.parallel.n_threads = n_threads
+
+    mode_str = "🚀 并行" if config.parallel.enabled else "🧵 串行"
+    click.echo(f"  {mode_str} (配置: {config.parallel.n_tiles_x or "auto"}×{config.parallel.n_tiles_y or "auto"} 瓦片)")
+    model = SolarFarmModel(config, forcing, topography=topo)
+
+    import time
+    t0 = time.time()
+    results = model.run(
+        resume_from=resume,
+        output_dir=out_dir,
+        verbose=True,
+        parallel=config.parallel.enabled,
+    )
+    elapsed = time.time() - t0
+
+    # ── 4. 完成 ──
+    click.echo(f"\n[4/4] 完成！({elapsed:.1f}s)")
+    click.echo(f"  输出目录: {Path(out_dir).resolve()}")
+    click.echo(f"  最终 SMC: {results.state_variables['x'][1:-1,1:-1,1].mean():.4f}")
+
+
+def _load_topography(config, project_dir, dem_path, pv_path):
+    """加载地形数据，返回 TopographyData"""
+    from openkarhydro.io.load_topography import (
+        load_dem_geotiff, load_pv_layout, load_topography_from_arrays,
+    )
+    inputs_dir = project_dir / "inputs"
+    dem_file = dem_path or (str(inputs_dir / "dem.tif") if (inputs_dir / "dem.tif").exists() else None)
+    pv_file = pv_path or _find_pv_file(inputs_dir)
+
+    if dem_file and Path(dem_file).exists():
+        dem, crs, transform, dem_nodata = load_dem_geotiff(dem_file)
+        L, W = dem.shape
+    else:
+        click.echo(f"  ❌ 未找到 DEM: {dem_file or '无文件'}")
+        click.echo("     请将 DEM GeoTIFF 放入 inputs/dem.tif")
+        return None
+
+    pv_index = _load_pv_index(pv_file, crs, transform, (L, W))
+
+    # NODATA 需转换到 cm（与 DEM 单位一致）
+    nodata_cm = dem_nodata * 100.0 if dem_nodata is not None else None
+    if nodata_cm is not None:
+        mask = (dem != nodata_cm)
+    else:
+        mask = np.ones(dem.shape, dtype=bool)
+    return load_topography_from_arrays(
+        dem, pv_index=pv_index, mask=mask, crs=crs, transform=transform,
+        nodata=dem_nodata,
+    )
+
+
+def _find_pv_file(inputs_dir):
+    """在 inputs/ 目录下查找 PV 布局文件"""
+    if not inputs_dir.exists():
+        return None
+    for ext in [".tif", ".tiff", ".geojson", ".shp", ".npy", ".mat", ".csv"]:
+        files = list(inputs_dir.glob(f"pv_layout*{ext}"))
+        if files:
+            return str(files[0])
+    return None
+
+
+def _load_pv_index(path, crs, transform, grid_shape):
+    """加载 PV 索引"""
+    if path is None:
+        return np.zeros(grid_shape, dtype=int)
+    try:
+        from openkarhydro.io.load_topography import load_pv_layout
+        return load_pv_layout(path, crs=crs, transform=transform, grid_shape=grid_shape)
+    except Exception as e:
+        click.echo(f"  ⚠️  PV 布局加载失败: {e}")
+        return np.zeros(grid_shape, dtype=int)
+
+
+# ═══════════════════════════════════════════════════════════════
+# postprocess — SQLite + spatial_stats 生成
+# ═══════════════════════════════════════════════════════════════
+
+@click.command()
+@click.argument("output_dir", default="outputs")
+@click.option("--db", "-d", default=None,
+              help="SQLite 输出路径（默认 {output_dir}/results.sqlite）")
+def postprocess(output_dir, db):
+    """后处理: 从 NC/CSV 生成 SQLite（时间序列 + 空间统计）
+
+    读取 {output_dir} 目录中的 timeseries.csv 和 LDASOUT*.nc，
+    写入 results.sqlite（daily/monthly/annual + spatial_stats 表）。
+
+    QGIS 中直接打开 LDASOUT*.nc 即可查看空间结果。
+    """
+    from openkarhydro.io.postprocess import postprocess as _run_postprocess
+    _run_postprocess(output_dir, sqlite_path=db)
+
+
+# ═══════════════════════════════════════════════════════════════
+# plot
+# ═══════════════════════════════════════════════════════════════
+
+@click.command()
+@click.argument("input_path")
+@click.option("--output", "-o", default=None)
+@click.option("--var", "-v", default="all",
+              help="变量名（x/B/LAI/DEM 等），默认 all")
+def plot(input_path, output, var):
+    """可视化 .npz 检查点或 .csv 时间序列"""
+    import matplotlib.pyplot as plt
+    p = Path(input_path)
+
+    if p.suffix == ".csv":
+        import pandas as pd
+        df = pd.read_csv(str(p))
+        numeric_cols = df.select_dtypes(include="number").columns
+        if var != "all":
+            numeric_cols = [c for c in numeric_cols if var in c]
+        fig, axes = plt.subplots(
+            len(numeric_cols[:6]), 1,
+            figsize=(10, 2 * len(numeric_cols[:6])),
+            sharex=True,
+        )
+        if len(numeric_cols[:6]) == 1:
+            axes = [axes]
+        for ax, col in zip(axes, numeric_cols[:6]):
+            ax.plot(df.index, df[col])
+            ax.set_ylabel(col)
+            ax.grid(True, alpha=0.3)
+        axes[-1].set_xlabel("Day")
+        fig.suptitle(p.stem, fontsize=12)
+        fig.tight_layout()
+
+    elif p.suffix == ".npz":
+        data = np.load(p, allow_pickle=True)
+        skip_keys = {"_crs", "_transform", "_pv_index"}
+        plot_keys = [k for k in data.keys()
+                     if not k.startswith("_") and k not in skip_keys]
+        if var != "all" and var in data:
+            plot_keys = [var]
+        n_plots = min(len(plot_keys), 6)
+        fig, axes = plt.subplots(2, 3, figsize=(12, 8))
+        axes = axes.ravel()
+        for idx, k in enumerate(plot_keys[:6]):
+            v = data[k]
+            ax = axes[idx]
+            if v.ndim == 1 and v.size > 1:
+                ax.plot(v.ravel(), marker=".")
+                ax.set_title(k)
+            elif v.ndim == 2:
+                im = ax.imshow(v, cmap="YlOrRd", aspect="auto")
+                plt.colorbar(im, ax=ax)
+                ax.set_title(k)
+            elif v.ndim == 3:
+                if k == "B" and v.shape[-1] == 3:
+                    im = ax.imshow(v[1:-1, 1:-1, :].sum(axis=2),
+                                   cmap="YlGn", aspect="auto")
+                    plt.colorbar(im, ax=ax)
+                    ax.set_title("Biomass (总)")
+                else:
+                    im = ax.imshow(v[1:-1, 1:-1, 1], cmap="YlOrRd", aspect="auto")
+                    plt.colorbar(im, ax=ax)
+                    ax.set_title(f"{k} (层1)")
+            else:
+                ax.text(0.5, 0.5, f"{k}: shape={v.shape}", ha="center")
+        for idx in range(len(plot_keys[:6]), 6):
+            fig.delaxes(axes[idx])
+        fig.suptitle(p.stem, fontsize=12)
+        fig.tight_layout()
+    else:
+        click.echo(f"不支持: {p.suffix}")
+        return
+
+    if output:
+        plt.savefig(output, dpi=150)
+    plt.show()
+
+
+# ═══════════════════════════════════════════════════════════════
+# CLI group
+# ═══════════════════════════════════════════════════════════════
+
+@click.group()
+def cli():
+    """OpenKarHydro — 光伏电站水文模拟"""
+
+
+cli.add_command(init)
+cli.add_command(run)
+cli.add_command(postprocess)
+cli.add_command(plot)
+
+