Merge to main branch for v3.0.0 (#344)

* Update CONTRIBUTING.md to indicate PRs should be to the new `dev` branch * Update RELEASING.md to reflect new workflow with the `dev` branch * Set Default uniform_shift to False (#313) * Make uniform shift default false and fix test_core * Allow for non-uniform shift for impedance * update docstrings (#326) * damping naming and consistently change radiation damping (#328) * run CI + codeQL on dev PRs/pushses * Fix test failures (#330) * fix tests * fix pioneer * actually test power solution for irregular wave (#327) * Update test_integration with new scaling (#333) * Phase Realizations Demo and Docs (#315) * Pioneer tutorial realizations demo Add frequency array and realization study to beginning of pioneer tutorial * Update pioneer * Clean pioneer and update docs * remove print * Units * Update pioneer plots * Waves before frequencies * Explain less frequencies * Minor updates * Update pioneer * Merge branch 'dev' of https://github.com/sandialabs/WecOptTool into phases_demo * issue 321 fd_to_td() bug (#329) * bug bix : DC and Nyquist frequency should not be devided by two before ifft * Changed td_to_fd to scale single sided frequency components rather than TD signal * minor bug fix from issue332 #332 * nodf -> ndof (#334) * add DOI for Daniel's paper (#336) * Tutorial cleanup (#339) * run CI on PRs against dev branch * revamped tutorial 1, including fix for #293 * more tutorial cleanup and editorial changes * more cleanup and incorporated changes in #315 * fixed tutorial 2 colormaps * finishing touches * reverted a few accidental changes * fixes as per Jeff's review comments --------- Co-authored-by: Ryan Coe <[email protected]> * Utils dev - replaces old utilities PR (#343) * run CI on PRs against dev branch * coppied fundamental utility files * import utilities module * added utilities funtions to tut1 * added bem plot from utils * added bem plot from utils * updated sankey plot * updated check_radiation_damping * cleared outputs * corrected bug * changed Zi to hydro_impedance to be consistent with our variables name python convention * PR review edits * add grid to plots * removed draft functions in utilities.py * typo * Fixed one more typo I found while reviewing Daniel's changes --------- Co-authored-by: Ryan Coe <[email protected]> Co-authored-by: Michael Devin <[email protected]> * Post process docstrings; use loops for multiple realizations (#337) * post_processing docstrings - examples - parameters (order) * handle multiple phase realizations internally * Update wecopttool/core.py * making outputs lists * Update implementation to function with tutorial 1 for now * Update tutorials * Update LUPA * Make sure same WEC is passed in * Add test_utilities Revert "Add test_utilities" This reverts commit 27399f0. * Update utilities module * Update utilities * Update test_utilities * Update tutorial 1 utilities call --------- Co-authored-by: Carlos A. Michelén Ströfer <[email protected]> Co-authored-by: Carlos A. Michelén Ströfer <[email protected]> Co-authored-by: jtgrasb <[email protected]> Co-authored-by: jtgrasb <[email protected]> * v3.0.0 --------- Co-authored-by: Carlos A. Michelén Ströfer <[email protected]> Co-authored-by: jtgrasb <[email protected]> Co-authored-by: Ryan Coe <[email protected]> Co-authored-by: Daniel Gaebele <[email protected]> Co-authored-by: Carlos A. Michelén Ströfer <[email protected]> Co-authored-by: jtgrasb <[email protected]>
sandialabs · May 6, 2024 · 31b0361 · 31b0361
1 parent 5cf084f
commit 31b0361
Show file tree

Hide file tree

Showing 21 changed files with 1,969 additions and 980 deletions.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -42,7 +42,7 @@ Autograd does not support all NumPy and SciPy functionalities, see [autograd doc
   1. Create a fork of WecOptTool
   2. Create a branch for the specific issue
   3. Add desired code modifications. For enhancements add to documentation. Add or modify a test. Make sure all tests pass and documentation builds. Follow style guide above.
-  4. Do a pull request, and give admins edit access. [Link to any open issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) and add relevant tags. Use a concise but descriptive PR title, as this will be part of the [release notes](https://github.com/sandialabs/WecOptTool/releases) for the next version. Start the PR title with an all caps label followed by a colon, e.g., "BUG FIX: ...", "NEW FEATURE: ...", "DOCUMENTATION: ...", etc.
+  4. Do a pull request to the `dev` branch, and give admins edit access. [Link to any open issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) and add relevant tags. Use a concise but descriptive PR title, as this will be part of the [release notes](https://github.com/sandialabs/WecOptTool/releases) for the next version. Start the PR title with an all caps label followed by a colon, e.g., "BUG FIX: ...", "NEW FEATURE: ...", "DOCUMENTATION: ...", etc. **Note: Pull requests should be made to the `dev` branch, not the `main` branch**. 
 
 ## Tests
 There are a series of unit and integration tests defined in the `tests` directory.

diff --git a/.github/RELEASING.md b/.github/RELEASING.md
@@ -3,7 +3,8 @@ This section is for developers.
 
 Before a release make sure to:
 
-* change [version number](https://semver.org/) in `pyproject.toml`
+* change [version number](https://semver.org/) in `pyproject.toml` in the `dev` branch.
+* Merge the `dev` branch into the `main` branch. **Note: the `dev` branch should only be merged into `main` when it is ready for a new release.**
 
 ## GitHub
 In the GitHub repository, click on *Releases*, click on *Draft new release*.

diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml
@@ -4,9 +4,9 @@ name: "CodeQL"
 
 on:
   push:
-    branches: [ main ]
+    branches: [ main, dev ]
   pull_request:
-    branches: [ main ]
+    branches: [ main, dev ]
   schedule:
     - cron: '30 1 * * 0'
 

diff --git a/docs/source/theory.rst b/docs/source/theory.rst
@@ -146,6 +146,16 @@ This relationship can be derived from conservation of energy in both frames, and
     f_w = K^T f_p \\
     :label: conservation_energy
 
+Phase Realizations
+^^^^^^^^^^^^^^^^^^
+Irregular waves are defined in WecOptTool as a spectrum of complex frequency-domain wave elevations. The phase of each of the elevation elements impacts the time-domain result. Thus, the standard calculation of the objective function (average power) may change across a range of phase realizations. The amount of variance in power depends on multiple factors such as the optimization problem and the frequency array. When creating an irregular wave using :py:meth:`wecopttool.waves.long_crested_wave` or :py:meth:`wecopttool.waves.irregular_wave`, :code:`nrealizations` can be used to select the number of phase realizations to be used. By default, random realizations will be used to create the selected number of wave elevation spectra. The :py:meth:`wecopttool.WEC.solve` function will automatically iterate through and solve the optimization problem for each realization, and the overall result can be found by averaging the value of the objective function across all realizations. A general recommendation is to use sufficient random phase realizations such that the total simulation time sums to 20 minutes. 
+
+.. math::
+    t_{total} = \frac{nrealizations}{f1}
+    :label: total_time
+
+The selection of the number of realizations is further detailed in :doc:`_examples/tutorial_4_Pioneer`.
+
 Troubleshooting
 ---------------
 If your simulation is not behaving as expected, consider some of the general troubleshooting steps below:

diff --git a/docs/source/wecopttool_refs.bib b/docs/source/wecopttool_refs.bib
@@ -7,6 +7,7 @@ @inproceedings{Gaebele:2023wf
 	date-added = {2023-01-12 14:02:25 -0700},
 	date-modified = {2023-10-03 08:41:16 -0600},
 	month = {June},
+	doi = {10.1115/OMAE2023-103899},
 	series = {International Conference on Ocean, Offshore and Arctic Engineering},
 	title = {INCORPORATING EMPIRICAL NONLINEAR EFFICIENCY INTO CONTROL CO-OPTIMIZATION OF A REAL WORLD HEAVING POINT ABSORBER USING {WECOPTTOOL}},
 	year = {2023}}

diff --git a/examples/data/tutorial_4_freq_range.nc b/examples/data/tutorial_4_freq_range.nc
diff --git a/examples/data/tutorial_4_nfreqs.nc b/examples/data/tutorial_4_nfreqs.nc
diff --git a/examples/data/tutorial_4_nrealizations.nc b/examples/data/tutorial_4_nrealizations.nc
diff --git a/examples/tutorial_1_WaveBot.ipynb b/examples/tutorial_1_WaveBot.ipynb
diff --git a/examples/tutorial_2_AquaHarmonics.ipynb b/examples/tutorial_2_AquaHarmonics.ipynb
diff --git a/examples/tutorial_3_LUPA.ipynb b/examples/tutorial_3_LUPA.ipynb
diff --git a/examples/tutorial_4_Pioneer.ipynb b/examples/tutorial_4_Pioneer.ipynb
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "wecopttool"
-version = "2.7.0"
+version = "3.0.0"
 description = "WEC Design Optimization Toolbox"
 readme = "README.md"
 authors = [

diff --git a/tests/test_core.py b/tests/test_core.py
@@ -919,8 +919,8 @@ def test_read_write_netcdf(self, hydro_data, hydro_data_new):
         assert hydro_data.equals(hydro_data_new)
 
 
-class TestCheckLinearDamping:
-    """Test function :python:`check_linear_damping`."""
+class TestCheckRadiationDamping:
+    """Test function :python:`check_radiation_damping`."""
 
     @pytest.fixture(scope="class")
     def data(self, hydro_data):
@@ -933,44 +933,39 @@ def data(self, hydro_data):
 
     @pytest.fixture(scope="class")
     def tol(self, data):
-        """Tolerance for function :python:`check_linear_damping`."""
+        """Tolerance for function :python:`check_radiation_damping`."""
         return 0.01
 
     @pytest.fixture(scope="class")
     def data_new_uniform(self, data, tol):
         """Hydrodynamic data structure for which the function
-        :python:`check_linear_damping` has been called.
+        :python:`check_radiation_damping` has been called.
         """
-        return wot.check_linear_damping(data, tol)
+        return wot.check_radiation_damping(data, tol, True)
 
     @pytest.fixture(scope="class")
     def data_new_nonuniform(self, data, tol):
         """Hydrodynamic data structure for which the function
-        :python:`check_linear_damping` has been called.
+        :python:`check_radiation_damping` has been called.
         """
-        return wot.check_linear_damping(data, tol, False)
+        return wot.check_radiation_damping(data, tol, False)
 
-    def test_friction(self, data_new_uniform, tol):
+    def test_radiation(self, data, data_new_uniform, tol):
         """Test that the modified friction diagonal has the expected
         value for a uniform shift.
         """
-        assert np.allclose(np.diagonal(data_new_uniform.friction.values), tol)
+        radiation_diff = (data_new_uniform.radiation_damping.values
+                            - data.radiation_damping.values)
+        assert np.allclose(radiation_diff, radiation_diff[0], tol)
 
-    def test_only_diagonal_friction(self, data, data_new_uniform):
-        """Test that only the diagonal was changed for a uniform shift."""
-        data_org = data.copy(deep=True)
-        def nodiag(x):
-            return x.friction.values - np.diag(np.diagonal(x.friction.values))
-        assert np.allclose(nodiag(data_new_uniform), nodiag(data_org))
-
-    def test_only_friction(self, data, data_new_uniform):
-        """Test that only the friction is changed in the hydrodynamic
+    def test_only_radiation(self, data, data_new_uniform):
+        """Test that only the radiation is changed in the hydrodynamic
         data for a uniform shift.
         """
-        data_new_nofric = data_new_uniform.copy(deep=True
-                                                ).drop_vars('friction')
-        data_org_nofric = data.copy(deep=True).drop_vars('friction')
-        assert data_new_nofric.equals(data_org_nofric)
+        data_new_norad = data_new_uniform.copy(deep=True
+                                               ).drop_vars('radiation_damping')
+        data_org_norad = data.copy(deep=True).drop_vars('radiation_damping')
+        assert data_new_norad.equals(data_org_norad)
 
     def test_damping(self, data_new_nonuniform, tol):
         """Test that the modified radiation damping diagonal has the expected