cwatqim 0.1.1

Crop-Water Quota Irrigation Model - ABM for Yellow River water allocation

CWatQIM: Crop-Water Quota Irrigation Model

An agent-based model (ABM) for simulating water quota allocation and irrigation decisions in China's Yellow River Basin.

Overview

CWatQIM (Crop-Water Quota Irrigation Model) is a agent-based 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.

Key Features

• Multi-scale agents: Province-level and prefecture-level (city) agents representing water management agencies
• Crop modeling integration: Built-in integration with AquaCrop for crop yield simulation
• Social learning mechanisms: Implements Standing strategy (evolutionary game theory) for behavioral adaptation
• Policy analysis: Enables counterfactual analysis to assess policy effects under different enforcement regimes

Installation

From GitHub (Recommended)

Clone the repository to get the full model with configurations:

git clone https://github.com/SongshGeoLab/CWatQIM.git
cd CWatQIM
pip install -e .

From PyPI

pip install cwatqim

Publication

This model is published on:

• Zenodo: [DOI link will be added after first release]
• CoMSES Net: [Link will be added after submission]

For citation and archival purposes, please use the Zenodo DOI.

Quick Start

After cloning the repository, run the model from the repository root:

# Run with default configuration
python -m cwatqim

# Override configuration parameters
python -m cwatqim exp.repeats=5 exp.num_process=4

# Use a different dataset configuration
python -m cwatqim ds=mac

Using Python API

from cwatqim import CWatQIModel
from hydra import compose, initialize

# Initialize configuration (from config/ directory in repository)
with initialize(config_path="config", version_base=None):
    cfg = compose(config_name="config")

    # Create and run model
    model = CWatQIModel(parameters=cfg)
    model.setup()

    # Run simulation
    for _ in range(10):
        model.step()

    model.end()

Configuration

The repository includes Hydra configurations in the config/ directory:

• config/config.yaml: Main configuration with model parameters
• config/ds/default.yaml: Default dataset paths (uses relative paths)
• config/ds/mac.yaml: macOS-specific paths (for local development)
• config/exp/test.yaml: Test experiment configuration
• config/exp/exp.yaml: Full experiment configuration

You can override any configuration parameter via command line arguments or create your own configuration files.

Model Components

Agents

• Province: Province-level agents managing water quota allocation
• City: Prefecture-level agents making irrigation water withdrawal decisions
• Farmer: Individual farmer agents (optional, for future extensions)

Core Modules

• CWatQIModel: Main model class orchestrating the simulation
• Algorithms: Optimization algorithms for water source portfolio decisions
• Data Loaders: Utilities for loading climate, quota, and agricultural data
• Payoff: Economic and social payoff calculations

Documentation

• ODD+D Protocol - Complete model description following the ODD+D protocol
• CHANGELOG - Version history and release notes
• API Reference - Full API documentation

Requirements

• Python >=3.11, <3.12
• See pyproject.toml for full dependency list

Citation

If you use this model in your research, please cite:

@software{cwatqim2026,
  title = {CWatQIM: Crop-Water Quota Irrigation Model},
  author = {Song, Shuang},
  year = {2026},
  url = {https://github.com/SongshGeoLab/CWatQIM},
  doi = {10.5281/zenodo.XXXXXXX}
}

Note: Please replace XXXXXXX with the actual Zenodo DOI after the first release.

License

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

Acknowledgments

• Supported by National Natural Science Foundation of China (No. 42041007, No. U2243601)
• Built on the ABSESpy framework
• Integrates with AquaCrop for crop modeling

Contact

• Author: Shuang Song
• Email: [e-mail]
• GitHub: @SongshGeo
• Website: https://cv.songshgeo.com/