diff --git a/README.md b/README.md old mode 100755 new mode 100644 index 5d0a2b5..969e637 --- a/README.md +++ b/README.md @@ -1,106 +1,7 @@ -# Automated Water Supply Model +# Fork of the Automated Water Supply Model (AWSM) -[![GitHub version](https://badge.fury.io/gh/USDA-ARS-NWRC%2Fawsm.svg)](https://badge.fury.io/gh/USDA-ARS-NWRC%2Fawsm) -[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.898158.svg)](https://doi.org/10.5281/zenodo.898158) -[![DOI](https://readthedocs.org/projects/awsm/badge/)](https://awsm.readthedocs.io) -[![Docker Build Status](https://img.shields.io/docker/build/usdaarsnwrc/awsm.svg)](https://hub.docker.com/r/usdaarsnwrc/awsm/) -[![Docker Automated build](https://img.shields.io/docker/automated/usdaarsnwrc/awsm.svg)](https://hub.docker.com/r/usdaarsnwrc/awsm/) -[![Coverage Status](https://coveralls.io/repos/github/USDA-ARS-NWRC/awsm/badge.svg?branch=HEAD)](https://coveralls.io/github/USDA-ARS-NWRC/awsm?branch=HEAD) -[![Build Status](https://travis-ci.org/USDA-ARS-NWRC/awsm.svg?branch=devel)](https://travis-ci.org/USDA-ARS-NWRC/awsm) +This is a fork of the [USDA-ARS-NWRC AWSM](https://github.com/USDA-ARS-NWRC/awsm) repo with the +model development state used for publication in +[Geoscientific Model Development](https://gmd.copernicus.org/). - -Automated Water Supply Model (AWSM) was developed at the USDA Agricultural -Research Service (ARS) in Boise, ID. AWSM was designed to streamline the work -flow used by the ARS to forecast the water supply of multiple water basins. -AWSM standardizes the steps needed to distribute weather station data with SMRF, -run an energy and mass balance with iSnobal, and process the results, while -maintaining the flexibility of each program. - -![image](https://raw.githubusercontent.com/USDA-ARS-NWRC/awsm/master/docs/_static/ModelSystemOverview_new.png) - -## Quick Start - -The fastest way to get up and running with AWSM is to use the docker images that -are pre-built and can deployed cross platform. - -To build AWSM natively from source checkout the install instructions [here]. - -[here]: https://awsm.readthedocs.io/en/latest/installation.html - -### Docker - -Docker images are containers that allow us to ship the software to our users -seamlessly and without a headache. It is by far the easiest way to use AWSM. If -you are curious to read more about them, visit [Whats a container] on docker's -website. - -[Whats a container]: https://www.docker.com/what-container - -Using docker images comes with very minor quirks though, such as requiring you to -mount a volume to access the data when you are done with your run. To mount a -data volume, so that you can share data between the local file system and the -docker, the `-v` option must be used. For a more in depth discussion and -tutorial, read about [docker volumes]. The container has a shared data volume -at `/data` where the container can access the local file system. - -[docker volumes]: https://docs.docker.com/storage/volumes/ - - -**NOTE: On the host paths to the volume to mount, you must use full absolute paths!** - -### Running the Demo - -To simply run the AWSM demo; mount the desired directory as a volume and run -the image, using the following command: - -**For Linux:** - -``` - docker run -v :/data -it usdaarsnwrc/awsm:develop -``` - -**For MacOSX:** - -``` - docker run -v /Users/:/data -it usdaarsnwrc/awsm:develop -``` - -**For Windows:** - -``` - docker run -v /c/Users/:/data -it usdaarsnwrc/awsm:develop -``` - -The output netCDF files will be placed in the location you mounted (using the --v option). We like to use [ncview] to view our netcdf files quickly. - -[ncview]: http://meteora.ucsd.edu/~pierce/ncview_home_page.html - -### Setting Up Your Run - -To use the AWSM docker image to create your own runs, you need to setup a -project folder containing all the files necessary to run the model. Then using -the same command above, mount your project folder and provide a path to the -configuration file. An example of a project folder might like: - -``` -My_Basin - ├── air_temp.csv - ├── cloud_factor.csv - ├── config.ini - ├── maxus.nc - ├── metadata.csv - ├── output - ├── precip.csv - ├── solar.csv - ├── topo.nc - ├── vapor_pressure.csv - ├── wind_direction.csv - └── wind_speed.csv -``` - -Then the command would be: - -``` -docker run -v /My_Basin:/data -it usdaarsnwrc/awsm:develop /My_Basin/config.ini -``` +The original repo README [can be found here](README_awsm.md) diff --git a/README_awsm.md b/README_awsm.md new file mode 100755 index 0000000..5d0a2b5 --- /dev/null +++ b/README_awsm.md @@ -0,0 +1,106 @@ +# Automated Water Supply Model + +[![GitHub version](https://badge.fury.io/gh/USDA-ARS-NWRC%2Fawsm.svg)](https://badge.fury.io/gh/USDA-ARS-NWRC%2Fawsm) +[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.898158.svg)](https://doi.org/10.5281/zenodo.898158) +[![DOI](https://readthedocs.org/projects/awsm/badge/)](https://awsm.readthedocs.io) +[![Docker Build Status](https://img.shields.io/docker/build/usdaarsnwrc/awsm.svg)](https://hub.docker.com/r/usdaarsnwrc/awsm/) +[![Docker Automated build](https://img.shields.io/docker/automated/usdaarsnwrc/awsm.svg)](https://hub.docker.com/r/usdaarsnwrc/awsm/) +[![Coverage Status](https://coveralls.io/repos/github/USDA-ARS-NWRC/awsm/badge.svg?branch=HEAD)](https://coveralls.io/github/USDA-ARS-NWRC/awsm?branch=HEAD) +[![Build Status](https://travis-ci.org/USDA-ARS-NWRC/awsm.svg?branch=devel)](https://travis-ci.org/USDA-ARS-NWRC/awsm) + + +Automated Water Supply Model (AWSM) was developed at the USDA Agricultural +Research Service (ARS) in Boise, ID. AWSM was designed to streamline the work +flow used by the ARS to forecast the water supply of multiple water basins. +AWSM standardizes the steps needed to distribute weather station data with SMRF, +run an energy and mass balance with iSnobal, and process the results, while +maintaining the flexibility of each program. + +![image](https://raw.githubusercontent.com/USDA-ARS-NWRC/awsm/master/docs/_static/ModelSystemOverview_new.png) + +## Quick Start + +The fastest way to get up and running with AWSM is to use the docker images that +are pre-built and can deployed cross platform. + +To build AWSM natively from source checkout the install instructions [here]. + +[here]: https://awsm.readthedocs.io/en/latest/installation.html + +### Docker + +Docker images are containers that allow us to ship the software to our users +seamlessly and without a headache. It is by far the easiest way to use AWSM. If +you are curious to read more about them, visit [Whats a container] on docker's +website. + +[Whats a container]: https://www.docker.com/what-container + +Using docker images comes with very minor quirks though, such as requiring you to +mount a volume to access the data when you are done with your run. To mount a +data volume, so that you can share data between the local file system and the +docker, the `-v` option must be used. For a more in depth discussion and +tutorial, read about [docker volumes]. The container has a shared data volume +at `/data` where the container can access the local file system. + +[docker volumes]: https://docs.docker.com/storage/volumes/ + + +**NOTE: On the host paths to the volume to mount, you must use full absolute paths!** + +### Running the Demo + +To simply run the AWSM demo; mount the desired directory as a volume and run +the image, using the following command: + +**For Linux:** + +``` + docker run -v :/data -it usdaarsnwrc/awsm:develop +``` + +**For MacOSX:** + +``` + docker run -v /Users/:/data -it usdaarsnwrc/awsm:develop +``` + +**For Windows:** + +``` + docker run -v /c/Users/:/data -it usdaarsnwrc/awsm:develop +``` + +The output netCDF files will be placed in the location you mounted (using the +-v option). We like to use [ncview] to view our netcdf files quickly. + +[ncview]: http://meteora.ucsd.edu/~pierce/ncview_home_page.html + +### Setting Up Your Run + +To use the AWSM docker image to create your own runs, you need to setup a +project folder containing all the files necessary to run the model. Then using +the same command above, mount your project folder and provide a path to the +configuration file. An example of a project folder might like: + +``` +My_Basin + ├── air_temp.csv + ├── cloud_factor.csv + ├── config.ini + ├── maxus.nc + ├── metadata.csv + ├── output + ├── precip.csv + ├── solar.csv + ├── topo.nc + ├── vapor_pressure.csv + ├── wind_direction.csv + └── wind_speed.csv +``` + +Then the command would be: + +``` +docker run -v /My_Basin:/data -it usdaarsnwrc/awsm:develop /My_Basin/config.ini +``` diff --git a/setup.py b/setup.py index c9abb40..8a43a82 100755 --- a/setup.py +++ b/setup.py @@ -4,7 +4,7 @@ from setuptools import find_packages, setup -with open('README.md') as readme_file: +with open('README_awsm.md') as readme_file: readme = readme_file.read() with open('requirements.txt') as requirements_file: