Add UKACM & GACM tutorial: Orchestrating 4C simulations with QUEENS

.github/workflows/build_documentation.yml

@@ -16,11 +16,24 @@ permissions:
 jobs:
   build-documentation:
     runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/4c-multiphysics/4c-minimal:main
+      options: --user root --env OMPI_ALLOW_RUN_AS_ROOT=1 --env OMPI_ALLOW_RUN_AS_ROOT_CONFIRM=1
     defaults:
       run:
         shell: bash -l {0}
     steps:
       - uses: actions/checkout@v4
+      - name: Mark repo as safe for git
+        run: |
+          git config --global --add safe.directory "$GITHUB_WORKSPACE"
+      - name: Install rsync
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y rsync
+      - name: Create links to 4C
+        run: |
+          ln -s /home/user/4C/bin/ config/4C_build
       - name: Create Python environment
         id: environment
         uses: ./.github/actions/create_python_environment
@@ -31,14 +44,19 @@ jobs:
           $PYTHON_PACKAGE_MANAGER activate queens
           pip install -e .[tutorial]
           python -m ipykernel install --user --name queens --display-name "Python (queens)"
+      - name: Install xvfb
+        run: |
+          apt-get update
+          apt-get install -y xvfb
       - name: Sphinx build
         env:
           PYTHON_PACKAGE_MANAGER: ${{steps.environment.outputs.ppm}}
         run: |
+          set -euxo pipefail
           $PYTHON_PACKAGE_MANAGER activate queens
           sphinx-apidoc -o doc/source src/ -fMT
           cd doc
-          sphinx-build -b html -d build/doctrees source build/html -W
+          xvfb-run -a sphinx-build -b html -d build/doctrees source build/html -W
       - name: Upload html
         uses: actions/upload-pages-artifact@v3
         with:

doc/source/_ext/create_documentation_files.py

@@ -286,14 +286,22 @@ def download_file_from_url(url, file_name):
 
 
 def copy_tutorials():
-    """Copy tutorials from source to doc."""
-    for tutorial in relative_path_from_root("tutorials").glob("*.ipynb"):
-        destination = relative_to_doc_source("tutorials/" + tutorial.name)
+    """Copy tutorials and other util and input files from source to doc."""
+    source_root = relative_path_from_root("tutorials")
+    destination_root = relative_to_doc_source("tutorials")
+    allowed_patterns = ("*.ipynb", "*.py", "*.exo", "*.yaml")
 
-        if destination.exists():
-            destination.unlink()
+    for pattern in allowed_patterns:
+        for source in source_root.rglob(pattern):
+            rel = source.relative_to(source_root)
+            destination = destination_root / rel
 
-        shutil.copyfile(tutorial, destination)
+            destination.parent.mkdir(parents=True, exist_ok=True)
+
+            if destination.exists():
+                destination.unlink()
+
+            shutil.copyfile(source, destination)
 
 
 def main():

tutorial-requirements.in

@@ -4,3 +4,4 @@
 
 # Tutorials
 scikit-fem
+pyvista

tutorial-requirements.txt

@@ -4,14 +4,104 @@
 #
 #    pip-compile --constraint=requirements.txt --output-file=tutorial-requirements.txt tutorial-requirements.in
 #
+certifi==2024.8.30
+    # via
+    #   -c requirements.txt
+    #   requests
+charset-normalizer==3.4.0
+    # via
+    #   -c requirements.txt
+    #   requests
+contourpy==1.3.0
+    # via
+    #   -c requirements.txt
+    #   matplotlib
+cycler==0.12.1
+    # via
+    #   -c requirements.txt
+    #   matplotlib
+fonttools==4.54.1
+    # via
+    #   -c requirements.txt
+    #   matplotlib
+idna==3.10
+    # via
+    #   -c requirements.txt
+    #   requests
+kiwisolver==1.4.7
+    # via
+    #   -c requirements.txt
+    #   matplotlib
+matplotlib==3.9.2
+    # via
+    #   -c requirements.txt
+    #   pyvista
+    #   vtk
 numpy==1.26.4
     # via
     #   -c requirements.txt
+    #   contourpy
+    #   matplotlib
+    #   pyvista
     #   scikit-fem
     #   scipy
+packaging==24.1
+    # via
+    #   -c requirements.txt
+    #   matplotlib
+    #   pooch
+pillow==11.0.0
+    # via
+    #   -c requirements.txt
+    #   matplotlib
+    #   pyvista
+platformdirs==4.3.6
+    # via
+    #   -c requirements.txt
+    #   pooch
+pooch==1.8.2
+    # via
+    #   -c requirements.txt
+    #   pyvista
+pyparsing==3.2.0
+    # via
+    #   -c requirements.txt
+    #   matplotlib
+python-dateutil==2.9.0.post0
+    # via
+    #   -c requirements.txt
+    #   matplotlib
+pyvista==0.44.1
+    # via
+    #   -c requirements.txt
+    #   -r tutorial-requirements.in
+requests==2.32.3
+    # via
+    #   -c requirements.txt
+    #   pooch
 scikit-fem==11.0.0
-    # via -r tuto-requirements.in
+    # via -r tutorial-requirements.in
 scipy==1.14.1
     # via
     #   -c requirements.txt
     #   scikit-fem
+scooby==0.10.0
+    # via
+    #   -c requirements.txt
+    #   pyvista
+six==1.16.0
+    # via
+    #   -c requirements.txt
+    #   python-dateutil
+typing-extensions==4.12.2
+    # via
+    #   -c requirements.txt
+    #   pyvista
+urllib3==2.2.3
+    # via
+    #   -c requirements.txt
+    #   requests
+vtk==9.3.1
+    # via
+    #   -c requirements.txt
+    #   pyvista