Pioneer tutorial updates (empirical impedance model and nonlinear spring)

.github/CONTRIBUTING.md

@@ -4,15 +4,15 @@ Community contributions are welcomed! 🎊
 ## Installation for developers
 
 * It is recommended that you create a *virtual environment*, e.g. using `conda`, `venv`, or similar.
-* If you want to build the documentation locally you will also need to install [pandoc](https://pandoc.org/installing.html) and [gifsicle](https://github.com/kohler/gifsicle).
-* If you do not have Fortran compilers properly setup in your system, install `capytaine` and `wavesspectra` using `conda`. In this case you will need to have a `conda` virtual environment. This is recommended for *Windows* users since compiling `capytaine` on *Windows* requires [extra steps](https://github.com/capytaine/capytaine/issues/115).
+* If you want to build the documentation locally you will also need to install [pandoc](https://pandoc.org/installing.html) and [gifsicle](https://github.com/kohler/gifsicle). On *Windows*, we recommend installing pandoc using `conda` (i.e. `conda install -c conda-forge pandoc`)
+* Building using `pip` on *MacOS* requires the manual installation of Fortran compilers, see discussion [here](https://github.com/sandialabs/WecOptTool/discussions/111). For ARM-based Macs, see [issue #324](https://github.com/sandialabs/WecOptTool/issues/324)
 * On a ZSH shell (*MacOS*) do `pip install -e .\[dev]` instead of `pip install -e .[dev]` in the instructions below (i.e., escape the opening square bracket).
 
 Using `conda` this looks like:
 ```bash
-conda create -n wecopttool python=3.11
+conda create -n wecopttool
 conda activate wecopttool
-conda install -c conda-forge capytaine wavespectra
+conda install -c conda-forge python=3.11 capytaine wavespectra
 git clone git@github.com:<YOUR_USER_NAME>/WecOptTool.git
 cd WecOptTool
 pip install -e .[dev]
@@ -63,13 +63,13 @@ The documentation is built using [Sphinx](https://www.sphinx-doc.org/en/master/)
 The source code (restructured text) is in `./docs/source` and images are in `./docs/source/_static`.
 The homepage source code is in `./docs/source/index.rst`.
 
-To build the documentation locally (not required but good check)
+To build the documentation locally (not required but good check), go to `./docs/versions.yaml` and change the value of `latest` to be your local branch. Then run:
 
 ```bash
 python3 docs/build_docs.py
 ```
 
-The built documentation will be in `./docs/_build` and the homepage is `./docs/_build/index.html`.
+The built documentation will be in `./docs/pages` and the homepage is `./docs/pages/index.html`.
 To delete, do `python3 docs/clean_docs.py`.
 
 The documentation uses the Jupyter notebook tutorials in the `examples` directory.

.github/pull_request_template.md

@@ -9,7 +9,7 @@ Concise description of the pull request with references to any [issues](https://
 
 ## Checklist for PR
 - [ ] Authors read the [contribution guidelines](https://github.com/sandialabs/WecOptTool/blob/main/.github/CONTRIBUTING.md)
-- [ ] The pull request is from an issue branch (not main) on *your* fork, to the [main branch in WecOptTool](https://github.com/sandialabs/WecOptTool).
+- [ ] The pull request is from an issue branch (not main) on *your* fork, to the [dev branch in WecOptTool](https://github.com/sandialabs/WecOptTool/tree/dev).
 - [ ] The authors have given the admins edit access
 - [ ] All changes adhere to the style guide including PEP8, Docstrings, and Type Hints.
 - [ ] Modified the documentation if applicable

.github/workflows/pr.yml

@@ -0,0 +1,142 @@
+name: Build and Test
+# 1. Build and test WecOptTool
+#   - check that WecOptTool builds on a matrix of OS + Python versions
+#   - check that all tests pass on the same matrix
+#   - report the test code coverage
+# 2. Check that the documentation builds correctly
+
+on:
+  pull_request:
+    branches: [ main, dev ]
+
+jobs:
+  wecopttool_test:
+    name: Build (${{ matrix.python-version }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ["ubuntu-latest", "macos-latest", "windows-latest"]
+        python-version: ["3.10", "3.11"]  # CHANGE: Python version
+
+    steps:
+    # Checkout the WecOptTool repo
+    - uses: actions/checkout@v3
+
+    # Cache the conda environment >>>
+    # The cache key includes the OS, the date, the hash of the pyproject.toml file, and the cache number.
+    # A new cache is created if:
+    #   - this is the first time today that this file is run (date changes)
+    #   - 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
+      uses: conda-incubator/setup-miniconda@v2
+      with:
+          miniforge-variant: Mambaforge
+          miniforge-version: latest
+          activate-environment: test-env
+          use-mamba: true
+
+    # save the date to include in the cache key
+    - name: Get Date
+      id: get-date
+      run: echo "DATE=$(/bin/date -u '+%Y%m%d')" >> $GITHUB_ENV
+      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;
+        echo " " >> environment.yml
+        echo "dependencies:" >> environment.yml
+        echo "  - python=${{ matrix.python-version }}" >> environment.yml
+        echo "  - capytaine" >> environment.yml
+        echo "  - wavespectra" >> environment.yml
+        cat environment.yml
+
+    # use the cache if it exists
+    - uses: actions/cache@v3
+      env:
+        CACHE_NUMBER: 0  # increase to reset cache manually
+      with:
+        path: ${{ env.CONDA }}/envs
+        key: conda-${{ runner.os }}--${{ runner.arch }}--${{ env.DATE }}-${{ hashFiles('pyproject.toml') }}-${{ env.CACHE_NUMBER }}
+      id: cache
+
+    # if cache key has changed, create new cache
+    - name: Update environment
+      run: mamba env update -n test-env -f environment.yml
+      if: steps.cache.outputs.cache-hit != 'true'
+    # <<< Cache the conda environment
+
+    # install libglu on ubuntu.
+    - name: Install libglu
+      if: matrix.os == 'ubuntu-latest'
+      run: sudo apt-get install libglu1
+
+    # install WecOptTool, pytest/coveralls, and gmsh/pygmsh
+    - name: Install WecOptTool
+      shell: bash -l {0}
+      run: |
+        conda activate test-env
+        python3 -m pip install --upgrade pip
+        pip3 install gmsh pygmsh coveralls pytest
+        pip3 install .
+
+    # run all tests & coverage
+    - name: Run Test
+      shell: bash -l {0}
+      run: coverage run -m pytest
+
+    # upload coverage data
+    - name: Upload coverage data to coveralls.io
+      shell: bash -l {0}
+      run: coveralls --service=github
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        COVERALLS_FLAG_NAME: ${{ matrix.os }}-${{ matrix.python-version }}
+        COVERALLS_PARALLEL: true
+
+
+  coveralls:
+    name: Indicate completion to coveralls.io
+    needs: wecopttool_test
+    runs-on: ubuntu-latest
+    container: python:3-slim
+    steps:
+    - name: Finished
+      run: |
+        pip3 install --upgrade coveralls
+        coveralls --finish
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+
+  documentation_test:
+    name: Build documentation
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'  # CHANGE: Python version
+
+    - name: Install dependencies
+      run: sudo apt-get install libglu1 pandoc gifsicle
+
+    - name: Install WecOptTool for documentation
+      shell: bash -l {0}
+      run: |
+        python3 -m pip install --upgrade pip
+        pip3 install wheel coveralls
+        pip3 install .[dev,geometry]
+
+    - name: Build documentation
+      shell: bash -l {0}
+      run: |
+        git fetch --tags
+        python3 docs/build_docs.py

.github/workflows/push.yml

@@ -1,15 +1,13 @@
-name: Build and Test
+name: Test and Deploy
 # 1. Build and test WecOptTool
 #   - check that WecOptTool builds on a matrix of OS + Python versions
 #   - check that all tests pass on the same matrix
 #   - report the test code coverage
-# 2. Check that the documentation builds correctly
+# 2. Test and deploy the documentation website
 
 on:
   push:
     branches: [ main, dev ]
-  pull_request:
-    branches: [ main, dev ]
 
 jobs:
   wecopttool_test:
@@ -55,7 +53,7 @@ jobs:
         echo " " >> environment.yml
         echo "dependencies:" >> environment.yml
         echo "  - python=${{ matrix.python-version }}" >> environment.yml
-        echo "  - capytaine=1.5" >> environment.yml
+        echo "  - capytaine" >> environment.yml
         echo "  - wavespectra" >> environment.yml
         cat environment.yml
 
@@ -85,8 +83,7 @@ jobs:
       run: |
         conda activate test-env
         python3 -m pip install --upgrade pip
-        pip3 install gmsh pygmsh
-        pip3 install coveralls pytest
+        pip3 install gmsh pygmsh coveralls pytest
         pip3 install .
 
     # run all tests & coverage
@@ -103,7 +100,6 @@ jobs:
         COVERALLS_FLAG_NAME: ${{ matrix.os }}-${{ matrix.python-version }}
         COVERALLS_PARALLEL: true
 
-
   coveralls:
     name: Indicate completion to coveralls.io
     needs: wecopttool_test
@@ -117,20 +113,20 @@ jobs:
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-
-  documentation_test:
-    name: Build documentation
+              
+  GitHub_Pages:
+    name: Build and deploy website
     runs-on: ubuntu-latest
 
     steps:
     - uses: actions/checkout@v3
     - uses: actions/setup-python@v4
       with:
-        python-version: '3.11'  # CHANGE: Python version
+        python-version: '3.11' # CHANGE: Python version
 
     - name: Install dependencies
       run: sudo apt-get install libglu1 pandoc gifsicle
-      
+
     - name: Install WecOptTool for documentation
       shell: bash -l {0}
       run: |
@@ -141,4 +137,11 @@ jobs:
     - name: Build documentation
       shell: bash -l {0}
       run: |
+        git fetch --tags
         python3 docs/build_docs.py
+
+    - name: Deploy
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs/pages

.github/workflows/release.yml

@@ -1,7 +1,6 @@
 name: Release new version
 # 1. Publish to TestPyPi and PyPi, sequentially
-# 2. Publish to conda-forge
-# 3. Deploy documentation website
+# 2. Deploy documentation website
 
 on:
   release:
@@ -17,7 +16,7 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v4
       with:
-        python-version: '3.11'
+        python-version: '3.11' # CHANGE: Python version
 
     - name: Build a binary wheel and a source tarball
       run: |
@@ -47,7 +46,7 @@ jobs:
     - uses: actions/checkout@v3
     - uses: actions/setup-python@v4
       with:
-        python-version: '3.11'
+        python-version: '3.11' # CHANGE: Python version
 
     - name: Install dependencies
       run: sudo apt-get install libglu1 pandoc gifsicle
@@ -62,10 +61,11 @@ jobs:
     - name: Build documentation
       shell: bash -l {0}
       run: |
+        git fetch --tags
         python3 docs/build_docs.py
 
     - name: Deploy
       uses: peaceiris/actions-gh-pages@v3
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: ./docs/_build/html
+        publish_dir: ./docs/pages

docs/build_docs.py

@@ -1,8 +1,14 @@
 import os
+import subprocess
+import shutil
 import re
-import source.make_theory_animations
+import yaml
+
 from sphinx.application import Sphinx
 
+import source.make_theory_animations
+
+
 docs_dir = os.path.dirname(os.path.abspath(__file__))
 source_dir = os.path.join(docs_dir, 'source')
 conf_dir = source_dir
@@ -32,6 +38,7 @@ def html():
 
     app.build()
 
+
 def cleanup():
     index_file = os.path.join(html_dir, 'index.html')
     with open(index_file, 'r', encoding='utf-8') as f:
@@ -43,8 +50,37 @@ def cleanup():
             '', data, flags=re.DOTALL)
         f.write(data2)
 
-if __name__ == '__main__':
+
+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)
     source.make_theory_animations
     linkcheck()
     html()
     cleanup()
+    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'))
+    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)

docs/clean_docs.py

@@ -6,11 +6,13 @@
 source_dir = os.path.join(docs_dir, 'source')
 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(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__':
     clean()