Documentation improvements/updates (#267)

* typographical errors

* move MATLAB version note to end
(not so relevant anymore)

* add recent papers

* add volume, issue, page to Michelen2023

* more explicit guidance on conda environments

* add new/missing papers

* links to webinars + companion notebooks

* minor typos

* how to disable docs build link check + notebooks

* note mamba is an option

* ignore link check for Sandia webinars pages

* removed disclaimer for Windows capytaine install

* fixed broken GitHub link on Releasing documentation page

* fixed typo in derivative docstrings

* added expanded installation instructions

* Fixed markdown levels in installation instructions

* minor formatting/grammar fixes

* Update INSTALLATION.md

Co-authored-by: Carlos A. Michelén Ströfer <cmichel@sandia.gov>

* rewrote Mac install instructions, lots of cleanup

* Update README.md

---------

Co-authored-by: mcdevin <mcdevin@sandia.gov>
Co-authored-by: Michael Devin <michaelcdevin@outlook.com>
Co-authored-by: Carlos A. Michelén Ströfer <cmichel@sandia.gov>

.github/CONTRIBUTING.md

@@ -76,6 +76,21 @@ The documentation uses the Jupyter notebook tutorials in the `examples` director
 When building the documentation locally you will need to have installed [pandoc](https://pandoc.org/installing.html) and [gifsicle](https://github.com/kohler/gifsicle).
 We recommend installing pandoc using its Anaconda distribution: `conda install -c conda-forge pandoc`.
 
+**NOTE:** it may be expedient at times to:
+
+ 1. **Avoid running the tutorial notebooks:** Add [`nbsphinx_execute = 'never'`](https://nbsphinx.readthedocs.io/en/0.9.3/configuration.html#nbsphinx_execute) to `docs/source/conf.py`
+ 2. **Disable the link check operation:** Comment out the `linkcheck` call in `docs/build_docs.py`
+
+```python
+if __name__ == '__main__':
+    source.make_theory_animations
+    # linkcheck()
+    html()
+    cleanup()
+```
+
+Make sure not to commit these changes!
+
 ### Editing the tutorials
 The tutorials are used as part of the Documentation.
 Before pushing any changes make sure that the saved version of the notebooks are clear (no cells run and no results).

.github/RELEASING.md

@@ -24,7 +24,7 @@ For details see the [Python packaging user guide](https://packaging.python.org/e
 
 The PyPI package is created and uploaded automatically to [TestPyPI](https://test.pypi.org/) and [PyPI](https://pypi.org/) on every GitHub release.
 This is done sequentially, so that if *TestPyPi* fails the package is not pushed to `PyPi`.
-See the [GitHub workflow](https://github.com/sandialabs/WecOptTool/blob/main/.github/workflows/publish-to-pypi.yml).
+See the [GitHub release workflow](https://github.com/sandialabs/WecOptTool/blob/main/.github/workflows/release.yml).
 
 **NOTE:** While GitHub lets you delete a release and then create a new one with the same name, PyPI does not. You can delete releases but you cannot upload a package with the same version as a previous one (even a deleted one).
 

INSTALLATION.md

@@ -0,0 +1,45 @@
+# Installation for users
+
+## Software requirements
+WecOptTool is supported on Windows, MacOS, and Linux. It requires Python 3.8 or higher. [Xcode](https://developer.apple.com/xcode/) may also be required on Mac.
+
+
+## Creating a virtual environment
+WecOptTool depends on many other Python packages, which can be organized into a *virtual environment*. Setting up a dedicated virtual environment allows for easier and more organized management of Python packages for your projects. The instructions below will walk you through creating a dedicated virtual environment and installing WecOptTool.
+
+Several tools exist that can both manage virtual environment and install Python pacakges. We provide instructions for two such tools:
+
+* If you are brand new to Python, or currently use Conda and want to try a much faster alternative, [click here](#installing-using-mamba) for installation instructions using **Mamba**.
+* If you already have Anaconda/Miniconda installed on your computer, [click here](#installing-using-conda) for instructions using **Conda**.
+
+### Installing using Mamba
+1. Download Miniforge3 (which contains Mamba) for your operating system [here](https://github.com/conda-forge/miniforge#download).
+2. Double-click on the file you just downloaded and follow the prompts on the new window to install Miniforge3. When the "Advanced Installation Options" prompt comes up, check the box next to "Add Miniforge3 to my PATH environment variable". All the other default selections should work.
+3. After installation completes, open a command prompt or terminal window and copy/paste the following code to confirm Mamba installed correctly. If installed correctly, the terminal should print both a Mamba and Conda version number (since Conda is used for some Mamba functions):
+    ```bash
+    mamba --version
+    ```
+4. Copy/paste the following code to create a new virtual environment named `wot`, activate the environment, and install WecOptTool and its dependencies in the environment. Feel free to replace `wot` in the first two lines with a different environment name if you would like:
+    ```bash
+    mamba create -n wot
+    mamba activate wot
+    mamba install wecopttool jupyter
+    pip install gmsh pygmsh meshio
+    ```
+
+### Installing using Conda
+1. Download Miniconda3 (which contains Conda) for your operating system [here](https://docs.conda.io/projects/miniconda/en/latest/index.html).
+2. Double-click on the file you just downloaded and follow the prompts on the new window to install Miniconda3. When the "Advanced Installation Options" prompt comes up, check the box next to "Add Miniforge3 to my PATH environment variable". All the other default selections should work.
+3. After installation completes, open a command prompt or terminal window (close any command/terminal windows you had open previously) and copy/paste the following code to confirm Conda installed correctly. If installed correctly, the terminal should print a Conda version number:
+    ```bash
+    conda --version
+    ```
+4. Copy/paste the following code to create a new virtual environment named `wot`, activate the environment, and install WecOptTool and its dependencies in the environment. Feel free to replace `wot` in the third and fourth lines with a different environment name if you would like:
+    ```bash
+    conda config --add channels conda-forge
+    conda config --set channel_priority strict
+    conda create -n wot
+    conda activate wot
+    conda install wecopttool jupyter
+    pip install gmsh pygmsh meshio
+    ```

README.md

@@ -10,8 +10,12 @@ The Wave Energy Converter Design Optimization Toolbox (WecOptTool) allows users
 Refer to [WecOptTool documentation](https://sandialabs.github.io/WecOptTool/) for more information, including project overview, tutorials, theory, and API documentation.
 
 ## Getting started
+**If you are brand new to Python and/or want detailed installation instructions, [click here](https://github.com/sandialabs/WecOptTool/INSTALLATION.md).**
+
 WecOptTool requires Python >= 3.8. Python 3.10 & 3.11 are supported.
-It is strongly recommended you create a dedicated virtual environment (e.g., using `conda`, `venv`, etc.) before installing `wecopttool`.
+It is strongly recommended you create a dedicated virtual environment (e.g., using [`conda`](https://www.anaconda.com/), [`mamba`](https://mamba.readthedocs.io/en/latest/), `venv`, etc.) before installing WecOptTool.
+
+From your dedicated environment, you can install WecOptTool via `conda`, `pip`, or `mamba`:
 
 **Option 1** - using `Conda` (requires having `conda-forge` added as a channel in your environment, see instructions [here](https://conda-forge.org/docs/user/introduction.html#how-can-i-install-packages-from-conda-forge)):
 
@@ -25,7 +29,11 @@ conda install -c conda-forge wecopttool
 pip install wecopttool
 ```
 
-This approach is not recommended for Windows users since compiling `capytaine` on Windows requires [extra steps](https://github.com/capytaine/capytaine/issues/115).
+**Option 3** - using `Mamba`:
+
+```bash
+mamba install wecopttool
+```
 
 **Geometry module and tutorials**
 

docs/source/conf.py

@@ -20,7 +20,7 @@
 project = 'WecOptTool'
 copyright = (
     '2020 National Technology & Engineering Solutions of Sandia, ' +
-    'LLC(NTESS). ' +
+    'LLC (NTESS). ' +
     'Under the terms of Contract DE-NA0003525 with NTESS, the U.S. ' +
     'Government retains certain rights in this software'
 )
@@ -62,6 +62,7 @@ def setup(app):
     'https://doi.org/10.2172/1330189',
     'https://sandialabs.github.io/WecOptTool/*',
     'https://doi.org/10.1080/17445302.2015.1089052',
+    'https://digitalops.sandia.gov/*',
 ]
 
 linkcheck_request_headers = {

docs/source/index.rst

@@ -18,9 +18,6 @@ This allows for the optimization study (e.g., to find the WEC geometry that resu
 The code is written to support arbitrary optimization studies, control strategies, and constraints.
 The code is written as a Python package and the source code can be found in the `GitHub repository`_.
 
-.. note::
-    A MATLAB version of WecOptTool was previously released and, while no longer being developed, is still available on GitHub: `WecOptTool-MATLAB`_.
-
 Getting Started
 ===============
 See installation instructions in the `GitHub repository`_.
@@ -33,6 +30,9 @@ WecOptTool is developed by `Sandia National Laboratories`_.
 The developers would like to acknowledge funding support from the US Department of Energy's Water Power Technologies Office.
 The developers would also like to acknowledge benefit from past collaborations with `Data Only Greater`_ and the `Oregon State University Design Engineering Lab`_.
 
+.. note::
+    A MATLAB version of WecOptTool was previously released and, while no longer being developed, is still available on GitHub: `WecOptTool-MATLAB`_.
+
 Sandia National Laboratories is a multi-mission laboratory managed and operated by National Technology and Engineering Solutions of Sandia, LLC., a wholly owned subsidiary of Honeywell International, Inc., for the U.S. Department of Energy's National Nuclear Security Administration under contract DE-NA0003525.
 
 .. _GitHub repository: https://github.com/sandialabs/WecOptTool

docs/source/references.rst

@@ -1,7 +1,23 @@
 References
 ==========
+
+General resources
+-----------------
+
+    * Companion notebooks to published papers:
+        * `Control Co-Design of Power Take-off Systems for Wave Energy Converters using WecOptTool <https://github.com/cmichelenstrofer/IEEE_TSTE_2023>`_ (:cite:t:`Michelen2023`:)
+        * `Incorporating empirical nonlinear efficiency into control co-optimization of a real world heaving point absorber using WECOPTTOOL <https://github.com/dtgaebe/OMAE_2023_103899>`_ (:cite:t:`Gaebele:2023wf`:)
+        * `Control co-design and uncertainty analysis of the LUPA's PTO using WecOptTool <https://github.com/cmichelenstrofer/EWTEC_2023>`_ (:cite:t:`Strofer:2023vw`:)
+    * Webinar recordings:
+        * `October, 2022 <https://digitalops.sandia.gov/Mediasite/Play/b3a653193c1a4da4a4d71d9908c3ac031d?enablejsapi=1>`_
+        * `February, 2022 <https://digitalops.sandia.gov/Mediasite/Play/fde6b77d82f944319dc19d9c7d11d8a51d?enablejsapi=1>`_
+
+Bibliography
+------------
 .. bibliography:: wecopttool_refs.bib
     :style: unsrt
 
     Falnes2002
-    Michelen2023
+    Grasberger:2023aa
+    Strofer:2023vw
+    Coe2020Initial

docs/source/theory.rst

@@ -3,14 +3,13 @@ Theory & Practice
 
 .. note::
     This theory section is intended to give a very high-level understanding of key concepts for WecOptTool.
-    For a more detailed explanation, please see :cite:`Bacelli2014Optimal,Bacelli2014Numerical,Coe2020Initial`.
-    A journal paper will be available soon.
+    For a more detailed explanation, please see :cite:`Michelen2023,Bacelli2014Optimal,Bacelli2014Numerical`.
 
 
 Basic concept
 -------------
 
-WecOptTool uses a pseudo-spectral method :cite:`Elnagar1995pseudospectral` to perform two tasks synchronously:
+WecOptTool uses a pseudo-spectral method :cite:`Elnagar1995pseudospectral` to perform two tasks simultaneously:
 
     1. Optimize the solution for the desired objective function (e.g. power generation)
     2. Simulate the wave energy converter (WEC) dynamics
@@ -83,7 +82,7 @@ When creating this frequency array, consider:
 
     * Exciting frequencies of the wave and, if you expect a nonlinear response, superharmonics of the exciting frequencies
     * Power absorption occurs at two times the exciting frequencies (only important for visualization)
-    * The fundamental frequency is also the frequency step (:math:`f_1=\Delta f`); set this sufficiently small to resolve the wave spectra and frequency response functios of interest
+    * The fundamental frequency is also the frequency step (:math:`f_1=\Delta f`); set this sufficiently small to resolve the wave spectra and frequency response functions of interest
 
 Automatic differentiation
 ^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -127,7 +126,7 @@ Here, the kinematics matrix, :math:`K`, is defined as the linear transformation
     p = K x
     :label: kinematics
 
-The relationship :math:`p(x)` is typically referred to as the *backward kinematics*, in the field of robotics. If the WEC were considered to be a robot it's hydrodynamic body would be equivalent to an endeffector represented in a global coordinate frame. The PTO positions would be equivalent to joint positions in local coordinates.
+The relationship :math:`p(x)` is typically referred to as the *backward kinematics*, in the field of robotics. If the WEC were considered to be a robot it's hydrodynamic body would be equivalent to an end effector represented in a global coordinate frame. The PTO positions would be equivalent to joint positions in local coordinates.
 The matrix :math:`K` has a size equal to the number of DOFs of the PTOs times the number of DOFs of the WEC.
 Note, however that the real kinematics might not be linear.
 Equation :eq:`kinematics` represents a linearization of :math:`p(x)` about the mean :math:`x=0` position, with the matrix :math:`K` being the inverse Jacobian of :math:`p(x)` at :math:`x=0`.
@@ -138,7 +137,7 @@ The transpose of :math:`K` is used to transform the PTO forces in PTO frame, :ma
     f_w = K^T f_p
     :label: k
 
-This relationship can be derived from conservation of energy in both frames, and using the definition in Equation :eq:`kinematics`:
+This relationship can be derived from conservation of energy in both frames, and using the definition in :eq:`kinematics`:
 
 .. math::
     f_w^T x = f_p^T p \\
@@ -149,7 +148,7 @@ This relationship can be derived from conservation of energy in both frames, and
 
 Troubleshooting
 ---------------
-If your simlation is not behaving as expected, consider some of the general troubleshooting steps below:
+If your simulation is not behaving as expected, consider some of the general troubleshooting steps below:
 
     * Check that the hydrodynamic coefficients are displaying expected behavior for high frequencies:
 

docs/source/tutorials.rst

@@ -1,25 +1,22 @@
 Tutorials
 =========
-This section presents two tutorials illustrating the application of WecOptTool.
+This section presents tutorials illustrating the application of WecOptTool.
 The tutorials are written as Jupyter Notebooks and are available in the `GitHub repository`_.
 
 The first tutorial uses the `WaveBot`_ WEC, which is a single-body WEC developed at Sandia.
 The tutorial has three sequential parts of increased complexity.
 The first and second parts solve only the inner optimization loop for optimal mechanical and electrical power, respectively.
 The third part builds on the second to solve a design optimization problem, using both the inner and outer optimization loops, and is more reflective of the optimization problems WecOptTool is designed to solve.
 
-
     - :doc:`_examples/tutorial_1_WaveBot`: Three part example of using the inner and outer optimization loops for a simple control co-design study.
 
+The second and third tutorials use the `AquaHarmonics`_ and `LUPA`_ WECs, respectively, and provide more robust optimization examples illustrating more complex cases of the WEC body, power take-off, applied forces, and constraints.
+These tutorials each have two parts, which are similar in structure to the second and third parts of Tutorial 1.
 
-The second and third tutorials uses the `AquaHarmonics`_ and `LUPA`_ WECs respectively, and provides more robust optimization examples illustrating more complex cases of the WEC body, power take-off, applied forces, and constraints.
-The tutorials each have two parts, which are similar in structure to the second and third parts of Tutorial 1.
-
-
-    - :doc:`_examples/tutorial_2_AquaHarmonics`: Two part example with a realistic power take-off system and co-design study.
+    - :doc:`_examples/tutorial_2_AquaHarmonics`: Two part example with a realistic power take-off system and co-design study. You can find an extended version 
     - :doc:`_examples/tutorial_3_LUPA`: Two part example with multiple bodies, multiple degrees of freedom, irregular waves, a mooring system, and realistic constraints.
 
-The fourth tutorial uses the `Pioneer` WEC model, which includes a unique pitch resonator PTO system. This tutorial illustrates how to use WecOptTool to implement and optimize control strategies for less common PTO archetypes.
+The fourth tutorial uses the `Pioneer WEC` model, which includes a unique pitch resonator PTO system. This tutorial illustrates how to use WecOptTool to implement and optimize control strategies for less common PTO archetypes.
 
     - :doc:`_examples/tutorial_4_Pioneer`: Example with custom PTO physics and modeling both hydrodynamic and non-hydrodynamic degrees of freedom.