Merge remote-tracking branch 'origin/refactor'

doc/contact.rst

@@ -1,6 +1,7 @@
 Contact
 =======
-For help using the `WDRT`, please use the GitHub Issue Tracker forum: https://github.com/WEC-Sim/WDRT/issues. By posting your questions and comments here, you can receive feedback/solutions from the `WDRT` development team as well as the general user community.
+For help using the `WDRT`, please use the GitHub Issue Tracker forum: https://github.com/WEC-Sim/WDRT/issues.
+By posting your questions and comments here, you can receive feedback/solutions from the `WDRT` development team as well as the general user community.
 
 .. image::  _static/IssueTracker.png
    :align: center

doc/examples.rst

@@ -28,7 +28,7 @@ Short-term extreme response analysis
 ------------------------------------
 A short term extreme distribution is the answer to “If a device is in sea-state X for Y amount of time, what will be the largest Z observed?", where X is the environmental condition, Y the short-term period, and Z the response parameter of interest (e.g. the mooring load, bending moment).
 The short-term extreme response module provides five different methods for obtaining this distribution based on observations of the quantity of interest "Z" at the desired sea-state "X".
-These methods are described in detail in :ref:`Michelen and Coe 2015 <pubs>`
+These methods are described in detail in :ref:`Michelen and Coe 2015 <pubs>`.
 
 In this example the Weibull tail-fit method is used.
 The proccess of obtaiing the sort-term extreme distribution using the Weibull tail-fit method is as follows:
@@ -42,7 +42,7 @@ The proccess of obtaiing the sort-term extreme distribution using the Weibull ta
 
 		F^{\prime}(x_i) = \frac{i}{N+1}
 
-	where :math:`x_i` is the :math:`i^{\textrm{th}}`-ordered peak
+	where :math:`x_i` is the :math:`i^{\textrm{th}}`-ordered peak.
 
 	3. Fit Weibull distributions to seven subsets of the points (:math:`x_i`, :math:`F^{\prime}(x_i)`) corresponding to :math:`F^{\prime}(x_i) > \left(0.95, 0.90, 0.85, 0.80, 0.75, 0.70, 0.65 \right)`.
 
@@ -130,7 +130,9 @@ For this example, we will simply load data that was previously produced with a s
 
 3. Short term extreme statistics 
 ''''''''''''''''''''''''''''''''
-The extreme response for each sea state can be defined as a percentile, :math:`\alpha`, in the extreme response distributions. The percentile chosen here should ideally be based on some experience with similar systems. Typical values for :math:`\alpha` used for marine structures range from 75 to 99\%. This approach has less variability than simply picking the maximum QOI observed in each sea state.
+The extreme response for each sea state can be defined as a percentile, :math:`\alpha`, in the extreme response distributions.
+The percentile chosen here should ideally be based on some experience with similar systems.
+Typical values for :math:`\alpha` used for marine structures range from 75 to 99\%. This approach has less variability than simply picking the maximum QOI observed in each sea state.
 
 .. literalinclude:: ../examples/example_contourApproach.py
 	:language: python
@@ -139,7 +141,9 @@ The extreme response for each sea state can be defined as a percentile, :math:`\
 
 5. Determine design load condition(s) 
 '''''''''''''''''''''''''''''''''''''
-For the quantity of interest (QOI), find the sea state that represents the design load condition; this will be the design load condition (DLC) for that (QOI). The DLC is defined as the scenario that gives the largest response. To define the DLC by statistically-supported process, it is best to use a short-term extreme response analysis process to examine the QOI in each of the considered sea states.
+For the quantity of interest (QOI), find the sea state that represents the design load condition; this will be the design load condition (DLC) for that (QOI).
+The DLC is defined as the scenario that gives the largest response.
+To define the DLC by statistically-supported process, it is best to use a short-term extreme response analysis process to examine the QOI in each of the considered sea states.
 
 .. literalinclude:: ../examples/example_contourApproach.py
 	:language: python
@@ -252,43 +256,11 @@ The required inputs to the module are:
 
 	3. And, :math:`N`, the number of cycles expected in the WEC’s design life, which is up to the user to ascertain given a specified design life and environmental characterization.
 
-This example is shown below and can found in ``$WDRT_SOURCE/examples/example_fatigue.py``::
-
-	# This example loads pre-calculated PTO force histories for a reduced size joint
-	# probability distribution. Then uses the WDRT fatigue function to calculate
-	# equivalent fatigue loads for a 1 hour timeframe and a 1 year timeframe.
-
-	import numpy as np
-	import WDRT.fatigue as fatigue
-
-	# Reduced size joint probability distribution
-	Te = [[6.0,10.0,14.0],[6.0,10.0,14.0],[6.0,10.0,14.0]]  # Wave energy periods
-	Hs = [[1.25,1.25,1.25],[2.75,2.75,2.75],[4.25,4.25,4.25]]   # Significant wave heights
-	P = np.multiply([[23.45,24.78,1.64],[9.18,28.21,4.11],[0.05,5.00,2.34]],0.01)   # Probability
-
-	N1h = 0
-	N1y = 0
-	[h,t] = np.shape(P)
-	for i in range(h):
-	    for j in range(t):
-	        N1h = N1h+1*60*60*P[i][j]/(Te[i][j]*.82476)   # Average N in 1 hour (Tavg = 0.82476*Te)
-	        N1y = N1y+1*365*24*60*60*P[i][j]/(Te[i][j]*.82476)   # Average N in 1 year
-	        
-	m = float(6)    # Assume an S-N curve slope of 6 (representative of cast iron)
-	Feq_1h = np.zeros((h,t))
-	Feq_1y = 0
-	for i in range(h):
-	    for j in range(t):
-	        # Read pre-calculated PTO force histories for each sea state
-	        Fpto = np.loadtxt('examples\data\FptoH'+str(int(Hs[i][j]))+'T'+str(int(Te[i][j]))+'.txt')	
-	        Feq_1h[i][j] = fatigue.EqLoad(Fpto, N1h, m) # Equivalent fatigue load for a 1 hour timeframe
-	        Feq_1y = Feq_1y+(Feq_1h[i][j]**m)*N1h*P[i][j]
-	Feq_1y = (Feq_1y/N1y)**(1/m)	# Equivalent fatigue load for a 1 year timeframe
-
-	print('1 hour equivalent fatigue loads:')
-	print(Feq_1h)
-	print('1 year equivalent fatigue load:')
-	print(Feq_1y)
+This example is shown below and can found in ``$WDRT_SOURCE/examples/example_fatigue.py``.
+
+.. literalinclude:: ../examples/example_fatigue.py
+	:language: python
+   	:linenos:
 
 In this example, 1 hour PTO force histories (for the `RM3 WEC <http://wec-sim.github.io/WEC-Sim/tutorials.html#two-body-point-absorber-rm3>`_) have been numerically obtained (using `WEC-Sim <http://wec-sim.github.io/WEC-Sim/index.html>`_) for each sea state in the hypothetical joint probability distribution shown below.
 The average number of cycles expected in 1 hour, :math:`N_{\textrm{1-hr}}`, and 1 year, :math:`N_{\textrm{1-yr}}`, timeframes are estimated from the joint probability distribution.
@@ -300,22 +272,27 @@ And finally, the annual damage equivalent load is calculated by reapplying the P
    :align: center
    :width: 400pt
 
-
-
 Most-likely extreme response (MLER)
 -----------------------------------
 
-The extreme load is often a matter of chance created by the instantaneous position of the device and a series of random waves. The occurrence of an extreme load should be studied as a stochastic event because of the nature of the irregular sea states. The MLER toolbox were developed to generate a focused wave profile that gives the largest response with the consideration of wave statistics based on spectral analysis and the response amplitude operators (RAOs) of the device.
+The extreme load is often a matter of chance created by the instantaneous position of the device and a series of random waves.
+The occurrence of an extreme load should be studied as a stochastic event because of the nature of the irregular sea states.
+The MLER toolbox were developed to generate a focused wave profile that gives the largest response with the consideration of wave statistics based on spectral analysis and the response amplitude operators (RAOs) of the device.
 
 An example can be found in ``$WDRT_SOURCE/WDRT/MLER_toolbox/example/testrun.py``.
 
 .. literalinclude:: ../WDRT/MLER_toolbox/example/testrun.py
 	:language: python
    	:linenos:
 
-In this example, the MLER method was applied to model a floating ellipsoid (Quon et al. OMAE 2016). The waves were generated from the extreme wave statistics data and the linear RAOs were obtained from a simple radiation-and-diffraction-method-based numerical model known as the `Wave Energy Converter Simulator, or WEC- Sim <https://wec-sim.github.io/WEC-Sim/>`_. 
+In this example, the MLER method was applied to model a floating ellipsoid (Quon et al. OMAE 2016).
+The waves were generated from the extreme wave statistics data and the linear RAOs were obtained from a simple radiation-and-diffraction-method-based numerical model known as the `Wave Energy Converter Simulator, or WEC- Sim <https://wec-sim.github.io/WEC-Sim/>`_. 
 
-The figure below explains how the MLER waves were generated and used. For this particular example, the target sea state has a significant wave height of 9 m and energy period of 15.1 sec and was represented using Brettschneider spectrum. A specific wave profile is required for different responses of interest (e.g., motion, mooring load, shear stress and bending moment). For example, the MLER wave profile targeting maximum pitch motion is different from the profile for heave, as seen below in the "heave conditioned" and "pitch conditioned" curves. This is expected because the maximum heave and pitch are most likely to occur at different times.
+The figure below explains how the MLER waves were generated and used.
+For this particular example, the target sea state has a significant wave height of 9 m and energy period of 15.1 sec and was represented using Brettschneider spectrum.
+A specific wave profile is required for different responses of interest (e.g., motion, mooring load, shear stress and bending moment).
+For example, the MLER wave profile targeting maximum pitch motion is different from the profile for heave, as seen below in the "heave conditioned" and "pitch conditioned" curves.
+This is expected because the maximum heave and pitch are most likely to occur at different times.
 
 .. figure::  _static/MLER.png
    :align: center

doc/index.rst

@@ -22,9 +22,13 @@ Contributors
 * Ryan Coe, Sandia National Laboratories
 * Carlos Michelen, Sandia National Laboratories
 * Aubrey Eckert-Gallup, Sandia National Laboratories
+* Nevin Martin, Sandia National Laboratories
+* Tyler Esterly, Sandia National Laboratories
 * Jennifer van Rij, National Renewable Energy Laboratory
 * Yi-Hsiang Yu, National Renewable Energy Laboratory
 * Eliot Quon, National Renewable Energy Laboratory
+* Lance Manuel, University of Texas at Austin
+* Phong Nguyen, University of Texas at Austin
 
 Contents
 ========

doc/installation.rst

@@ -1,9 +1,10 @@
 Installation
-==========================
+============
 
 Downloading `WDRT`
-------------------------
-`WDRT` is distributed through the `WDRT GitHub repository <https://github.com/WEC-Sim/WDRT/>`_. The toolbox can either be downloaded via ``git`` or simply by visiting the the `WDRT GitHub repository <https://github.com/WEC-Sim/WDRT/>`_ and downloading it directly.
+------------------
+`WDRT` is distributed through the `WDRT GitHub repository <https://github.com/WEC-Sim/WDRT/>`_.
+The toolbox can either be downloaded via ``git`` or simply by visiting the the `WDRT GitHub repository <https://github.com/WEC-Sim/WDRT/>`_ and downloading it directly.
 
 .. note::
 
@@ -38,6 +39,12 @@ The following installation procedure allows for easier updating of the code with
 
 **Step 2:** Add the ``$WDRT_SOURCE`` directory to your `PYTHONPATH <https://docs.python.org/2/using/cmdline.html#environment-variables>`_ environment variable (`Windows <https://docs.python.org/2/using/windows.html#excursus-setting-environment-variables>`_, `Mac OSX <https://docs.python.org/2/using/mac.html?highlight=pythonpath#configuration>`_, `Linux <https://wiki.archlinux.org/index.php/Environment_variables>`_).
 
-**Step 3:** Verify the installation's functionality::
+**Step 3:** Verify the installation's functionality by running the examples located in``$WDRT_SOURCE/examples``
 
-	python verifyInstall.py
+.. code-block:: none
+
+	cd examples
+	python example_envSamplying.py
+	python example_contourApproach.py
+	python example_shortTermExtreme.py
+	python example_fatigue.py

doc/modules.rst

@@ -1,6 +1,8 @@
 Toolbox Modules
 ===============
-The following sections contain the documentation for `WDRT`. Note that this documentation is also contained in the python source code. As such, documentation for any `WDRT` function or classs can also be accessed in iPython via by calling
+The following sections contain the documentation for `WDRT`.
+Note that this documentation is also contained in the python source code.
+As such, documentation for any `WDRT` function or classs can also be accessed in iPython via by calling
 
 >>> help(<wdrt class or module>)
 

doc/publications.rst

@@ -8,7 +8,9 @@ If you desire to cite `WDRT` in a publication, please use
 
 R.G. Coe, C. Michelen, A. Eckert-Gallup, Y. Yu and J. van Rij, “WDRT: A toolbox for design-response analysis of wave energy converters,” Proceedings of the 4th Marine Energy Technology Symposium (METS), Washington, DC, 2016.
 
-BibTex key::
+BibTex key
+
+.. code-block:: none
 
 	@InProceedings{,
 	    author    = {Ryan G. Coe and Carlos Michelen and Aubrey C. Eckert-Gallup and Yi-Hsiang Yu and Jennifer van Rij},
@@ -23,18 +25,22 @@ BibTex key::
 Related publications
 --------------------
 
-[1] R.G. Coe, C. Michelen, A. Eckert-Gallup, Y. Yu and J. van Rij, WDRT: A toolbox for design-response analysis of wave energy converters, Proceedings of the 4th Marine Energy Technology Symposium (METS), Washington, DC, 2016.
+-- A. Eckert-Gallup, and N. Martin, `Kernel density estimation (KDE) with adaptive bandwidth selection for environmental contours of extreme sea states <http://ieeexplore.ieee.org/abstract/document/7761150/>`_, in: OCEANS 2016 MTS/IEEE Monterey. IEEE, 2016.
+
+-- L. Manuel, J. Canning, R. G. Coe, C. Michelen, On the short-term uncertainty in performance of a point absorber wave energy converter, in: Proceedings of the 4th Marine Energy Technology Symposium (METS), Washington, DC, 2016.
+
+-- R. G. Coe, C. Michelen, A. Eckert-Gallup, Y. Yu and J. van Rij, `WDRT: A toolbox for design-response analysis of wave energy converters <https://www.researchgate.net/publication/308794966_WDRT_A_Toolbox_for_design-response_analysis_of_wave_energy_converters>`_, in: Proceedings of the 4th Marine Energy Technology Symposium (METS), Washington, DC, 2016.
 
-[2] E. Quon, A. Platt, Y.-H. Yu, M. Lawson, Application of the Most Likely Extreme Response Method for Wave Energy Converters, in: Proceedings of the 35th International Conference on Ocean, Offshore and Arctic Engineering, ASME, Busan, South Korea, 2016.
+-- E. Quon, A. Platt, Y.-H. Yu, M. Lawson, `Application of the Most Likely Extreme Response Method for Wave Energy Converters <http://www.nrel.gov/docs/fy16osti/65926.pdf>`_, in: Proceedings of the 35th International Conference on Ocean, Offshore and Arctic Engineering, ASME, Busan, South Korea, 2016.
 
-[3] A. C. Eckert-Gallup, C. J. Sallaberry, A. R. Dallman, V. S. Neary, `Application of principal component analysis (PCA) and improved joint probability distributions to the inverse first-order reliability method (I-FORM) for predicting extreme sea states <http://www.sciencedirect.com/science/article/pii/S0029801815006721>`_, Ocean Engineering 112 (2016) 307 – 319. doi:http://dx.doi.org/10.1016/j.oceaneng.2015.12.018.
+-- A. C. Eckert-Gallup, C. J. Sallaberry, A. R. Dallman, V. S. Neary, `Application of principal component analysis (PCA) and improved joint probability distributions to the inverse first-order reliability method (I-FORM) for predicting extreme sea states <http://www.sciencedirect.com/science/article/pii/S0029801815006721>`_, Ocean Engineering 112 (2016) 307 – 319. doi:http://dx.doi.org/10.1016/j.oceaneng.2015.12.018.
 
-[4] C. Michelen, R. Coe, `Comparison of methods for estimating short-term extreme response of wave energy converters <http://ieeexplore.ieee.org/xpls/abs_all.jsp?arnumber=7401878&tag=1>`_, in: OCEANS 2015 - MTS/IEEE Washington, IEEE, Washington, D.C., 2015.
+-- C. Michelen, R. Coe, `Comparison of methods for estimating short-term extreme response of wave energy converters <http://ieeexplore.ieee.org/document/7401878/>`_, in: OCEANS 2015 - MTS/IEEE Washington, IEEE, Washington, D.C., 2015.
 
-[5] Y.-H. Yu, J. Van Rij, R. G. Coe, M. Lawson, `Development and application of a methodology for predicting wave energy converters design load <http://proceedings.asmedigitalcollection.asme.org/proceeding.aspx?articleID=2465994>`_, in: Proceedings of the 34th International Conference on Ocean, Offshore and Arctic Engineering, ASME, St. Johns, Canada, 2015.
+-- Y.-H. Yu, J. Van Rij, R. G. Coe, M. Lawson, `Development and application of a methodology for predicting wave energy converters design load <http://proceedings.asmedigitalcollection.asme.org/proceeding.aspx?articleID=2465994>`_, in: Proceedings of the 34th International Conference on Ocean, Offshore and Arctic Engineering, ASME, St. Johns, Canada, 2015.
 
-[6] A. C. Eckert-Gallup, C. J. Sallaberry, A. R. Dallman, V. S. Neary, `Modified inverse first order reliability method (I-FORM) for predicting extreme sea states <https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&cad=rja&uact=8&ved=0CCMQFjAAahUKEwiShYidmcLIAhVIlIgKHe6tAsw&url=http%3A%2F%2Fprod.sandia.gov%2Ftechlib%2Faccess-control.cgi%2F2014%2F1417550.pdf&usg=AFQjCNGaXmRbm0SvIS3zrIxd0z14q3BVYg&sig2=cLHjej-znRIW3fIIGlh5_Q>`_, Tech. Rep. SAND2014-17550, Sandia National Laboratories, Albuquerque, NM (United States) 2014.
+-- A. C. Eckert-Gallup, C. J. Sallaberry, A. R. Dallman, V. S. Neary, `Modified inverse first order reliability method (I-FORM) for predicting extreme sea states <https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&cad=rja&uact=8&ved=0CCMQFjAAahUKEwiShYidmcLIAhVIlIgKHe6tAsw&url=http%3A%2F%2Fprod.sandia.gov%2Ftechlib%2Faccess-control.cgi%2F2014%2F1417550.pdf&usg=AFQjCNGaXmRbm0SvIS3zrIxd0z14q3BVYg&sig2=cLHjej-znRIW3fIIGlh5_Q>`_, Tech. Rep. SAND2014-17550, Sandia National Laboratories, Albuquerque, NM (United States) 2014.
 
-[7] R. Coe, V. Neary, M. Lawson, Y.-H. Yu, J. Weber, `Extreme conditions modeling workshop report <http://prod-http-80-800498448.us-east-1.elb.amazonaws.com/w/images/8/81/WEC_Extreme_Conditions_Modeling_Workshop_Report.pdf>`_, Tech. Rep. NREL/ TP-5000-62305 SNL/ SAND2014-16384R, Sandia National Laboratories, Albuquerque, New Mexico (2014).
+-- R. Coe, V. Neary, M. Lawson, Y.-H. Yu, J. Weber, `Extreme conditions modeling workshop report <http://prod-http-80-800498448.us-east-1.elb.amazonaws.com/w/images/8/81/WEC_Extreme_Conditions_Modeling_Workshop_Report.pdf>`_, Tech. Rep. NREL/ TP-5000-62305 SNL/ SAND2014-16384R, Sandia National Laboratories, Albuquerque, New Mexico (2014).
 
-[8] R. G. Coe, V. S. Neary, `Review of methods for modeling wave energy converter survival in extreme sea states <http://vtechworks.lib.vt.edu/bitstream/handle/10919/49221/101-Coe.pdf?sequence=1&isAllowed=y>`_, in: Proceedings of the 2nd Marine Energy Technology Symposium, Seattle, WA, USA, 2014.
+-- R. G. Coe, V. S. Neary, `Review of methods for modeling wave energy converter survival in extreme sea states <http://vtechworks.lib.vt.edu/bitstream/handle/10919/49221/101-Coe.pdf?sequence=1&isAllowed=y>`_, in: Proceedings of the 2nd Marine Energy Technology Symposium, Seattle, WA, USA, 2014.

examples/example_contourApproach.py

@@ -9,6 +9,7 @@
 import h5py
 import os
 
+
 # Load data from example_envSampling.py
 envFile = h5py.File(os.path.join('data', 'NDBC46022.h5'), 'r')
 Hs = np.array(envFile['buoy_Data/Hs'])
@@ -68,8 +69,8 @@
 ax.plot(T_Return, Hs_Return, np.zeros_like(T_Return), 'k')
 ax.plot(T_sample, Hs_sample, np.zeros_like(Hs_sample), 'yo')
 for i in range(len(T_sample)):
-    ax.plot([T_sample[i], T_sample[i]], [Hs_sample[i], Hs_sample[i]], [0, ev[i]],
-            '-', linewidth=2, color='b', alpha=.5)
+    ax.plot([T_sample[i], T_sample[i]], [Hs_sample[i], Hs_sample[i]],
+            [0, ev[i]], '-', linewidth=2, color='b', alpha=0.5)
 ax.plot(T_sample, Hs_sample, ev, '-o')
 ax.set_xlabel('Energy period, $T_e$ (s)')
 ax.set_ylabel('Sig. wave height, $H_s$ (m)')
@@ -82,6 +83,5 @@
 plt.grid(True)
 plt.xlabel('$x$')
 plt.ylabel('$CDF(x)$')
-plt.show()
 
 plt.show()