Skip to content

Commit

Permalink
update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@philip928lin
philip928lin committed Nov 3, 2024
1 parent b499af5 commit 0b132f1
Show file tree
Hide file tree
Showing 2 changed files with 18 additions and 20 deletions.
36 changes: 17 additions & 19 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,42 +1,38 @@
[![Documentation Status](https://readthedocs.org/projects/hydrocnhs/badge/?version=latest)](https://hydrocnhs.readthedocs.io)

[![Docs](https://github.com/philip928lin/PathNavigator/actions/workflows/docs.yml/badge.svg)](philip928lin.github.io/HydroCNHS/)

# HydroCNHS
A Python Package of Hydrological Model for Coupled Natural–Human Systems

<img src="https://github.com/philip928lin/HydroCNHS/blob/main/docs/source/figs/fig3_hydrocnhs.png" alt="Complex Adaptive Water System" width="500"/>

Modeling Coupled Natural–Human Systems (CNHS) to inform comprehensive water resources management policies or describe hydrological cycles in the Anthropocene has become popular in recent years. To fulfill this need, we developed a semi-distributed Hydrological model for Coupled Natural–Human Systems, HydroCNHS. The HydroCNHS is an open-source Python package supporting four Application Programming Interfaces (APIs) that enable users to integrate their human decision models, which can be programmed with the agent-based modeling concept, into the HydroCNHS. Specifically, we design Dam API, RiverDiv API, Conveying API, and InSitu API to integrate, respectively, customized man-made infrastructures such as reservoirs, off-stream diversions, trans-basin aqueducts, and drainage systems that abstract human behaviors (e.g., operator and farmers’ water use decisions). Each of the HydroCNHS APIs has a unique plug-in structure that respects within-subbasin and inter-subbasin (i.e., river) routing logic for maintaining the water balance. In addition, the HydroCNHS uses a single model configuration file to organize input features for the hydrological model and case-specific human systems models. Also, HydroCNHS enables the model calibration using parallel computing power. We demonstrate the functionalities of the HydroCNHS package through a case study in the Northwest United States. Given the integrity of the modeling framework, HydroCNHS can benefit water resources planning and management in various aspects, including the uncertainty analysis in CNHS modeling and more complex agent design.
Modeling Coupled Natural–Human Systems (CNHS) to inform comprehensive water resources management policies or describe hydrological cycles in the Anthropocene has become popular in recent years. To fulfill this need, we developed a semi-distributed Hydrological model for Coupled Natural–Human Systems, HydroCNHS. HydroCNHS is an open-source Python package supporting four Application Programming Interfaces (APIs) that enable users to integrate their human decision models, which can be programmed with the agent-based modeling concept, into HydroCNHS. Specifically, we designed the Dam API, RiverDiv API, Conveying API, and InSitu API to integrate, respectively, customized man-made infrastructures such as reservoirs, off-stream diversions, trans-basin aqueducts, and drainage systems that abstract human behaviors (e.g., operator and farmers’ water use decisions). Each of the HydroCNHS APIs has a unique plug-in structure that respects within-subbasin and inter-subbasin (i.e., river) routing logic for maintaining the water balance. In addition, HydroCNHS uses a single model configuration file to organize input features for the hydrological model and case-specific human systems models. Also, HydroCNHS enables model calibration using parallel computing power. We demonstrate the functionalities of the HydroCNHS package through a case study in the Northwest United States. Given the integrity of the modeling framework, HydroCNHS can benefit water resources planning and management in various aspects, including uncertainty analysis in CNHS modeling and more complex agent design.


## Install
Install HydroCNHS by *pip*.
Install HydroCNHS using *pip*:
```
pip install hydrocnhs
```
To install the latest version (recommend) of HydroCNHS, users can (1) install HydroCNHS by *git*.
To install the latest version (recommended) of HydroCNHS, users can (1) install HydroCNHS using *git*:
```
pip install git+https://github.com/philip928lin/HydroCNHS.git
```
Or, (2) download the HydroCNHS package directly from the HydroCNHS GitHub repository. Then, install HydroCNHS from the *setup.py*.
```
# Need to move to the folder containing setup.py first.
python setup.py install
Or, (2) download the HydroCNHS package directly from the HydroCNHS GitHub repository.
```
If you fail to install HydroCNHS due to the DEAP package, first downgrade setuptools to 57 and try to install HydroCNHS again.
```
pip install setuptools==57
# Move to the HydroCNHS folder, then.
# "-e" will create an edible soft link.
pip install -e .
```

## User Manual & Example
Click [![Documentation Status](https://readthedocs.org/projects/hydrocnhs/badge/?version=latest)](https://hydrocnhs.readthedocs.io)
[![Docs](https://github.com/philip928lin/PathNavigator/actions/workflows/docs.yml/badge.svg)](philip928lin.github.io/HydroCNHS/)

## When should you use HydroCNHS?
1. Want to build a hydrological model with auto-parameter-tuning (calibration) features.
2. Want to add human components into a hydrological model under a unified framework without worrying about routing logic.
3. Want to calibrate the entire integrated model (hydrological + ABM modules) with customized agents' parameters.
4. Want to design human behaviors with a high degree of freedom, including coupling with external software.
5. Want to conduct extensive numerical experiments to test various human behavioral designs (i.e., integrating and testing many ABM modules).
1. Want to build a hydrological model with auto-parameter-tuning (calibration) features.
2. Want to add human components into a hydrological model under a unified framework without worrying about routing logic.
3. Want to calibrate the entire integrated model (hydrological + ABM modules) with customized agents' parameters.
4. Want to design human behaviors with a high degree of freedom, including coupling with external software.
5. Want to conduct extensive numerical experiments to test various human behavioral designs (i.e., integrating and testing many ABM modules).

## Feature highlights
- Built-in genetic algorithm calibration module that can utilize parallel computing power.
Expand All @@ -60,10 +56,12 @@ Link to human actions that convey water beyond basin boundaries and gravitationa
Link to human actions that locally alter the runoff in a subbasin, e.g., drainage systems, urbanization, and water diversion from wells or local streams (within-subbasin).


Those human/agent actions can be modeled with various complexities according to users' ABM design. Actions can simply be an inputted daily time series or governed by complex endogenous behavior rules (i.e., decision-making rules). Institutional decisions (a group of agents making decisions together with institutional rules) are allowed in HydroCNHS. Users require to have some level of object-oriented programing concept to design an ABM module (*.py*).
Those human/agent actions can be modeled with various complexities according to users' ABM design. Actions can simply be an inputted daily time series or governed by complex endogenous behavior rules (i.e., decision-making rules). Institutional decisions (a group of agents making decisions together with institutional rules) are allowed in HydroCNHS. Users are required to have some level of object-oriented programming concept to design an ABM module (*.py*).

## How to cite?
Lin, C. Y., Yang, Y. C. E., & Wi S. (2022). [HydroCNHS: A Python Package of Hydrological Model for Coupled Natural Human Systems](https://doi.org/10.1061/(ASCE)WR.1943-5452.0001630), Journal of Water Resources Planning and Management, 148(12), 6022005.

## Related studies
Lin, C. Y., & Yang, Y. E. (2022). [The effects of model complexity on model output uncertainty in co‐evolved coupled natural–human systems](https://doi.org/10.1029/2021EF002403). Earth's Future, e2021EF002403.

Lin, C.-Y., Yang, Y. E., & Chaudhary, A. K. (2023). [Pay-for-practice or Pay-for-performance? A coupled agent-based evaluation tool for assessing sediment management incentive policies](https://doi.org/10.1016/j.jhydrol.2023.129959). Journal of Hydrology, 624, 129959.
2 changes: 1 addition & 1 deletion docs/source/files/2_installation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ To install the latest version (beta version) of `HydroCNHS <https://github.com/
pip install git+https://github.com/philip928lin/HydroCNHS.git
Or, (2) download the HydroCNHS package directly from the HydroCNHS GitHub repository. Then, install HydroCNHS from the *setup.py*.
Or, (2) download the HydroCNHS package directly from the HydroCNHS GitHub repository.

.. code-block:: python
Expand Down

0 comments on commit 0b132f1

Please sign in to comment.