cwatqim 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- cwatqim-0.1.0/.github/workflows/release.yml +151 -0
- cwatqim-0.1.0/.zenodo.json +37 -0
- cwatqim-0.1.0/CHANGELOG.md +20 -0
- cwatqim-0.1.0/CITATION.cff +24 -0
- cwatqim-0.1.0/PKG-INFO +189 -0
- cwatqim-0.1.0/README.md +154 -0
- cwatqim-0.1.0/__init__.py +58 -0
- cwatqim-0.1.0/__main__.py +81 -0
- cwatqim-0.1.0/agents/__init__.py +28 -0
- cwatqim-0.1.0/agents/city.py +1572 -0
- cwatqim-0.1.0/agents/province.py +391 -0
- cwatqim-0.1.0/core/__init__.py +50 -0
- cwatqim-0.1.0/core/algorithms.py +173 -0
- cwatqim-0.1.0/core/data_loaders.py +276 -0
- cwatqim-0.1.0/core/payoff.py +448 -0
- cwatqim-0.1.0/docs/ODD+D.md +141 -0
- cwatqim-0.1.0/model/__init__.py +18 -0
- cwatqim-0.1.0/model/main.py +297 -0
- cwatqim-0.1.0/pyproject.toml +68 -0
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
# Release workflow for CWatQIM public repository
|
|
2
|
+
# Handles: Auto-tagging, GitHub Release creation, PyPI publishing
|
|
3
|
+
#
|
|
4
|
+
# NOTE: This workflow does NOT modify any files.
|
|
5
|
+
# Version management is handled in the private repository.
|
|
6
|
+
# This workflow only creates tags and releases when it detects a version change.
|
|
7
|
+
|
|
8
|
+
name: Release
|
|
9
|
+
|
|
10
|
+
on:
|
|
11
|
+
push:
|
|
12
|
+
branches:
|
|
13
|
+
- main
|
|
14
|
+
|
|
15
|
+
permissions:
|
|
16
|
+
contents: write
|
|
17
|
+
|
|
18
|
+
jobs:
|
|
19
|
+
check-version:
|
|
20
|
+
runs-on: ubuntu-latest
|
|
21
|
+
outputs:
|
|
22
|
+
version: ${{ steps.get_version.outputs.version }}
|
|
23
|
+
tag_exists: ${{ steps.check_tag.outputs.exists }}
|
|
24
|
+
should_release: ${{ steps.check_tag.outputs.should_release }}
|
|
25
|
+
steps:
|
|
26
|
+
- uses: actions/checkout@v4
|
|
27
|
+
with:
|
|
28
|
+
fetch-depth: 0 # Need full history for tag checking
|
|
29
|
+
|
|
30
|
+
- name: Get version from __init__.py
|
|
31
|
+
id: get_version
|
|
32
|
+
run: |
|
|
33
|
+
VERSION=$(grep -oP '__version__\s*=\s*"\K[^"]+' __init__.py)
|
|
34
|
+
echo "version=$VERSION" >> $GITHUB_OUTPUT
|
|
35
|
+
echo "Detected version: $VERSION"
|
|
36
|
+
|
|
37
|
+
- name: Check if tag exists
|
|
38
|
+
id: check_tag
|
|
39
|
+
run: |
|
|
40
|
+
VERSION="${{ steps.get_version.outputs.version }}"
|
|
41
|
+
TAG="v${VERSION}"
|
|
42
|
+
|
|
43
|
+
if git rev-parse "refs/tags/${TAG}" >/dev/null 2>&1; then
|
|
44
|
+
echo "Tag ${TAG} already exists"
|
|
45
|
+
echo "exists=true" >> $GITHUB_OUTPUT
|
|
46
|
+
echo "should_release=false" >> $GITHUB_OUTPUT
|
|
47
|
+
else
|
|
48
|
+
echo "Tag ${TAG} does not exist, will create release"
|
|
49
|
+
echo "exists=false" >> $GITHUB_OUTPUT
|
|
50
|
+
echo "should_release=true" >> $GITHUB_OUTPUT
|
|
51
|
+
fi
|
|
52
|
+
|
|
53
|
+
create-release:
|
|
54
|
+
needs: check-version
|
|
55
|
+
if: needs.check-version.outputs.should_release == 'true'
|
|
56
|
+
runs-on: ubuntu-latest
|
|
57
|
+
outputs:
|
|
58
|
+
tag_name: ${{ steps.create_tag.outputs.tag_name }}
|
|
59
|
+
steps:
|
|
60
|
+
- uses: actions/checkout@v4
|
|
61
|
+
|
|
62
|
+
- name: Create and push tag
|
|
63
|
+
id: create_tag
|
|
64
|
+
env:
|
|
65
|
+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
|
66
|
+
run: |
|
|
67
|
+
VERSION="${{ needs.check-version.outputs.version }}"
|
|
68
|
+
TAG="v${VERSION}"
|
|
69
|
+
|
|
70
|
+
git config user.name "github-actions[bot]"
|
|
71
|
+
git config user.email "github-actions[bot]@users.noreply.github.com"
|
|
72
|
+
|
|
73
|
+
# Create annotated tag
|
|
74
|
+
git tag -a "${TAG}" -m "Release ${TAG}"
|
|
75
|
+
git push origin "${TAG}"
|
|
76
|
+
|
|
77
|
+
echo "tag_name=${TAG}" >> $GITHUB_OUTPUT
|
|
78
|
+
echo "Created and pushed tag: ${TAG}"
|
|
79
|
+
|
|
80
|
+
- name: Extract changelog for this version
|
|
81
|
+
id: changelog
|
|
82
|
+
run: |
|
|
83
|
+
VERSION="${{ needs.check-version.outputs.version }}"
|
|
84
|
+
|
|
85
|
+
# Extract the changelog section for this version
|
|
86
|
+
# Looks for ## [VERSION] and extracts until the next ## or end of file
|
|
87
|
+
CHANGELOG=$(awk -v ver="$VERSION" '
|
|
88
|
+
/^## \[/ {
|
|
89
|
+
if (found) exit
|
|
90
|
+
if (index($0, "[" ver "]")) found=1
|
|
91
|
+
}
|
|
92
|
+
found && !/^## \[/ { print }
|
|
93
|
+
' CHANGELOG.md)
|
|
94
|
+
|
|
95
|
+
# If no changelog found, use a default message
|
|
96
|
+
if [ -z "$CHANGELOG" ]; then
|
|
97
|
+
CHANGELOG="Release version ${VERSION}"
|
|
98
|
+
fi
|
|
99
|
+
|
|
100
|
+
# Save to file for multi-line output
|
|
101
|
+
echo "$CHANGELOG" > /tmp/changelog.md
|
|
102
|
+
echo "Extracted changelog for version ${VERSION}"
|
|
103
|
+
|
|
104
|
+
- name: Create GitHub Release
|
|
105
|
+
env:
|
|
106
|
+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
|
107
|
+
run: |
|
|
108
|
+
TAG="${{ steps.create_tag.outputs.tag_name }}"
|
|
109
|
+
|
|
110
|
+
gh release create "${TAG}" \
|
|
111
|
+
--title "Release ${TAG}" \
|
|
112
|
+
--notes-file /tmp/changelog.md
|
|
113
|
+
|
|
114
|
+
publish-pypi:
|
|
115
|
+
needs: [check-version, create-release]
|
|
116
|
+
if: needs.check-version.outputs.should_release == 'true'
|
|
117
|
+
runs-on: ubuntu-latest
|
|
118
|
+
steps:
|
|
119
|
+
- uses: actions/checkout@v4
|
|
120
|
+
with:
|
|
121
|
+
ref: ${{ needs.create-release.outputs.tag_name }}
|
|
122
|
+
|
|
123
|
+
- name: Set up Python
|
|
124
|
+
uses: actions/setup-python@v5
|
|
125
|
+
with:
|
|
126
|
+
python-version: '3.11'
|
|
127
|
+
|
|
128
|
+
- name: Install build dependencies
|
|
129
|
+
run: |
|
|
130
|
+
python -m pip install --upgrade pip
|
|
131
|
+
pip install build twine
|
|
132
|
+
|
|
133
|
+
- name: Build package
|
|
134
|
+
run: python -m build
|
|
135
|
+
|
|
136
|
+
- name: Publish to PyPI
|
|
137
|
+
env:
|
|
138
|
+
TWINE_USERNAME: __token__
|
|
139
|
+
TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
|
|
140
|
+
run: twine upload dist/*
|
|
141
|
+
|
|
142
|
+
notify-release:
|
|
143
|
+
needs: [check-version, create-release, publish-pypi]
|
|
144
|
+
if: needs.check-version.outputs.should_release == 'true'
|
|
145
|
+
runs-on: ubuntu-latest
|
|
146
|
+
steps:
|
|
147
|
+
- name: Release notification
|
|
148
|
+
run: |
|
|
149
|
+
echo "🎉 Released version ${{ needs.check-version.outputs.version }}"
|
|
150
|
+
echo "Tag: ${{ needs.create-release.outputs.tag_name }}"
|
|
151
|
+
echo "Published to PyPI successfully"
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
{
|
|
2
|
+
"title": "CWatQIM: Crop-Water Quota Irrigation Model",
|
|
3
|
+
"description": "An agent-based model (ABM) for simulating water quota allocation and irrigation decisions in China's Yellow River Basin. The model investigates how water quota institutions shape irrigation water withdrawal decisions and their system-wide consequences, focusing on the mechanisms through which administrative water quotas influence water source composition (surface water versus groundwater), irrigation efficiency, and crop productivity.",
|
|
4
|
+
"upload_type": "software",
|
|
5
|
+
"creators": [
|
|
6
|
+
{
|
|
7
|
+
"name": "Song, Shuang",
|
|
8
|
+
"affiliation": "Peking University",
|
|
9
|
+
"orcid": "0000-0002-xxxx-xxxx"
|
|
10
|
+
}
|
|
11
|
+
],
|
|
12
|
+
"keywords": [
|
|
13
|
+
"agent-based model",
|
|
14
|
+
"water resources",
|
|
15
|
+
"Yellow River",
|
|
16
|
+
"irrigation",
|
|
17
|
+
"water quota",
|
|
18
|
+
"ABM",
|
|
19
|
+
"hydrology",
|
|
20
|
+
"multi-agent simulation"
|
|
21
|
+
],
|
|
22
|
+
"license": "MIT",
|
|
23
|
+
"access_right": "open",
|
|
24
|
+
"communities": [
|
|
25
|
+
{
|
|
26
|
+
"identifier": "comses"
|
|
27
|
+
}
|
|
28
|
+
],
|
|
29
|
+
"related_identifiers": [
|
|
30
|
+
{
|
|
31
|
+
"relation": "isSupplementTo",
|
|
32
|
+
"identifier": "10.xxxx/paper",
|
|
33
|
+
"resource_type": "publication-article"
|
|
34
|
+
}
|
|
35
|
+
],
|
|
36
|
+
"notes": "This model is developed and maintained as part of the water_quota research project. For the complete research codebase including analysis scripts, please contact the authors."
|
|
37
|
+
}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [0.1.0] - 2026-01-14
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- Initial release of CWatQIM (Crop-Water Quota Irrigation Model)
|
|
13
|
+
- Province-level water resource management agents
|
|
14
|
+
- City-level agricultural irrigation agents
|
|
15
|
+
- Water quota allocation mechanisms based on Yellow River "87 Agreement"
|
|
16
|
+
- Integration with ABSESpy framework for agent-based modeling
|
|
17
|
+
- Support for AquaCrop model integration via aquacrop-abses
|
|
18
|
+
- Climate data processing from ERA5 reanalysis
|
|
19
|
+
- Groundwater and surface water source switching logic
|
|
20
|
+
- Payoff calculation for irrigation decisions
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
cff-version: 1.2.0
|
|
2
|
+
message: "If you use this software, please cite it as below."
|
|
3
|
+
title: "CWatQIM: Crop-Water Quota Irrigation Model"
|
|
4
|
+
version: 0.1.1
|
|
5
|
+
date-released: 2026-01-14
|
|
6
|
+
doi: 10.5281/zenodo.XXXXXXX
|
|
7
|
+
authors:
|
|
8
|
+
- family-names: Song
|
|
9
|
+
given-names: Shuang
|
|
10
|
+
email: songshgeo@gmail.com
|
|
11
|
+
affiliation: Peking University
|
|
12
|
+
orcid: "https://orcid.org/0000-0002-xxxx-xxxx"
|
|
13
|
+
license: MIT
|
|
14
|
+
repository-code: "https://github.com/SongshGeoLab/CWatQIM"
|
|
15
|
+
keywords:
|
|
16
|
+
- "agent-based model"
|
|
17
|
+
- "water resources"
|
|
18
|
+
- "Yellow River"
|
|
19
|
+
- "irrigation"
|
|
20
|
+
- "water quota"
|
|
21
|
+
- "ABM"
|
|
22
|
+
- "hydrology"
|
|
23
|
+
- "multi-agent simulation"
|
|
24
|
+
abstract: "An agent-based model (ABM) for simulating water quota allocation and irrigation decisions in China's Yellow River Basin. The model investigates how water quota institutions shape irrigation water withdrawal decisions and their system-wide consequences, focusing on the mechanisms through which administrative water quotas influence water source composition (surface water versus groundwater), irrigation efficiency, and crop productivity."
|
cwatqim-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: cwatqim
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Crop-Water Quota Irrigation Model - ABM for Yellow River water allocation
|
|
5
|
+
Project-URL: Homepage, https://github.com/SongshGeoLab/CWatQIM
|
|
6
|
+
Project-URL: Documentation, https://github.com/SongshGeoLab/CWatQIM#readme
|
|
7
|
+
Project-URL: Repository, https://github.com/SongshGeoLab/CWatQIM
|
|
8
|
+
Project-URL: Issues, https://github.com/SongshGeoLab/CWatQIM/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/SongshGeoLab/CWatQIM/blob/main/CHANGELOG.md
|
|
10
|
+
Author-email: Shuang Song <songshgeo@gmail.com>
|
|
11
|
+
License: MIT
|
|
12
|
+
Keywords: ABM,Yellow River,agent-based model,hydrology,irrigation,water quota,water resources
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Topic :: Scientific/Engineering :: Hydrology
|
|
18
|
+
Requires-Python: <3.12,>=3.11
|
|
19
|
+
Requires-Dist: abses>=0.9.4
|
|
20
|
+
Requires-Dist: aquacrop-abses>=0.5.1
|
|
21
|
+
Requires-Dist: fiona>=1.9
|
|
22
|
+
Requires-Dist: geopandas>=0.14
|
|
23
|
+
Requires-Dist: hydra-core>=1.3
|
|
24
|
+
Requires-Dist: networkx>=3.0
|
|
25
|
+
Requires-Dist: numpy<2.2,>=1.24
|
|
26
|
+
Requires-Dist: pandas>=2.0
|
|
27
|
+
Requires-Dist: rasterio>=1.3
|
|
28
|
+
Requires-Dist: rioxarray>=0.13
|
|
29
|
+
Requires-Dist: xarray>=2023.1.0
|
|
30
|
+
Provides-Extra: dev
|
|
31
|
+
Requires-Dist: ipykernel>=6.21.2; extra == 'dev'
|
|
32
|
+
Requires-Dist: jupyterlab<5.0,>4.0; extra == 'dev'
|
|
33
|
+
Requires-Dist: pytest>=7.2.1; extra == 'dev'
|
|
34
|
+
Description-Content-Type: text/markdown
|
|
35
|
+
|
|
36
|
+
# CWatQIM: Crop-Water Quota Irrigation Model
|
|
37
|
+
|
|
38
|
+
[](https://github.com/SongshGeoLab/CWatQIM/releases)
|
|
39
|
+
[](https://doi.org/10.5281/zenodo.XXXXXXX)
|
|
40
|
+
[](LICENSE)
|
|
41
|
+
[](https://www.comses.net)
|
|
42
|
+
[](https://www.python.org/downloads/)
|
|
43
|
+
|
|
44
|
+
An agent-based model (ABM) for simulating water quota allocation and irrigation decisions in China's Yellow River Basin.
|
|
45
|
+
|
|
46
|
+
## Overview
|
|
47
|
+
|
|
48
|
+
CWatQIM (Crop-Water Quota Irrigation Model) is a multi-agent model that simulates the coupled human-water system in the Yellow River Basin. The model investigates how water quota institutions shape irrigation water withdrawal decisions and their system-wide consequences, focusing on the mechanisms through which administrative water quotas influence water source composition (surface water versus groundwater), irrigation efficiency, and crop productivity.
|
|
49
|
+
|
|
50
|
+
### Key Features
|
|
51
|
+
|
|
52
|
+
- **Multi-scale agents**: Province-level and prefecture-level (city) agents representing water management agencies
|
|
53
|
+
- **Crop modeling integration**: Built-in integration with AquaCrop for crop yield simulation
|
|
54
|
+
- **Social learning mechanisms**: Implements Standing strategy (evolutionary game theory) for behavioral adaptation
|
|
55
|
+
- **Policy analysis**: Enables counterfactual analysis to assess policy effects under different enforcement regimes
|
|
56
|
+
|
|
57
|
+
## Installation
|
|
58
|
+
|
|
59
|
+
### From GitHub (Recommended)
|
|
60
|
+
|
|
61
|
+
Clone the repository to get the full model with configurations:
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
git clone https://github.com/SongshGeoLab/CWatQIM.git
|
|
65
|
+
cd CWatQIM
|
|
66
|
+
pip install -e .
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### From PyPI
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
pip install cwatqim
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## Publication
|
|
76
|
+
|
|
77
|
+
This model is published on:
|
|
78
|
+
|
|
79
|
+
- **Zenodo**: [DOI link will be added after first release]
|
|
80
|
+
- **CoMSES Net**: [Link will be added after submission]
|
|
81
|
+
|
|
82
|
+
For citation and archival purposes, please use the Zenodo DOI.
|
|
83
|
+
|
|
84
|
+
## Quick Start
|
|
85
|
+
|
|
86
|
+
After cloning the repository, run the model from the repository root:
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
# Run with default configuration
|
|
90
|
+
python -m cwatqim
|
|
91
|
+
|
|
92
|
+
# Override configuration parameters
|
|
93
|
+
python -m cwatqim exp.repeats=5 exp.num_process=4
|
|
94
|
+
|
|
95
|
+
# Use a different dataset configuration
|
|
96
|
+
python -m cwatqim ds=mac
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### Using Python API
|
|
100
|
+
|
|
101
|
+
```python
|
|
102
|
+
from cwatqim import CWatQIModel
|
|
103
|
+
from hydra import compose, initialize
|
|
104
|
+
|
|
105
|
+
# Initialize configuration (from config/ directory in repository)
|
|
106
|
+
with initialize(config_path="config", version_base=None):
|
|
107
|
+
cfg = compose(config_name="config")
|
|
108
|
+
|
|
109
|
+
# Create and run model
|
|
110
|
+
model = CWatQIModel(parameters=cfg)
|
|
111
|
+
model.setup()
|
|
112
|
+
|
|
113
|
+
# Run simulation
|
|
114
|
+
for _ in range(10):
|
|
115
|
+
model.step()
|
|
116
|
+
|
|
117
|
+
model.end()
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
## Configuration
|
|
121
|
+
|
|
122
|
+
The repository includes Hydra configurations in the `config/` directory:
|
|
123
|
+
|
|
124
|
+
- **`config/config.yaml`**: Main configuration with model parameters
|
|
125
|
+
- **`config/ds/default.yaml`**: Default dataset paths (uses relative paths)
|
|
126
|
+
- **`config/ds/mac.yaml`**: macOS-specific paths (for local development)
|
|
127
|
+
- **`config/exp/test.yaml`**: Test experiment configuration
|
|
128
|
+
- **`config/exp/exp.yaml`**: Full experiment configuration
|
|
129
|
+
|
|
130
|
+
You can override any configuration parameter via command line arguments or create your own configuration files.
|
|
131
|
+
|
|
132
|
+
## Model Components
|
|
133
|
+
|
|
134
|
+
### Agents
|
|
135
|
+
|
|
136
|
+
- **Province**: Province-level agents managing water quota allocation
|
|
137
|
+
- **City**: Prefecture-level agents making irrigation water withdrawal decisions
|
|
138
|
+
- **Farmer**: Individual farmer agents (optional, for future extensions)
|
|
139
|
+
|
|
140
|
+
### Core Modules
|
|
141
|
+
|
|
142
|
+
- **CWatQIModel**: Main model class orchestrating the simulation
|
|
143
|
+
- **Algorithms**: Optimization algorithms for water source portfolio decisions
|
|
144
|
+
- **Data Loaders**: Utilities for loading climate, quota, and agricultural data
|
|
145
|
+
- **Payoff**: Economic and social payoff calculations
|
|
146
|
+
|
|
147
|
+
## Documentation
|
|
148
|
+
|
|
149
|
+
- [ODD+D Protocol](docs/ODD+D.md) - Complete model description following the ODD+D protocol
|
|
150
|
+
- [CHANGELOG](CHANGELOG.md) - Version history and release notes
|
|
151
|
+
- [API Reference](https://github.com/SongshGeoLab/CWatQIM) - Full API documentation
|
|
152
|
+
|
|
153
|
+
## Requirements
|
|
154
|
+
|
|
155
|
+
- Python >=3.11, <3.12
|
|
156
|
+
- See [pyproject.toml](pyproject.toml) for full dependency list
|
|
157
|
+
|
|
158
|
+
## Citation
|
|
159
|
+
|
|
160
|
+
If you use this model in your research, please cite:
|
|
161
|
+
|
|
162
|
+
```bibtex
|
|
163
|
+
@software{cwatqim2026,
|
|
164
|
+
title = {CWatQIM: Crop-Water Quota Irrigation Model},
|
|
165
|
+
author = {Song, Shuang},
|
|
166
|
+
year = {2026},
|
|
167
|
+
url = {https://github.com/SongshGeoLab/CWatQIM},
|
|
168
|
+
doi = {10.5281/zenodo.XXXXXXX}
|
|
169
|
+
}
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
> **Note**: Please replace `XXXXXXX` with the actual Zenodo DOI after the first release.
|
|
173
|
+
|
|
174
|
+
## License
|
|
175
|
+
|
|
176
|
+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
177
|
+
|
|
178
|
+
## Acknowledgments
|
|
179
|
+
|
|
180
|
+
- Supported by National Natural Science Foundation of China (No. 42041007, No. U2243601)
|
|
181
|
+
- Built on the [ABSESpy](https://github.com/AB-SES/absespy) framework
|
|
182
|
+
- Integrates with [AquaCrop](https://www.fao.org/aquacrop) for crop modeling
|
|
183
|
+
|
|
184
|
+
## Contact
|
|
185
|
+
|
|
186
|
+
- **Author**: Shuang Song
|
|
187
|
+
- **Email**: songshgeo@gmail.com
|
|
188
|
+
- **GitHub**: [@SongshGeo](https://github.com/SongshGeo)
|
|
189
|
+
- **Website**: [https://cv.songshgeo.com/](https://cv.songshgeo.com/)
|
cwatqim-0.1.0/README.md
ADDED
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
# CWatQIM: Crop-Water Quota Irrigation Model
|
|
2
|
+
|
|
3
|
+
[](https://github.com/SongshGeoLab/CWatQIM/releases)
|
|
4
|
+
[](https://doi.org/10.5281/zenodo.XXXXXXX)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
[](https://www.comses.net)
|
|
7
|
+
[](https://www.python.org/downloads/)
|
|
8
|
+
|
|
9
|
+
An agent-based model (ABM) for simulating water quota allocation and irrigation decisions in China's Yellow River Basin.
|
|
10
|
+
|
|
11
|
+
## Overview
|
|
12
|
+
|
|
13
|
+
CWatQIM (Crop-Water Quota Irrigation Model) is a multi-agent model that simulates the coupled human-water system in the Yellow River Basin. The model investigates how water quota institutions shape irrigation water withdrawal decisions and their system-wide consequences, focusing on the mechanisms through which administrative water quotas influence water source composition (surface water versus groundwater), irrigation efficiency, and crop productivity.
|
|
14
|
+
|
|
15
|
+
### Key Features
|
|
16
|
+
|
|
17
|
+
- **Multi-scale agents**: Province-level and prefecture-level (city) agents representing water management agencies
|
|
18
|
+
- **Crop modeling integration**: Built-in integration with AquaCrop for crop yield simulation
|
|
19
|
+
- **Social learning mechanisms**: Implements Standing strategy (evolutionary game theory) for behavioral adaptation
|
|
20
|
+
- **Policy analysis**: Enables counterfactual analysis to assess policy effects under different enforcement regimes
|
|
21
|
+
|
|
22
|
+
## Installation
|
|
23
|
+
|
|
24
|
+
### From GitHub (Recommended)
|
|
25
|
+
|
|
26
|
+
Clone the repository to get the full model with configurations:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
git clone https://github.com/SongshGeoLab/CWatQIM.git
|
|
30
|
+
cd CWatQIM
|
|
31
|
+
pip install -e .
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
### From PyPI
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
pip install cwatqim
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Publication
|
|
41
|
+
|
|
42
|
+
This model is published on:
|
|
43
|
+
|
|
44
|
+
- **Zenodo**: [DOI link will be added after first release]
|
|
45
|
+
- **CoMSES Net**: [Link will be added after submission]
|
|
46
|
+
|
|
47
|
+
For citation and archival purposes, please use the Zenodo DOI.
|
|
48
|
+
|
|
49
|
+
## Quick Start
|
|
50
|
+
|
|
51
|
+
After cloning the repository, run the model from the repository root:
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
# Run with default configuration
|
|
55
|
+
python -m cwatqim
|
|
56
|
+
|
|
57
|
+
# Override configuration parameters
|
|
58
|
+
python -m cwatqim exp.repeats=5 exp.num_process=4
|
|
59
|
+
|
|
60
|
+
# Use a different dataset configuration
|
|
61
|
+
python -m cwatqim ds=mac
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### Using Python API
|
|
65
|
+
|
|
66
|
+
```python
|
|
67
|
+
from cwatqim import CWatQIModel
|
|
68
|
+
from hydra import compose, initialize
|
|
69
|
+
|
|
70
|
+
# Initialize configuration (from config/ directory in repository)
|
|
71
|
+
with initialize(config_path="config", version_base=None):
|
|
72
|
+
cfg = compose(config_name="config")
|
|
73
|
+
|
|
74
|
+
# Create and run model
|
|
75
|
+
model = CWatQIModel(parameters=cfg)
|
|
76
|
+
model.setup()
|
|
77
|
+
|
|
78
|
+
# Run simulation
|
|
79
|
+
for _ in range(10):
|
|
80
|
+
model.step()
|
|
81
|
+
|
|
82
|
+
model.end()
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
## Configuration
|
|
86
|
+
|
|
87
|
+
The repository includes Hydra configurations in the `config/` directory:
|
|
88
|
+
|
|
89
|
+
- **`config/config.yaml`**: Main configuration with model parameters
|
|
90
|
+
- **`config/ds/default.yaml`**: Default dataset paths (uses relative paths)
|
|
91
|
+
- **`config/ds/mac.yaml`**: macOS-specific paths (for local development)
|
|
92
|
+
- **`config/exp/test.yaml`**: Test experiment configuration
|
|
93
|
+
- **`config/exp/exp.yaml`**: Full experiment configuration
|
|
94
|
+
|
|
95
|
+
You can override any configuration parameter via command line arguments or create your own configuration files.
|
|
96
|
+
|
|
97
|
+
## Model Components
|
|
98
|
+
|
|
99
|
+
### Agents
|
|
100
|
+
|
|
101
|
+
- **Province**: Province-level agents managing water quota allocation
|
|
102
|
+
- **City**: Prefecture-level agents making irrigation water withdrawal decisions
|
|
103
|
+
- **Farmer**: Individual farmer agents (optional, for future extensions)
|
|
104
|
+
|
|
105
|
+
### Core Modules
|
|
106
|
+
|
|
107
|
+
- **CWatQIModel**: Main model class orchestrating the simulation
|
|
108
|
+
- **Algorithms**: Optimization algorithms for water source portfolio decisions
|
|
109
|
+
- **Data Loaders**: Utilities for loading climate, quota, and agricultural data
|
|
110
|
+
- **Payoff**: Economic and social payoff calculations
|
|
111
|
+
|
|
112
|
+
## Documentation
|
|
113
|
+
|
|
114
|
+
- [ODD+D Protocol](docs/ODD+D.md) - Complete model description following the ODD+D protocol
|
|
115
|
+
- [CHANGELOG](CHANGELOG.md) - Version history and release notes
|
|
116
|
+
- [API Reference](https://github.com/SongshGeoLab/CWatQIM) - Full API documentation
|
|
117
|
+
|
|
118
|
+
## Requirements
|
|
119
|
+
|
|
120
|
+
- Python >=3.11, <3.12
|
|
121
|
+
- See [pyproject.toml](pyproject.toml) for full dependency list
|
|
122
|
+
|
|
123
|
+
## Citation
|
|
124
|
+
|
|
125
|
+
If you use this model in your research, please cite:
|
|
126
|
+
|
|
127
|
+
```bibtex
|
|
128
|
+
@software{cwatqim2026,
|
|
129
|
+
title = {CWatQIM: Crop-Water Quota Irrigation Model},
|
|
130
|
+
author = {Song, Shuang},
|
|
131
|
+
year = {2026},
|
|
132
|
+
url = {https://github.com/SongshGeoLab/CWatQIM},
|
|
133
|
+
doi = {10.5281/zenodo.XXXXXXX}
|
|
134
|
+
}
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
> **Note**: Please replace `XXXXXXX` with the actual Zenodo DOI after the first release.
|
|
138
|
+
|
|
139
|
+
## License
|
|
140
|
+
|
|
141
|
+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
142
|
+
|
|
143
|
+
## Acknowledgments
|
|
144
|
+
|
|
145
|
+
- Supported by National Natural Science Foundation of China (No. 42041007, No. U2243601)
|
|
146
|
+
- Built on the [ABSESpy](https://github.com/AB-SES/absespy) framework
|
|
147
|
+
- Integrates with [AquaCrop](https://www.fao.org/aquacrop) for crop modeling
|
|
148
|
+
|
|
149
|
+
## Contact
|
|
150
|
+
|
|
151
|
+
- **Author**: Shuang Song
|
|
152
|
+
- **Email**: songshgeo@gmail.com
|
|
153
|
+
- **GitHub**: [@SongshGeo](https://github.com/SongshGeo)
|
|
154
|
+
- **Website**: [https://cv.songshgeo.com/](https://cv.songshgeo.com/)
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
#!/usr/bin/env python 3.11.0
|
|
2
|
+
# -*-coding:utf-8 -*-
|
|
3
|
+
# @Author : Shuang (Twist) Song
|
|
4
|
+
# @Contact : SongshGeo@gmail.com
|
|
5
|
+
# GitHub : https://github.com/SongshGeo
|
|
6
|
+
# Website: https://cv.songshgeo.com/
|
|
7
|
+
|
|
8
|
+
"""Water Quota Incentive Model (CWatQIM) Package.
|
|
9
|
+
|
|
10
|
+
A multi-agent model for simulating Yellow River water quota allocation and
|
|
11
|
+
analyzing policy incentives. This package implements an agent-based model (ABM)
|
|
12
|
+
that simulates the interactions between provinces, cities, and farmers in the
|
|
13
|
+
Yellow River Basin, focusing on water quota compliance and social learning
|
|
14
|
+
mechanisms.
|
|
15
|
+
|
|
16
|
+
The model is built on the ABSESpy framework and integrates with AquaCrop for
|
|
17
|
+
crop yield simulation. It can be published independently as it contains only
|
|
18
|
+
the core model components without analysis dependencies.
|
|
19
|
+
|
|
20
|
+
Main Components:
|
|
21
|
+
- CWatQIModel: The main model class that orchestrates the simulation
|
|
22
|
+
- City: City-level agents representing irrigation units
|
|
23
|
+
- Province: Province-level agents managing water quota allocation
|
|
24
|
+
- Core utilities: Algorithms, data loaders, and payoff calculations
|
|
25
|
+
|
|
26
|
+
Example:
|
|
27
|
+
Basic usage of the model:
|
|
28
|
+
|
|
29
|
+
```python
|
|
30
|
+
from cwatqim import CWatQIModel
|
|
31
|
+
from hydra import compose, initialize
|
|
32
|
+
|
|
33
|
+
with initialize(config_path="config"):
|
|
34
|
+
cfg = compose(config_name="config")
|
|
35
|
+
model = CWatQIModel(parameters=cfg)
|
|
36
|
+
model.setup()
|
|
37
|
+
for _ in range(10):
|
|
38
|
+
model.step()
|
|
39
|
+
model.end()
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Note:
|
|
43
|
+
This package is designed to be independent of analysis tools. For result
|
|
44
|
+
analysis, use the separate `water_quota_analysis` package.
|
|
45
|
+
"""
|
|
46
|
+
|
|
47
|
+
from .agents import City, Farmer, Province
|
|
48
|
+
from .model import CWatQIModel
|
|
49
|
+
|
|
50
|
+
__all__ = [
|
|
51
|
+
"City",
|
|
52
|
+
"Farmer",
|
|
53
|
+
"Province",
|
|
54
|
+
"Experiment",
|
|
55
|
+
"CWatQIModel",
|
|
56
|
+
]
|
|
57
|
+
|
|
58
|
+
__version__ = "0.1.0"
|