Merge pull request #112 from UW-Hydro/develop

Develop

Author: arbennett

README.md

@@ -1,109 +1,68 @@
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/DavidChoi76/pysumma_binder_test.git/master)
+# pysumma
 
-# pySUMMA                                        
-
-The pySUMMA is an Object-Oriented Python wrapper for the manipulation, display and analysis of 
-SUMMA model (Structure for Unifying Multiple Modeling Alternatives)
+pysumma is a Python wrapper for manipulating, running, managing, and analyzing
+of SUMMA (Structure for Unifying Multiple Modeling Alternatives)
 * [SUMMA web site at UCAR ](https://www.rap.ucar.edu/projects/summa)
 
-## The pySUMMA is intended to provide
-
- - Get and set model parameters and method (fileManager and Decision file) 
- - Run SUMMA Model 
- - Visualize netcdf of SUMMA outputs
- - Operate pySUMMA with jupyter notebook environment 
- - Interact Hydorshare to download SUMMA TestCases and post the output of SUMMA 
- - Automate model calibration or sensitivity analysis (Future work)
-
-## How to run pySUMMA on HydroShare 
- (Link YouTube: https://www.youtube.com/watch?v=pL-LNd474Tw)
- 1) log in HydoShare(https://www.hydroshare.org)
- 2) Start CUAHSI JupyterHub from APPS menu on HydroShare(https://www.hydroshare.org/apps/)
- 3) Open "Welcome.ipynb" to download pySUMMA resources from HydroShare
-  - run the code "1.How to connect with HydroShare"
-  - change the code from "resid = os.environ['HS_RES_ID']" to "resid = 'c1bb4a12bff44bf08c5958cba7947348'". 
- 4) You can see the list of Jupyter Notebooks and click one of Jupyter Notebook.
- 5) Run one of Jupyter Notebooks.
-
-### Examples of manipulating and running pySUMMA :
-
-Refereed paper : Clark, M. P., B. Nijssen, J. D. Lundquist, D. Kavetski, D. E. Rupp, R. A. Woods, 
-J. E. Freer, E. D. Gutmann, A. W. Wood, D. J. Gochis, R. M. Rasmussen, D. G. Tarboton, V. Mahat, 
-G. N. Flerchinger, D. G. Marks, 2015b: A unified approach for process-based hydrologic modeling: 
-Part 2. Model implementation and case studies. Water Resources Research, 
-[doi:10.1002/2015WR017200](https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1002/2015WR017200).
-
-#### HydroShare resources 
-**(Composite Resource)** [Jupyter Notebooks to demonstrate SUMMA Model at Reynolds Mountain East on HydroShare](https://www.hydroshare.org/resource/c1bb4a12bff44bf08c5958cba7947348/) 
-
-**(Composite Resource)** [Procedure and Supplementary documents Collaborative hydrologic modeling on HydroShare](https://www.hydroshare.org/resource/184eea3d3412418a886db87ffdb510b6/)
-
-**(Model Program)** [SUMMA 2.0.0 Sopron version (lubuntu-16.10)](https://www.hydroshare.org/resource/a5dbd5b198c9468387f59f3fefc11e22/)
-
-**(Model Program)** [SUMMA 2.0.0 Sopron version (lubuntu-16.04.4)](https://www.hydroshare.org/resource/041671fbc8a544cd8a979af6c2227f92/)
-
-**(Model Instance)** [Sensitivity to Stomatal Resistance Parameterization of SUMMA Model in Aspen stand at Reynolds Mountain East)](https://www.hydroshare.org/resource/e1a73bc4e7c34166895ff20ae53371f5/)
-
-**(Model Instance)** [The Impact of Root Distributions Parameters of SUMMA Model in Aspen stand at Reynolds Mountain East)](https://www.hydroshare.org/resource/eed6f3faedad4c17992bb361bd492caa/)
-
-**(Model Instance)** [The Impact of Lateral Flow Parameterizations on ET of SUMMA Model at Reynolds Mountain East)](https://www.hydroshare.org/resource/11d471b6096d4eaa81068256d281a919/)
-
-**(Model Instance)** [The Impact of Lateral Flow Parameterizations on Runoff of SUMMA Model at Reynolds Mountain East)](https://www.hydroshare.org/resource/5d20a87ecc5b495097e073e4d5f58d0c/)
+pysumma provides methods for:
+ - Running SUMMA
+ - Modifying SUMMA input files
+ - Automatically parallelizing distributed and sensitivity analysis type experiments
+ - Calibration via OSTRICH
+ - Visualizing output
 
-**(Model Instance)** [The Impact of the canopy shortwave radiation parameterizations of SUMMA Model at Reynolds Mountain East)](https://www.hydroshare.org/resource/0c4fd861a9694b2f9fcdf19eb33a6b54/)
+# Installation
 
-**(Model Instance)** [The Impact of LAI parameter on the below canopy shortwave radiation of SUMMA Model at Reynolds Mountain East)](https://www.hydroshare.org/resource/2bedc3b88f3547d5b9b0ade7248dfdd5/)
-
-**(Model Instance)** [The Impact of the canopy wind parameter for the exponential wind profile of SUMMA Model at Reynolds Mountain East)](https://www.hydroshare.org/resource/4064a7b014094f50aa63730e4a3ff976/)
-
-**(Collection Resource)** [Test Cases of SUMMA modeling that include model instances and Jupyter notebooks for SUMMA 2nd Paper(2015))](https://www.hydroshare.org/resource/1b7a9af74daa4a449190f922b5db366e/)
-
-## How to run pySUMMA locally 
- 
-### Installation and Usage
+## Dependencies
+A conda environment is available for management of pysumma's dependencies.
+You can create your own environment from this file by running:
+```
+conda env create -f environment.yml
+```
 
-#### pySUMMA requires Python 3.6 and following packages :
+Then, you can activate this environment with `conda activate pysumma`.
+Before installing pysumma into this environment you may also wish to install it as a kernel in your Jupyter environments.
+This can be accomplished by running:
 
- - xarray 0.10.7 : N-D labeled arrays and datasets in python
- - numpy 1.16.1 : the fundamental package for scientific computing with Python
- - matplotlib 3.0.2 : a Python 2D plotting library 
- - seaborn 0.9.0 : statistical data visualization 
- - jupyterthemes 0.20.0 : select and install a Jupyter notebook theme
- - hs-restclient 1.3.3 : HydroShare REST API python client library
- - ipyleaflet 0.9.2 : A jupyter widget for dynamic Leaflet maps 
- - Linux Environment (VirtualBox 5.2.8)
-   - [lubuntu-16.10 executable](https://www.hydroshare.org/resource/a5dbd5b198c9468387f59f3fefc11e22/)
-   - [lubuntu-16.04.4 executable](https://www.hydroshare.org/resource/041671fbc8a544cd8a979af6c2227f92/)        
+```
+python -m ipykernel install --user --name=pysumma
+```
 
-### Download and Install pySUMMA:
+With this environment active you can install pysumma this environment with the instructions below.
 
-**1.)**  Download pySUMMA
-```python
-~/Downloads$ git clone https://github.com/uva-hydroinformatics/pysumma.git
+## Installing pysumma
+Currently we only support building pysumma from source. This can be accomplished by
+running:
 ```
-        
-**2.)**  change directory into pysumma folder same level with setup.py.
-```python
-~/Downloads/pysumma$ pip install .
+git clone https://github.com/UW-Hydro/pysumma.git
+cd pysumma
+python setup.py install
 ```
 
-#### The UML of pySUMMA
-![Image of UML](UML.png)
-
-## Reference of SUMMA
+If you plan on helping to develop pysumma you may wish to use the following to install
+```
+git clone https://github.com/UW-Hydro/pysumma.git
+cd pysumma
+python setup.py develop
+```
 
+# Additional SUMMA References
  - [Document](http://summa.readthedocs.io/en/latest/) : SUMMA documentation is available online and remains a work in progress.
  - [Source Code](https://github.com/NCAR/summa) : NCAR github
- 
-## Bugs
-  Our issue tracker is at https://github.com/uva-hydroinformatics/pysumma/issues.
+
+# Bugs
+  Our issue tracker is at https://github.com/UW-Hydro/pysumma/issues.
   Please report any bugs that you find.  Or, even better, fork the repository on
   GitHub and create a pull request.  All changes are welcome, big or small, and we
   will help you make the pull request if you are new to git
   (just ask on the issue).
 
-## License
-  Distributed with a MIT license; see LICENSE.txt::
-
-  Copyright (C) 2017 pySUMMA Developers
-  YoungDon Choi <[email protected]>
+# How to run pySUMMA on HydroShare
+ (Link YouTube: https://www.youtube.com/watch?v=pL-LNd474Tw)
+ 1) log in HydoShare(https://www.hydroshare.org)
+ 2) Start CUAHSI JupyterHub from APPS menu on HydroShare(https://www.hydroshare.org/apps/)
+ 3) Open "Welcome.ipynb" to download pySUMMA resources from HydroShare
+  - run the code "1.How to connect with HydroShare"
+  - change the code from "resid = os.environ['HS_RES_ID']" to "resid = 'c1bb4a12bff44bf08c5958cba7947348'".
+ 4) You can see the list of Jupyter Notebooks and click one of Jupyter Notebook.
+ 5) Run one of Jupyter Notebooks.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = pysumma
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api.rst

@@ -0,0 +1,27 @@
+.. currentmodule:: pysumma
+.. _api:
+
+#############
+API reference
+#############
+
+This page provides an auto-generated summary of pysumma's API. For more details
+and examples, refer to the main documentation.
+
+Simulation
+==========
+.. autoclass:: pysumma.Simulation
+    :members:
+
+Ensemble
+=======
+
+.. autoclass:: pysumma.Ensemble
+    :members:
+
+Distributed
+=======
+
+.. autoclass:: pysumma.Distributed
+    :members:
+

docs/conf.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+
+import sphinx_rtd_theme
+
+sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('../'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['sphinx.ext.autodoc',
+              'sphinx.ext.extlinks',
+              'sphinx.ext.mathjax',
+              'sphinx.ext.viewcode',
+              'sphinx.ext.napoleon',
+              'sphinx.ext.autosummary']
+
+extlinks = {'issue': ('https://github.com/UW-Hydro/pysumma/issues/%s', 'GH'),
+            'pull': ('https://github.com/UW-Hydro/pysumma/pull/%s', 'PR'),
+            }
+
+napoleon_google_docstring = False
+napoleon_use_param = False
+napoleon_use_ivar = False
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'pysumma'
+copyright = '2020, YoungDon Choi, Andrew Bennett'
+author = 'YoungDon Choi, Andrew Bennett'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.0.0'
+# The full version, including alpha/beta/rc tags.
+release = '0.0.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'pysummadoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'pysumma.tex', 'pysumma Documentation',
+     'YounDon Choi, Andrew Bennett', 'manual'),
+]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'pysumma', 'pysumma Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'pysumma', 'pysumma Documentation',
+     author, 'pysumma ', 'One line description of project.',
+     'Miscellaneous'),
+]