Re-build the joss-submission branch from main

.github/workflows/build_uw3_and_test.yml

@@ -1,4 +1,4 @@
-name: Build and test UW3
+name: test_uw3
 
 # We should trigger this from an upload event. Note that pdoc requires us to import the
 # built code, so this is a building test as well as documentation deployment
@@ -15,7 +15,7 @@ on:
   workflow_dispatch:
 
 jobs:
-  deploy:
+  test:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -27,12 +27,6 @@ jobs:
           cache-downloads: true
           cache-environment: true
 
-          # # gmsh is such a pig to install properly
-          # - name: Add gmsh package
-          #   shell: bash -l {0}
-          #   run: |
-          #     pip install gmsh
-
       - name: Build UW3
         shell: bash -l {0}
         run: |
@@ -42,12 +36,8 @@ jobs:
 
           ## TODO. Use compile.sh once it is in development
           pip install -e . --no-build-isolation
-          ## ./compile.sh
-
-      # Test - split into short, low memory tests 0???_*
-      #        and longer, solver-based tests 1???_*
 
-      - name: Run pytest
+      - name: Run tests 
         shell: bash -l {0}
         run: |
           ./test.sh

.github/workflows/docker-image.yml

@@ -1,32 +1,33 @@
-name: Docker Image CI
+name: Image Build and Push
 
 on:
-  push:
-    branches: ["development"]
+  push: 
+    branches:
+      - development
+
 jobs:
-  build:
+  push-to-dockerhub:
     runs-on: ubuntu-latest
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Exact branch name
         run: echo "BRANCH=${GITHUB_REF##*/}" >> $GITHUB_ENV
 
       - name: Login to DockerHub
-        uses: docker/login-action@v2
+        uses: docker/login-action@v3
         with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_PWORD }}
+          username: ${{ secrets.XXX_USERNAME }}
+          password: ${{ secrets.XXX_PWORD }}
 
       - name: Build and push Docker image
-        uses: docker/build-push-action@v4.1.1
+        uses: docker/build-push-action@v6
         with:
           context: .
           push: true
           file: ./Dockerfile
           platforms: linux/amd64
           # see https://github.com/docker/build-push-action/issues/276 for syntax help
-          tags: julesg/underworld3:${{ env.BRANCH }}
-          #-$(date +%s)
+          tags: underworldcode/underworld3:${{ env.BRANCH }} #-$(date +%s)

Dockerfile

@@ -0,0 +1,48 @@
+# syntax=docker/dockerfile:1.7-labs
+
+### how to build docker image
+
+# (1) run from the underworld3 top directory
+# podman build . \
+# --rm \
+# -f ./.github/Dockerfile \
+# --format docker \
+# -t underworldcode/underworld3:0.99
+
+### needs the --format tag to run on podman
+
+FROM docker.io/mambaorg/micromamba:2.3.0
+
+USER $MAMBA_USER
+ENV NB_HOME=/home/$MAMBA_USER
+
+# create the env
+COPY --chown=$MAMBA_USER:$MAMBA_USER environment.yml /tmp/env.yaml
+RUN micromamba install -y -n base -f /tmp/env.yaml && \
+    micromamba clean --all --yes
+
+# activate mamba env during `docker build`
+ARG MAMBA_DOCKERFILE_ACTIVATE=1
+
+# install UW3
+WORKDIR /tmp
+COPY --exclude=**/.git \
+     --chown=$MAMBA_USER:$MAMBA_USER \
+     . /tmp/underworld3
+WORKDIR /tmp/underworld3
+
+RUN pip install --no-build-isolation --no-cache-dir .
+
+# copy files across
+RUN mkdir -p $NB_HOME/workspace
+
+COPY --chown=$MAMBA_USER:$MAMBA_USER ./tests   $NB_HOME/Underworld/tests
+
+EXPOSE 8888
+WORKDIR $NB_HOME
+USER $MAMBA_USER
+
+# Declare a volume space
+VOLUME $NB_HOME/workspace
+
+CMD ["jupyter-lab", "--no-browser", "--ip=0.0.0.0"]

README.md

@@ -8,7 +8,16 @@ Welcome to `Underworld3`, a mathematically self-describing, finite-element code
 
 All `Underworld3` source code is released under the LGPL-3 open source licence. This covers all files in `underworld3` constituting the Underworld3 Python module. Notebooks, stand-alone documentation and Python scripts which show how the code is used and run are licensed under the Creative Commons Attribution 4.0 International License.
 
-[![Build and test UW3](https://github.com/underworldcode/underworld3/actions/workflows/build_uw3_and_test.yml/badge.svg?branch=main)](https://github.com/underworldcode/underworld3/actions/workflows/build_uw3_and_test.yml)
+## Status
+
+main branch
+
+[![test_uw3](https://github.com/underworldcode/underworld3/actions/workflows/build_uw3_and_test.yml/badge.svg?branch=main)](https://github.com/underworldcode/underworld3/actions/workflows/build_uw3_and_test.yml)
+
+
+development branch
+
+[![test_uw3](https://github.com/underworldcode/underworld3/actions/workflows/build_uw3_and_test.yml/badge.svg?branch=development)](https://github.com/underworldcode/underworld3/actions/workflows/build_uw3_and_test.yml)
 
 ## Documentation
 

docs/joss-paper/paper.md

@@ -67,6 +67,8 @@ Users of `underworld3` typically develop python scripts within `jupyter` noteboo
 
 # Statement of need
 
+Typical problems in geodynamics usually require computing material deformation, damage evolution, and interface tracking in the large-deformation limit. These are typically not well supported by standard engineering finite element simulation codes. Underworld is a python software framework that is intended to solve geodynamics problems that sit at the interface between computational fluid mechanics and solid mechanics (often known as *complex fluids*). It does so by putting Lagrangian and Eulerian variables on an equal footing at both the user and computational levels.
+
 Underworld is built around a general, symbolic partial differential equation solver but provides template forms to solve common geophysical fluid dynamics problems such as the Stokes equation for mantle convection, subduction-zone evolution, lithospheric deformation, glacial isostatic adjustment, ice flow; Navier-Stokes equations for finite Prandtl number fluid flow and short-timescale, viscoelastic deformation; and Darcy Flow for porous media problems including groundwater flow and contaminant transport.
 
 These problems have a number of defining characteristics:  geomaterials are non-linear, viscoelastic/plastic and have a propensity for strain-dependent softening during deformation; strain localisation is very common as a consequence. Geological structures that we seek to understand are often emergent over the course of loading and are observed in the very-large deformation limit. Material properties have strong spatial gradients arising from pressure and temperature dependence and jumps of several orders of magnitude resulting from material interfaces.

docs/user/NextSteps.qmd

@@ -16,9 +16,11 @@ In addition to the notebooks in this brief set of examples, there are a number o
 
   - [The Underworld Website / Blog](https://www.underworldcode.org)
 
-  - [The API documentation](https://underworldcode.github.io/underworld3/main_api/underworld3/index.html) 
+  - [The API documentation](https://underworldcode.github.io/underworld3/main_api/underworld3/index.html)
     (all the modules and functions and their full sets of arguments) is automatically generated from the source code and uses the same rich markdown content as the notebook help text.
 
+  - [The API documentation (development branch)](https://underworldcode.github.io/underworld3/development_api/underworld3/index.html)
+
   - The [`underworld3` GitHub repository](https://github.com/underworldcode/underworld3) is the most active development community for the code.
 
 
@@ -44,6 +46,33 @@ Almost all of our notebook examples are annotated python for this reason.An exce
 
 The main difference between the notebook development environment and HPC is the lack of interactivity, particularly in sending parameters to the script at launch time. Typically, we expect the HPC version to be running at much higher resolution, or for many more timesteps than the development notebook. We use the `PETSc` command line parsing machinery to generate notebooks that also can ingest run-time parameters from a script (as above).
 
+#### Parallel scaling / performance
+
+Running geodynamic models on a single CPU/processor (i.e. serial) is time-consuming and limits us to low resolution. Underworld is build from the ground-up as a parallel computing solution which means we can easily run large models on high performance computing clusters (HPC); that is, sub-divide the problem into many smaller chunks and use multiple processors to solve each one, taking care to combine and synchronise the answers from each processor to obtain the correct solution to the original problem.
+
+Parallel computation can reduce time we need to wait for the our results to be computed but it does happen at the expense of some overhead The overhead does depend on the nature of the computer we are using but typically we need to think about:
+
+ - **Code complexity**: any time we manage computations across different processors, we have additional coding to reassemble the calculations correctly and we need to think about many special cases. For example, integrating a quantity of the surface of a mesh: many processes contribute, some do not, the results have to be computed independently then combined.
+
+ - **Additional memory is often required**: to manage copies of information that lives on / near boundaries, to store the topology of the decomposed domain and to help navigate the passing of information between processes.
+
+ - **The time taken to synchronise results** and the work required to keep track of who is doing what, when they are done, and in making sure everyone waits for everyone else. There is a time-cost in actually sending information as part of a synchronisation and a computational cost in ensuring that work is distributed efficiently.
+
+To determine the efficiency of parallel computation, we introduce the *strong scaling test* which measures the time taken to solve a problem in parallel compared to the same problem solved in serial. In strong scaling tests, the size of the problem is kept constant, while the number of processors is increased. The reduction in run-time due to the addition of more processors is commonly expressed in terms of the speed-up:
+
+$$
+\textrm{speed up} = \frac{t(N_{ref})}{t(N)}
+$$
+
+where $t(N_{ref})$ is the run-time for a reference number of processors, $N_{ref}$, and $t(N)$ is the run-time when $N$ processors are used. In the ideal case, $N$ additional processors should contribute all of its resources in solving the problem and reduce the compute time by a factor of $N$ relative to the reference run time. For example, using $2 N_{ref}$ processors will ideally halve the run-time resulting to a speed-up = 2.
+
+::: {#fig-strong-scaling}
+
+![](media/UW3-StrongScalingSolvers.png)
+
+Strong parallel-scaling tests run on Australia's peak computing system, [GADI, at the National Computational Infrastructure](https://nci.org.au/our-systems/hpc-systems?ref=underworldcode.org). This is a typical High Performance Computing facility with large numbers of dedicated, identical CPUs and fast communication links.
+:::
+
 
 ### Advanced capabilities
 
@@ -77,11 +106,11 @@ It is also possible to use the PETSc mesh adaption capabilities, to refine the r
 
 ```{=html}
 <center>
-<iframe src="media/pyvista/AdaptedSphere.html" width="600" height="300">
+<iframe src="media/pyvista/AdaptedSphere.html" width="600" height="500">
 </iframe>
 </center>
 ```
-*Live Image: Static mesh adaptation to the slope of a field. The driving buoyancy term is three plume-like upwellings and the slope of this field is shown in colour (red high, blue low). The adapted mesh is shown in green.*
+*Live Image: Static mesh adaptation to the slope of a field. The driving buoyancy term is a plume-like upwelling and the slope of this field is shown in colour (red high, blue low). Don't forget to zoom in !*
 
 ```python