Merge remote-tracking branch 'upstream/master' into documentation

.gitattributes

@@ -1 +1,2 @@
 /tests/**/* linguist-generated=true
+/toolchain/mechanisms/* linguist-generated=true

.github/CODEOWNERS

@@ -13,3 +13,5 @@ CMakeLists.txt     @sbryngelson @henryleberre
 .vscode/           @sbryngelson @henryleberre
 .github/workflows/ @sbryngelson @henryleberre
 
+# Spencer H. Bryngelson & Ben Wilfong
+.typos.toml        @sbryngelson @wilfonba

.github/file-filter.yml

@@ -7,7 +7,7 @@ fortran_src: &fortran_src
 
 python_src: &python_src
   - '**/*.py'
-  - 'toolchain/requirements.txt'
+  - 'toolchain/pyproject.toml'
 
 cmakelist: &cmakelist
   - 'CMakeLists.txt'

.github/workflows/cleanliness.yml

@@ -0,0 +1,105 @@
+name: Cleanliness
+
+on: [push, pull_request, workflow_dispatch]
+
+jobs:
+    cleanliness:
+        name: Code Cleanliness Test
+        runs-on: "ubuntu-latest"
+        env:
+            pr_everything: 0
+            master_everything: 0
+        steps:
+            - name: Clone - PR
+              uses: actions/checkout@v3
+              with:
+                path: pr
+            - name: Clone - Master
+              uses: actions/checkout@v3
+              with:
+                repository: MFlowCode/MFC
+                ref: master
+                path: master
+
+            - name: Setup Ubuntu
+              run: |
+                sudo apt update -y
+                sudo apt install -y tar wget make cmake gcc g++ python3 python3-dev "openmpi-*" libopenmpi-dev
+            
+            - name: Build
+              run: |
+                (cd pr && /bin/bash mfc.sh build -j $(nproc) --debug 2> ../pr.txt) 
+                (cd master && /bin/bash mfc.sh build -j $(nproc) --debug 2> ../master.txt)
+                sed -i '/\/pr\//d' pr.txt
+                sed -i '/\/master\//d' master.txt
+            
+            - name: Unused Variables Diff
+              run: |
+                grep -F 'Wunused-variable' master.txt > mUnused.txt
+                grep -F 'Wunused-variable' pr.txt > prUnused.txt
+                diff prUnused.txt mUnused.txt || true
+            
+            - name: Unused Dummy Arguments Diff
+              run: |
+                grep -F 'Wunused-dummy-argument' pr.txt > prDummy.txt
+                grep -F 'Wunused-dummy-argument' master.txt > mDummy.txt
+                diff prDummy.txt mDummy.txt || true
+
+            - name: Unused Value Diff
+              run: |
+                grep -F 'Wunused-value' pr.txt > prUnused_val.txt
+                grep -F 'Wunused-value' master.txt > mUnused_val.txt
+                diff prUnused_val.txt mUnused_val.txt || true
+
+            - name: Maybe Uninitialized Variables Diff
+              run: |
+                grep -F 'Wmaybe-uninitialized' pr.txt > prMaybe.txt
+                grep -F 'Wmaybe-uninitialized' master.txt > mMaybe.txt
+                diff prMaybe.txt mMaybe.txt || true
+
+
+            - name: Everything Diff
+              run: |
+                grep '\-W' pr.txt > pr_every.txt 
+                grep '\-W' master.txt > m_every.txt
+                diff pr_every.txt m_every.txt || true
+
+            - name: List of Warnings
+              run: |
+                cat pr_every.txt
+                
+
+            - name: Summary
+              run: |  
+                pr_variable=$(grep -c -F 'Wunused-variable' pr.txt)
+                pr_argument=$(grep -c -F 'Wunused-dummy-argument' pr.txt)
+                pr_value=$(grep -c -F 'Wunused-value' pr.txt)
+                pr_uninit=$(grep -c -F 'Wmaybe-uninitialized' pr.txt)
+                pr_everything=$(grep -c '\-W' pr.txt)
+
+                master_variable=$(grep -c -F 'Wunused-variable' master.txt)
+                master_argument=$(grep -c -F 'Wunused-dummy-argument' master.txt)
+                master_value=$(grep -c -F 'Wunused-value' master.txt)
+                master_uninit=$(grep -c -F 'Wmaybe-uninitialized' master.txt)
+                master_everything=$(grep -c '\-W' master.txt  )    
+
+                echo "pr_everything=$pr_everything" >> $GITHUB_ENV
+                echo "master_everything=$master_everything" >> $GITHUB_ENV
+
+                echo "Difference is how many warnings were added or removed from master to PR."
+                echo "Negative numbers are better since you are removing warnings." 
+                echo " "
+                echo "Unused Variable Count: $pr_variable, Difference: $((pr_variable - master_variable))"
+                echo "Unused Dummy Argument: $pr_argument, Difference: $((pr_argument - master_argument))"
+                echo "Unused Value: $pr_value, Difference: $((pr_value - master_value))"
+                echo "Maybe Uninitialized: $pr_uninit, Difference: $((pr_uninit - master_uninit))"
+                echo "Everything: $pr_everything, Difference: $((pr_everything - master_everything))"
+            
+
+            - name: Check Differences
+              if: env.pr_everything > env.master_everything 
+              run: |
+                echo "Difference between warning count in PR is greater than in master."
+                exit 1
+
+

.github/workflows/docs.yml

@@ -1,18 +1,12 @@
 name: Documentation
 
-on:
-  push:
-    branches:
-      - master
-
-  workflow_dispatch:
+on: [push, pull_request, workflow_dispatch]
 
 jobs:
   docs:
     name:    Build & Publish
     runs-on: ubuntu-latest
 
-    if: github.repository == 'MFlowCode/MFC'
     concurrency:
       group: docs-publish
       cancel-in-progress: true
@@ -53,6 +47,7 @@ jobs:
         echo "excluded-count = ${{ steps.sitemap.outputs.excluded-count }}"
 
     - name: Publish Documentation
+      if:   github.repository == 'MFlowCode/MFC' && github.ref == 'refs/heads/master' && github.event_name == 'push'
       run:  |
         set +e
         git ls-remote "${{ secrets.DOC_PUSH_URL }}" -q

.github/workflows/test.yml

@@ -49,8 +49,9 @@ jobs:
       - name: Setup MacOS
         if:   matrix.os == 'macos'
         run:  |
-          brew install coreutils python cmake fftw hdf5 gcc@14 open-mpi
+          brew install coreutils python cmake fftw hdf5 gcc@14 boost open-mpi
           echo "FC=gfortran-14" >> $GITHUB_ENV
+          echo "BOOST_INCLUDE=/opt/homebrew/include/" >> $GITHUB_ENV
 
       - name: Setup Ubuntu
         if:   matrix.os == 'ubuntu' && matrix.intel == false
@@ -138,4 +139,3 @@ jobs:
         with:
           name: logs
           path: test-${{ matrix.device }}.out
-

CMakeLists.txt

@@ -133,6 +133,8 @@ if (CMAKE_Fortran_COMPILER_ID STREQUAL "GNU")
             -fimplicit-none
             #-ffpe-trap=invalid,zero,denormal,overflow
             -fsignaling-nans
+            -finit-real=snan
+            -finit-integer=-99999999
 	    )
     endif()
 
@@ -340,6 +342,7 @@ macro(HANDLE_SOURCES target useCommon)
                                  -D MFC_${${target}_UPPER}
                                  -D MFC_COMPILER="${CMAKE_Fortran_COMPILER_ID}"
                                  -D MFC_CASE_OPTIMIZATION=False
+                                 -D chemistry=False
                                  --line-numbering
                                  --no-folding
                                  "${fpp}" "${f90}"

README.md

@@ -58,14 +58,20 @@ It's rather straightforward.
 We'll give a brief intro. here for MacOS.
 Using [brew](https://brew.sh), install MFC's dependencies:
 ```shell
-brew install coreutils python cmake fftw hdf5 gcc open-mpi
+brew install coreutils python cmake fftw hdf5 gcc boost open-mpi
 ```
 You're now ready to build and test MFC!
 Put it to a convenient directory via
 ```shell
 git clone https://github.com/MFlowCode/MFC
 cd MFC
 ```
+and be sure MFC knows where to find Boost by appending to your dotfiles and sourcing them again
+```shell
+echo -e "export BOOST_INCLUDE='$(brew --prefix --installed boost)/include'" | tee -a ~/.bash_profile ~/.zshrc
+. ~/.bash_profile 2>/dev/null || . ~/.zshrc 2>/dev/null
+! [ -z "${BOOST_INCLUDE+x}" ] && echo 'Environment is ready!' || echo 'Error: $BOOST_INCLUDE is unset. Please adjust the previous commands to fit with your environment.'
+```
 then you can build MFC and run the test suite!
 ```shell
 ./mfc.sh build -j $(nproc)
@@ -126,7 +132,7 @@ They are organized below. Just click the drop-downs!
 
 * Shock and interface capturing schemes
 	* First-order upwinding
- 	* WENO reconstructions of order 3 and 5
+ 	* WENO reconstructions of order 3, 5, and 7
   	* WENO variants: WENO-JS, WENO-M, WENO-Z, TENO
    	* Monotonicity-preserving reconstructions
 	* Reliable handling of high density ratios

benchmarks/5eq_rk3_weno3_hllc/case.py

@@ -14,11 +14,13 @@
     description="This MFC case was created for the purposes of benchmarking MFC.",
     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
 
-parser.add_argument("dict", type=str, metavar="DICT", help=argparse.SUPPRESS)
-parser.add_argument("gbpp", type=int, metavar="MEM", default=16, help="Adjusts the problem size per rank to fit into [MEM] GB of GPU memory per GPU.")
+parser.add_argument("--mfc", type=json.loads, default='{}', metavar="DICT",
+                    help="MFC's toolchain's internal state.")
+parser.add_argument("--gbpp", type=int, metavar="MEM", default=16,
+                    help="Adjusts the problem size per rank to fit into [MEM] GB of GPU memory per GPU.")
 
 ARGS = vars(parser.parse_args())
-DICT = json.loads(ARGS["dict"])
+DICT = ARGS["mfc"]
 
 size = 1 if DICT["gpu"] else 0
 

benchmarks/hypo_hll/case.py

@@ -12,11 +12,13 @@
     description="This MFC case was created for the purposes of benchmarking MFC.",
     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
 
-parser.add_argument("dict", type=str, metavar="DICT", help=argparse.SUPPRESS)
-parser.add_argument("gbpp", type=int, metavar="MEM", default=16, help="Adjusts the problem size per rank to fit into [MEM] GB of GPU memory per GPU.")
+parser.add_argument("--mfc", type=json.loads, default='{}', metavar="DICT",
+                    help="MFC's toolchain's internal state.")
+parser.add_argument("--gbpp", type=int, metavar="MEM", default=16,
+                    help="Adjusts the problem size per rank to fit into [MEM] GB of GPU memory per GPU.")
 
 ARGS = vars(parser.parse_args())
-DICT = json.loads(ARGS["dict"])
+DICT = ARGS["mfc"]
 
 size = 1 if DICT["gpu"] else 0
 

benchmarks/ibm/case.py

@@ -11,11 +11,13 @@
     description="This MFC case was created for the purposes of benchmarking MFC.",
     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
 
-parser.add_argument("dict", type=str, metavar="DICT", help=argparse.SUPPRESS)
-parser.add_argument("gbpp", type=int, metavar="MEM", default=16, help="Adjusts the problem size per rank to fit into [MEM] GB of GPU memory per GPU.")
+parser.add_argument("--mfc", type=json.loads, default='{}', metavar="DICT",
+                    help="MFC's toolchain's internal state.")
+parser.add_argument("--gbpp", type=int, metavar="MEM", default=16,
+                    help="Adjusts the problem size per rank to fit into [MEM] GB of GPU memory per GPU.")
 
 ARGS = vars(parser.parse_args())
-DICT = json.loads(ARGS["dict"])
+DICT = ARGS["mfc"]
 
 size = 1 if DICT["gpu"] else 0
 

benchmarks/viscous_weno5_sgb_acoustic/case.py

@@ -16,11 +16,13 @@
     description="This MFC case was created for the purposes of benchmarking MFC.",
     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
 
-parser.add_argument("dict", type=str, metavar="DICT", help=argparse.SUPPRESS)
-parser.add_argument("gbpp", type=int, metavar="MEM", default=16, help="Adjusts the problem size per rank to fit into [MEM] GB of GPU memory per GPU.")
+parser.add_argument("--mfc", type=json.loads, default='{}', metavar="DICT",
+                    help="MFC's toolchain's internal state.")
+parser.add_argument("--gbpp", type=int, metavar="MEM", default=16,
+                    help="Adjusts the problem size per rank to fit into [MEM] GB of GPU memory per GPU.")
 
 ARGS = vars(parser.parse_args())
-DICT = json.loads(ARGS["dict"])
+DICT = ARGS["mfc"]
 
 size = 1 if DICT["gpu"] else 0
 

docs/documentation/case.md

@@ -34,24 +34,26 @@ Input files can accept command line arguments, forwarded by `mfc.sh run`.
 Consider this example from the `scaling` case:
 
 ```python
-import argparse
+import json, argparse
 
 parser = argparse.ArgumentParser(
     prog="scaling",
     description="Weak- and strong-scaling benchmark case.",
     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
 
-parser.add_argument("dict", type=str, metavar="DICT")
-parser.add_argument("-s", "--scaling",  type=str, metavar="SCALING",  choices=["weak", "strong"], help="Whether weak- or strong-scaling is being exercised.")
+parser.add_argument("--mfc", type=json.loads, default='{}', metavar="DICT",
+                    help="MFC's toolchain's internal state.")
+parser.add_argument("-s", "--scaling", type=str, metavar="SCALING", choices=["weak", "strong"],
+                    help="Whether weak- or strong-scaling is being exercised.")
 
 # Your parsed arguments are here
 args = parser.parse_args()
 ```
 
-The first argument is always a JSON string representing `mfc.sh run`'s internal
-state.
+The `--mfc` argument is a JSON string representing `mfc.sh run`'s internal
+state, passed in when MFC runs your input file.
 It contains all the runtime information you might want from the build/run system.
-You can add as many additional arguments as you may need.
+You can add as many additional arguments and options as you may need.
 
 To run such a case, use the following format:
 
@@ -123,7 +125,7 @@ For example, $m=n=p=499$ discretizes the domain into $500^3$ cells.
 When the simulation is 2D/axi-symmetric or 1D, it requires that $p=0$ or $p=n=0$, respectively.
 
 - `stretch_[x,y,z]` activates grid stretching in the $[x,y,z]$ directions.
-The grid is gradually stretched such that the domain boundaries are pushed away from the origin along a specified axis.
+The grid is gradually stretched such that the domain boundaries are pushed away from the origin along a specified axis. WENO7 does not support grid stretching.
 
 - `a_[x,y,z]`, `[x,y,z]_a`, and `[x,y,z]_b` are parameters that define the grid stretching function. When grid stretching along the $x$ axis is considered, the stretching function is given as:
 
@@ -347,6 +349,7 @@ Details of implementation of viscosity in MFC can be found in [Coralic (2015)](r
 | `weno_eps`	         | Real    | WENO perturbation (avoid division by zero) |
 | `mapped_weno`	         | Logical | WENO-M (WENO with mapping of nonlinear weights) |
 | `wenoz`	             | Logical | WENO-Z |
+| `wenoz_q`              | Real    | WENO-Z power parameter q (only for WENO7) |
 | `teno`                 | Logical | TENO (Targeted ENO) |
 | `teno_CT`              | Real    | TENO threshold for smoothness detection |
 | `null_weights`         | Logical | Null WENO weights at boundaries |
@@ -406,18 +409,20 @@ Note that `time_stepper = 3` specifies the total variation diminishing (TVD), th
 
 - `adap_dt` activates the Strang operator splitting scheme which splits flux and source terms in time marching, and an adaptive time stepping strategy is implemented for the source term. It requires ``bubbles = 'T'``, ``polytropic = 'T'``, ``adv_n = 'T'`` and `time_stepper = 3`.
 
-- `weno_order` specifies the order of WENO scheme that is used for spatial reconstruction of variables by an integer of 1, 3, and 5, that correspond to the 1st, 3rd, and 5th order, respectively.
+- `weno_order` specifies the order of WENO scheme that is used for spatial reconstruction of variables by an integer of 1, 3, 5, and 7, that correspond to the 1st, 3rd, 5th, and 7th order, respectively. WENO7 does not support grid stretching.
 
 - `weno_eps` specifies the lower bound of the WENO nonlinear weights.
-Practically, `weno_eps` $<10^{-6}$ is used.
+It is recommended to set `weno_eps` to $10^{-6}$ for WENO-JS, and to $10^{-40}$ for other WENO variants.
 
 - `mapped_weno` activates the WENO-M scheme in place of the default WENO-JS scheme ([Henrick et al., 2005](references.md#Henrick05)). WENO-M a variant of the WENO scheme that remaps the nonlinear WENO-JS weights by assigning larger weights to non-smooth stencils, reducing dissipation compared to the default WENO-JS scheme, at the expense of higher computational cost. Only one of `mapped_weno`, `wenoz`, and `teno` can be activated.
 
 - `wenoz` activates the WENO-Z scheme in place of the default WENO-JS scheme ([Borges et al., 2008](references.md#Borges08)). WENO-Z is a variant of the WENO scheme that further reduces the dissipation compared to the WENO-M scheme. It has similar computational cost to the WENO-JS scheme.
 
-- `teno` activates the TENO scheme in place of the default WENO-JS scheme ([Fu et al., 2016](references.md#Fu16)). TENO is a variant of the ENO scheme that is the least dissipative, but could be less robust for extreme cases. It uses a threshold to identify smooth and non-smooth stencils, and applies optimal weights to the smooth stencils. Only available for `weno_order = 5`. Requires `teno_CT` to be set.
+- `wenoz_q` specifies the power parameter `q` used in the WENO-Z scheme. It controls how aggressively the smoothness coefficients scale the weights. A higher value of `wenoz_q` increases the sensitivity to smoothness, improving stability but worsening numerical dissipation. For WENO3 and WENO5, `q=1` is fixed, so `wenoz_q` must not be set. For WENO7, `wenoz_q` can be set to 2, 3, or 4.
 
-- `teno_CT` specifies the threshold for the TENO scheme. This dimensionless constant, also known as $C_T$, sets a threshold to identify smooth and non-smooth stencils. Larger values make the scheme more robust but also more dissipative. A recommended value for teno_CT is `1e-6`. When adjusting this parameter, it is recommended to try values like `1e-5` or `1e-7`.
+- `teno` activates the TENO scheme in place of the default WENO-JS scheme ([Fu et al., 2016](references.md#Fu16)). TENO is a variant of the ENO scheme that is the least dissipative, but could be less robust for extreme cases. It uses a threshold to identify smooth and non-smooth stencils, and applies optimal weights to the smooth stencils. Only available for `weno_order = 5` and `7`. Requires `teno_CT` to be set.
+
+- `teno_CT` specifies the threshold for the TENO scheme. This dimensionless constant, also known as $C_T$, sets a threshold to identify smooth and non-smooth stencils. Larger values make the scheme more robust but also more dissipative. A recommended value for teno_CT is `1e-6`. When adjusting this parameter, it is recommended to try values like `1e-5` or `1e-7` for TENO5. A smaller value can be used for TENO7.
 
 - `null_weights` activates nullification of the nonlinear WENO weights at the buffer regions outside the domain boundaries when the Riemann extrapolation boundary condition is specified (`bc_[x,y,z]%%beg[end]} = -4`).