Xinanjiang Hydrological Model Implementation

A Python implementation of the Xinanjiang (XAJ) rainfall-runoff model for hydrological forecasting and water resource management. This project includes both daily and flood event (sub-hourly) model implementations.

Overview

The Xinanjiang model is a conceptual hydrological model developed in China, widely used for:

Flood forecasting in humid and semi-humid regions
Water resource assessment and planning
Rainfall-runoff simulation at various temporal scales

This implementation features:

🌧️ Daily Model: Long-term water balance simulation
⛈️ Flood Event Model: Sub-hourly simulation for detailed flood analysis
📊 Visualization Tools: Publication-ready figures with error metrics
🔧 Data Preprocessing: Utilities for data preparation

Model Structure

┌─────────────────────────────────────────────────────────────┐
│                    Precipitation (P)                        │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│              Three-Layer Evapotranspiration                 │
│   ┌─────────┐   ┌─────────┐   ┌─────────┐                  │
│   │  Upper  │   │  Lower  │   │  Deep   │                  │
│   │  Layer  │   │  Layer  │   │  Layer  │                  │
│   │  (WU)   │   │  (WL)   │   │  (WD)   │                  │
│   └─────────┘   └─────────┘   └─────────┘                  │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│              Runoff Generation (Saturation Excess)          │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                 Three-Source Separation                      │
│   ┌─────────┐   ┌─────────┐   ┌─────────┐                  │
│   │ Surface │   │Interflow│   │Groundwa-│                  │
│   │  (RS)   │   │  (RI)   │   │ter (RG) │                  │
│   └─────────┘   └─────────┘   └─────────┘                  │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    Flow Routing                              │
│         Linear Reservoir + Muskingum Method                 │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
                    Outlet Discharge (Q)

Project Structure

hydro_prediction/
├── src/                          # Source code
│   ├── daily_model.py           # Daily model implementation
│   ├── daily_model_plot.py      # Daily model visualization
│   ├── flood_event_model.py     # Flood event model implementation
│   ├── flood_event_plot.py      # Flood event visualization
│   ├── error_calculation.py     # Error metrics calculation
│   └── data_preprocessing.py    # Data preprocessing utilities
├── data/                         # Input data
│   ├── daily/                   # Daily model input data
│   └── flood_events/            # Flood event data (1-15)
├── output/                       # Model outputs
│   ├── daily_model/             # Daily model results
│   ├── flood_model/             # Flood event results
│   └── figures/                 # Generated figures
├── docs/                         # Documentation
│   └── REPORT.md                # Technical report (English)
├── reference/                    # Reference materials
├── requirements.txt              # Python dependencies
└── README.md                     # This file

Installation

Clone the repository:

git clone https://github.com/yourusername/xinanjiang-model.git
cd xinanjiang-model

Create a virtual environment (recommended):

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install dependencies:
```
pip install -r requirements.txt
```

Usage

Daily Model

from src.daily_model import calculate_daily_model
from src.daily_model_plot import plot_daily_results

# Run the model
calculate_daily_model(
    input_file="data/daily/day_data.xlsx",
    output_file="output/daily_model/day_data_results.xlsx"
)

# Visualize results
plot_daily_results(
    input_file="output/daily_model/day_data_results.xlsx",
    output_dir="output/figures"
)

Flood Event Model

from src.flood_event_model import run_flood_model, plot_flood_results

# Run model for flood event 4
run_flood_model(
    flood_event_id=4,
    input_dir="data/flood_events",
    output_dir="output/flood_model"
)

# Generate visualization
plot_flood_results(
    flood_event_id=4,
    output_dir="output/flood_model",
    figure_dir="output/figures"
)

Model Parameters

Evapotranspiration Parameters

Parameter	Description	Typical Range
K	Pan coefficient	0.8 - 1.0
WUM	Upper layer capacity (mm)	10 - 30
WLM	Lower layer capacity (mm)	50 - 90
WDM	Deep layer capacity (mm)	30 - 50
C	Deep layer ET coefficient	0.1 - 0.2

Runoff Generation Parameters

Parameter	Description	Typical Range
b	Tension water curve exponent	0.1 - 0.4
IM	Impervious area ratio	0.01 - 0.05
Sm	Free water capacity (mm)	10 - 50
EX	Free water curve exponent	1.0 - 2.0

Flow Routing Parameters

Parameter	Description	Typical Range
KG	Groundwater coefficient	0.2 - 0.7
KI	Interflow coefficient	0.3 - 0.5
CG	Groundwater recession	0.95 - 0.99
CI	Interflow recession	0.3 - 0.8
CS	Channel routing coefficient	0.3 - 0.9

Evaluation Metrics

The model performance is evaluated using:

Runoff Depth Error (%): Overall water balance error
Nash-Sutcliffe Efficiency (NSE): Measure of predictive power (optimal = 1)
Peak Flow Error (%): Accuracy of peak discharge prediction
Peak Time Lag (hours): Timing accuracy of flood peaks

Study Area

The model was applied to the Chengcun Watershed in China, featuring:

Total catchment area: ~290 km²
10 sub-catchments with individual monitoring stations
Multi-year daily data (1989-1996)
15 historical flood events

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Original Xinanjiang model developed by Prof. Zhao Renjun
Hydrological data provided by local water resources bureau

新安江水文模型实现

新安江降雨-径流模型的Python实现，用于水文预报和水资源管理。本项目包含日模型和次洪（小时尺度）模型两种实现。

概述

新安江模型是一种在中国广泛应用的概念性水文模型，主要用于：

洪水预报：适用于湿润和半湿润地区
水资源评估：水资源规划与管理
降雨-径流模拟：多时间尺度的水文过程模拟

本实现的特点：

🌧️ 日模型：长期水量平衡模拟
⛈️ 次洪模型：小时尺度的详细洪水分析
📊 可视化工具：生成出版级别的图表，包含误差指标
🔧 数据预处理：数据准备工具

模型结构

┌─────────────────────────────────────────────────────────────┐
│                       降水量 (P)                             │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    三层蒸散发计算                            │
│   ┌─────────┐   ┌─────────┐   ┌─────────┐                  │
│   │  上层   │   │  下层   │   │  深层   │                  │
│   │  (WU)   │   │  (WL)   │   │  (WD)   │                  │
│   └─────────┘   └─────────┘   └─────────┘                  │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                  产流计算（蓄满产流）                         │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                      三水源划分                              │
│   ┌─────────┐   ┌─────────┐   ┌─────────┐                  │
│   │ 地表径流│   │  壤中流 │   │ 地下径流│                  │
│   │  (RS)   │   │  (RI)   │   │  (RG)   │                  │
│   └─────────┘   └─────────┘   └─────────┘                  │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                        汇流演算                              │
│            线性水库法 + 马斯京根法                           │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
                      出口断面流量 (Q)

项目结构

hydro_prediction/
├── src/                          # 源代码
│   ├── daily_model.py           # 日模型实现
│   ├── daily_model_plot.py      # 日模型可视化
│   ├── flood_event_model.py     # 次洪模型实现
│   ├── flood_event_plot.py      # 次洪模型可视化
│   ├── error_calculation.py     # 误差计算模块
│   └── data_preprocessing.py    # 数据预处理工具
├── data/                         # 输入数据
│   ├── daily/                   # 日模型输入数据
│   └── flood_events/            # 次洪数据（1-15场）
├── output/                       # 模型输出
│   ├── daily_model/             # 日模型结果
│   ├── flood_model/             # 次洪模型结果
│   └── figures/                 # 生成的图表
├── docs/                         # 文档
│   └── REPORT.md                # 技术报告（英文）
├── reference/                    # 参考资料
├── requirements.txt              # Python依赖
└── README.md                     # 本文件

安装

克隆仓库：

git clone https://github.com/yourusername/xinanjiang-model.git
cd xinanjiang-model

创建虚拟环境（推荐）：

python -m venv venv
source venv/bin/activate  # Windows系统: venv\Scripts\activate

安装依赖：
```
pip install -r requirements.txt
```

使用方法

日模型

from src.daily_model import calculate_daily_model
from src.daily_model_plot import plot_daily_results

# 运行模型
calculate_daily_model(
    input_file="data/daily/day_data.xlsx",
    output_file="output/daily_model/day_data_results.xlsx"
)

# 可视化结果
plot_daily_results(
    input_file="output/daily_model/day_data_results.xlsx",
    output_dir="output/figures"
)

次洪模型

from src.flood_event_model import run_flood_model, plot_flood_results

# 运行第4场洪水模型
run_flood_model(
    flood_event_id=4,
    input_dir="data/flood_events",
    output_dir="output/flood_model"
)

# 生成可视化图
plot_flood_results(
    flood_event_id=4,
    output_dir="output/flood_model",
    figure_dir="output/figures"
)

模型参数

蒸散发参数

参数	描述	典型取值范围
K	蒸发皿折算系数	0.8 - 1.0
WUM	上层蓄水容量 (mm)	10 - 30
WLM	下层蓄水容量 (mm)	50 - 90
WDM	深层蓄水容量 (mm)	30 - 50
C	深层蒸散发系数	0.1 - 0.2

产流参数

参数	描述	典型取值范围
b	张力水蓄水容量曲线指数	0.1 - 0.4
IM	不透水面积比例	0.01 - 0.05
Sm	自由水蓄水容量 (mm)	10 - 50
EX	自由水蓄水容量曲线指数	1.0 - 2.0

汇流参数

参数	描述	典型取值范围
KG	地下水出流系数	0.2 - 0.7
KI	壤中流出流系数	0.3 - 0.5
CG	地下水消退系数	0.95 - 0.99
CI	壤中流消退系数	0.3 - 0.8
CS	河道汇流系数	0.3 - 0.9

评价指标

模型性能通过以下指标评价：

径流深误差 (%)：总体水量平衡误差
Nash-Sutcliffe效率系数 (NSE)：模型预测能力（最优值=1）
洪峰相对误差 (%)：洪峰流量预测精度
洪峰滞时 (小时)：洪峰时间预测精度

研究区域

模型应用于中国呈村流域，具有以下特征：

流域总面积：约290 km²
10个子流域，各设有监测站
多年日资料（1989-1996年）
15场历史洪水事件

许可证

本项目采用MIT许可证 - 详见 LICENSE 文件。

致谢

新安江模型由赵人俊教授原创开发
水文数据由当地水资源局提供

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
data		data
docs		docs
output		output
reference		reference
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
requirements.txt		requirements.txt

License

ibnode/Xinanjiang-Model

Folders and files

Latest commit

History

Repository files navigation

Xinanjiang Hydrological Model Implementation

Overview

Model Structure

Project Structure

Installation

Usage

Daily Model

Flood Event Model

Model Parameters

Evapotranspiration Parameters

Runoff Generation Parameters

Flow Routing Parameters

Evaluation Metrics

Study Area

License

Acknowledgments

新安江水文模型实现

概述

模型结构

项目结构

安装

使用方法

日模型

次洪模型

模型参数

蒸散发参数

产流参数

汇流参数

评价指标

研究区域

许可证

致谢

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages