FOSWEC Example

.github/CONTRIBUTING.md

@@ -12,7 +12,7 @@ Using `conda` this looks like:
 ```bash
 conda create -n wecopttool
 conda activate wecopttool
-conda install -c conda-forge python=3.11 capytaine wavespectra
+conda install -c conda-forge python=3.12 capytaine wavespectra
 git clone [email protected]:<YOUR_USER_NAME>/WecOptTool.git
 cd WecOptTool
 pip install -e .[dev]
@@ -22,7 +22,7 @@ And using `pip`:
 ```bash
 git clone [email protected]:<YOUR_USER_NAME>/WecOptTool.git
 cd WecOptTool
-python3.11 -m venv .venv
+python3.12 -m venv .venv
 . .venv/bin/activate
 pip install -e .[dev]
 ```

.github/RELEASING.md

@@ -30,6 +30,20 @@ See the [GitHub release workflow](https://github.com/sandialabs/WecOptTool/blob/
 **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).
 
 ## Conda package
-When a new release is available on PyPI, Conda-forge has a [bot](https://github.com/regro/autotick-bot) that will automatically find this and create a pull request in [wecopttool-feedstock](https://github.com/conda-forge/wecopttool-feedstock), the GitHub repository that houses the Conda recipe for WecOptTool. Conda-forge does not currently have full integration with `pyproject.toml` files, so we have to manually update the [`meta.yaml`](https://github.com/conda-forge/wecopttool-feedstock/blob/main/recipe/meta.yaml) file in the WecOptTool Conda recipe with any new or removed dependencies if changes were made in `pyproject.toml`. The version number, SHA256, and build number should be automatically updated by the bot, but these should also be checked just in case.
+The Conda package for WecOptTool is housed in the [wecopttool-feedstock](https://github.com/conda-forge/wecopttool-feedstock) repository.
+When a new release is available on PyPI, Conda-forge has a [bot](https://github.com/regro/autotick-bot) that will automatically detect it, create a pull request in wecopttool-feedstock, and merge it.
+In other words, the WecOptTool Conda package will usually update automatically within a few hours of a new release being published.
 
-Follow the instructions on the [Conda-forge maintainer documentation](https://conda-forge.org/docs/maintainer/updating_pkgs.html#pushing-to-regro-cf-autotick-bot-branch) to push any required changes to the bot-generated pull request. Merge and close the pull request once these updates are pushed and the Conda-forge CI passes. The Conda build will now install the new release for users.
+If any dependencies are added, removed, or changed in `pyproject.toml`[^1], the Conda recipe must be manually updated to reflect these changes.
+To do this:
+
+1. Fork `wecopttool-feedstock`
+2. In a new branch, update [`wecopttool-feedstock/recipe/meta.yaml`](https://github.com/conda-forge/wecopttool-feedstock/blob/main/recipe/meta.yaml) (the file containing the Conda recipe) by editing the `run` list of `requirements` to mirror the dependency list in `pyproject.toml`.
+3. Create a [pull request](https://github.com/conda-forge/wecopttool-feedstock/pulls) to the `main` branch of `wecopttool-feedstock` from your new branch.
+4. Follow the instructions in the autogenerated checklist in the pull request description.
+5. Merge the pull request once the linter comes back clean and the CI passes.
+
+Other changes to the Conda configuration unrelated to a new version release, such as changing package metadata or the maintainers list, also require a manual update to the recipe through this same process.
+
+[^1]: At time of writing, Conda-forge does not currently have full integration with `pyproject.toml` files, see https://github.com/conda-forge/wecopttool-feedstock/pull/8.
+This may change in the future though: see https://github.com/conda/conda/issues/12462.

.github/workflows/pr.yml

@@ -17,7 +17,7 @@ jobs:
       fail-fast: false
       matrix:
         os: ["ubuntu-latest", "macos-latest", "windows-latest"]
-        python-version: ["3.10", "3.11"]  # CHANGE: Python version
+        python-version: ["3.11", "3.12"]  # CHANGE: Python version
 
     steps:
     # Checkout the WecOptTool repo
@@ -30,10 +30,10 @@ jobs:
     #   - the content of pyproject.toml changes
     #   - you manually change the value of the CACHE_NUMBER below
     # Else the existing cache is used.
-    - name: Setup Mambaforge
+    - name: Setup Miniforge
       uses: conda-incubator/setup-miniconda@v2
       with:
-          miniforge-variant: Mambaforge
+          miniforge-variant: Miniforge3
           miniforge-version: latest
           activate-environment: test-env
           use-mamba: true
@@ -45,8 +45,6 @@ jobs:
       shell: bash
 
     # create a conda yaml file
-    # for some reason Windows installs capytaine 1.4 instead of latest.
-    # CHANGE: Capytaine version
     - name: Create environment.yml file
       run: |
         echo "name: test-env" >> environment.yml;
@@ -123,7 +121,7 @@ jobs:
     - uses: actions/checkout@v3
     - uses: actions/setup-python@v4
       with:
-        python-version: '3.11'  # CHANGE: Python version
+        python-version: '3.12'  # CHANGE: Python version
 
     - name: Install dependencies
       run: sudo apt-get install libglu1 pandoc gifsicle
@@ -139,4 +137,4 @@ jobs:
       shell: bash -l {0}
       run: |
         git fetch --tags
-        python3 docs/build_docs.py
+        python3 docs/build_docs.py --build production

.github/workflows/push.yml

@@ -17,7 +17,7 @@ jobs:
       fail-fast: false
       matrix:
         os: ["ubuntu-latest", "macos-latest", "windows-latest"]
-        python-version: ["3.10", "3.11"]  # CHANGE: Python version
+        python-version: ["3.11", "3.12"]  # CHANGE: Python version
 
     steps:
     # Checkout the WecOptTool repo
@@ -30,10 +30,10 @@ jobs:
     #   - the content of pyproject.toml changes
     #   - you manually change the value of the CACHE_NUMBER below
     # Else the existing cache is used.
-    - name: Setup Mambaforge
+    - name: Setup Miniforge
       uses: conda-incubator/setup-miniconda@v2
       with:
-          miniforge-variant: Mambaforge
+          miniforge-variant: Miniforge3
           miniforge-version: latest
           activate-environment: test-env
           use-mamba: true
@@ -45,8 +45,6 @@ jobs:
       shell: bash
 
     # create a conda yaml file
-    # for some reason Windows installs capytaine 1.4 instead of latest.
-    # CHANGE: Capytaine version
     - name: Create environment.yml file
       run: |
         echo "name: test-env" >> environment.yml;
@@ -122,7 +120,7 @@ jobs:
     - uses: actions/checkout@v3
     - uses: actions/setup-python@v4
       with:
-        python-version: '3.11' # CHANGE: Python version
+        python-version: '3.12' # CHANGE: Python version
 
     - name: Install dependencies
       run: sudo apt-get install libglu1 pandoc gifsicle
@@ -132,13 +130,13 @@ jobs:
       run: |
         python3 -m pip install --upgrade pip
         pip3 install wheel coveralls
-        pip3 install .[dev,geometry]
+        pip3 install -e .[dev,geometry]
 
     - name: Build documentation
       shell: bash -l {0}
       run: |
         git fetch --tags
-        python3 docs/build_docs.py
+        python3 docs/build_docs.py --build production
 
     - name: Deploy
       uses: peaceiris/actions-gh-pages@v3

.github/workflows/release.yml

@@ -16,7 +16,7 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v4
       with:
-        python-version: '3.11' # CHANGE: Python version
+        python-version: '3.12' # CHANGE: Python version
 
     - name: Build a binary wheel and a source tarball
       run: |
@@ -46,7 +46,7 @@ jobs:
     - uses: actions/checkout@v3
     - uses: actions/setup-python@v4
       with:
-        python-version: '3.11' # CHANGE: Python version
+        python-version: '3.12' # CHANGE: Python version
 
     - name: Install dependencies
       run: sudo apt-get install libglu1 pandoc gifsicle
@@ -62,7 +62,7 @@ jobs:
       shell: bash -l {0}
       run: |
         git fetch --tags
-        python3 docs/build_docs.py
+        python3 docs/build_docs.py --build production
 
     - name: Deploy
       uses: peaceiris/actions-gh-pages@v3

.gitignore

@@ -6,9 +6,9 @@ WecOptTool.egg-info
 dist/
 
 # Sphinx
-docs/_build/
 docs/source/_examples
 docs/source/api_docs
+docs/pages/
 
 # Tutorials results
 results*

README.md

@@ -12,7 +12,7 @@ Refer to [WecOptTool documentation](https://sandialabs.github.io/WecOptTool/) fo
 ## Getting started
 **If you are brand new to Python and/or want detailed installation instructions, [click here](https://github.com/sandialabs/WecOptTool/blob/main/INSTALLATION.md).**
 
-WecOptTool requires Python >= 3.8. Python 3.10 & 3.11 are supported.
+WecOptTool requires Python >= 3.8. Python 3.11 & 3.12 are supported.
 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`:

docs/README.md

@@ -0,0 +1,8 @@
+# Sphinx Documentation
+This directory contains the files used to generate the [Sphinx documentation site for WecOptTool](https://sandialabs.github.io/WecOptTool/).
+
+* `build_docs.py` is a script used to run the Sphinx build itself. This script uses the built-in Sphinx API (i.e. the `Sphinx` class and `Sphinx.build()`) rather than Makefiles, which runs counter to the general Sphinx documentation. This is so the Sphinx build process cooperates better with Windows and GitHub Actions, see [#204](https://github.com/sandialabs/WecOptTool/pull/204). This script can be called with either  `python build_docs.py --build production` or `python build_docs.py --build debug` options. `--build debug` is best for testing a documentation build locally, and will only build for the Git branch you are currently on. `--build production` is used in the GitHub CI workflows, and generates documentation for all the branches specified in `versions.yaml`.
+* The `source/` subdirectory includes `conf.py` (the Sphinx configuration file for the Sphinx build) and all the files populating the documentation site.
+* `clean_docs.py` removes the files and directories automatically generated by Sphinx during a build. This should be run before committing changes in this directory to GitHub.
+* `versions.yaml` specifies which branches to build the documentation from when the `production` build option is selected when `build_docs.py` is called. This is currently set so `main` is the default landing page (aka `latest`) with `dev` also being built.
+

docs/build_docs.py

@@ -3,6 +3,7 @@
 import shutil
 import re
 import yaml
+import argparse 
 
 from sphinx.application import Sphinx
 
@@ -17,6 +18,10 @@
 html_dir = os.path.join(build_dir, 'html')
 doctree_dir = os.path.join(build_dir, 'doctrees')
 
+parser = argparse.ArgumentParser()
+parser.add_argument('-b', '--build', nargs=1, type=str,
+                    choices=['debug', 'production'],
+                    default='debug')
 
 def linkcheck():
     app = Sphinx(source_dir,
@@ -51,36 +56,56 @@ def cleanup():
         f.write(data2)
 
 
-def build_doc(version, tag, home_branch):
-    os.environ['current_version'] = version
-    subprocess.run(f'git checkout {tag}', shell=True)
-    subprocess.run(
-        f"git checkout {home_branch} -- {os.path.join(source_dir, 'conf.py')}", shell=True)
-    subprocess.run(
-        f"git checkout {home_branch} -- {os.path.join(docs_dir, 'versions.yaml')}", shell=True)
-    subprocess.run(
-        f"git checkout {home_branch} -- {os.path.join(source_dir, '_templates/versions.html')}", shell=True)
+def build_doc(version, tag, home_branch, build):
+    if build != 'debug':
+        os.environ['current_version'] = version
+        subprocess.run(f'git checkout {tag}', shell=True)
+        subprocess.run(
+            f"git checkout {home_branch} -- {os.path.join(source_dir, 'conf.py')}",
+            shell=True)
+        subprocess.run(
+            f"git checkout {home_branch} -- {os.path.join(docs_dir, 'versions.yaml')}",
+            shell=True)
+        subprocess.run(
+            f"git checkout {home_branch} -- {os.path.join(source_dir, '_templates/versions.html')}",
+            shell=True)
     source.make_theory_animations
     linkcheck()
     html()
     cleanup()
-    subprocess.run(
-        f"git checkout {home_branch}", shell=True)
+    if build != 'debug':
+        subprocess.run(
+            f"git checkout {home_branch}", shell=True)
 
 
-if __name__ == '__main__':
-    home_name = 'latest'
-    with open(os.path.join(docs_dir, 'versions.yaml'), 'r') as v_file:
-        versions = yaml.safe_load(v_file)
-    home_branch = versions[home_name]
-    build_doc(home_name, home_branch, home_branch)
-    print(f"Moving HTML pages to {os.path.join(docs_dir, 'pages')}...")
-    shutil.copytree(html_dir, os.path.join(docs_dir, 'pages'))
+def move_pages(dest_dir=None):
+    if dest_dir is None:
+        print(f"Moving HTML pages to {os.path.join(docs_dir, 'pages')}...")
+        shutil.copytree(
+            html_dir, os.path.join(docs_dir, 'pages'))
+    else:
+        print(f"Moving HTML pages to {os.path.join(docs_dir, 'pages', dest_dir)}...")
+        shutil.copytree(
+            html_dir, os.path.join(docs_dir, 'pages', dest_dir))
+    shutil.rmtree(build_dir, ignore_errors=True)
     print('Done.')
-    for name, tag in versions.items():
-        if name != home_name:
-            build_doc(name, tag, home_branch)
-            print(f"Moving HTML pages to {os.path.join(docs_dir, 'pages', name)}...")
-            shutil.copytree(html_dir, os.path.join(docs_dir, 'pages', name))
-            print('Done.')
-    shutil.rmtree(html_dir)
+
+
+if __name__ == '__main__':
+    args = parser.parse_args()
+    build = args.build
+    if build == 'debug':
+        print(f'Building docs in current branch...')
+        build_doc('latest', '', '', build)
+        move_pages()
+    else:
+        home_name = 'latest'
+        with open(os.path.join(docs_dir, 'versions.yaml'), 'r') as v_file:
+            versions = yaml.safe_load(v_file)
+        home_branch = versions[home_name]
+        build_doc(home_name, home_branch, home_branch, build)
+        move_pages()
+        for name, tag in versions.items():
+            if name != home_name:
+                build_doc(name, tag, home_branch, build)
+                move_pages(dest_dir=name)

docs/clean_docs.py

@@ -2,16 +2,16 @@
 from shutil import rmtree
 
 docs_dir = os.path.dirname(os.path.abspath(__file__))
-build_dir = os.path.join(docs_dir, '_build')
 source_dir = os.path.join(docs_dir, 'source')
+build_dir = os.path.join(docs_dir, '_build')
 example_dir = os.path.join(source_dir, '_examples')
 api_dir = os.path.join(source_dir, 'api_docs')
 pages_dir = os.path.join(docs_dir, 'pages')
 
 def clean():
+    rmtree(build_dir, ignore_errors=True)
     rmtree(example_dir, ignore_errors=True)
     rmtree(api_dir, ignore_errors=True)
-    rmtree(build_dir, ignore_errors=True)
     rmtree(pages_dir, ignore_errors=True)
 
 if __name__ == '__main__':

docs/source/conf.py

@@ -57,6 +57,7 @@
   'current_version' : current_branch,
   'other_versions' : [],
 }
+
 with open(os.path.join(project_root, 'docs/versions.yaml'), 'r') as v_file:
     versions = yaml.safe_load(v_file)
 for name in versions.keys():

docs/source/references.rst

@@ -21,3 +21,5 @@ Bibliography
     Grasberger:2023aa
     Strofer:2023vw
     Coe2020Initial
+    DEVIN2024119124
+    Coe:2024aa

docs/source/theory.rst

@@ -54,15 +54,15 @@ How's this different from what I'm used to?
 Most users will be more familiar with a time-stepping approach for differential equations--this is the method applied in Simulink and therefore `WEC-Sim`_.
 Starting from an initial time (e.g., :math:`t=0`), the solution is solved by iteratively stepping forward in time.
 
-.. image:: ../_build/html/_static/theory_animation_td.gif
+.. image:: ../pages/_static/theory_animation_td.gif
     :width: 600
     :alt: Time-domain solution animation
     :align: center
 
 Pseudo-spectral methods can be applied to solve the same differential equations, but solve the entire time period of interest at once.
 At first the solution will not be correct, but as the optimization algorithm iterates, it will progressively improve the solution.
 
-.. image:: ../_build/html/_static/theory_animation_ps.gif
+.. image:: ../pages/_static/theory_animation_ps.gif
     :width: 600
     :alt: Pseudo-spectral solution animation
     :align: center

docs/source/wecopttool_refs.bib

@@ -99,3 +99,22 @@ @article{Bacelli2014Numerical
 	title = {Numerical optimal control of wave energy converters},
 	volume = {6},
 	year = {2014}}
+
+@article{DEVIN2024119124,
+	title = {High-dimensional control co-design of a wave energy converter with a novel pitch resonator power takeoff system},
+	author = {Michael C. Devin and Daniel T. Gaebele and Carlos A. Michelén Ströfer and Jeff T. Grasberger and Jantzen Lee and Ryan G. Coe and Giorgio Bacelli},
+	journal = {Ocean Engineering},
+	volume = {312},
+	pages = {119124},
+	year = {2024},
+	issn = {0029-8018},
+	doi = {10.1016/j.oceaneng.2024.119124}}
+
+@inproceedings{Coe:2024aa,
+	address = {Blacksburg, VA},
+	author = {Ryan G. Coe and Michael C. Devin and Carlos A. {Michel{\'e}n Str{\"o}fer} and Jantzen Lee and Giorgio Bacelli and Alicia Keow and Daniel T. Gaebele and Jeff Grasberger and Steven J. Spencer and Johannes Spinneken and Vincent S. Neary and Brek Meuris},
+	booktitle = {15th IFAC Conference on Control Applications in Marine Systems, Robotics and Vehicles (IFAC-CAMS)},
+	month = {September},
+	organization = {IFAC},
+	title = {Co-design of a wave energy converter for autonomous power},
+	year = {2024}}