Merge pull request #26 from amoodie/feat_verbosity

feat: verbosity and random seed

README.rst

@@ -0,0 +1,49 @@
+**************
+pyDeltaRCM_WMT
+**************
+
+
+.. image:: https://api.travis-ci.com/DeltaRCM/pyDeltaRCM_WMT.svg?branch=develop
+    :target: https://travis-ci.com/DeltaRCM/pyDeltaRCM_WMT
+
+.. image:: https://coveralls.io/repos/github/DeltaRCM/pyDeltaRCM_WMT/badge.svg?branch=develop
+    :target: https://coveralls.io/github/DeltaRCM/pyDeltaRCM_WMT?branch=develop
+
+
+pyDeltaRCM is the Python version of the [Matlab deltaRCM](http://csdms.colorado.edu/wiki/Model:DeltaRCM) model by Man Liang. 
+The pyDeltaRCM scripts in this repository can be run as a stand-alone model following the instructions below.
+
+
+Documentation
+#############
+
+`Find the full documentation here <https://deltarcm.org/pyDeltaRCM_WMT/index.html>`_.
+
+
+
+Installation
+############
+
+To install this package into an existing Python 3.x environment, download or clone the repository and run:
+
+.. code::bash
+    $ python setup.py install
+
+Or for a developer installation run:
+
+.. code::bash
+    $ pip install -e .
+
+
+Executing the model
+###################
+
+We recommend you check out our **`pyDeltaRCM in 10 minutes tutorial <https://deltarcm.org/pyDeltaRCM_WMT/guides/10min.html>`_**, which is part of our documentation.
+
+Additionally, the model can be run with example script ``run_pyDeltaRCM.py``:
+
+.. code::bash
+    $ python run_pyDeltaRCM.py
+
+This reads the input file ``tests/test.yaml`` and runs a 1 timestep simulation. 
+This script will create an output folder in the working directory and save a PNG file of the parameter ``eta`` (surface elevation) every 50 timesteps.

docs/Makefile

@@ -12,12 +12,26 @@ BUILDDIR      = build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help docs 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
+
+docs: test clean html
+
+
+clean :
 	rm -rf source/api/
 	rm -rf source/_autosummary/
-	rm -rf ../build/
+	rm -rf ./build/
+
+
+test : clean
+	@$(SPHINXBUILD) -b doctest "$(SOURCEDIR)" "$(BUILDDIR)"
+	@$(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)"
+	@$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)"
+
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: clean Makefile 
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+

docs/source/conf.py

@@ -12,8 +12,6 @@
 #
 import os
 import sys
-sys.path.insert(0, os.path.abspath('../..'))
-sys.setrecursionlimit(1500)
 
 import pyDeltaRCM
 
@@ -33,7 +31,8 @@
 # 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', 
+extensions = ['sphinx.ext.autodoc',
+              'sphinx.ext.doctest',
               'sphinx.ext.autosummary',
               'sphinx.ext.napoleon',
               'sphinx.ext.graphviz',
@@ -67,6 +66,25 @@
 automodapi_inheritance_diagram = False
 autodoc_default_flags = ['members', 'inherited-members', 'no-private-members']
 
+# doctest
+doctest_global_setup = '''
+import pyDeltaRCM
+import numpy as np
+from matplotlib import pyplot as plt
+'''
+doctest_test_doctest_blocks = ''  # empty string disables testing all code in any docstring
+
+## mpl plots
+plot_basedir = 'pyplots'
+plot_html_show_source_link = False
+plot_formats = ['png', ('hires.png', 300)]
+plot_pre_code = '''
+import numpy as np
+from matplotlib import pyplot as plt
+import pyDeltaRCM
+'''
+
+
 # img math
 # imgmath_latex_preamble = '\\usepackage{fouriernc}' # newtxsf, mathptmx
 

docs/source/guides/10min.rst

@@ -35,4 +35,4 @@ We can visualize the delta bed elevation, though it's not very exciting after on
     >>> ax.imshow(delta.bed_elevation, vmax=-4.5)
     >>> plt.show()
 
-.. plot:: pyplots/10min/model_run_visual.py
+.. plot:: 10min/model_run_visual.py

pyDeltaRCM/bmi_delta.py

@@ -88,7 +88,7 @@ class BmiDelta(Bmi):
         'model_output__opt_velocity_grids': {'name': 'save_velocity_grids',
             'type': 'bool', 'default': False},
         'model_output__opt_time_interval': {'name': 'save_dt',
-            'type': 'float', 'default': 50.0},
+            'type': 'float', 'default': 50},
         'coeff__surface_smoothing': {'name': 'Csmooth',
             'type': 'float', 'default': 0.9},
         'coeff__under_relaxation__water_surface': {'name': 'omega_sfc',

pyDeltaRCM/default.yml

@@ -7,20 +7,26 @@ case_prefix:
 out_dir:
   type: 'str'
   default: 'deltaRCM_Output'
+verbose:
+  type: 'int'
+  default: 0
+seed:
+  type: ['int', 'None']
+  default: null
 Length:
-  type: 'float'
+  type: ['float', 'int']
   default: 1000.
 Width:
-  type: 'float'
+  type: ['float', 'int']
   default: 2000.
 dx:
-  type: 'float'
+  type: ['float', 'int']
   default: 50.
 L0_meters:
-  type: 'float'
+  type: ['float', 'int']
   default: 150.0
 S0:
-  type: 'float'
+  type: ['float', 'int']
   default: 0.0002
 itermax:
   type: 'int'
@@ -29,40 +35,40 @@ Np_water:
   type: 'int'
   default: 2000
 u0:
-  type: 'float'
+  type: ['float', 'int']
   default: 1.0
 N0_meters:
-  type: 'float'
+  type: ['float', 'int']
   default: 200.0
 h0:
-  type: 'float'
+  type: ['float', 'int']
   default: 5.0
 H_SL:
-  type: 'float'
+  type: ['float', 'int']
   default: 0.0
 SLR:
-  type: 'float'
+  type: ['float', 'int']
   default: 0.0
 Np_sed:
   type: 'int'
   default: 1000
 f_bedload:
-  type: 'float'
+  type: ['float', 'int']
   default: 0.5
 C0_percent:
-  type: 'float'
+  type: ['float', 'int']
   default: 0.1
 Csmooth:
-  type: 'float'
+  type: ['float', 'int']
   default: 0.9
 toggle_subsidence:
   type: 'bool'
   default: False
 sigma_max:
-  type: 'float'
+  type: ['float', 'int']
   default: 0.000825
 start_subsidence:
-  type: 'float'
+  type: ['float', 'int']
   default: 2.5
 save_eta_figs:
   type: 'bool'
@@ -95,44 +101,44 @@ save_velocity_grids:
   type: 'bool'
   default: True
 save_dt:
-  type: 'float'
+  type: 'int'
   default: 50
 save_strata:
   type: 'bool'
   default: True
 omega_sfc:
-  type: 'float'
+  type: ['float', 'int']
   default: 0.1
 omega_flow:
-  type: 'float'
+  type: ['float', 'int']
   default: 0.9
 Nsmooth:
   type: 'int'
   default: 5
 theta_water:
-  type: 'float'
+  type: ['float', 'int']
   default: 1.0
 coeff_theta_sand:
-  type: 'float'
+  type: ['float', 'int']
   default: 2.0
 coeff_theta_mud:
-  type: 'float'
+  type: ['float', 'int']
   default: 1.0
 beta:
   type: 'int'
   default: 3
 sed_lag:
-  type: 'float'
+  type: ['float', 'int']
   default: 1.0
 coeff_U_dep_mud:
-  type: 'float'
+  type: ['float', 'int']
   default: 0.3
 coeff_U_ero_mud:
-  type: 'float'
+  type: ['float', 'int']
   default: 1.5
 coeff_U_ero_sand:
-  type: 'float'
+  type: ['float', 'int']
   default: 1.05
 alpha:
-  type: 'float'
+  type: ['float', 'int']
   default: 0.1

pyDeltaRCM/deltaRCM_driver.py

@@ -8,11 +8,7 @@
 
 class pyDeltaRCM(Tools):
 
-    #############################################
-    ################## __init__ #################
-    #############################################
-
-    def __init__(self, input_file = None):
+    def __init__(self, input_file=None):
         """Creates an instance of the pyDeltaRCM model.
 
         This method handles setting up the run, including parsing input files,
@@ -33,7 +29,6 @@ def __init__(self, input_file = None):
         self._time = 0.
         self._time_step = 1.
 
-        self.verbose = False
         self.input_file = input_file
         self._file_dir = os.path.realpath(os.path.dirname(__file__))
         self.default_file = os.path.join(self._file_dir, 'default.yml')
@@ -71,7 +66,7 @@ def finalize(self):
 
         try:
             self.output_netcdf.close()
-            if self.verbose:
+            if self.verbose >= 1:
                 print('Closed output netcdf file.')
         except Exception:
             pass