Merge recent updates to shallow water branch

.github/workflows/fprettify-lint.yml

@@ -3,7 +3,6 @@ name: fprettify-lint
 on:
   push:
     branches:
-      - master
       - main
     paths-ignore:
       - 'AUTHORS.md'

.github/workflows/linux-amdflang-cmake.yaml

@@ -3,21 +3,22 @@ name: linux-amdflang-cmake
 on:
   push:
     branches:
-      - master
       - main
     paths-ignore:
+      - 'docs/'
       - 'AUTHORS.md'
       - 'LICENSE.md'
       - 'README.md'
   pull_request:
     paths-ignore:
+      - 'docs/'
       - 'AUTHORS.md'
       - 'LICENSE.md'
       - 'README.md'
 
 jobs:
   linux-tests:
-    timeout-minutes: 30
+    timeout-minutes: 60
     if: "!contains(github.event.head_commit.message, 'skip ci')"
     name: ${{ matrix.os }} - ${{ matrix.fcompiler }} - ${{ matrix.build_type }}
     runs-on: ${{ matrix.os }}
@@ -56,6 +57,8 @@ jobs:
 
       - name: Set up Spack
         uses: spack/setup-spack@v2
+        with:
+          ref: develop-2024-10-06
 
       - name: Install dependencies in spack environment
         run: |

.github/workflows/linux-gnu-cmake.yml

@@ -3,21 +3,22 @@ name: linux-gnu-cmake
 on:
   push:
     branches:
-      - master
       - main
     paths-ignore:
+      - 'docs/'
       - 'AUTHORS.md'
       - 'LICENSE.md'
       - 'README.md'
   pull_request:
     paths-ignore:
+      - 'docs/'
       - 'AUTHORS.md'
       - 'LICENSE.md'
       - 'README.md'
 
 jobs:
   linux-tests:
-    timeout-minutes: 30
+    timeout-minutes: 60
     if: "!contains(github.event.head_commit.message, 'skip ci')"
     name: ${{ matrix.os }} - ${{ matrix.fcompiler }} - ${{ matrix.build_type }}
     runs-on: ${{ matrix.os }}
@@ -80,6 +81,8 @@ jobs:
 
       - name: Set up Spack
         uses: spack/setup-spack@v2
+        with:
+          ref: develop-2024-10-06
 
       - name: Install dependencies in spack environment
         run: |

.github/workflows/linux-gnu-multithreaded-cmake.yml

@@ -3,21 +3,22 @@ name: linux-gnu-multithreaded-cmake
 on:
   push:
     branches:
-      - master
       - main
     paths-ignore:
+      - 'docs/'
       - 'AUTHORS.md'
       - 'LICENSE.md'
       - 'README.md'
   pull_request:
     paths-ignore:
+      - 'docs/'
       - 'AUTHORS.md'
       - 'LICENSE.md'
       - 'README.md'
 
 jobs:
   linux-tests:
-    timeout-minutes: 30
+    timeout-minutes: 60
     if: "!contains(github.event.head_commit.message, 'skip ci')"
     name: ${{ matrix.os }} - ${{ matrix.fcompiler }} - ${{ matrix.build_type }}
     runs-on: ${{ matrix.os }}
@@ -80,6 +81,8 @@ jobs:
 
       - name: Set up Spack
         uses: spack/setup-spack@v2
+        with:
+          ref: develop-2024-10-06
 
       - name: Install dependencies in spack environment
         run: |

.github/workflows/linux-nvfortran-cmake.yaml

@@ -3,21 +3,22 @@ name: linux-nvidia-hpc-cmake
 on:
   push:
     branches:
-      - master
       - main
     paths-ignore:
+      - 'docs/'
       - 'AUTHORS.md'
       - 'LICENSE.md'
       - 'README.md'
   pull_request:
     paths-ignore:
+      - 'docs/'
       - 'AUTHORS.md'
       - 'LICENSE.md'
       - 'README.md'
 
 jobs:
   linux-tests:
-    timeout-minutes: 45
+    timeout-minutes: 60
     if: "!contains(github.event.head_commit.message, 'skip ci')"
     name: ${{ matrix.os }} - ${{ matrix.toolchain.compiler }} - ${{ matrix.build_type }}
     runs-on: ${{ matrix.os }}
@@ -63,6 +64,8 @@ jobs:
 
       - name: Set up Spack
         uses: spack/setup-spack@v2
+        with:
+          ref: develop-2024-10-06
 
       - name: Install dependencies in spack environment
         run: |

.github/workflows/main-docs.yml

@@ -0,0 +1,34 @@
+name: Publish documentation
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v2
+
+      - name: Set up Python 3.9
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.9
+
+      - name: Install docs dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r docs/requirements.txt
+
+      - name: Generate API docs
+        run: |
+          ford self.md
+
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CONFIG_FILE: mkdocs.yml
+          REQUIREMENTS: docs/requirements.txt

CONTRIBUTING.md

@@ -1,21 +1,5 @@
 # Spectral Element Library in Fortran (SELF)
-Copyright 2017-2020 Fluid Numerics LLC
-
-## What do I need to know to help?
-If you are looking to help to with a code contribution, SELF uses the following programming languages and tools
-* Fortran (2008 Standard)
-* [HIP](link needed) for GPU acceleration
-* [MPI](link needed) for Multi-Process parallelization (multi-core, multi-gpu)
-* [CMake](https://cmake.org) (Build System)
-* [HDF5](https://www.hdfgroup.org/solutions/hdf5/)
-
-If you are interested in making a code contribution and would like to learn more about the technologies that we use, check out the list below.
-
-* [SELF Specifications](./SPECIFICATIONS.md)
-* [Understanding the SELF Software Layout](link needed)
-* [Commit Guidelines](link needed)
-
-## Branching Model
+Copyright 2017-2024 Fluid Numerics LLC
 
 ## Contribute Code
 1. Find an issue that you are interested in addressing or a feature that you would like to add.
@@ -24,7 +8,7 @@ If you are interested in making a code contribution and would like to learn more
 4. Create a new branch for your contribution. To help maintainers easily determine the type of code contribution, name your branch using bugfix/issue-NN or feature/issue-NN prefixes.
 5. Make the appropriate changes for the issue you are trying to address or the feature that you want to add.
 6. When committing your changes, follow the commit guidelines when writing your commit messages.
-7. You are encouraged to run the SELF test harness before opening a pull request. These tests will help you make sure you're changes meet formatting guidelines, build successfully, and produce test results within acceptable tolerance levels. If you don't have a GPU, that's ok. Your contribution will be fully tested when you open a pull request.
+7. You are encouraged to run the SELF tests using `ctest` on your local system before opening a pull request. If you don't have a GPU, that's ok. Your contribution will be fully tested when you open a pull request.
 8. Open a pull request with the upstream SELF repository. In the title, reference the issue number that you worked on. Include a detailed description of the changes you made and why. If you have recommendations for updates to documentation as a result of your changes, please indicate so. If you've added a new routine, you will need to work with the maintainers to develop tests when integrating your new feature in. 
 
 ### Code formatting

README.md

@@ -1,18 +1,23 @@
 # Spectral Element Libraries in Fortran (SELF)
-Copyright 2020-2023 Fluid Numerics LLC
+Copyright 2017-2024 Fluid Numerics LLC
 
 [![codecov](https://codecov.io/gh/FluidNumerics/SELF/branch/main/graph/badge.svg?token=AKKSL5CWK6)](https://codecov.io/gh/FluidNumerics/SELF)
 
 [![linux-gnu-cmake](https://github.com/FluidNumerics/SELF/actions/workflows/linux-gnu-cmake.yml/badge.svg)](https://github.com/FluidNumerics/SELF/actions/workflows/linux-gnu-cmake.yml)
 
 [![linux-gnu-multithreaded-cmake](https://github.com/FluidNumerics/SELF/actions/workflows/linux-gnu-multithreaded-cmake.yml/badge.svg)](https://github.com/FluidNumerics/SELF/actions/workflows/linux-gnu-multithreaded-cmake.yml)
 
-[![linux-amdflang-cmake](https://github.com/FluidNumerics/SELF/actions/workflows/linux-amdflang-cmake.yaml/badge.svg)](https://github.com/FluidNumerics/SELF/actions/workflows/linux-amdflang-cmake.yaml)
-
 ## Licensing
-SELF is licensed for use under a [non-commercial use visible-source license](./LICENSE). Fluid Numerics is a small family-owned business and wants to make SELF available to researchers for academic use. Under the license, you can use, modify, and redistribute SELF so long as attribution is given to Fluid Numerics. However, since we are interested in protecting our time-and-effort investment in SELF, sale and commercial-use of SELF is prohibited under the license.
+SELF is licensed for use under a [3 Clause BSD with attribution license](./LICENSE). [Fluid Numerics](https://www.fluidnumerics.com) is a small family-owned business. We want to make SELF available to folks who want to build conservation laws that run on a wide range of platforms. Under the license, you can use, modify, and redistribute SELF so long as attribution is given to Fluid Numerics. 
+
+## How to support this repository
+Continued support of SELF relies on users and customers. Here's a few ways you can support this project:
 
-If you are interested in commercial licensure and would like support from Fluid Numerics, reach out to support@fluidnumerics.com
+* Give this repository a star on Github
+* [Open an issue](https://github.com/FluidNumerics/SELF/issues/new/choose) if you have a question or want to report a problem. We want to help!
+* [Subscribe to Fluid Numerics on Youtube](https://www.youtube.com/@FluidNumerics?sub_confirmation=1)
+* [Sponsor this project on Open Collective](https://opencollective.com/opensource-fluidnumerics)
+* [Work with us](https://www.fluidnumerics.com/services)
 
 ## About
 SELF is an object-oriented Fortran library that support the implementation of Spectral Element Methods for solving partial differential equations.
@@ -29,25 +34,24 @@ The following combinations are tested on the main branch of self :
 
 Name | Version | Platform | Build System | Stack | Architecture
 --- | --- | --- | --- | --- | --- |
-GNU Fortran `gfortran` | 13.2.0 | Ubuntu 22.04.2 LTS | `cmake` | openmpi/5.0.1, feq-parse/2.2.2, hdf5/1.14.3 | x86_64 - gfx90a (MI210)
+GNU Fortran `gfortran` | 13.2.0 | Ubuntu 22.04.2 LTS | `cmake` | openmpi/5.0.1, feq-parse/2.2.2, hdf5/1.14.3, rocm/6.1.0 | x86_64 - gfx90a (MI210)
 GNU Fortran `gfortran` | 13.2.0 | Ubuntu 22.04.2 LTS | `cmake` | openmpi/5.0.1, feq-parse/2.2.2, hdf5/1.14.3 | x86_64
 GNU Fortran `gfortran` | 12.3.0 | Ubuntu 22.04.2 LTS | `cmake` | openmpi/5.0.1, feq-parse/2.2.2, hdf5/1.14.3 | x86_64
-GNU Fortran `gfortran` | 12.3.0 | Ubuntu 22.04.2 LTS | `cmake` | openmpi/5.0.3 (ucx+rocm), feq-parse/2.2.2, hdf5/1.14.3 | x86_64 - gfx90a (MI210)
+GNU Fortran `gfortran` | 12.3.0 | Ubuntu 22.04.2 LTS | `cmake` | openmpi/5.0.3 (ucx+rocm), feq-parse/2.2.2, hdf5/1.14.3, rocm/6.0.2 | x86_64 - gfx90a (MI210)
 GNU Fortran `gfortran` | 11.4.0 | Ubuntu 22.04.2 LTS | `cmake` | openmpi/5.0.1, feq-parse/2.2.2, hdf5/1.14.3 | x86_64
 GNU Fortran `gfortran` | 10.5.0 | Ubuntu 22.04.2 LTS | `cmake` | openmpi/5.0.1, feq-parse/2.2.2, hdf5/1.14.3 | x86_64
 GNU Fortran `gfortran` | 9.5.0 | Ubuntu 22.04.2 LTS | `cmake` | openmpi/5.0.1, feq-parse/2.2.2, hdf5/1.14.3 | x86_64
-AOMP `amdflang` | 6.1.2 | Ubuntu 22.04.2 LTS | `cmake` | openmpi/5.0.1, feq-parse/2.2.2, hdf5/1.14.3 | x86_64 - gfx90a (MI210)
-AOMP `amdflang` | 6.1.2 | Ubuntu 22.04.2 LTS | `cmake` | openmpi/5.0.1, feq-parse/2.2.2, hdf5/1.14.3 | x86_64
 
 
-"Supported" for us means that we test `self` regularly on the platforms listed. Of course, we want to have `self` working on as many platforms as possible; [open an issue](https://github.com/FluidNumerics/SELF/issues/new/choose) if you encounter any problems installing or running `self` on your own platform.
+
+"Supported" for us means that we test `self` regularly on the platforms listed; `self` may work just fine on a different platform. Of course, we want to have `self` working on as many platforms as possible; [open an issue](https://github.com/FluidNumerics/SELF/issues/new/choose) if you encounter any problems installing or running `self` on your own platform.
 
 ## Support
 
 ### Documentation
 
-* [**User & Developer Documentation**](https://fluidnumerics.github.io/SELF)
-* [**API Documentation**](https://fluidnumerics.github.io/SELF/ford/)
+* [**User & Developer Documentation**](https://self.fluidnumerics.com)
+* [**API Documentation**](https://self.fluidnumerics.com/ford/)
 
 
 If you'd like to contribute, see [CONTRIBUTING.md](./CONTRIBUTING.md) to get started.

docs/GettingStarted/building-with-self.md

@@ -0,0 +1 @@
+# Using SELF to Build your own applications