Merge to main branch for v3.0.0

.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.

.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*.

.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'
 

.github/workflows/push.yml

@@ -7,9 +7,9 @@ name: Build and Test
 
 on:
   push:
-    branches: [ main ]
+    branches: [ main, dev ]
   pull_request:
-    branches: [ main ]
+    branches: [ main, dev ]
 
 jobs:
   wecopttool_test:

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:

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}}