Metadata-Version: 2.2
Name: miniflood
Version: 2.1.0
Summary: A simplified 2D flood diffusion model with GPU acceleration
Author-Email: wang longyang <451215954@qq.com>
License: GPL-3.0-or-later
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: C++
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: GIS
Project-URL: Homepage, https://github.com/user/miniflood
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# MiniFlood

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

---

## 构建与安装

### 前置条件

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

### 安装方式

```bash
# 方式一：从源码安装（推荐）
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**：

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

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

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

---

## 使用示例

```python
from miniflood import flood

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

案例配置 (`case01/config.json`)：
```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               # 示例启动脚本
```

---

## 打包发布

```bash
# 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 |