ATS modeling workflow#

This is a Jupyter Book about modeling workflows using the Advanced Terrestrial Simulator (ATS) [1]. Thoughout this book, you will learn the basics of integrated watershed modeling ranging from model setup, executation, and post-processes. This book is intended to introduce beginers to process-based hydrologic modeling and does not cover the basics in programming using Python.

Note

To start, you will either need to install ATS locally or use pre-installed ATS on HPC clusters. The installation instruction can be found under ATS Github repo

Prerequisites#

Instructions#

  1. Open a terminal and clone this repository

# specify a tag (e.g., v1.0) to clone a specific version of the repo
git clone -b v1.1 https://github.com/pinshuai/ats-workflow 

cd ats-workflow

  1. Download data All data associated with the notebook examples can be downloaded from Zenodo.

# install zenodo_get
pip3 install zenodo_get

# download data from zenodo. This will download a zip file (e.g., data.zip)
zenodo_get 10.5281/zenodo.10982774

Extract the data and put them in the right folder.

# extract data.zip to current data folder
tar -xf data.zip -C ./data

  1. Pull the Docker image

docker pull pshuai/ats_workflow:v1.0

Important

Make sure the tag name is the same as the docker image tag name. For example, if you are using v1.0 tag, you will need to use pshuai/ats_workflow:v1.0 as the docker image name.

  1. Run the Docker image

docker run -it --rm -p 8888:8888 -e JUPYTER_ENABLE_LAB=yes -v $(pwd):/home/jovyan/workdir:delegated -v $(pwd)/data:/home/jovyan/data:delegated pshuai/ats_workflow:v1.0

Note

  • The docker command above mounted two local volumes to the container through -v. The first mounts current working directory (i.e., path/to/ats-workflow) to the workdir insider docker. The second mounts a local data directory to the data directory inside docker. In fact, you can mount any data directory you want for storing large raw data such as GLHYMPS, NLCD landcover, and depth-to-bedrock.

  • Make sure the local port number (8888) is not occupied by other processes. Alternatively, you can change the local port number to other numbers (e.g., -p 8890:8888).

  • On Windows, you may need to replace $(pwd) with the absolute path of the current directory (e.g., C:\Home\Documents\ats-workflow).

  1. Follow the prompt on screen to open the Jupyter Lab in your browser. For example, copy the following URL to your browser.

http://127.0.0.1:8888/lab?token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Important

  • If you are using a local port number different than 8888, you will need to manually replace 8888 with the new port number (e.g., 8890) specified in the last step in the url.

Now you should be able to run all notebooks within the Jupyter Lab.

You can find more about Jupyter Book and ATS.

Changelog#

v1.1#

  • 2024-04-16: Added instructions to download supplemental data from zenodo; updated notebooks to set the data library. This allows all notebooks to run regardless of upstream data source changes.

v1.0#

  • 2023-07-21: Initial release. The meshing, downloading forcing, and generating input files workflow has been updated to work with ATS v1.5.x using Coal Creek Watershed as an example.

Bibliography#

[1]

Ethan T. Coon, J. David Moulton, Evgeny Kikinzon, Markus Berndt, Gianmarco Manzini, Rao Garimella, Konstantin Lipnikov, and Scott L. Painter. Coupling surface flow and subsurface flow in complex soil structures using mimetic finite differences. Advances in Water Resources, 144(July):103701, 2020. URL: https://doi.org/10.1016/j.advwatres.2020.103701, doi:10.1016/j.advwatres.2020.103701.

[2]

Peishi Jiang, Pin Shuai, Alexander Sun, Maruti K. Mudunuru, and Xingyuan Chen. Knowledge-informed deep learning for hydrological model calibration: an application to Coal Creek Watershed in Colorado. Hydrology and Earth System Sciences, 27(14):2621–2644, July 2023. Publisher: Copernicus GmbH. URL: https://hess.copernicus.org/articles/27/2621/2023/ (visited on 2023-07-19), doi:10.5194/hess-27-2621-2023.