From aa5055da26d8d1764699e26779f63403b95be981 Mon Sep 17 00:00:00 2001
From: Malmahrouqi3 <mohdsaid497566@gmail.com>
Date: Tue, 29 Jul 2025 11:08:07 -0400
Subject: [PATCH 01/14] implemented all changes

---
 .github/.dockerignore        | 83 ++++++++++++++++++++++++++++++++++++
 .github/Dockerfile           | 55 ++++++++++++++++++++++++
 .github/workflows/docker.yml | 59 +++++++++++++++++++++++++
 3 files changed, 197 insertions(+)
 create mode 100644 .github/.dockerignore
 create mode 100644 .github/Dockerfile
 create mode 100644 .github/workflows/docker.yml

diff --git a/.github/.dockerignore b/.github/.dockerignore
new file mode 100644
index 0000000000..dad61a765a
--- /dev/null
+++ b/.github/.dockerignore
@@ -0,0 +1,83 @@
+node_modules/
+package.json
+yarn.lock
+
+.venv/
+.vscode/
+src/*/include/case.fpp
+src/*/autogen/
+
+*.swo
+*.swp
+
+*:Zone.Identifier
+
+.nfs*
+
+__pycache__
+
+*.egg-info
+
+.DS_Store
+
+# NVIDIA Nsight Compute
+*.nsys-rep
+*.sqlite
+
+docs/*/initial*
+docs/*/result*
+docs/documentation/*-example.png
+docs/documentation/examples.md
+
+examples/*batch/*/
+examples/**/D/*
+examples/**/p*
+examples/**/D_*
+examples/**/*.inf
+examples/**/*.inp
+examples/**/*.dat
+examples/**/*.o*
+examples/**/silo*
+examples/**/restart_data*
+examples/**/*.out
+examples/**/binary
+examples/**/fort.1
+examples/**/*.sh
+examples/**/*.err
+examples/**/viz/
+examples/*.jpg
+examples/*.png
+examples/*/workloads/
+examples/*/run-*/
+examples/*/logs/
+examples/**/*.f90
+!examples/3D_lag_bubbles_shbubcollapse/input/lag_bubbles.dat
+!examples/3D_lag_bubbles_bubblescreen/input/lag_bubbles.dat
+workloads/
+
+benchmarks/*batch/*/
+benchmarks/*/D/*
+benchmarks/*/p*
+benchmarks/*/D_*
+benchmarks/*/*.inf
+benchmarks/*/*.inp
+benchmarks/*/*.dat
+benchmarks/*/*.o*
+benchmarks/*/silo*
+benchmarks/*/restart_data*
+benchmarks/*/*.out
+benchmarks/*/binary
+benchmarks/*/fort.1
+benchmarks/*/*.sh
+benchmarks/*/*.err
+benchmarks/*/viz/
+benchmarks/*.jpg
+benchmarks/*.png
+
+*.mod
+
+# Video Files
+*.mp4
+*.mov
+*.mkv
+*.avi
\ No newline at end of file
diff --git a/.github/Dockerfile b/.github/Dockerfile
new file mode 100644
index 0000000000..eac1a3dc44
--- /dev/null
+++ b/.github/Dockerfile
@@ -0,0 +1,55 @@
+ARG BASE_IMAGE
+FROM ${BASE_IMAGE}
+
+ARG TARGET
+ARG CC_COMPILER
+ARG CXX_COMPILER
+ARG FC_COMPILER
+ARG COMPILER_PATH
+ARG COMPILER_LD_LIBRARY_PATH
+
+RUN apt-get update -y && \
+    if [ "$TARGET" != "gpu" ]; then \
+        apt-get install -y \
+            build-essential git make cmake gcc g++ gfortran \
+            python3 python3-venv python3-pip \
+            openmpi-bin libopenmpi-dev libfftw3-dev \
+            libatlas-base-dev mpich libmpich-dev; \
+    else \
+        apt-get install -y \
+            build-essential git make cmake \
+            python3 python3-venv python3-pip \
+            libfftw3-dev libatlas-base-dev \
+            openmpi-bin libopenmpi-dev; \
+    fi && \
+    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
+
+ENV OMPI_ALLOW_RUN_AS_ROOT=1
+ENV OMPI_ALLOW_RUN_AS_ROOT_CONFIRM=1
+ENV PATH="/opt/MFC:$PATH"
+
+COPY ../ /opt/MFC
+
+ENV CC=${CC_COMPILER}
+ENV CXX=${CXX_COMPILER}
+ENV FC=${FC_COMPILER}
+ENV PATH="${COMPILER_PATH}:$PATH"
+ENV LD_LIBRARY_PATH="${COMPILER_LD_LIBRARY_PATH}:${LD_LIBRARY_PATH:-}"
+
+RUN echo "TARGET=$TARGET CC=$CC_COMPILER FC=$FC_COMPILER" && \
+    cd /opt/MFC && \
+    if [ "$TARGET" = "gpu" ]; then \
+      ./mfc.sh build --gpu -j $(nproc); \
+    else \
+      ./mfc.sh build -j $(nproc); \
+    fi
+
+RUN cd /opt/MFC && \
+    if [ "$TARGET" = "gpu" ]; then \
+      ./mfc.sh test --dry-run --gpu -j $(nproc); \
+    else \
+      ./mfc.sh test --dry-run -j $(nproc); \
+    fi
+
+WORKDIR /opt/MFC
+ENTRYPOINT ["bash"]
\ No newline at end of file
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
new file mode 100644
index 0000000000..bd7ea8f171
--- /dev/null
+++ b/.github/workflows/docker.yml
@@ -0,0 +1,59 @@
+name: Containerization
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  Container:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        config:
+          - { name: 'cpu',         base_image: 'ubuntu:22.04'}
+          - { name: 'gpu',         base_image: 'nvcr.io/nvidia/nvhpc:23.11-devel-cuda12.3-ubuntu22.04'}
+
+    steps:
+      - name: Clone
+        uses: actions/checkout@v4
+        with:
+          path: mfc
+
+      - name: Login
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Setup
+        uses: docker/setup-buildx-action@v3
+
+      - name: Stage
+        run: |
+          sudo mkdir -p /mnt/share
+          sudo chmod 777 /mnt/share
+          cp -r mfc/* /mnt/share/
+          cp -r mfc/.git /mnt/share/.git
+          cp mfc/.github/Dockerfile /mnt/share/
+          cp mfc/.github/.dockerignore /mnt/share/
+          docker buildx create --name mfcbuilder --driver docker-container --use
+
+      - name: Build and Deploy
+        uses: docker/build-push-action@v5
+        with:
+          builder: mfcbuilder
+          context: /mnt/share
+          file: /mnt/share/Dockerfile
+          build-args: |
+            BASE_IMAGE=${{ matrix.config.base_image }}
+            TARGET=${{ matrix.config.name }}
+            CC_COMPILER=${{ contains(matrix.config.name, 'gpu') && 'nvc' || 'gcc' }}
+            CXX_COMPILER=${{ contains(matrix.config.name, 'gpu') && 'nvc++' || 'g++' }}
+            FC_COMPILER=${{ contains(matrix.config.name, 'gpu') && 'nvfortran' || 'gfortran' }}
+            COMPILER_PATH=${{ contains(matrix.config.name, 'gpu') && '/opt/nvidia/hpc_sdk/Linux_x86_64/compilers/bin' || '/usr/bin' }}
+            COMPILER_LD_LIBRARY_PATH=${{ contains(matrix.config.name, 'gpu') && '/opt/nvidia/hpc_sdk/Linux_x86_64/compilers/lib' || '/usr/lib' }}
+          tags: sbryngelson/mfc:${{ github.ref_name }}-${{ matrix.config.name }}
+          push: true
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
\ No newline at end of file

From f348b7810c6ce8a8b19b0ce930eeeb5e9f1716c0 Mon Sep 17 00:00:00 2001
From: Malmahrouqi3 <mohdsaid497566@gmail.com>
Date: Tue, 29 Jul 2025 11:34:50 -0400
Subject: [PATCH 02/14] Better handling of manual triggers

---
 .github/workflows/docker.yml | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index bd7ea8f171..b91a29875d 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -24,13 +24,19 @@ jobs:
         uses: docker/login-action@v3
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
 
       - name: Setup
         uses: docker/setup-buildx-action@v3
 
       - name: Stage
         run: |
+          if [ -n "${{ github.event.inputs.tag }}" ]; then
+            echo "TAG=${{ github.event.inputs.tag }}" >> $GITHUB_ENV
+          elif [[ "${{ github.ref }}" == refs/tags/* ]]; then
+            echo "TAG=${{ github.ref_name }}" >> $GITHUB_ENV
+          fi
+
           sudo mkdir -p /mnt/share
           sudo chmod 777 /mnt/share
           cp -r mfc/* /mnt/share/
@@ -53,7 +59,7 @@ jobs:
             FC_COMPILER=${{ contains(matrix.config.name, 'gpu') && 'nvfortran' || 'gfortran' }}
             COMPILER_PATH=${{ contains(matrix.config.name, 'gpu') && '/opt/nvidia/hpc_sdk/Linux_x86_64/compilers/bin' || '/usr/bin' }}
             COMPILER_LD_LIBRARY_PATH=${{ contains(matrix.config.name, 'gpu') && '/opt/nvidia/hpc_sdk/Linux_x86_64/compilers/lib' || '/usr/lib' }}
-          tags: sbryngelson/mfc:${{ github.ref_name }}-${{ matrix.config.name }}
+          tags: sbryngelson/mfc:${{ env.TAG }}-${{ matrix.config.name }}
           push: true
           cache-from: type=gha
           cache-to: type=gha,mode=max
\ No newline at end of file

From 0aca803cb6eb881760ab7fb4d55482f072150b2e Mon Sep 17 00:00:00 2001
From: Malmahrouqi3 <mohdsaid497566@gmail.com>
Date: Tue, 5 Aug 2025 23:17:05 -0400
Subject: [PATCH 03/14] devcontainer & workflow updates

---
 .devcontainer/devcontainer.json |  9 +++++
 .github/.dockerignore           |  1 -
 .github/Dockerfile              |  6 +--
 .github/workflows/docker.yml    | 72 +++++++++++++++++++++++++--------
 4 files changed, 68 insertions(+), 20 deletions(-)
 create mode 100644 .devcontainer/devcontainer.json

diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 0000000000..8b0e0fdafb
--- /dev/null
+++ b/.devcontainer/devcontainer.json
@@ -0,0 +1,9 @@
+{
+  "name": "MFC Container",
+  "image": "sbryngelson/mfc:latest-cpu",
+  "workspaceFolder": "/opt/MFC",
+  "settings": {
+    "terminal.integrated.shell.linux": "/bin/bash",
+    "editor.formatOnSave": true
+  },
+}
\ No newline at end of file
diff --git a/.github/.dockerignore b/.github/.dockerignore
index dad61a765a..452cfea06a 100644
--- a/.github/.dockerignore
+++ b/.github/.dockerignore
@@ -4,7 +4,6 @@ yarn.lock
 
 .venv/
 .vscode/
-src/*/include/case.fpp
 src/*/autogen/
 
 *.swo
diff --git a/.github/Dockerfile b/.github/Dockerfile
index eac1a3dc44..b9abcb7c7a 100644
--- a/.github/Dockerfile
+++ b/.github/Dockerfile
@@ -14,12 +14,12 @@ RUN apt-get update -y && \
             build-essential git make cmake gcc g++ gfortran \
             python3 python3-venv python3-pip \
             openmpi-bin libopenmpi-dev libfftw3-dev \
-            libatlas-base-dev mpich libmpich-dev; \
+            mpich libmpich-dev; \
     else \
         apt-get install -y \
             build-essential git make cmake \
             python3 python3-venv python3-pip \
-            libfftw3-dev libatlas-base-dev \
+            libfftw3-dev \
             openmpi-bin libopenmpi-dev; \
     fi && \
     rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
@@ -52,4 +52,4 @@ RUN cd /opt/MFC && \
     fi
 
 WORKDIR /opt/MFC
-ENTRYPOINT ["bash"]
\ No newline at end of file
+ENTRYPOINT ["tail", "-f", "/dev/null"]
\ No newline at end of file
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index b91a29875d..066b4ddf1c 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -4,32 +4,39 @@ on:
   release:
     types: [published]
   workflow_dispatch:
+    inputs:
+      tag:
+        description: 'tag to containerize'
+        required: true
+
+concurrency:
+  group: Containerization-${{ github.event.inputs.tag || github.ref_name }}
+  cancel-in-progress: false
 
 jobs:
   Container:
-    runs-on: ubuntu-latest
     strategy:
       matrix:
         config:
-          - { name: 'cpu',         base_image: 'ubuntu:22.04'}
-          - { name: 'gpu',         base_image: 'nvcr.io/nvidia/nvhpc:23.11-devel-cuda12.3-ubuntu22.04'}
-
+            - { name: 'cpu', runner: 'ubuntu-22.04',     base_image: 'ubuntu:22.04' }
+            - { name: 'cpu', runner: 'ubuntu-22.04-arm', base_image: 'ubuntu:22.04' }
+            - { name: 'gpu', runner: 'ubuntu-22.04',     base_image: 'nvcr.io/nvidia/nvhpc:23.11-devel-cuda12.3-ubuntu22.04' }
+            - { name: 'gpu', runner: 'ubuntu-22.04-arm', base_image: 'nvcr.io/nvidia/nvhpc:23.11-devel-cuda12.3-ubuntu22.04' }
+    runs-on: ${{ matrix.config.runner }}
     steps:
-      - name: Clone
-        uses: actions/checkout@v4
-        with:
-          path: mfc
-
       - name: Login
         uses: docker/login-action@v3
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_PASSWORD }}
 
-      - name: Setup
+      - name: Setup Buildx
         uses: docker/setup-buildx-action@v3
 
-      - name: Stage
+      - name: Setup QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Clone
         run: |
           if [ -n "${{ github.event.inputs.tag }}" ]; then
             echo "TAG=${{ github.event.inputs.tag }}" >> $GITHUB_ENV
@@ -37,18 +44,21 @@ jobs:
             echo "TAG=${{ github.ref_name }}" >> $GITHUB_ENV
           fi
 
+          git clone --branch ${{ env.TAG }} --depth 1 https://github.com/MFlowCode/MFC.git mfc
+
+      - name: Stage
+        run: |
           sudo mkdir -p /mnt/share
           sudo chmod 777 /mnt/share
           cp -r mfc/* /mnt/share/
           cp -r mfc/.git /mnt/share/.git
           cp mfc/.github/Dockerfile /mnt/share/
           cp mfc/.github/.dockerignore /mnt/share/
-          docker buildx create --name mfcbuilder --driver docker-container --use
 
       - name: Build and Deploy
         uses: docker/build-push-action@v5
         with:
-          builder: mfcbuilder
+          builder: default
           context: /mnt/share
           file: /mnt/share/Dockerfile
           build-args: |
@@ -59,7 +69,37 @@ jobs:
             FC_COMPILER=${{ contains(matrix.config.name, 'gpu') && 'nvfortran' || 'gfortran' }}
             COMPILER_PATH=${{ contains(matrix.config.name, 'gpu') && '/opt/nvidia/hpc_sdk/Linux_x86_64/compilers/bin' || '/usr/bin' }}
             COMPILER_LD_LIBRARY_PATH=${{ contains(matrix.config.name, 'gpu') && '/opt/nvidia/hpc_sdk/Linux_x86_64/compilers/lib' || '/usr/lib' }}
-          tags: sbryngelson/mfc:${{ env.TAG }}-${{ matrix.config.name }}
+          tags: ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-${{ matrix.config.name }}-${{ matrix.config.runner}}
           push: true
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
\ No newline at end of file
+
+  manifests:
+    runs-on: ubuntu-latest
+    needs: Container
+    steps:
+      - name: Login
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
+
+      - name: Create and Push Manifest Lists
+        run: |
+          docker manifest create ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-cpu \
+            ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-cpu-ubuntu-22.04 \
+            ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-cpu-ubuntu-22.04-arm
+          docker manifest push ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-cpu
+
+          docker manifest create ${{ secrets.DOCKERHUB_USERNAME }}/mfc:latest-cpu \
+            ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-cpu-ubuntu-22.04 \
+            ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-cpu-ubuntu-22.04-arm
+          docker manifest push ${{ secrets.DOCKERHUB_USERNAME }}/mfc:latest-cpu
+
+          docker manifest create ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-gpu \
+            ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-gpu-ubuntu-22.04 \
+            ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-gpu-ubuntu-22.04-arm
+          docker manifest push ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-gpu
+
+          docker manifest create ${{ secrets.DOCKERHUB_USERNAME }}/mfc:latest-gpu \
+            ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-gpu-ubuntu-22.04 \
+            ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-gpu-ubuntu-22.04-arm
+          docker manifest push ${{ secrets.DOCKERHUB_USERNAME }}/mfc:latest-gpu
\ No newline at end of file

From 2ec920985a08eda897e3e26942c0d43723bad935 Mon Sep 17 00:00:00 2001
From: Malmahrouqi3 <mohdsaid497566@gmail.com>
Date: Tue, 5 Aug 2025 23:54:23 -0400
Subject: [PATCH 04/14] trying to fix the issue with TAG

---
 .github/workflows/docker.yml | 47 +++++++++++++++---------------------
 1 file changed, 20 insertions(+), 27 deletions(-)

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 066b4ddf1c..a36db5bb24 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -23,6 +23,8 @@ jobs:
             - { name: 'gpu', runner: 'ubuntu-22.04',     base_image: 'nvcr.io/nvidia/nvhpc:23.11-devel-cuda12.3-ubuntu22.04' }
             - { name: 'gpu', runner: 'ubuntu-22.04-arm', base_image: 'nvcr.io/nvidia/nvhpc:23.11-devel-cuda12.3-ubuntu22.04' }
     runs-on: ${{ matrix.config.runner }}
+    outputs:
+      tag: ${{ steps.clone.outputs.tag }}
     steps:
       - name: Login
         uses: docker/login-action@v3
@@ -37,14 +39,12 @@ jobs:
         uses: docker/setup-qemu-action@v3
 
       - name: Clone
+        id: clone
         run: |
-          if [ -n "${{ github.event.inputs.tag }}" ]; then
-            echo "TAG=${{ github.event.inputs.tag }}" >> $GITHUB_ENV
-          elif [[ "${{ github.ref }}" == refs/tags/* ]]; then
-            echo "TAG=${{ github.ref_name }}" >> $GITHUB_ENV
-          fi
-
-          git clone --branch ${{ env.TAG }} --depth 1 https://github.com/MFlowCode/MFC.git mfc
+          TAG="${{ github.event.inputs.tag || github.ref_name }}"
+          echo "tag=$TAG" >> $GITHUB_OUTPUT
+          echo "TAG=$TAG" >> $GITHUB_ENV
+          git clone --branch "$TAG" --depth 1 https://github.com/MFlowCode/MFC.git mfc
 
       - name: Stage
         run: |
@@ -56,7 +56,7 @@ jobs:
           cp mfc/.github/.dockerignore /mnt/share/
 
       - name: Build and Deploy
-        uses: docker/build-push-action@v5
+        uses: docker/build-push-action@v6
         with:
           builder: default
           context: /mnt/share
@@ -83,23 +83,16 @@ jobs:
           password: ${{ secrets.DOCKERHUB_PASSWORD }}
 
       - name: Create and Push Manifest Lists
+        env:
+          TAG: ${{ needs.Container.outputs.tag }}
+          REGISTRY: ${{ secrets.DOCKERHUB_USERNAME }}/mfc
         run: |
-          docker manifest create ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-cpu \
-            ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-cpu-ubuntu-22.04 \
-            ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-cpu-ubuntu-22.04-arm
-          docker manifest push ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-cpu
-
-          docker manifest create ${{ secrets.DOCKERHUB_USERNAME }}/mfc:latest-cpu \
-            ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-cpu-ubuntu-22.04 \
-            ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-cpu-ubuntu-22.04-arm
-          docker manifest push ${{ secrets.DOCKERHUB_USERNAME }}/mfc:latest-cpu
-
-          docker manifest create ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-gpu \
-            ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-gpu-ubuntu-22.04 \
-            ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-gpu-ubuntu-22.04-arm
-          docker manifest push ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-gpu
-
-          docker manifest create ${{ secrets.DOCKERHUB_USERNAME }}/mfc:latest-gpu \
-            ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-gpu-ubuntu-22.04 \
-            ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-gpu-ubuntu-22.04-arm
-          docker manifest push ${{ secrets.DOCKERHUB_USERNAME }}/mfc:latest-gpu
\ No newline at end of file
+          docker manifest create $REGISTRY:$TAG-cpu $REGISTRY:$TAG-cpu-ubuntu-22.04 $REGISTRY:$TAG-cpu-ubuntu-22.04-arm
+          docker manifest create $REGISTRY:$TAG-gpu $REGISTRY:$TAG-gpu-ubuntu-22.04 $REGISTRY:$TAG-gpu-ubuntu-22.04-arm
+          docker manifest create $REGISTRY:latest-cpu $REGISTRY:$TAG-cpu-ubuntu-22.04 $REGISTRY:$TAG-cpu-ubuntu-22.04-arm
+          docker manifest create $REGISTRY:latest-gpu $REGISTRY:$TAG-gpu-ubuntu-22.04 $REGISTRY:$TAG-gpu-ubuntu-22.04-arm
+          
+          docker manifest push $REGISTRY:$TAG-cpu
+          docker manifest push $REGISTRY:$TAG-gpu
+          docker manifest push $REGISTRY:latest-cpu
+          docker manifest push $REGISTRY:latest-gpu
\ No newline at end of file

From 3297583fc89e3acb743307d1252e9eb79db79763 Mon Sep 17 00:00:00 2001
From: Malmahrouqi3 <mohdsaid497566@gmail.com>
Date: Wed, 6 Aug 2025 22:21:19 -0400
Subject: [PATCH 05/14] updated workflow

---
 .github/workflows/docker.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index a36db5bb24..1a6d44a8cb 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -10,7 +10,7 @@ on:
         required: true
 
 concurrency:
-  group: Containerization-${{ github.event.inputs.tag || github.ref_name }}
+  group: Containerization
   cancel-in-progress: false
 
 jobs:

From 987a04b7c1fcb8ededdefddba801df5e0f5473f3 Mon Sep 17 00:00:00 2001
From: Malmahrouqi3 <mohdsaid497566@gmail.com>
Date: Wed, 1 Oct 2025 00:45:19 -0400
Subject: [PATCH 06/14] docs updated

---
 README.md                             |   5 +-
 docs/documentation/docker.md          | 173 ++++++++++++++++++++++++++
 docs/documentation/getting-started.md |  10 ++
 3 files changed, 187 insertions(+), 1 deletion(-)
 create mode 100644 docs/documentation/docker.md

diff --git a/README.md b/README.md
index 196315ee20..777af226a2 100644
--- a/README.md
+++ b/README.md
@@ -84,8 +84,11 @@ And here is a high amplitude acoustic wave reflecting and emerging through a cir
 
 
 ## Getting started
+for a quick start, open a GitHub Codespace to load a pre-configured docker container to get familiar with MFC. Click <kbd> <> Code</kbd> (green button at top right) → <kbd>Codespaces</kbd> (right tab) → <kbd>+</kbd> (create a codespace).
 
-You can navigate [to this webpage](https://mflowcode.github.io/documentation/md_getting-started.html) to get started using MFC!
+****Notes:**** Codespaces is a free service with a monthly quota of compute time and storage usage. It is commended for testing commands, troubleshooting, and running simple case files without the need to install dependencies and build MFC on your device. Remember to save any important files locally before closing your codespace. To learn more, read through [docker](https://mflowcode.github.io/documentation/docker.html).
+
+Otherwise, you can navigate [to this webpage](https://mflowcode.github.io/documentation/md_getting-started.html) to get started using MFC!
 It's rather straightforward.
 We'll give a brief intro. here for MacOS.
 Using [brew](https://brew.sh), install MFC's dependencies:
diff --git a/docs/documentation/docker.md b/docs/documentation/docker.md
new file mode 100644
index 0000000000..bf358aa338
--- /dev/null
+++ b/docs/documentation/docker.md
@@ -0,0 +1,173 @@
+# Docker
+
+## Navigating Docker Desktop/CLI
+
+- Install Docker on [Mac](https://docs.docker.com/desktop/setup/install/mac-install/), [Windows](https://docs.docker.com/desktop/setup/install/windows-install/), or [Linux](https://docs.docker.com/desktop/setup/install/linux/).
+
+Via Docker Desktop GUI,
+- Search for [sbryngelson/mfc](https://hub.docker.com/r/sbryngelson/mfc) repository where all MFC images are stored then pull a release tag (e.g. `lastest-cpu`). 
+
+    Read through **Tag Details** below to distinguish between them. Docker Desktop's left sidebar has two key tabs: **Images** stores your program copies, while **Containers** shows instances of those images. You can launch multiple containers from a single image.
+
+- Start a container by clicking the Run button in the Images tab.
+
+    Use the *Exec* section to interact with MFC directly via terminal, the *Files* section to transfer files between your device and container, and the *Stats* section displays resource usage of it.
+
+Or via Docker CLI,
+
+- Pull from [sbryngelson/mfc](https://hub.docker.com/r/sbryngelson/mfc) repository and run the latest MFC container.
+
+```bash
+docker run -it --rm --entrypoint bash sbryngelson/mfc:latest-cpu
+```
+
+## Running Containers
+
+Start a CPU container
+```bash
+docker run -it --rm --entrypoint bash sbryngelson/mfc:latest-cpu
+```
+Start a GPU container
+```bash
+docker run -it --rm --entrypoint bash --gpus all sbryngelson/mfc:latest-gpu
+```
+**Note:** `--gpus all` exposes the container to available GPUs, and only Nvidia GPUs are currently supported. Make sure your device CUDA version is at least 12.3 to avoid backward compatibility issues.
+
+*⚠️ Append the `--debug` option to the  `./mfc.sh` command inside the container with **Apple Silicon** (ARM-based Architecture) to bypass any potential errors or run `./mfc.sh clean && ./mfc.sh build` if needed.*
+<br>
+<br>
+
+**Mounting Directory:** 
+
+Mount a directory to `mnt` inside the container to easily transfer files between the host and the container, e.g. `cp -r <source> /mnt/`.
+```bash
+docker run -it --rm --entrypoint bash -v "$PWD":/mnt sbryngelson/mfc:latest-cpu
+```
+<br>
+
+**Shared Memory:** 
+
+Increase the shared memory size to prevent MPI memory binding errors which may fail some tests and cases. Otherwie, you can disable MPI inside the container `--no-mpi`. 
+```bash
+docker run -it --rm --entrypoint bash --shm-size=<e.g. 4gb> sbryngelson/mfc:latest-cpu
+```
+
+
+
+
+### **For Portability,**
+
+On the source machine,
+- Pull and save the image
+```bash
+docker pull sbryngelson/mfc:latest-cpu
+docker save -o mfc:latest-cpu.tar sbryngelson/mfc:latest-cpu
+```
+On the target machine,
+- Load and run the image
+```bash
+docker load -i mfc:latest-cpu.tar
+docker run -it --rm mfc:latest-cpu
+```
+
+<br>
+
+## HPC Cluster Usage (Apptainer/Singularity)
+
+### **Interactive Shell**
+```bash
+apptainer exec --fakeroot --writable-tmpfs --bind "$PWD":/mnt  docker://sbryngelson/mfc:latest-gpu bash -c "cd /opt/MFC && bash"
+```
+or 
+```bash
+apptainer shell --fakeroot --writable-tmpfs --bind "$PWD":/mnt  docker://sbryngelson/mfc:latest-gpu
+Apptainer>cd /opt/MFC
+```
+
+### **For Portability,**
+On the source machine,
+- Pull and translate the image into `.sif` format
+```bash
+apptainer build mfc:latest-gpu.sif docker://sbryngelson/mfc:latest-gpu
+```
+On the target machine,
+- Load and start an interactive shell
+```bash
+apptainer shell --fakeroot --writable-tmpfs --bind "$PWD":/mnt mfc:latest-gpu.sif
+```
+
+
+
+### Slurm Job
+```bash
+#!/bin/bash
+#SBATCH --job-name=mfc-sim
+#SBATCH --nodes=2
+#SBATCH --ntasks-per-node=12
+#SBATCH --time=06:00:00
+#SBATCH --partition=
+#SBATCH --output=mfc-sim-%j.out
+#SBATCH --error=mfc-sim-%j.err
+
+# Load required modules
+module load apptainer
+
+cd $SLURM_SUBMIT_DIR
+
+# Define container image
+CONTAINER="mfc:latest-gpu.sif"
+
+apptainer exec --fakeroot --writable-tmpfs \
+--bind "$PWD":/mnt \
+  $CONTAINER \
+  bash -c "cd /opt/MFC && ./mfc.sh run sim/case.py -c <computer>"
+```
+Where 
+
+`/sim` directory contains all simulation files including case setup (`case.py`).
+ 
+`--fakeroot --writable-tmpfs` are critical to:
+- Enable root-like permissions inside the container without actual root access
+- Allow temporary write access to the container filesystem
+
+
+
+## Tag Details
+### Base Images
+- CPU images (v4.3.0-latest releases) are built on **Ubuntu 22.04**.
+- GPU images (v4.3.0-latest releases) are built on **NVHPC SDK 23.11 (CUDA 12.3) & Ubuntu 22.04**.
+
+### Tag Structure
+- **`vx.x.x`** - Official MFC release versions (recommended: use `latest` release)
+- **`cpu/gpu`** - Build configurations for CPU or GPU acceleration.
+- **`ubuntu-xx.xx`** - Base Ubuntu version (standard = `amd64`, `-arm` = `arm64`)
+
+### Available Tags
+```
+mfc:latest-xxx                   # Latest version (amd64 & arm64)
+mfc:vx.x.x-cpu                   # CPU version    (amd64 & arm64)
+mfc:vx.x.x-gpu                   # GPU version    (amd64 & arm64)
+mfc:vx.x.x-xxx-ubuntu-xx.xx      # amd64 natively-supported version
+mfc:vx.x.x-xxx-ubuntu-xx.xx-arm  # arm64 natively-supported version
+```
+### **Architecture Support**
+You can specify the desired architecture with `--platform <os>/<arch>` - either `linux/amd64` or `linux/arm64`. If not sure, Docker automatically selects the available image compatible with your system architecture. If native support isn't available, QEMU emulation is enabled for the following architectures albeit with degraded performance.
+```
+linux/amd64
+linux/amd64/v2
+linux/amd64/v3
+linux/arm64
+linux/riscv64
+linux/ppc64le
+linux/s390x
+linux/386
+linux/mips64le
+linux/mips64
+linux/loong64
+linux/arm/v7
+linux/arm/v6
+```
+
+
+<br>
+<br>
diff --git a/docs/documentation/getting-started.md b/docs/documentation/getting-started.md
index 885c528cb9..c88b5978c4 100644
--- a/docs/documentation/getting-started.md
+++ b/docs/documentation/getting-started.md
@@ -145,6 +145,16 @@ Examples:
 - Build MFC using a single thread without MPI, GPU, and Debug support: `./mfc.sh build --no-mpi`.
 - Build MFC's `simulation` code in Debug mode with MPI and GPU support: `./mfc.sh build --debug --gpu -t simulation`.
 
+## Using Containers
+As an alternative to building MFC from scratch, use containers to quickly access pre-built MFC with all its dependencies.
+
+Run the latest MFC container.
+```bash
+docker run -it --rm --entrypoint bash sbryngelson/mfc:latest-cpu
+```
+Please refer to the [Docker](https://mflowcode.github.io/documentation/docker.html) document for more information.
+
+
 ## Running the Test Suite
 
 Run MFC's test suite with 8 threads:

From 121ad13e84e1184100fbbe8f7b1351d5b1614396 Mon Sep 17 00:00:00 2001
From: Malmahrouqi3 <mohdsaid497566@gmail.com>
Date: Wed, 1 Oct 2025 01:15:16 -0400
Subject: [PATCH 07/14] typos and note on Selecting OS/ARCH

---
 README.md                    |  4 ++--
 docs/documentation/docker.md | 13 +++++++++++--
 2 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 777af226a2..4d547f7d75 100644
--- a/README.md
+++ b/README.md
@@ -84,9 +84,9 @@ And here is a high amplitude acoustic wave reflecting and emerging through a cir
 
 
 ## Getting started
-for a quick start, open a GitHub Codespace to load a pre-configured docker container to get familiar with MFC. Click <kbd> <> Code</kbd> (green button at top right) → <kbd>Codespaces</kbd> (right tab) → <kbd>+</kbd> (create a codespace).
+For a quick start, open a GitHub Codespace to load a pre-configured docker container to get familiar with MFC commands. Click <kbd> <> Code</kbd> (green button at top right) → <kbd>Codespaces</kbd> (right tab) → <kbd>+</kbd> (create a codespace).
 
-****Notes:**** Codespaces is a free service with a monthly quota of compute time and storage usage. It is commended for testing commands, troubleshooting, and running simple case files without the need to install dependencies and build MFC on your device. Remember to save any important files locally before closing your codespace. To learn more, read through [docker](https://mflowcode.github.io/documentation/docker.html).
+****Notes:**** Codespaces is a free service with a monthly quota of compute time and storage usage. It is commended for testing commands, troubleshooting, and running simple case files without the need to install dependencies and build MFC on your device. Remember to save any important files locally before closing your codespace. To learn more, read through [how docker & containers work](https://mflowcode.github.io/documentation/docker.html).
 
 Otherwise, you can navigate [to this webpage](https://mflowcode.github.io/documentation/md_getting-started.html) to get started using MFC!
 It's rather straightforward.
diff --git a/docs/documentation/docker.md b/docs/documentation/docker.md
index bf358aa338..531e3f4b18 100644
--- a/docs/documentation/docker.md
+++ b/docs/documentation/docker.md
@@ -5,7 +5,7 @@
 - Install Docker on [Mac](https://docs.docker.com/desktop/setup/install/mac-install/), [Windows](https://docs.docker.com/desktop/setup/install/windows-install/), or [Linux](https://docs.docker.com/desktop/setup/install/linux/).
 
 Via Docker Desktop GUI,
-- Search for [sbryngelson/mfc](https://hub.docker.com/r/sbryngelson/mfc) repository where all MFC images are stored then pull a release tag (e.g. `lastest-cpu`). 
+- Search for [sbryngelson/mfc](https://hub.docker.com/r/sbryngelson/mfc) repository where all MFC images are stored then pull a release tag (e.g. `latest-cpu`). 
 
     Read through **Tag Details** below to distinguish between them. Docker Desktop's left sidebar has two key tabs: **Images** stores your program copies, while **Containers** shows instances of those images. You can launch multiple containers from a single image.
 
@@ -20,6 +20,15 @@ Or via Docker CLI,
 ```bash
 docker run -it --rm --entrypoint bash sbryngelson/mfc:latest-cpu
 ```
+<br>
+
+**Selecting OS/ARCH:** 
+
+Docker by default selects the compatible architecture when pulling and running a container. However, you can manually specify your platform (i.e. `linux/amd64` for most devices or `linux/arm64`for Apple Silicon).
+```bash
+docker run -it --rm --entrypoint bash --platform linux/amd64 sbryngelson/mfc:latest-cpu
+```
+<br>
 
 ## Running Containers
 
@@ -47,7 +56,7 @@ docker run -it --rm --entrypoint bash -v "$PWD":/mnt sbryngelson/mfc:latest-cpu
 
 **Shared Memory:** 
 
-Increase the shared memory size to prevent MPI memory binding errors which may fail some tests and cases. Otherwie, you can disable MPI inside the container `--no-mpi`. 
+Increase the shared memory size to prevent MPI memory binding errors which may fail some tests and cases. Otherwise, you can disable MPI inside the container `--no-mpi`. 
 ```bash
 docker run -it --rm --entrypoint bash --shm-size=<e.g. 4gb> sbryngelson/mfc:latest-cpu
 ```

From b9dc1b33628c6de1977caf8b7b795d0c9297c0e6 Mon Sep 17 00:00:00 2001
From: Malmahrouqi3 <mohdsaid497566@gmail.com>
Date: Sat, 11 Oct 2025 16:42:45 -0400
Subject: [PATCH 08/14] few fixes: docker builder + bc package

---
 .github/Dockerfile           |  4 +--
 .github/workflows/docker.yml | 64 +++++++++++++++++++++++++++---------
 2 files changed, 51 insertions(+), 17 deletions(-)

diff --git a/.github/Dockerfile b/.github/Dockerfile
index b9abcb7c7a..1c50b4c09e 100644
--- a/.github/Dockerfile
+++ b/.github/Dockerfile
@@ -11,13 +11,13 @@ ARG COMPILER_LD_LIBRARY_PATH
 RUN apt-get update -y && \
     if [ "$TARGET" != "gpu" ]; then \
         apt-get install -y \
-            build-essential git make cmake gcc g++ gfortran \
+            build-essential git make cmake gcc g++ gfortran bc\
             python3 python3-venv python3-pip \
             openmpi-bin libopenmpi-dev libfftw3-dev \
             mpich libmpich-dev; \
     else \
         apt-get install -y \
-            build-essential git make cmake \
+            build-essential git make cmake bc\
             python3 python3-venv python3-pip \
             libfftw3-dev \
             openmpi-bin libopenmpi-dev; \
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 1a6d44a8cb..b12c6cdc5f 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -18,14 +18,24 @@ jobs:
     strategy:
       matrix:
         config:
-            - { name: 'cpu', runner: 'ubuntu-22.04',     base_image: 'ubuntu:22.04' }
-            - { name: 'cpu', runner: 'ubuntu-22.04-arm', base_image: 'ubuntu:22.04' }
-            - { name: 'gpu', runner: 'ubuntu-22.04',     base_image: 'nvcr.io/nvidia/nvhpc:23.11-devel-cuda12.3-ubuntu22.04' }
-            - { name: 'gpu', runner: 'ubuntu-22.04-arm', base_image: 'nvcr.io/nvidia/nvhpc:23.11-devel-cuda12.3-ubuntu22.04' }
+            - { name: 'cpu', runner: 'ubuntu-22.04',         base_image: 'ubuntu:22.04' }
+            - { name: 'gpu', runner: 'ubuntu-22.04',         base_image: 'nvcr.io/nvidia/nvhpc:23.11-devel-cuda_multi-ubuntu22.04' }
+            - { name: 'gpu', runner: 'ubuntu-22.04-arm',     base_image: 'nvcr.io/nvidia/nvhpc:23.11-devel-cuda_multi-ubuntu22.04' }
     runs-on: ${{ matrix.config.runner }}
     outputs:
       tag: ${{ steps.clone.outputs.tag }}
     steps:
+      - name: Free Disk Space
+        uses: jlumbroso/free-disk-space@main
+        with:
+          tool-cache: false
+          android: true
+          dotnet: true
+          haskell: true
+          large-packages: true
+          docker-images: true
+          swap-storage: true
+
       - name: Login
         uses: docker/login-action@v3
         with:
@@ -48,15 +58,43 @@ jobs:
 
       - name: Stage
         run: |
+          sudo fallocate -l 8G /swapfile
+          sudo chmod 600 /swapfile
+          sudo mkswap /swapfile
+          sudo swapon /swapfile
+          sudo mkdir -p /home/runner/tmp
+          export TMPDIR=/home/runner/tmp
+          free -h
           sudo mkdir -p /mnt/share
           sudo chmod 777 /mnt/share
           cp -r mfc/* /mnt/share/
           cp -r mfc/.git /mnt/share/.git
           cp mfc/.github/Dockerfile /mnt/share/
           cp mfc/.github/.dockerignore /mnt/share/
+          docker buildx create --name mfcbuilder --driver docker-container --use
 
-      - name: Build and Deploy
+      - name: Build and push image (cpu)
+        if: ${{ matrix.config.name == 'cpu' }}
         uses: docker/build-push-action@v6
+        with:
+          builder: mfcbuilder
+          context: /mnt/share
+          file: /mnt/share/Dockerfile
+          platforms: linux/amd64,linux/arm64
+          build-args: |
+            BASE_IMAGE=${{ matrix.config.base_image }}
+            TARGET=${{ matrix.config.name }}
+            CC_COMPILER=${{ 'gcc' }}
+            CXX_COMPILER=${{ 'g++' }}
+            FC_COMPILER=${{ 'gfortran' }}
+            COMPILER_PATH=${{ '/usr/bin' }}
+            COMPILER_LD_LIBRARY_PATH=${{ '/usr/lib' }}
+          tags: ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-${{ matrix.config.name }}
+          push: true
+
+      - name: Build and push image (gpu)
+        if: ${{ matrix.config.name == 'gpu' }}
+        uses: docker/build-push-action@v5
         with:
           builder: default
           context: /mnt/share
@@ -64,11 +102,11 @@ jobs:
           build-args: |
             BASE_IMAGE=${{ matrix.config.base_image }}
             TARGET=${{ matrix.config.name }}
-            CC_COMPILER=${{ contains(matrix.config.name, 'gpu') && 'nvc' || 'gcc' }}
-            CXX_COMPILER=${{ contains(matrix.config.name, 'gpu') && 'nvc++' || 'g++' }}
-            FC_COMPILER=${{ contains(matrix.config.name, 'gpu') && 'nvfortran' || 'gfortran' }}
-            COMPILER_PATH=${{ contains(matrix.config.name, 'gpu') && '/opt/nvidia/hpc_sdk/Linux_x86_64/compilers/bin' || '/usr/bin' }}
-            COMPILER_LD_LIBRARY_PATH=${{ contains(matrix.config.name, 'gpu') && '/opt/nvidia/hpc_sdk/Linux_x86_64/compilers/lib' || '/usr/lib' }}
+            CC_COMPILER=${{ 'nvc' }}
+            CXX_COMPILER=${{ 'nvc++' }}
+            FC_COMPILER=${{ 'nvfortran' }}
+            COMPILER_PATH=${{ '/opt/nvidia/hpc_sdk/Linux_x86_64/compilers/bin' }}
+            COMPILER_LD_LIBRARY_PATH=${{ '/opt/nvidia/hpc_sdk/Linux_x86_64/compilers/lib' }}
           tags: ${{ secrets.DOCKERHUB_USERNAME }}/mfc:${{ env.TAG }}-${{ matrix.config.name }}-${{ matrix.config.runner}}
           push: true
 
@@ -87,12 +125,8 @@ jobs:
           TAG: ${{ needs.Container.outputs.tag }}
           REGISTRY: ${{ secrets.DOCKERHUB_USERNAME }}/mfc
         run: |
-          docker manifest create $REGISTRY:$TAG-cpu $REGISTRY:$TAG-cpu-ubuntu-22.04 $REGISTRY:$TAG-cpu-ubuntu-22.04-arm
+          docker buildx imagetools create -t $REGISTRY:latest-cpu $REGISTRY:$TAG-cpu
           docker manifest create $REGISTRY:$TAG-gpu $REGISTRY:$TAG-gpu-ubuntu-22.04 $REGISTRY:$TAG-gpu-ubuntu-22.04-arm
-          docker manifest create $REGISTRY:latest-cpu $REGISTRY:$TAG-cpu-ubuntu-22.04 $REGISTRY:$TAG-cpu-ubuntu-22.04-arm
           docker manifest create $REGISTRY:latest-gpu $REGISTRY:$TAG-gpu-ubuntu-22.04 $REGISTRY:$TAG-gpu-ubuntu-22.04-arm
-          
-          docker manifest push $REGISTRY:$TAG-cpu
           docker manifest push $REGISTRY:$TAG-gpu
-          docker manifest push $REGISTRY:latest-cpu
           docker manifest push $REGISTRY:latest-gpu
\ No newline at end of file

From a56e1e3518f0f35e30d6b65ae62020ed46e0b67f Mon Sep 17 00:00:00 2001
From: Malmahrouqi3 <mohdsaid497566@gmail.com>
Date: Mon, 13 Oct 2025 14:55:58 -0400
Subject: [PATCH 09/14] few adjustments

---
 .github/Dockerfile           |  4 +--
 docs/documentation/docker.md | 58 ++++++++++++++++++------------------
 2 files changed, 31 insertions(+), 31 deletions(-)

diff --git a/.github/Dockerfile b/.github/Dockerfile
index 1c50b4c09e..c7ddcd95a7 100644
--- a/.github/Dockerfile
+++ b/.github/Dockerfile
@@ -46,9 +46,9 @@ RUN echo "TARGET=$TARGET CC=$CC_COMPILER FC=$FC_COMPILER" && \
 
 RUN cd /opt/MFC && \
     if [ "$TARGET" = "gpu" ]; then \
-      ./mfc.sh test --dry-run --gpu -j $(nproc); \
+      ./mfc.sh test -a --dry-run --gpu -j $(nproc); \
     else \
-      ./mfc.sh test --dry-run -j $(nproc); \
+      ./mfc.sh test -a --dry-run -j $(nproc); \
     fi
 
 WORKDIR /opt/MFC
diff --git a/docs/documentation/docker.md b/docs/documentation/docker.md
index 531e3f4b18..8548a34f5c 100644
--- a/docs/documentation/docker.md
+++ b/docs/documentation/docker.md
@@ -5,13 +5,13 @@
 - Install Docker on [Mac](https://docs.docker.com/desktop/setup/install/mac-install/), [Windows](https://docs.docker.com/desktop/setup/install/windows-install/), or [Linux](https://docs.docker.com/desktop/setup/install/linux/).
 
 Via Docker Desktop GUI,
-- Search for [sbryngelson/mfc](https://hub.docker.com/r/sbryngelson/mfc) repository where all MFC images are stored then pull a release tag (e.g. `latest-cpu`). 
+- Search for [sbryngelson/mfc](https://hub.docker.com/r/sbryngelson/mfc) repository where all the MFC images are stored then pull a release tag (e.g., `latest-cpu`).
 
-    Read through **Tag Details** below to distinguish between them. Docker Desktop's left sidebar has two key tabs: **Images** stores your program copies, while **Containers** shows instances of those images. You can launch multiple containers from a single image.
+    Read through the **Tag Details** below to distinguish between them. Docker Desktop's left sidebar has two key tabs: **Images** stores your program copies, while **Containers** shows instances of those images. You can launch multiple containers from a single image.
 
 - Start a container by clicking the Run button in the Images tab.
 
-    Use the *Exec* section to interact with MFC directly via terminal, the *Files* section to transfer files between your device and container, and the *Stats* section displays resource usage of it.
+    Use the *Exec* section to interact with MFC directly via terminal, the *Files* section to transfer files between your device and container, and the *Stats* section to display resource usage.
 
 Or via Docker CLI,
 
@@ -24,7 +24,7 @@ docker run -it --rm --entrypoint bash sbryngelson/mfc:latest-cpu
 
 **Selecting OS/ARCH:** 
 
-Docker by default selects the compatible architecture when pulling and running a container. However, you can manually specify your platform (i.e. `linux/amd64` for most devices or `linux/arm64`for Apple Silicon).
+Docker by default selects the compatible architecture when pulling and running a container. However, you can manually specify your platform (i.e., `linux/amd64` for most devices or `linux/arm64` for Apple Silicon).
 ```bash
 docker run -it --rm --entrypoint bash --platform linux/amd64 sbryngelson/mfc:latest-cpu
 ```
@@ -32,23 +32,22 @@ docker run -it --rm --entrypoint bash --platform linux/amd64 sbryngelson/mfc:lat
 
 ## Running Containers
 
-Start a CPU container
+Start a CPU container.
 ```bash
 docker run -it --rm --entrypoint bash sbryngelson/mfc:latest-cpu
 ```
-Start a GPU container
+Start a GPU container.
 ```bash
-docker run -it --rm --entrypoint bash --gpus all sbryngelson/mfc:latest-gpu
+docker run -it --rm --gpus all --entrypoint bash sbryngelson/mfc:latest-gpu
 ```
-**Note:** `--gpus all` exposes the container to available GPUs, and only Nvidia GPUs are currently supported. Make sure your device CUDA version is at least 12.3 to avoid backward compatibility issues.
+**Note:** `--gpus all` exposes the container to available GPUs, and only Nvidia GPUs are currently supported. Make sure your device's CUDA version is at least 12.3 to avoid backward compatibility issues.
 
-*⚠️ Append the `--debug` option to the  `./mfc.sh` command inside the container with **Apple Silicon** (ARM-based Architecture) to bypass any potential errors or run `./mfc.sh clean && ./mfc.sh build` if needed.*
 <br>
 <br>
 
 **Mounting Directory:** 
 
-Mount a directory to `mnt` inside the container to easily transfer files between the host and the container, e.g. `cp -r <source> /mnt/`.
+Mount a directory to `mnt` inside the container to easily transfer files between the host and the container, e.g. `cp -r <source> /mnt/destination>`.
 ```bash
 docker run -it --rm --entrypoint bash -v "$PWD":/mnt sbryngelson/mfc:latest-cpu
 ```
@@ -56,9 +55,9 @@ docker run -it --rm --entrypoint bash -v "$PWD":/mnt sbryngelson/mfc:latest-cpu
 
 **Shared Memory:** 
 
-Increase the shared memory size to prevent MPI memory binding errors which may fail some tests and cases. Otherwise, you can disable MPI inside the container `--no-mpi`. 
+Increase the shared memory size to prevent MPI memory binding errors which may fail some tests and cases. Otherwise, you can disable MPI inside the container (`--no-mpi`). 
 ```bash
-docker run -it --rm --entrypoint bash --shm-size=<e.g. 4gb> sbryngelson/mfc:latest-cpu
+docker run -it --rm --entrypoint bash --shm-size=<e.g., 4gb> sbryngelson/mfc:latest-cpu
 ```
 
 
@@ -67,13 +66,13 @@ docker run -it --rm --entrypoint bash --shm-size=<e.g. 4gb> sbryngelson/mfc:late
 ### **For Portability,**
 
 On the source machine,
-- Pull and save the image
+- Pull and save the image.
 ```bash
 docker pull sbryngelson/mfc:latest-cpu
 docker save -o mfc:latest-cpu.tar sbryngelson/mfc:latest-cpu
 ```
 On the target machine,
-- Load and run the image
+- Load and run the image.
 ```bash
 docker load -i mfc:latest-cpu.tar
 docker run -it --rm mfc:latest-cpu
@@ -85,24 +84,24 @@ docker run -it --rm mfc:latest-cpu
 
 ### **Interactive Shell**
 ```bash
-apptainer exec --fakeroot --writable-tmpfs --bind "$PWD":/mnt  docker://sbryngelson/mfc:latest-gpu bash -c "cd /opt/MFC && bash"
+apptainer shell --nv --fakeroot --writable-tmpfs --bind "$PWD":/mnt  docker://sbryngelson/mfc:latest-gpu
+Apptainer>cd /opt/MFC
 ```
-or 
+or
 ```bash
-apptainer shell --fakeroot --writable-tmpfs --bind "$PWD":/mnt  docker://sbryngelson/mfc:latest-gpu
-Apptainer>cd /opt/MFC
+apptainer exec --nv --fakeroot --writable-tmpfs --bind "$PWD":/mnt  docker://sbryngelson/mfc:latest-gpu bash -c "cd /opt/MFC && bash"
 ```
 
 ### **For Portability,**
 On the source machine,
-- Pull and translate the image into `.sif` format
+- Pull and translate the image into `.sif` format.
 ```bash
 apptainer build mfc:latest-gpu.sif docker://sbryngelson/mfc:latest-gpu
 ```
 On the target machine,
-- Load and start an interactive shell
+- Load and start an interactive shell.
 ```bash
-apptainer shell --fakeroot --writable-tmpfs --bind "$PWD":/mnt mfc:latest-gpu.sif
+apptainer shell --nv --fakeroot --writable-tmpfs --bind "$PWD":/mnt mfc:latest-gpu.sif
 ```
 
 
@@ -126,18 +125,19 @@ cd $SLURM_SUBMIT_DIR
 # Define container image
 CONTAINER="mfc:latest-gpu.sif"
 
-apptainer exec --fakeroot --writable-tmpfs \
+apptainer exec --nv --fakeroot --writable-tmpfs \
 --bind "$PWD":/mnt \
   $CONTAINER \
-  bash -c "cd /opt/MFC && ./mfc.sh run sim/case.py -c <computer>"
+  bash -c "cd /opt/MFC && ./mfc.sh run sim/case.py -- -c <computer>"
 ```
-Where 
+Where,
 
-`/sim` directory contains all simulation files including case setup (`case.py`).
+`/sim` directory should all the simulation files, including the case setup (`case.py`).
  
-`--fakeroot --writable-tmpfs` are critical to:
-- Enable root-like permissions inside the container without actual root access
-- Allow temporary write access to the container filesystem
+`--nv --fakeroot --writable-tmpfs`, these flags are critical to:
+- Grant access to the host system's Nvidia GPU and its CUDA libraries.
+- Enable root-like permissions inside the container without actual root access.
+- Allow temporary write access to the container filesystem.
 
 
 
@@ -160,7 +160,7 @@ mfc:vx.x.x-xxx-ubuntu-xx.xx      # amd64 natively-supported version
 mfc:vx.x.x-xxx-ubuntu-xx.xx-arm  # arm64 natively-supported version
 ```
 ### **Architecture Support**
-You can specify the desired architecture with `--platform <os>/<arch>` - either `linux/amd64` or `linux/arm64`. If not sure, Docker automatically selects the available image compatible with your system architecture. If native support isn't available, QEMU emulation is enabled for the following architectures albeit with degraded performance.
+You can specify the desired architecture with `--platform <os>/<arch>` - either `linux/amd64` or `linux/arm64`. If unsure, Docker automatically selects the compatible image with your system architecture. If native support isn't available, QEMU emulation is enabled for the following architectures albeit with degraded performance.
 ```
 linux/amd64
 linux/amd64/v2

From 4e5516d7a97eca292c4cd5efdc9bd1c769384bdc Mon Sep 17 00:00:00 2001
From: "Mohammed S. Al-Mahrouqi"
 <145478595+Malmahrouqi3@users.noreply.github.com>
Date: Mon, 13 Oct 2025 23:22:26 -0400
Subject: [PATCH 10/14] Update .dockerignore to remove lag_bubbles.dat
 exceptions

Removed specific exceptions for lag_bubbles.dat files from .dockerignore.
---
 .github/.dockerignore | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/.github/.dockerignore b/.github/.dockerignore
index 452cfea06a..57de78cc35 100644
--- a/.github/.dockerignore
+++ b/.github/.dockerignore
@@ -34,7 +34,6 @@ examples/**/p*
 examples/**/D_*
 examples/**/*.inf
 examples/**/*.inp
-examples/**/*.dat
 examples/**/*.o*
 examples/**/silo*
 examples/**/restart_data*
@@ -50,8 +49,6 @@ examples/*/workloads/
 examples/*/run-*/
 examples/*/logs/
 examples/**/*.f90
-!examples/3D_lag_bubbles_shbubcollapse/input/lag_bubbles.dat
-!examples/3D_lag_bubbles_bubblescreen/input/lag_bubbles.dat
 workloads/
 
 benchmarks/*batch/*/
@@ -79,4 +76,4 @@ benchmarks/*.png
 *.mp4
 *.mov
 *.mkv
-*.avi
\ No newline at end of file
+*.avi

From cbf9f6158edfdd8b6b88164dadba04b55b638f85 Mon Sep 17 00:00:00 2001
From: Malmahrouqi3 <mohdsaid497566@gmail.com>
Date: Mon, 20 Oct 2025 12:53:33 -0400
Subject: [PATCH 11/14] improved docs

---
 README.md                             |  4 ++--
 docs/documentation/docker.md          | 18 ++++++++++++------
 docs/documentation/getting-started.md |  2 +-
 3 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 4d547f7d75..29694deaef 100644
--- a/README.md
+++ b/README.md
@@ -84,9 +84,9 @@ And here is a high amplitude acoustic wave reflecting and emerging through a cir
 
 
 ## Getting started
-For a quick start, open a GitHub Codespace to load a pre-configured docker container to get familiar with MFC commands. Click <kbd> <> Code</kbd> (green button at top right) → <kbd>Codespaces</kbd> (right tab) → <kbd>+</kbd> (create a codespace).
+For a quick start, open a GitHub Codespace to load a pre-configured Docker container to get familiar with MFC commands. Click <kbd> <> Code</kbd> (green button at top right) → <kbd>Codespaces</kbd> (right tab) → <kbd>+</kbd> (create a codespace).
 
-****Notes:**** Codespaces is a free service with a monthly quota of compute time and storage usage. It is commended for testing commands, troubleshooting, and running simple case files without the need to install dependencies and build MFC on your device. Remember to save any important files locally before closing your codespace. To learn more, read through [how docker & containers work](https://mflowcode.github.io/documentation/docker.html).
+****Notes:**** Codespaces is a free service with a monthly quota of compute time and storage usage. It is recommended for testing commands, troubleshooting, and running simple case files without the need to install dependencies and build MFC on your device. Remember to save any important files locally before closing your codespace. To learn more, read through [how Docker & Containers work](https://mflowcode.github.io/documentation/docker.html).
 
 Otherwise, you can navigate [to this webpage](https://mflowcode.github.io/documentation/md_getting-started.html) to get started using MFC!
 It's rather straightforward.
diff --git a/docs/documentation/docker.md b/docs/documentation/docker.md
index 8548a34f5c..1cdc9e337c 100644
--- a/docs/documentation/docker.md
+++ b/docs/documentation/docker.md
@@ -30,6 +30,13 @@ docker run -it --rm --entrypoint bash --platform linux/amd64 sbryngelson/mfc:lat
 ```
 <br>
 
+**What is Next:** 
+
+After starting a container, the primary working directory is `/opt/MFC`, where all necessary files are located. Read through [Example Cases](https://mflowcode.github.io/documentation/md_examples.html) to get familiar with running cases, then review [Case Files](https://mflowcode.github.io/documentation/md_case.html) to write a custom case file.
+
+
+<br>
+
 ## Running Containers
 
 Start a CPU container.
@@ -40,7 +47,7 @@ Start a GPU container.
 ```bash
 docker run -it --rm --gpus all --entrypoint bash sbryngelson/mfc:latest-gpu
 ```
-**Note:** `--gpus all` exposes the container to available GPUs, and only Nvidia GPUs are currently supported. Make sure your device's CUDA version is at least 12.3 to avoid backward compatibility issues.
+**Note:** `--gpus all` exposes the container to available GPUs, and only NVIDIA GPUs are currently supported. Make sure your device's CUDA version is at least 12.3 to avoid backward compatibility issues.
 
 <br>
 <br>
@@ -55,7 +62,7 @@ docker run -it --rm --entrypoint bash -v "$PWD":/mnt sbryngelson/mfc:latest-cpu
 
 **Shared Memory:** 
 
-Increase the shared memory size to prevent MPI memory binding errors which may fail some tests and cases. Otherwise, you can disable MPI inside the container (`--no-mpi`). 
+When encountering MPI memory binding errors resulting in failed tests and cases, increase the shared memory size or disable MPI inside the container (`./mfc.sh --no-mpi`).
 ```bash
 docker run -it --rm --entrypoint bash --shm-size=<e.g., 4gb> sbryngelson/mfc:latest-cpu
 ```
@@ -91,6 +98,7 @@ or
 ```bash
 apptainer exec --nv --fakeroot --writable-tmpfs --bind "$PWD":/mnt  docker://sbryngelson/mfc:latest-gpu bash -c "cd /opt/MFC && bash"
 ```
+**Note:** To run MFC on CPU cores, omit `--nv` and use `mfc:latest-cpu` container image.
 
 ### **For Portability,**
 On the source machine,
@@ -107,6 +115,7 @@ apptainer shell --nv --fakeroot --writable-tmpfs --bind "$PWD":/mnt mfc:latest-g
 
 
 ### Slurm Job
+Below is a slurm job template. Refer to your HPC user guide for instructions on properly loading and using apptainer.
 ```bash
 #!/bin/bash
 #SBATCH --job-name=mfc-sim
@@ -117,9 +126,6 @@ apptainer shell --nv --fakeroot --writable-tmpfs --bind "$PWD":/mnt mfc:latest-g
 #SBATCH --output=mfc-sim-%j.out
 #SBATCH --error=mfc-sim-%j.err
 
-# Load required modules
-module load apptainer
-
 cd $SLURM_SUBMIT_DIR
 
 # Define container image
@@ -135,7 +141,7 @@ Where,
 `/sim` directory should all the simulation files, including the case setup (`case.py`).
  
 `--nv --fakeroot --writable-tmpfs`, these flags are critical to:
-- Grant access to the host system's Nvidia GPU and its CUDA libraries.
+- Grant access to the host system's NVIDIA GPUs and its CUDA libraries.
 - Enable root-like permissions inside the container without actual root access.
 - Allow temporary write access to the container filesystem.
 
diff --git a/docs/documentation/getting-started.md b/docs/documentation/getting-started.md
index c88b5978c4..0f0e3cc728 100644
--- a/docs/documentation/getting-started.md
+++ b/docs/documentation/getting-started.md
@@ -146,7 +146,7 @@ Examples:
 - Build MFC's `simulation` code in Debug mode with MPI and GPU support: `./mfc.sh build --debug --gpu -t simulation`.
 
 ## Using Containers
-As an alternative to building MFC from scratch, use containers to quickly access pre-built MFC with all its dependencies.
+Instead of building MFC from scratch, use containers to quickly access pre-built MFC along with its dependencies.
 
 Run the latest MFC container.
 ```bash

From 06c7592d403cbaf3dcdd8407ed7aebf87358c9c1 Mon Sep 17 00:00:00 2001
From: Spencer Bryngelson <shb@gatech.edu>
Date: Tue, 21 Oct 2025 09:39:29 -0400
Subject: [PATCH 12/14] Revise Docker documentation for clarity and structure

Updated Docker documentation to improve clarity and organization, including sections on installation, usage, and architecture support.
---
 docs/documentation/docker.md | 134 +++++++++++++++++------------------
 1 file changed, 67 insertions(+), 67 deletions(-)

diff --git a/docs/documentation/docker.md b/docs/documentation/docker.md
index 1cdc9e337c..168a1b8ee6 100644
--- a/docs/documentation/docker.md
+++ b/docs/documentation/docker.md
@@ -1,95 +1,97 @@
-# Docker
+# Containers
 
-## Navigating Docker Desktop/CLI
+## Navigating Docker
 
-- Install Docker on [Mac](https://docs.docker.com/desktop/setup/install/mac-install/), [Windows](https://docs.docker.com/desktop/setup/install/windows-install/), or [Linux](https://docs.docker.com/desktop/setup/install/linux/).
+Install Docker on 
+* [MacOS](https://docs.docker.com/desktop/setup/install/mac-install/)
+* [Windows](https://docs.docker.com/desktop/setup/install/windows-install/)
+* [Linux](https://docs.docker.com/desktop/setup/install/linux/)
 
-Via Docker Desktop GUI,
-- Search for [sbryngelson/mfc](https://hub.docker.com/r/sbryngelson/mfc) repository where all the MFC images are stored then pull a release tag (e.g., `latest-cpu`).
+### Docker Desktop GUI
 
-    Read through the **Tag Details** below to distinguish between them. Docker Desktop's left sidebar has two key tabs: **Images** stores your program copies, while **Containers** shows instances of those images. You can launch multiple containers from a single image.
+- Search for the [sbryngelson/mfc](https://hub.docker.com/r/sbryngelson/mfc) repository. All the MFC containers are stored here.
 
-- Start a container by clicking the Run button in the Images tab.
+- Find and pull a release tag (e.g., `latest-cpu`).
 
-    Use the *Exec* section to interact with MFC directly via terminal, the *Files* section to transfer files between your device and container, and the *Stats* section to display resource usage.
+    * Read through the **Tag Details** below to distinguish between them. Docker Desktop's left sidebar has two key tabs: **Images** stores your program copies, and **Containers** shows instances of those images. You can launch multiple containers from a single image.
 
-Or via Docker CLI,
+- Start a container by navigating to the `Images` tab and clicking the `Run` button.
 
-- Pull from [sbryngelson/mfc](https://hub.docker.com/r/sbryngelson/mfc) repository and run the latest MFC container.
+    * Use the *Exec* section to interact with MFC directly via terminal, the *Files* section to transfer files between your device and container, and the *Stats* section to display resource usage.
 
+### Docker CLI
+
+You can navigate Docker entirely from the command line.
+From a bash-like shell, pull from the [sbryngelson/mfc](https://hub.docker.com/r/sbryngelson/mfc) repository and run the latest MFC container:
 ```bash
 docker run -it --rm --entrypoint bash sbryngelson/mfc:latest-cpu
 ```
-<br>
-
-**Selecting OS/ARCH:** 
 
-Docker by default selects the compatible architecture when pulling and running a container. However, you can manually specify your platform (i.e., `linux/amd64` for most devices or `linux/arm64` for Apple Silicon).
+**Selecting OS/ARCH:**  Docker selects the compatible architecture by default when pulling and running a container.
+You can manually specify your platform if something seems to go wrong, as Docker may suggest doing so.
+For example, `linux/amd64` handles many *nix-based x86 architectures, and `linux/arm64` handles Apple Silicon and Arm-based *nix devices.
+You can specify it like this: 
 ```bash
 docker run -it --rm --entrypoint bash --platform linux/amd64 sbryngelson/mfc:latest-cpu
 ```
-<br>
-
-**What is Next:** 
 
-After starting a container, the primary working directory is `/opt/MFC`, where all necessary files are located. Read through [Example Cases](https://mflowcode.github.io/documentation/md_examples.html) to get familiar with running cases, then review [Case Files](https://mflowcode.github.io/documentation/md_case.html) to write a custom case file.
+**What's Next?** 
 
+Once a container has started, the primary working directory is `/opt/MFC`, and all necessary files are located there.
+You can check out the usual MFC documentation, such as the [Example Cases](https://mflowcode.github.io/documentation/md_examples.html), to get familiar with running cases.
+Then, review the [Case Files](https://mflowcode.github.io/documentation/md_case.html) to write a custom case file.
 
-<br>
+## Details on Running Containers
 
-## Running Containers
-
-Start a CPU container.
+Let's take a closer look at running MFC within a container.
+Kick off a CPU container:
 ```bash
 docker run -it --rm --entrypoint bash sbryngelson/mfc:latest-cpu
 ```
-Start a GPU container.
+Or, start a GPU container.
 ```bash
 docker run -it --rm --gpus all --entrypoint bash sbryngelson/mfc:latest-gpu
 ```
-**Note:** `--gpus all` exposes the container to available GPUs, and only NVIDIA GPUs are currently supported. Make sure your device's CUDA version is at least 12.3 to avoid backward compatibility issues.
 
-<br>
-<br>
+**Note:** `--gpus all` exposes the container to available GPUs, and _only NVIDIA GPUs are currently supported_.
+[Ensure your device's CUDA version is at least 12.3](https://stackoverflow.com/questions/9727688/how-to-get-the-cuda-version) to avoid backward compatibility issues.
 
-**Mounting Directory:** 
+**Mounting Directory**
 
-Mount a directory to `mnt` inside the container to easily transfer files between the host and the container, e.g. `cp -r <source> /mnt/destination>`.
+Mount a directory to `mnt` inside the container to easily transfer files between your host computer and the separate container.
+For example, `cp -r <source> /mnt/destination>` moves something from your source computer to the container (reverse the order for the reverse to happen!).
 ```bash
 docker run -it --rm --entrypoint bash -v "$PWD":/mnt sbryngelson/mfc:latest-cpu
 ```
-<br>
 
-**Shared Memory:** 
+**Shared Memory**
 
-When encountering MPI memory binding errors resulting in failed tests and cases, increase the shared memory size or disable MPI inside the container (`./mfc.sh --no-mpi`).
+If you run a job with multiple MPI ranks, you could run into _MPI memory binding errors_.
+This can manifest as a failed test (launched via `./mfc.sh test`) and running cases with `./mfc.sh run -n X <path/to/case.py>` where `X > 1`.
+To avoid this issue, you can increase the shared memory size (to keep MPI working):
 ```bash
 docker run -it --rm --entrypoint bash --shm-size=<e.g., 4gb> sbryngelson/mfc:latest-cpu
 ```
+or avoid MPI altogether via `./mfc.sh <your commands> --no-mpi`.
 
 
+### Portability
 
-
-### **For Portability,**
-
-On the source machine,
-- Pull and save the image.
+On the source machine, pull and save the image:
 ```bash
 docker pull sbryngelson/mfc:latest-cpu
 docker save -o mfc:latest-cpu.tar sbryngelson/mfc:latest-cpu
 ```
-On the target machine,
-- Load and run the image.
+On the target machine, load and run the image:
 ```bash
 docker load -i mfc:latest-cpu.tar
 docker run -it --rm mfc:latest-cpu
 ```
 
-<br>
+## Using Supercomputers/Clusters via Apptainer/Singularity
 
-## HPC Cluster Usage (Apptainer/Singularity)
+### Interactive Shell
 
-### **Interactive Shell**
 ```bash
 apptainer shell --nv --fakeroot --writable-tmpfs --bind "$PWD":/mnt  docker://sbryngelson/mfc:latest-gpu
 Apptainer>cd /opt/MFC
@@ -98,24 +100,23 @@ or
 ```bash
 apptainer exec --nv --fakeroot --writable-tmpfs --bind "$PWD":/mnt  docker://sbryngelson/mfc:latest-gpu bash -c "cd /opt/MFC && bash"
 ```
-**Note:** To run MFC on CPU cores, omit `--nv` and use `mfc:latest-cpu` container image.
+To run MFC on CPUs, omit `--nv` and use the `mfc:latest-cpu` container image.
+
+### For Portability
 
-### **For Portability,**
-On the source machine,
-- Pull and translate the image into `.sif` format.
+On the source machine, pull and translate the image into `.sif` format:
 ```bash
 apptainer build mfc:latest-gpu.sif docker://sbryngelson/mfc:latest-gpu
 ```
-On the target machine,
-- Load and start an interactive shell.
+On the target machine, load and start an interactive shell:
 ```bash
 apptainer shell --nv --fakeroot --writable-tmpfs --bind "$PWD":/mnt mfc:latest-gpu.sif
 ```
 
-
-
 ### Slurm Job
-Below is a slurm job template. Refer to your HPC user guide for instructions on properly loading and using apptainer.
+
+Below is an example Slurm batch job script.
+Refer to your machine's user guide for instructions on properly loading and using Apptainer.
 ```bash
 #!/bin/bash
 #SBATCH --job-name=mfc-sim
@@ -136,18 +137,16 @@ apptainer exec --nv --fakeroot --writable-tmpfs \
   $CONTAINER \
   bash -c "cd /opt/MFC && ./mfc.sh run sim/case.py -- -c <computer>"
 ```
-Where,
-
-`/sim` directory should all the simulation files, including the case setup (`case.py`).
- 
-`--nv --fakeroot --writable-tmpfs`, these flags are critical to:
-- Grant access to the host system's NVIDIA GPUs and its CUDA libraries.
-- Enable root-like permissions inside the container without actual root access.
-- Allow temporary write access to the container filesystem.
-
 
+In the above,
+* The `/sim` directory should have all the simulation files, including the case setup (`case.py`).
+* The `--nv --fakeroot --writable-tmpfs` set of flags are needed to
+    - Grant access to the host system's NVIDIA GPUs and its CUDA libraries.
+    - Enable root-like permissions inside the container without actual root access.
+    - Allow temporary write access to the container filesystem.
 
 ## Tag Details
+
 ### Base Images
 - CPU images (v4.3.0-latest releases) are built on **Ubuntu 22.04**.
 - GPU images (v4.3.0-latest releases) are built on **NVHPC SDK 23.11 (CUDA 12.3) & Ubuntu 22.04**.
@@ -157,16 +156,21 @@ Where,
 - **`cpu/gpu`** - Build configurations for CPU or GPU acceleration.
 - **`ubuntu-xx.xx`** - Base Ubuntu version (standard = `amd64`, `-arm` = `arm64`)
 
-### Available Tags
-```
+### Example Tags
+
+```shell
 mfc:latest-xxx                   # Latest version (amd64 & arm64)
 mfc:vx.x.x-cpu                   # CPU version    (amd64 & arm64)
 mfc:vx.x.x-gpu                   # GPU version    (amd64 & arm64)
 mfc:vx.x.x-xxx-ubuntu-xx.xx      # amd64 natively-supported version
 mfc:vx.x.x-xxx-ubuntu-xx.xx-arm  # arm64 natively-supported version
 ```
-### **Architecture Support**
-You can specify the desired architecture with `--platform <os>/<arch>` - either `linux/amd64` or `linux/arm64`. If unsure, Docker automatically selects the compatible image with your system architecture. If native support isn't available, QEMU emulation is enabled for the following architectures albeit with degraded performance.
+
+### Architecture Support
+
+You can specify your architecture with `--platform <os>/<arch>`, typically either `linux/amd64` or `linux/arm64`.
+If you are unsure, Docker automatically selects the compatible image with your system architecture.
+If native support isn't available, QEMU emulation is enabled for the following architectures, albeit with degraded performance.
 ```
 linux/amd64
 linux/amd64/v2
@@ -182,7 +186,3 @@ linux/loong64
 linux/arm/v7
 linux/arm/v6
 ```
-
-
-<br>
-<br>

From 7b21a8fbd4d031a988f50d6d2a4e4b91043a3723 Mon Sep 17 00:00:00 2001
From: Spencer Bryngelson <shb@gatech.edu>
Date: Tue, 21 Oct 2025 09:45:02 -0400
Subject: [PATCH 13/14] Fix typos and enhance clarity in getting-started.md

Corrected typos and improved clarity in the documentation.
---
 docs/documentation/getting-started.md | 24 ++++++++++--------------
 1 file changed, 10 insertions(+), 14 deletions(-)

diff --git a/docs/documentation/getting-started.md b/docs/documentation/getting-started.md
index 0f0e3cc728..9478a72ce2 100644
--- a/docs/documentation/getting-started.md
+++ b/docs/documentation/getting-started.md
@@ -12,14 +12,14 @@ cd MFC
 ## Build Environment
 
 MFC can be built in multiple ways on various operating systems.
-Please select your desired configuration from the list bellow:
+Please select your desired configuration from the list below:
 
   <summary><h2>*nix</h2></summary>
 
 - **On supported clusters:** Load environment modules
 
 ```shell
-. ./mfc.sh load
+source ./mfc.sh load
 ```
 
 - **Via Aptitude:**
@@ -34,8 +34,7 @@ sudo apt install tar wget make cmake gcc g++      \
                  libblas-dev liblapack-dev
 ```
 
-If you wish to build MFC using [NVIDIA's NVHPC SDK](https://developer.nvidia.com/hpc-sdk),
-first follow the instructions [here](https://developer.nvidia.com/nvidia-hpc-sdk-downloads).
+If you wish to build MFC using [NVIDIA's NVHPC SDK](https://developer.nvidia.com/hpc-sdk), first follow the instructions [here](https://developer.nvidia.com/nvidia-hpc-sdk-downloads).
 
 
   <summary><h2>Windows</h2></summary>
@@ -116,12 +115,12 @@ MFC can be built with support for various (compile-time) features:
 
 | Feature            | Enable      | Disable        | Default | Description                                                     |
 | :----------------: | :---------: | :------------: | :-----: | --------------------------------------------------------------- |
-| **MPI**            | `--mpi`     | `--no-mpi`     | On      | Lets MFC run on multiple processors (and nodes) simultaneously. |
+| **MPI**            | `--mpi`     | `--no-mpi`     | On      | Allows MFC to run on multiple processors (and nodes). |
 | **GPU**            | `--gpu`     | `--no-gpu`     | Off     | Enables GPU acceleration via OpenACC.                           |
 | **Debug**          | `--debug`   | `--no-debug`   | Off     | Requests the compiler build MFC in debug mode.                  |
-| **GCov**           | `--gcov`    | `--no-gcov`    | Off     | Builds MFC with coverage flags on.                              |
-| **Unified Memory** | `--unified` | `--no-unified` | Off     | Builds MFC with unified CPU/GPU memory (GH-200 superchip only)  |
-| **Single**         | `--single`  | `--no-single`  | Off     | Builds MFC in single precision     
+| **GCov**           | `--gcov`    | `--no-gcov`    | Off     | Build MFC with coverage flags on.                              |
+| **Unified Memory** | `--unified` | `--no-unified` | Off     | Build MFC with unified CPU/GPU memory (GH200 superchip only)  |
+| **Single**         | `--single`  | `--no-single`  | Off     | Build MFC in single precision     
 
 _⚠️ The `--gpu` option requires that your compiler supports OpenACC for Fortran for your target GPU architecture._
 
@@ -139,26 +138,23 @@ Most first-time users will want to build MFC using 8 threads (or more!) with MPI
 ./mfc.sh build -j 8
 ```
 
-Examples:
-
+Some examples:
 - Build MFC using 8 threads with MPI and GPU acceleration: `./mfc.sh build --gpu -j 8`.
 - Build MFC using a single thread without MPI, GPU, and Debug support: `./mfc.sh build --no-mpi`.
 - Build MFC's `simulation` code in Debug mode with MPI and GPU support: `./mfc.sh build --debug --gpu -t simulation`.
 
 ## Using Containers
-Instead of building MFC from scratch, use containers to quickly access pre-built MFC along with its dependencies.
 
-Run the latest MFC container.
+Instead of building MFC from scratch, you can use containers to quickly access a pre-built version of MFC and its dependencies.
+In brief, you can run the latest MFC container:
 ```bash
 docker run -it --rm --entrypoint bash sbryngelson/mfc:latest-cpu
 ```
 Please refer to the [Docker](https://mflowcode.github.io/documentation/docker.html) document for more information.
 
-
 ## Running the Test Suite
 
 Run MFC's test suite with 8 threads:
-
 ```shell
 ./mfc.sh test -j 8
 ```

From d86b17a712ea3f0451ae8ad87c7eb6e768694df3 Mon Sep 17 00:00:00 2001
From: Spencer Bryngelson <shb@gatech.edu>
Date: Tue, 21 Oct 2025 09:54:03 -0400
Subject: [PATCH 14/14] Revise README for clarity and updates

Updated README for clarity and conciseness, including corrections and additional details about MFC's capabilities and sponsors.
---
 README.md | 43 +++++++++++++++++++++++--------------------
 1 file changed, 23 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 29694deaef..3c77b7f317 100644
--- a/README.md
+++ b/README.md
@@ -27,8 +27,9 @@
 
 **Welcome!**
 MFC simulates compressible multi-phase flows, [among other things](#what-else-can-this-thing-do). 
-It uses metaprogramming to stay short and portable (~20K lines).
-MFC conducted the largest known, open CFD simulation at <a href="https://arxiv.org/abs/2505.07392" target="_blank">200 trillion grid points</a>, and 1 quadrillion degrees of freedom (as of September 2025), and is a 2025 Gordon Bell Prize finalist.
+It uses metaprogramming and is short (20K lines) and portable.
+MFC conducted the largest known CFD simulation at <a href="https://arxiv.org/abs/2505.07392" target="_blank">200 trillion grid points</a>, and 1 quadrillion degrees of freedom (as of September 2025).
+MFC is a 2025 Gordon Bell Prize Finalist.
 
 <p align="center">
 <a href="https://doi.org/10.48550/arXiv.2503.07953" target="_blank">
@@ -76,7 +77,7 @@ This one simulates high-Mach flow over an airfoil:
     <img src="docs/res/airfoil.png" alt="Airfoil Example" width="700"/><br/>
 </p>
 
-And here is a high amplitude acoustic wave reflecting and emerging through a circular orifice:
+And here is a high-amplitude acoustic wave reflecting and emerging through a circular orifice:
 
 <p align="center">
     <img src="docs/res/orifice.png" alt="Orifice Example" width="700"/><br/>
@@ -84,19 +85,24 @@ And here is a high amplitude acoustic wave reflecting and emerging through a cir
 
 
 ## Getting started
-For a quick start, open a GitHub Codespace to load a pre-configured Docker container to get familiar with MFC commands. Click <kbd> <> Code</kbd> (green button at top right) → <kbd>Codespaces</kbd> (right tab) → <kbd>+</kbd> (create a codespace).
 
-****Notes:**** Codespaces is a free service with a monthly quota of compute time and storage usage. It is recommended for testing commands, troubleshooting, and running simple case files without the need to install dependencies and build MFC on your device. Remember to save any important files locally before closing your codespace. To learn more, read through [how Docker & Containers work](https://mflowcode.github.io/documentation/docker.html).
+For a _very_ quick start, open a GitHub Codespace to load a pre-configured Docker container and familiarize yourself with MFC commands.
+Click <kbd> <> Code</kbd> (green button at top right) → <kbd>Codespaces</kbd> (right tab) → <kbd>+</kbd> (create a codespace).
 
-Otherwise, you can navigate [to this webpage](https://mflowcode.github.io/documentation/md_getting-started.html) to get started using MFC!
+> ****Note:**** Codespaces is a free service with a monthly quota of compute time and storage usage.
+> It is recommended for testing commands, troubleshooting, and running simple case files without installing dependencies or building MFC on your device.
+> Don't conduct any critical work here!
+> To learn more, please see [how Docker & Containers work](https://mflowcode.github.io/documentation/docker.html).
+
+You can navigate [to this webpage](https://mflowcode.github.io/documentation/md_getting-started.html) to get you get started using MFC on your local machine, cluster, or supercomputer!
 It's rather straightforward.
-We'll give a brief intro. here for MacOS.
+We'll give a brief introdocution for MacOS below.
 Using [brew](https://brew.sh), install MFC's dependencies:
 ```shell
 brew install coreutils python cmake fftw hdf5 gcc boost open-mpi lapack
 ```
 You're now ready to build and test MFC!
-Put it to a convenient directory via
+Put it to a local directory via
 ```shell
 git clone https://github.com/MFlowCode/MFC
 cd MFC
@@ -126,17 +132,14 @@ You can visualize the output data in `examples/3d_shockdroplet/silo_hdf5` via Pa
 ## Is this _really_ exascale?
 
 [OLCF Frontier](https://www.olcf.ornl.gov/frontier/) is the first exascale supercomputer.
-The weak scaling of MFC on this machine shows near-ideal utilization. 
+The weak scaling of MFC on this machine shows near-ideal utilization.
+We also scale ideally to >98% of LLNL El Capitan.
 
 <p align="center">
     <img src="docs/res/scaling.png" alt="Scaling" width="400"/>
 </p>
 
-
-## What else can this thing do
-
-MFC has many features.
-They are organized below.
+## What else can this thing do?
 
 ### Physics
 
@@ -212,7 +215,7 @@ They are organized below.
 
 If you use MFC, consider citing it as below.
 Ref. 1 includes all modern MFC features, including GPU acceleration and many new physics features.
-If referencing MFC's (GPU) performance, consider citing ref. 1 and 2, which describe the solver and how it was crafted.
+If referencing MFC's (GPU) performance, consider citing ref. 1 and 2, which describe the solver and its design.
 The original open-source release of MFC is ref. 3, which should be cited for provenance as appropriate.
 
 ```bibtex
@@ -252,11 +255,11 @@ MFC is under the MIT license (see [LICENSE](LICENSE) for full text).
 
 ## Acknowledgements
 
-Federal sponsors have supported MFC development, including the US Department of Defense (DOD), the National Institutes of Health (NIH), the Department of Energy (DOE), and the National Science Foundation (NSF).
+Federal sponsors have supported MFC development, including the US Department of Defense (DOD), the National Institutes of Health (NIH), the Department of Energy (DOE) and National Nuclear Security Administration (NNSA), and the National Science Foundation (NSF).
 
 MFC computations have used many supercomputing systems. A partial list is below
-  * OLCF Frontier and Summit, and testbeds Wombat, Crusher, and Spock (allocation CFD154, PI Bryngelson)
-  * LLNL El Capitan, Tuolumne, and Lassen; El Capitan early access system Tioga
+  * OLCF Frontier and Summit, and testbeds Wombat, Crusher, and Spock (allocation CFD154, PI Bryngelson).
+  * LLNL El Capitan, Tuolumne, and Lassen; El Capitan early access system Tioga.
   * NCSA Delta and DeltaAI, PSC Bridges(1/2), SDSC Comet and Expanse, Purdue Anvil, TACC Stampede(1-3), and TAMU ACES via ACCESS-CI allocations from Bryngelson, Colonius, Rodriguez, and more.
-  * DOD systems Blueback, Onyx, Carpenter, Nautilus, and Narwhal via the DOD HPCMP program
-  * Sandia National Labs systems Doom and Attaway and testbed systems Weaver and Vortex
+  * DOD systems Blueback, Onyx, Carpenter, Nautilus, and Narwhal via the DOD HPCMP program.
+  * Sandia National Labs systems Doom and Attaway, and testbed systems Weaver and Vortex.