Merge branch 'develop'

Author: chrisleaman

docs/conf.py

@@ -10,9 +10,10 @@
 # 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
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../py_wave_runup/"))
 
 
 # -- Project information -----------------------------------------------------
@@ -26,11 +27,10 @@
 
 
 # -- General configuration ---------------------------------------------------
-
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = ["sphinx.ext.autodoc"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -43,6 +43,10 @@
 # The master toctree document.
 master_doc = "index"
 
+source_suffix = ".rst"
+autoclass_content = "both"
+
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -54,3 +58,15 @@
 # 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"]
+
+pygments_style = "sphinx"
+
+
+def autodoc_skip_member(app, what, name, obj, skip, options):
+    exclusions = ("RunupModel",)
+    exclude = name in exclusions
+    return skip or exclude
+
+
+def setup(app):
+    app.connect("autodoc-skip-member", autodoc_skip_member)

docs/index.rst

@@ -10,6 +10,9 @@ Welcome to py-wave-runup's documentation!
    :maxdepth: 2
    :caption: Contents:
 
+.. automodule:: models
+   :members:
+   :undoc-members:
 
 
 Indices and tables

py_wave_runup/models.py

@@ -1,35 +1,97 @@
+from abc import ABCMeta, abstractmethod
+
 import numpy as np
 
 
-class Stockdon2006(object):
+class RunupModel(object):
     """
-    Empirical wave runup model as per Stockdon et al. (2006).
-    DOI: 10.1016/j.coastaleng.2005.12.005
+    Abstract base class which our empirical runup models will inherit from
     """
 
-    def __init__(self, Hs, beta, Lp=None, Tp=None):
+    __metaclass__ = ABCMeta
+
+    doi = None
+
+    def __init__(self, Hs=None, Tp=None, beta=None, Lp=None):
+        """
+        Test
+
+        :param Hs: description
+        :param Tp: description
+        :param beta: description
+        :param Lp: description
+        """
+
+        self.Hs = Hs
+        self.Tp = Tp
+        self.beta = beta
+        self.Lp = Lp
 
         # Ensure wave length or peak period is specified
         if all(v is None for v in [Lp, Tp]):
             raise ValueError("Expected either Lp or Tp args")
 
+        # Ensure input is atleast 1d numpy array, this is so we can handle lists,
+        # arrays and floats.
+        self.Hs = np.atleast_1d(Hs)
+        self.beta = np.atleast_1d(beta)
+
         # Calculate wave length if it hasn't been specified.
         if not Lp:
             self.Tp = np.atleast_1d(Tp)
             self.Lp = 9.81 * (self.Tp ** 2) / 2 / np.pi
         else:
             self.Lp = np.atleast_1d(Lp)
+            self.Tp = np.sqrt(2 * np.pi * self.Lp / 9.81)
 
-        self.Hs = np.atleast_1d(Hs)
-        self.beta = np.atleast_1d(beta)
+        # Ensure arrays are of the same size
+        if len(set(x.size for x in [self.Hs, self.Tp, self.beta, self.Lp])) != 1:
+            raise ValueError("Input arrays are not the same length")
 
         # Calculate Iribarren number. Need since there are different
         # parameterizations for dissipative and intermediate/reflective beaches.
         self.zeta = self.beta / (self.Hs / self.Lp) ** (0.5)
 
+    def _return_one_or_array(self, val):
+        # If only calculating a single value, return a single value and not an array
+        # with length one.
+        if val.size == 1:
+            return val.item()
+        else:
+            return val
+
     @property
+    @abstractmethod
     def R2(self):
+        raise NotImplementedError
+
+    @property
+    @abstractmethod
+    def setup(self):
+        raise NotImplementedError
+
+    @property
+    @abstractmethod
+    def sinc(self):
+        raise NotImplementedError
+
+    @property
+    @abstractmethod
+    def sig(self):
+        raise NotImplementedError
 
+    @property
+    @abstractmethod
+    def swash(self):
+        raise NotImplementedError
+
+
+class Stockdon2006(RunupModel):
+
+    doi = "10.1016/j.coastaleng.2005.12.005"
+
+    @property
+    def R2(self):
         # Generalized runup (Eqn 19)
         result = 1.1 * (
             0.35 * self.beta * (self.Hs * self.Lp) ** 0.5
@@ -63,10 +125,8 @@ def sig(self):
         result = self._return_one_or_array(result)
         return result
 
-    def _return_one_or_array(self, val):
-        # If only calculating a single value, return a single value and not an array
-        # with length one.
-        if val.size == 1:
-            return val.item()
-        else:
-            return val
+    @property
+    def swash(self):
+        result = np.sqrt(self.sinc ** 2 + self.sig ** 2)
+        result = self._return_one_or_array(result)
+        return result

tests/test_models.py

@@ -1,33 +1,40 @@
 from py_wave_runup import models
-import pytest
+from pytest import raises, approx
 
 
 class TestStockdon2006(object):
     def test_reflective(self):
         model = models.Stockdon2006(Hs=4, Tp=11, beta=0.1)
-        assert model.R2 == pytest.approx(2.54, abs=0.01)
-        assert model.setup == pytest.approx(0.96, abs=0.01)
-        assert model.sig == pytest.approx(1.65, abs=0.01)
-        assert model.sinc == pytest.approx(2.06, abs=0.01)
+        assert model.R2 == approx(2.54, abs=0.01)
+        assert model.setup == approx(0.96, abs=0.01)
+        assert model.sig == approx(1.65, abs=0.01)
+        assert model.sinc == approx(2.06, abs=0.01)
+        assert model.swash == approx(2.64, abs=0.01)
 
     def test_dissipative(self):
         model = models.Stockdon2006(Hs=4, Tp=11, beta=0.001)
-        assert model.R2 == pytest.approx(1.18, abs=0.01)
-        assert model.setup == pytest.approx(0.0096, abs=0.01)
-        assert model.sig == pytest.approx(1.65, abs=0.01)
-        assert model.sinc == pytest.approx(0.02, abs=0.01)
+        assert model.R2 == approx(1.18, abs=0.01)
+        assert model.setup == approx(0.0096, abs=0.01)
+        assert model.sig == approx(1.65, abs=0.01)
+        assert model.sinc == approx(0.02, abs=0.01)
+        assert model.swash == approx(1.65, abs=0.01)
 
     def test_wave_length(self):
         model = models.Stockdon2006(Hs=4, Lp=200, beta=0.05)
-        assert model.R2 == pytest.approx(1.69, 0.1)
+        assert model.R2 == approx(1.69, 0.1)
 
     def test_list_input(self):
         model = models.Stockdon2006(Hs=[1, 2], Lp=[100, 200], beta=[0.05, 0.1])
-        assert model.R2 == pytest.approx((0.59, 1.84), abs=0.1)
-        assert model.setup == pytest.approx((0.17, 0.70), abs=0.1)
-        assert model.sig == pytest.approx((0.6, 1.2), abs=0.1)
-        assert model.sinc == pytest.approx((0.37, 1.5), abs=0.1)
+        assert model.R2 == approx((0.59, 1.84), abs=0.1)
+        assert model.setup == approx((0.17, 0.70), abs=0.1)
+        assert model.sig == approx((0.6, 1.2), abs=0.1)
+        assert model.sinc == approx((0.37, 1.5), abs=0.1)
+        assert model.swash == approx((0.71, 1.92), abs=0.01)
 
     def test_no_wave_length(self):
-        with pytest.raises(ValueError):
-            models.Stockdon2006(Hs=4, beta=0.1)
+        with raises(ValueError):
+            models.Stockdon2006(Hs=1, beta=0.1)
+
+    def test_different_list_input(self):
+        with raises(ValueError):
+            models.Stockdon2006(Hs=[1, 2], Lp=[100, 200], beta=[0.1])