miniflood 2.1.0

A simplified 2D flood diffusion model with GPU acceleration

MiniFlood

GPU 加速的简化二维洪水扩散模拟引擎。

---

构建与安装

前置条件

• CMake >= 3.18
• CUDA Toolkit（如需 GPU 加速）
• Python >= 3.10
• C++ 编译器（MSVC / GCC / Clang）

安装方式

# 方式一：从源码安装（推荐）
pip install . -v

# 方式二：构建 wheel 再安装
pip install build
python -m build
pip install dist/miniflood-*.whl

# 方式三：可编辑安装（开发模式）
pip install -e . -v

Windows + CUDA 用户须知

如果安装了多个 Visual Studio 版本（如 VS 2022 + VS 2026），CMake 默认选最新版本， 但 nvcc 可能不兼容最新 VS。请指定 VS 2022：

# 在构建前设置环境变量
$env:CMAKE_GENERATOR = "Visual Studio 17 2022"
pip install . -v --force-reinstall --no-deps

手动 CMake 构建（传统方式，仅用于调试）

pip install pybind11
mkdir build
cd build
cmake .. -DPython3_EXECUTABLE=python              # Windows / Linux / macOS 通用
cmake --build . --config Release

---

使用示例

from miniflood import flood

# 运行案例
status = flood.run("miniflood/examples/case01")
if status == 0:
    print("✅ 模拟成功！")
else:
    print(f"❌ 模拟失败，返回码: {status}")

案例配置 (case01/config.json)：

{
  "num_steps": 200,
  "dt": 1.0,
  "output_interval": 50
}

模拟结果将输出到 case01/output/ 目录，为 ASC 格式的水深栅格文件。

---

项目结构

MiniFlood/
├── pyproject.toml              # 现代构建配置（scikit-build-core）
├── CMakeLists.txt              # 顶层 CMake
├── miniflood/
│   ├── __init__.py
│   ├── version.py
│   ├── lib/flood/              # CUDA 核心 + pybind11 绑定
│   │   ├── flood_solver.cu     # CUDA 扩散求解器
│   │   ├── flood_solver.h
│   │   └── bindings/binding.cpp
│   ├── examples/               # 示例数据
│   ├── tests/                  # 单元测试
│   └── IO/                     # IO 工具
├── third_party/nlohmann_json/  # JSON 解析头文件库
└── python/run.py               # 示例启动脚本

---

打包发布

# 1. 构建 wheel + sdist（会自动检测 CUDA）
pip install build
python -m build

# 2. 上传到 PyPI
pip install twine
twine upload dist/*

跨平台说明

• sdist（源码包）：dist/miniflood-*.tar.gz 是跨平台的，Linux/macOS/Windows 均可 pip install 从源码编译
• wheel（二进制包）：dist/miniflood-*-win_amd64.whl 绑定当前平台，需在各目标平台分别构建
• 在 Linux 上构建：克隆仓库 → 安装 CUDA Toolkit → pip install .

CUDA 检测

构建时自动检测 CUDA，优先级：

1. 环境变量 CUDAToolkit_ROOT（如 C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.4）
2. CMake find_package(CUDAToolkit) 自动搜索标准路径
3. 未检测到则编译 CPU stub（运行时有明确提示）

---

技术栈

层面	技术
计算核心	CUDA C++
Python 绑定	pybind11
配置解析	nlohmann/json
构建系统	CMake + scikit-build-core
打包规范	PEP 517 / PEP 621